Troubleshooting Hive

Fixes for common Hive problems: keys that do nothing, agents not found, protocol mismatches, odd glyphs or colours, lost sessions, and how to report a bug.

Start with hive doctor

hive doctor

It shows the config file and whether it is valid, the socket path, whether the daemon is running, where the logs are, the colours and glyphs detected, and which agents are on your PATH. It changes nothing, never starts the daemon, and exits non-zero if it finds a problem.

Logs

hived.log (daemon) and hive.log (window) are in ~/.local/state/hive/. For more detail, restart with debug logging:

hive daemon stop && HIVE_LOG=debug hive

Common problems

Symptom	Cause and fix
A Ctrl+Space key goes to the wrong command	Keys are case-sensitive. `n` is the next session; `N` (Shift+n) opens notes. `Ctrl+Space` `?` lists the keys as you have them.
An integration's key does nothing, or says it is off	Integrations are off until enabled. Press `Ctrl+Space` `I` and turn it on; it works at once.
Ctrl+Space does nothing at all	Your desktop or input method uses it (input-method switching often does). Choose another leader: `[keys] leader = "ctrl+a"`.
The agent needs a key Hive takes	Only the leader and the Alt chords are intercepted. Press the leader twice to send it to the agent; free an Alt chord with `[keys.global] next_tab = []`.
Review opens git diff instead of lazygit	Neither lazygit nor tig is on `PATH`. Install one, or set `[integrations.review] command`.
GitHub checks or usage pane exits at once	The tool isn't installed or set up: `gh` needs `gh auth login`; usage needs `ccusage` (`npm i -g ccusage`) or another `command`.
No Obsidian vault in <project>	Hive looks for a folder with `.obsidian/` at or above the agent's directory, or one level below the repository root. Open the vault once in Obsidian to create it.
No desktop notifications	`notify-send` is missing (on Debian and Ubuntu it is in `libnotify-bin`), or your desktop has no notification service. On macOS set `[integrations.desktop_notify] command` to a tool such as `terminal-notifier`.
daemon speaks protocol vN, this client speaks vM	A daemon from an older version is still running. `hive daemon stop` (ends its sessions), then `hive`.
`claude` was not found on PATH	The agent isn't installed, or isn't on the `PATH` of the shell you ran `hive` from. Check `hive doctor`, or give an absolute `command` under `[agents.<name>]`.
hive: invalid config	The message names the key and line. Fix it and check with `hive doctor`. A config error never leaves a broken screen behind.
An agent shows no status	Hive only shows status for agents it has rules for, or that report it. `hive agents -a` lists which have rules.
Boxes, question marks or misaligned borders	The font or locale lacks the glyphs. Use a UTF-8 locale or set `[theme] glyphs = "ascii"`. Nerd Fonts are never needed.
Colours look wrong	Force a depth with `[theme] colors = "256"`, try `theme = "ansi"` to use your terminal's palette, or `theme = "hive-light"` on a light background.
Sessions show ◌ lost	The daemon stopped unexpectedly (crash, `kill -9`, reboot). The processes are gone; Enter relaunches one in the same directory, `x` forgets it. See what survives what.
Typing does nothing; the status bar says observing	Another window controls the session. `Ctrl+Space` `a` takes control.
Kept worktree …: it has uncommitted changes	Working as intended. Commit or stash, or `hive worktree rm <path> --force`.
hived did not come up	See `hived.log`. Another daemon may hold the lock: `hive daemon status`.
Socket errors with a custom HIVE_RUNTIME_DIR	Socket paths must be under about 107 bytes. Use a shorter directory; `hive doctor` warns about this.
Selecting text with the mouse doesn't work	Hold `Shift` while selecting, or turn the mouse off with `[terminal] mouse_support = false`.

Windows

Terminals stay in the space they started in (spaces don't follow cd).
hive update isn't available; rerun the PowerShell installer.

Reporting a bug

Open an issue with the output of hive doctor, your terminal, and the relevant part of hived.log (with HIVE_LOG=debug if you can reproduce it). Check the log for anything private before sharing.