castellan herd
Multiplexer UX over the in-tree PTY server — attach, status, and pane operations without raw socket JSON. The subcommand name is historical; in prose this is mux / pane control, not an animal metaphor. Verified against HerdCommands in crates/castellan-cli/src/main.rs.
Usage
castellan herd <SUBCOMMAND>
Subcommands
| Subcommand | Flags | Purpose |
|---|---|---|
server | --socket <PATH>, --session <NAME> | Start or attach to the multiplexer server |
status | --socket <PATH>, --notify | Rich agent dashboard JSON (--notify sends a macOS notification when agents are blocked) |
workspaces | --socket <PATH> | List workspaces on the multiplexer |
tabs | --socket <PATH>, --workspace <ID> | List tabs in a workspace (default: focused) |
attach | --socket <PATH>, --pane <ID>, --session <NAME> | Attach terminal UI to a pane (Ctrl+Q to detach); default is focused pane |
wait | --socket <PATH>, --pane <ID>, --status <STATUS> (default idle), --timeout-ms <MS> (default 30000) | Block until an agent reaches a status (events.wait wrapper) |
agent explain | --socket <PATH>, --pane <ID>, --verbose | Explain why a pane has its current status, with matched rules |
agent attach | --socket <PATH>, --takeover, <TARGET> | Attach directly to an agent by name, label, or pane id |
session list | --json | List named session servers |
session attach | --socket <PATH>, <NAME> | Attach to a named session server |
session stop | --json, <NAME> | Stop a named session server (persists snapshot) |
session delete | --json, <NAME> | Delete a named session and its data |
terminal attach | --socket <PATH>, --takeover, <TERM_ID> | Direct attach to a terminal by id |
terminal observe | --socket <PATH>, --pane <ID>, --cols, --rows | Read-only NDJSON terminal.frame stream |
terminal control | --socket <PATH>, --pane <ID>, --takeover, --cols, --rows | Writable NDJSON terminal (frames out, commands on stdin) |
remote | <HOST>, --session, --handoff, --remote-keybindings local|server, --socket | SSH thin-client remote attach |
Run castellan herd <subcommand> --help for the current flag list — this table tracks main.rs at time of writing.
Recipes
Check multiplexer health:
castellan herd status
Attach to a running agent by name:
castellan herd agent attach claude
Explain why an agent looks stuck:
castellan herd agent explain --pane w1:p1 --verbose
Wait for an agent to go idle (scripting):
castellan herd wait --pane w1:p1 --status idle --timeout-ms 60000
Named sessions (multi-project):
castellan herd session list --json
castellan herd session attach my-project
castellan herd session stop my-project
Read-only pane observation (headless monitor):
castellan herd terminal observe --pane w1:p1 --cols 100 --rows 30
Remote mux panes over SSH:
castellan herd remote user@host --session my-project
Daily-driver stack:
castellan multiplexer ensure
castellan herd status
castellan dashboard
Failure paths
| Symptom | Cause | Fix |
|---|---|---|
herd status returns "running": false | No server at the socket path | castellan multiplexer ensure, then retry |
herd wait times out | Agent never reached target status within --timeout-ms | Increase timeout, or herd agent explain --pane <id> to see why it’s stuck |
herd attach shows nothing | Wrong --pane/--session, or pane exited | herd tabs / herd workspaces to enumerate valid ids first |
herd remote fails to connect | SSH auth or ~/.ssh/config alias missing | Test ssh <host> directly before wrapping in herd remote |
| Ctrl+Q doesn’t detach | Terminal emulator intercepts the escape sequence | Use q from castellan dashboard’s agent list instead |