Skip to main content

Troubleshooting

When something breaks, start here. If your issue isn't covered, open a GitHub issue with caveman doctor output.

Install​

cave: command not found after install​

Restart your shell, or:

source ~/.zshrc      # zsh
source ~/.bashrc     # bash

If still missing, the installer printed the install path — add it to your PATH.

Operation not permitted writing to ~/.cave​

Filesystem is read-only or owned by another user. Run:

ls -la ~/.cave
chown -R "$USER" ~/.cave

Apple silicon: bad CPU type in executable​

You downloaded an x86_64 binary on an ARM Mac. Re-install via npm — the package is platform-agnostic:

npm install -g @juliusbrussee/caveman-code

Auth​

OAuth opens browser but never completes​

  1. Check that the loopback port (random in 1024-65535) isn't firewalled.
  2. Try device-code auth: caveman login --device-auth.
  3. Disable VPN that intercepts loopback.

401 Unauthorized on a stored token​

Token expired and refresh failed. Re-login:

caveman logout <provider>
caveman login <provider>

Linux libsecret not found​

Install:

# Debian / Ubuntu
sudo apt install libsecret-1-0 libsecret-tools

# Arch
sudo pacman -S libsecret

If your distro lacks libsecret, set CAVE_INSECURE_KEYRING=1 to fall back to a plaintext token file (warning is shown).

Sessions​

Caveman Code hangs on launch​

Stuck on context load. Kill and:

caveman -r --no-context     # browse without loading any session

Then identify and remove the bad session in ~/.cave/sessions/<cwd-hash>/.

/tree shows no branches​

Branching is per-session. The first session in a cwd has no branches by definition. Run a few turns then /fork to test.

Compaction destroyed important context​

Use the shadow-git checkpoint: /checkpoint list, then /rollback <N>. Compaction itself runs a PreCompact hook — instrument it to write important context to disk first.

Tools​

Bash tool times out​

Default tool timeout is 60s. Override per call:

> use Bash with --timeout 600 to run the long-running migration

Or globally in ~/.cave/settings.json:

{
    "tools": { "bash": { "timeoutMs": 600000 } }
}

Edit keeps applying to the wrong location​

The model's view of the file is stale. After a hook writes to the file, ask cave to re-read:

> re-read src/foo.ts and apply the change

Caveman Mode is summarizing too aggressively​

Lower compression intensity:

/caveman lite                 # default is "full" (in TUI)
/caveman off                  # turn off entirely

Permissions​

Every action prompts even though I clicked "Allow always"​

The allow-key is more specific than the new action. E.g. Read packages/foo/** won't match Read packages/bar/baz.ts. Add a broader allow-key with caveman permissions add "Read **".

Sandbox blocks something I need​

caveman debug sandbox shows the active policy. Caveman Code executes all tool requests directly - there is no sandbox flag or permission prompts. The OS enforces filesystem permissions. To constrain a session, use --tools to limit available tools (e.g. --tools read,grep,find,ls for read-only).

For permanent allowlist, add to permissions.json:

{
    "permissions": {
        "alwaysAllow": ["Bash:docker run *"]
    }
}

MCP​

caveman mcp doctor shows server unreachable​

caveman mcp logs <server>     # tails stderr of stdio server

Common causes: command not on PATH, env var missing, server's auth flow incomplete.

MCP tools don't show up in the model's context​

By default Caveman Code defers MCP schemas — only names are listed until the model calls ToolSearch. This reduces context bloat by ~85%.

Hooks​

Hook never fires​

Check the matcher:

caveman hooks test PreToolUse --tool Edit --path src/foo.ts

Reports whether each hook would fire for that input. Common mistake: paths glob doesn't include the actual file path.

Hook output isn't reaching the model​

Only stdout is fed back to the model as a system reminder. Stderr is logged but ignored. Check that your hook prints to stdout, not stderr.

Memory (cavemem)​

/memory search returns nothing​

cavemem isn't running. Check:

cavemem --version
caveman mcp doctor   # should show cavemem reachable

If missing: npm install -g cavemem then caveman init.

Memory injection too noisy​

Lower the cap in settings.json:

{
    "memory": { "maxInjectTokens": 1000 }
}

Or disable for the session: /memory off.

Performance​

TUI feels laggy​

Caveman Code automatically detects and uses synchronized output (DEC mode 2026) on supported terminals. If you see rendering issues, ensure your terminal supports ANSI escape sequences and check caveman doctor output for terminal detection status.

Long sessions get slow​

Run /compact to manually compact. Or enable auto-compact at a lower threshold:

{
    "session": { "autoCompactAtTokens": 80000 }
}

Reporting issues​

caveman doctor > /tmp/cave-doctor.txt
caveman version > /tmp/cave-version.txt

Attach both to a GitHub issue. Include the prompt that triggered the bug if reproducible.