herdr

What you will run into

You want persistent sessions on top of agent CLIs: keep several workspaces/worktrees alive, switch between them, get notifications — herdr is a persistent multi-session manager for agent CLIs: sessions, workspaces, worktrees, tabs, notifications, agent/pane/integration. The two things people trip on: the binary download from GitHub direct is slow on mainland networks (use the gh-proxy prefix), and after you exit a session the server may keep running (stop it with herdr server stop). When to use it:

• Managing several persistent sessions/workspaces/worktrees for agent CLIs;
• Background agent runs with notifications;
• Needing a session terminal surface that survives reconnects.

When not to use it: one-off single commands — a plain shell is enough; the control plane itself starts a background server.

Path: Quick fix (30s, one command) -> Step by step (skimmable) -> How to confirm it works (success criteria). In a hurry? Jump to Quick fix.

Why this happens

Single binary (Linux x86_64, no runtime deps): download + chmod and it works. herdr --session main enters a persistent session terminal surface; first run creates ~/.config/herdr/ (config) + ~/.local/state/herdr/ (state/agent detection); after exiting, the server may stay resident (socket + logs + session files), stopped via herdr server stop. Key concepts:

• session: persistent session terminal surface (herdr --session <name>);
• server: background process started by the full client (socket API);
• config check: validates config (passes even without config.toml — first run uses defaults).

Where it writes: ~/.config/herdr/ + ~/.local/state/herdr/ (created after starting a session).

Step by step

Step 1: Install the binary (why gh-proxy: mainland GitHub direct is slow, verified path)

Why: single binary download + chmod, no runtime deps. Mainland GitHub direct is slow, so download URLs use the gh-proxy prefix. Verify with --version after install.

curl -sL -o herdr https://gh-proxy.com/https://github.com/herdrdev/herdr/releases/download/v0.8.2/herdr-linux-x86_64
chmod +x herdr
./herdr --version

Expected output: herdr 0.8.2 After install, confirm:

• --version prints 0.8.2;
• herdr --help shows the full subcommand surface.

Stuck? How to recover:

• download timeout → confirm the network can reach gh-proxy; switch networks (campus/proxy) and retry;
• want it globally → put the binary on PATH (e.g. /usr/local/bin).

Step 2: Status and config check (does not start the server)

Why: status shows client version + channel + server state (prints a socket path when not running); config check validates config (passes even without config.toml — first run uses defaults). Run these two first to confirm the environment before entering sessions.

herdr status

Expected output: client version 0.8.2 + channel stable + server state (prints socket path when not running)

herdr config check

Expected output: config: ok (passes even without config.toml — first run uses defaults) After install, confirm:

• status prints version and server state normally;
• config check prints config: ok.

Stuck? How to recover:

• status abnormal → look at the socket path and log locations in the output;
• config check errors → fix config as prompted (defaults pass).

Step 3: Enter a persistent session (starts the background server)

Why: herdr --session main enters a persistent session terminal surface. First run creates config and state directories; after exiting, the server may stay resident — use herdr server stop when not in use.

herdr --session main

Expected output: enters the persistent session terminal surface (first run creates ~/.config/herdr/ + ~/.local/state/herdr/agent-detection/; server may stay resident after exit) After install, confirm:

• you enter the session terminal;
• after exit, herdr status shows the server state.

Stuck? How to recover:

• session won't start → run status/config check first to inspect the environment;
• server resident, want it stopped → herdr server stop.

How to confirm it works

Step 1: Confirm the command and config surface

Why: status and config check are this tool's two self-checks — status shows version and server state, config check validates config; both passing means the client environment is fine.

herdr status
herdr config check

Expected output: version 0.8.2 + channel stable + server state; config: ok Stuck? How to recover:

• status abnormal → look at the socket path and log locations in the output;
• config check errors → fix config as prompted (defaults pass).

Step 2: Confirm a session can be entered (optional, starts the background server)

Why: being able to enter the --session main persistent session terminal means the binary-to-runtime path is fully working; remember to stop the resident server with herdr server stop after exit.

herdr --session main

Expected output: enters the persistent session terminal surface (first run creates ~/.config/herdr/ + ~/.local/state/herdr/) Stuck? How to recover:

• session won't start → run status/config check first to inspect the environment;
• server resident, want it stopped → herdr server stop.

Other environments

• Non-Linux x86_64: official binaries exist for darwin etc. (not verified here, same command surface); no official native Windows support — use WSL.
• Want it globally: put the binary on PATH (e.g. /usr/local/bin), then call herdr instead of ./herdr.
• Background process: the full client starts a server (socket + logs + session files); use herdr server stop when not in use; config and state stay in ~/.config/herdr/ and ~/.local/state/herdr/ and are not auto-deleted.

Daily usage

Startup and entry

• Sessions: herdr --session <name>;
• Status: herdr status;
• Background server: stop with herdr server stop.

Common operations

Operation 1: View the command surface (verified here)

herdr --help

Expected output: session/workspace/worktree/tab/notification/agent/pane/integration/server/config/channel/api subcommands Operation 2: Status check (verified here; does not start the server)

herdr status

Expected output: client version 0.8.2 + channel stable + server state (prints socket path when not running) Operation 3: Config validation (verified here)

herdr config check

Expected output: config: ok (passes even without config.toml — first run uses defaults) Operation 4: Start/attach a persistent session (starts the background server)

herdr --session main

Expected output: enters the persistent session terminal surface (first run creates ~/.config/herdr/ + ~/.local/state/herdr/agent-detection/; server may stay resident after exit) Operation 5: Stop the background server

herdr server stop

Expected output: server stopped (via socket API)

Data and directories

• Config: ~/.config/herdr/;
• State/agent detection: ~/.local/state/herdr/.

Uninstall & cleanup

note: remove the single binary (per actual install path); own directories auto-deleted; stop a running server first

herdr server stop 2>/dev/null || true
rm -f /usr/local/bin/herdr ~/.local/bin/herdr
rm -rf ~/.config/herdr ~/.local/state/herdr
command -v herdr >/dev/null 2>&1 && echo '残留: herdr 仍存在' || echo 'herdr removed: OK'

Expected output: herdr removed: OK

Dependency warnings

• Version: [0.8.2, 0.8.2] locked (verified collection version).
• Environment: Linux x86_64; no runtime deps; /usr/local/bin writable (or put it on the user PATH).
• Network: GitHub direct slow, must use the gh-proxy prefix (verified path); official install.sh goes through herdr.dev (not tested).
• Write surface: ~/.config/herdr/ + ~/.local/state/herdr/ (created after starting a session).
• Background process: the full client starts a server (socket + logs + session files).
• Co-install: no conflict-matrix pairs (own-directory write surface, no overlap with common tools); member of combos combo-governance-stack / combo-env-init.

FAQ

• Q: Why is the server still there after exiting a session? A: persistent-session design — the server may stay resident; use herdr server stop when not in use.
• Q: Download slow? A: use the gh-proxy prefix from the install section; the official install.sh (herdr.dev) is not tested.
• Q: Conflicts with other tools? A: no conflict-matrix pairs — own-directory write surface, does not touch shared registration surfaces like ~/.claude.json.
• Q: Where to report problems? A: install/uninstall issues on this marketplace go through the entry feedback channel; project issues go to the author's repository.