Troubleshooting

Fresh

Install and update

Problem	Fix
Shell cannot find herdr after install	Restart the terminal or check that the install directory is on PATH
mise reports herdr not found in mise tool registry	Update mise and retry; or mise use -g github:ogulcancelik/herdr as a temporary fallback
herdr update does nothing on Homebrew/mise/Nix	Those installs update through their package managers; herdr update only manages direct installs
herdr channel set stable rejected on Windows	Expected; Windows builds are preview-only until stable Windows releases exist
New server version not active after update	If protocol changed, stop the old server: herdr server stop then herdr (or herdr session stop <name>)

Agent state

Problem	Fix
Pane shows the wrong agent state	herdr agent explain <target> shows the matched rule and why; add --verbose or --json for detail
New agent prompt shows idle instead of blocked	Blocked detection is deliberately strict; unknown screen shapes fall back to idle (default_known_agent_idle_fallback) until manifests learn them
Agent not detected at all	Unsupported agents still run as terminal processes; add an integration or report state over the socket API
Agent inside tmux not detected	Herdr sees tmux as the pane process; detection does not inspect tmux sessions launched inside a pane
Stale detection rules	herdr server update-agent-manifests fetches and reloads remote manifests immediately
Local manifest override not applied	Restart Herdr or run herdr server reload-agent-manifests
Integration state wrong	Confirm the agent runs inside Herdr and the hook/plugin was installed for the same user account; check herdr integration status

Session restore

Problem	Fix
Panes came back as plain shells after restart	Snapshot restore does not preserve processes; native agent session restore needs a current integration version (see Session State)
Agent did not resume its conversation	Run herdr integration status; reinstall outdated integrations. Unsupported, missing, invalid, duplicated, or stale session references restore as normal shells
Want recent screen contents back after restart	Enable [experimental] pane_history = true (off by default because pane output can include secrets)
Cursor agent did not resume	cursor-agent must be on PATH when Herdr restores the pane

Remote attach

Problem	Fix
herdr --remote fails non-interactively on a fresh host	Non-interactive runs do not install the remote binary; attach interactively once, or pre-install Herdr on the host
Remote install warning about PATH	Add ~/.local/bin to the remote PATH
Keybindings feel wrong on remote	Local keybindings are a snapshot from attach time; detach and reattach after editing, or use --remote-keybindings server
herdr --remote from Windows	Unsupported in the beta; SSH into the server and run herdr there
SSH drops	Herdr adds keepalive fallbacks by default; your own ServerAliveInterval settings win. [remote] manage_ssh_config = false to use plain ssh

UI and terminal

Problem	Fix
Mouse clicks going to Herdr instead of the terminal	Set [ui] mouse_capture = false
Ctrl-click does not open links	Your terminal must send the modified click; fallback is Shift-Ctrl-click (Linux) or Shift-Cmd-click (macOS)
Right-click needed inside a pane app	Set right_click_passthrough_modifier = "ctrl" and Ctrl-right-click
No scrollbar in vim/htop	Alternate-screen apps have no scrollback; scroll with the app's own keys
Full-screen flash when refocusing Herdr	Set redraw_on_focus_gained = false
macOS IME candidate window misplaced in agent TUIs	Set [experimental] reveal_hidden_cursor_for_cjk_ime = true, scope with cjk_ime_agents
Invalid config value	Herdr falls back to a safe default and shows a startup warning; fix the value in ~/.config/herdr/config.toml
Config edits not applied	herdr server reload-config; startup-only settings need a restart

Sound and notifications

Problem	Fix
No notifications	Default is [ui.toast] delivery = "off"; set herdr, terminal, or system
Linux system notifications fail	notify-send required plus DISPLAY or WAYLAND_DISPLAY
No sound on Linux	Needs one of: paplay, pw-play, ffplay, mpg123, mpv
Sound on a shared box	[ui.sound] enabled = false or HERDR_DISABLE_SOUND

Logs

~/.config/herdr/herdr.log
~/.config/herdr/herdr-client.log
~/.config/herdr/herdr-server.log

Logs rotate automatically. Include the current log and rotated siblings when reporting issues. Set HERDR_LOG=herdr=debug for verbose logging.

Reporting Windows beta issues

Include: Herdr version, Windows version, terminal app, shell (PowerShell or cmd), whether you used a named HERDR_SESSION, relevant logs, and exact reproduction steps.