Troubleshooting

“Not installed”, but the CLI works in my terminal

CodeHerd reads your PATH from your login shell when it starts. If you installed the CLI (or changed your shell configuration) after opening CodeHerd, press Re-detect in Settings → Agents.

If it still isn't found, check that command -v claude (or codex, gemini) prints a path in a new terminal window. Your shell configuration might only set PATH in a file your login shell doesn't read.

CodeHerd isn't getting updates

Settings → About says whether CodeHerd is up to date, and why not if it can't update. Only a copy in your Applications folder updates itself: if you opened CodeHerd from the .dmg or your Downloads folder, drag it into Applications and open it from there. CodeHerd 1.0.0 has no updater, so it needs the latest .dmg from the download page once.

My shell configuration is slow or prints a lot

CodeHerd sets CODEHERD_RESOLVING_ENVIRONMENT=1 while it reads your environment. You can skip slow parts of your ~/.zshrc for that one run:

[[ -n $CODEHERD_RESOLVING_ENVIRONMENT ]] && return

If reading takes longer than 10 seconds, CodeHerd falls back to common install locations (Homebrew, ~/.local/bin, npm, bun, cargo).

macOS asks to access Documents or Desktop

Agents you run inside CodeHerd access your project files, and macOS attributes that to CodeHerd. Allow it if the project lives there. See Privacy & security.

A session says “Interrupted”

CodeHerd quit unexpectedly while that agent was running. Any processes it left behind were stopped when CodeHerd started again. Click Restart to continue.

The agent's icons look like boxes

Prompt themes such as oh-my-posh or powerlevel10k use Nerd Font icons. Install a Nerd Font (for example JetBrains Mono Nerd Font); CodeHerd picks it up automatically, or set it in Settings → Terminal.

Still stuck?

Email support@codeherd.app with your CodeHerd and macOS versions (Settings → About). The diagnostic log in ~/Library/Application Support/CodeHerd/logs helps; it contains no terminal output.