Troubleshooting
Setup checks, missing agent status dots, and herdr display problems.
Setup checks
Settings → General → Setup lists what blockodile needs on this machine and what is wrong with
it. Every failing row carries the button that fixes it — use that rather than fixing around it,
because each one also re-checks afterwards. Cmd/Ctrl+K → Re-run setup checks runs the lot.
The common ones: herdr missing or older than 0.9.0 (Install herdr), a herdr server left
running from an older build (Restart herdr server — this closes every pane and its agents),
and herdr drawing its own tab bar or sidebar inside the terminal block (Apply herdr display
settings, which writes a marked, backed-up block into ~/.config/herdr/config.toml).
A pane shows no agent status
blockodile draws an indicator only for working, blocked and done. An idle agent shows nothing, and so does an agent herdr cannot read — so a missing dot is ambiguous. Ask herdr which one it is:
herdr agent explain <pane-id> # pane ids come from `herdr api snapshot`A detection that works names the rule that fired and the text it matched. One that does not looks like this:
agent: pi
state: idle
rule: none
fallback_reason: default_known_agent_idle_fallbackrule: none means herdr recognised the agent but has no way to read its state. Install the
agent-state integration and restart that agent:
herdr integration status # every supported agent and its hook path
herdr integration install piRestart the agent afterwards
The integration loads when the agent starts. A pane opened before you installed it keeps
reporting rule: none, which looks exactly like the install having failed.
Claude Code needs no integration — herdr reads its state from the terminal title. pi, codex, opencode and most others do. That is why status often works for one agent and not another.
Display problems
| Symptom | Fix |
|---|---|
| herdr's tab bar, sidebar, borders or scrollbars inside the terminal block | Apply herdr display settings |
| A header with workspace / tab / agent counts, on Linux but not macOS | Same command — the block is narrow enough to trigger herdr's mobile layout, and the fix pins the threshold |
Edited ~/.config/herdr/config.toml, nothing changed | herdr reads config on the server: herdr server reload-config |
nested herdr is disabled by default | blockodile was launched from inside a herdr pane. Start it from a plain terminal or your app launcher |
| Every pane squeezed side by side | herdr cleared the tab's zoom on a split or an agent exiting. blockodile re-zooms on the next poll — wait a moment |