Quickstart

Goal: Caveman Code installed, authenticated, first prompt answered. Target time: 30 seconds.

1. Install

npm install -g @juliusbrussee/caveman-code

Requires Node.js 20+. Other options (Homebrew, Docker, manual binary) are documented in Install.

Verify:

caveman --version

Pick one of these. Caveman Code detects which keys you already have in your environment.

::: code-group

export ANTHROPIC_API_KEY=sk-ant-...

export OPENAI_API_KEY=sk-...

caveman
# inside the TUI:
/login

:::

The OAuth flow opens a browser and stores tokens in your OS keychain (macOS Keychain, Linux libsecret, Windows Credential Manager).

See the full Auth & Providers page for the 20+ supported backends.

caveman "explain this codebase"

Or open the interactive TUI:

caveman

Type a prompt and the agent responds. Type /help for the full slash-command list.

npm installed the @juliusbrussee/caveman-code package globally, registering two binaries: caveman and caveman-code (aliases).
On first launch, the wizard ran (4 questions: theme, auth, default model, telemetry off-by-default) and persisted your choice to ~/.cave/settings.json.
Caveman Mode compression is on by default. Tool output (bash, grep, file reads) is summarized before re-entering context.

Task	Command / link
Continue your last session	`caveman -c`
Browse and resume past sessions	`caveman -r`
Pipe stdin to the agent	`cat README.md \| caveman -p "review"`
Switch model mid-session	`/model claude-sonnet-4`
Fork session to try a different path	`/fork`
Run in plan-only mode	`/plan` (slash command in TUI)
Migrate from Claude Code	Migration guide

caveman: command not found after install — restart your shell, or check that the npm global bin dir is on your PATH (npm config get prefix).
Wizard didn't appear — delete ~/.cave/settings.json and run caveman again.
Auth fails on Linux — install libsecret (apt install libsecret-1-0 on Debian/Ubuntu) or use API keys via env.