Troubleshooting
Install, TTY, crew startup, approval, session, and memory failures, with the fix for each.
Read the affected pane before retrying or approving anything. Most failures here are a native CLI waiting on a human, not Captain Barbossa losing track.
herdr agent read JackInstall and launch#
| Symptom | Fix |
|---|---|
captain: command not found | Run uv tool update-shell and restart the terminal. |
| Installed from Git before the PyPI release | Switch the install over once with uv tool install --force captain-barbossa. captain update then picks up each published release. |
Launch captain from an interactive Herdr terminal. | captain with no subcommand needs a TTY. Run it directly in a Herdr pane, not through a script or a pipe. |
Crew startup and approval#
| Symptom | Fix |
|---|---|
Crew pane opens but the task never starts, or is marked needs_attention | The native CLI may be waiting for approval or sign-in. Inspect the pane in Herdr; the task is not retried automatically past one resend. Send it by hand with herdr agent prompt <agent-name> '<task>'. |
| A Claude Code crew will not end its turn | Its Stop hook blocks while the crew has unread mail, or an unfinished assignment with no pending question. Read the mail with captain inbox <name> in that pane, finish with captain done <name> --report '...', or raise a question with captain ask. Any of the three releases it. |
Codex crew blocked on approval is invisible to captain wait <crew> --timeout 0 | Pane fallback starts after 6 seconds. Use a non-zero timeout. |
... is waiting for input or approval instead of starting the task. | Read the pane before approving, then send the requested key with herdr agent send-keys <name> <key>. Claude Code may need Enter or a number, not always y. |
... did not confirm the switch to ... | The native CLI did not echo the expected model name. Read the pane with herdr agent read <name> before retrying captain model. |
Model switch needs a readable empty composer without an approval prompt. | The crew has a draft, an approval prompt, or an unreadable pane. captain model types into the composer, so it refuses rather than typing over a human. Clear the pane, then retry. |
Sessions and memory#
| Symptom | Fix |
|---|---|
This session belongs to another project or Herdr workspace. | A session ID is tied to the project and workspace it was created in. Start a new captain, or pass the matching --session. |
durable memory root ... is inside the OS temp directory | A captain started before the state/temp split is still exporting one root to its children. Restart it so project-scope memory survives temp cleanup. |
memory query fails or reports a skip | Graphify is not installed. Run uv tool install graphifyy, or use memory show and add instead. |
| Ambiguous crew name or model | The error lists the available crew or models. Ask for one of those exactly. |
Still stuck#
Read the pane, then check captain status for which gate is holding a message. If a crew cannot be rung at all, its mail is marked bounced with a reason and the next wait reports it — nothing is silently parked. Failing that, open an issue on GitHub.