> **Status: frozen (August 2026).** Caveman Code is no longer in active > development. It still installs and works, but expect no new features or > fixes. The lesson moved into [caveman](https://github.com/JuliusBrussee/caveman): > `caveman wrap` makes the agent you already use cheaper instead of replacing > it. Note: this package installs a `caveman` binary that shadows the caveman > CLI from that repo β€” uninstall one before installing the other. > > This is the 2026 terminal agent, frozen. It is not the Caveman Code app at > caveman.so, which is proprietary. This repository stays MIT-licensed.
# πŸͺ¨ Caveman Code **The terminal coding agent that talks like a caveman.** 20+ providers Β· plan mode Β· autopilot loop Β· MIT.

Stars npm version npm downloads MIT License

Install Β· The Trick Β· How It Saves Tokens Β· Why Caveman Β· Features Β· SDK
--- ## πŸ”₯ The trick Big agent waffle. Waffle cost token. Caveman no waffle. **Asked** β–Έ *why does this component re-render on every keystroke?* | Ordinary agent Β· **~290 tokens** | πŸͺ¨ Caveman Code Β· **31 tokens** | |---|---| | Great question! A React component can re-render on every keystroke for several reasons. The most common cause is passing a fresh object or function reference as a prop on each render, which defeats React's referential-equality bail-out and forces the child to reconcile again … *(three more paragraphs)* | New object ref each render. Inline prop = new ref = re-render. Wrap in `useMemo`. | The agent reads its own context back on every turn, so shorter replies stay cheaper for the rest of the session. That is the entire product. Everything below is the coding agent it ships inside. --- ## Install ```bash npm install -g @juliusbrussee/caveman-code ``` Installs two binaries β€” `caveman` (primary) and `caveman-code` (alias). Same command, pick either. ```bash export ANTHROPIC_API_KEY=sk-ant-... # or any supported provider's key caveman # launch the TUI caveman "explain this codebase" # one-shot caveman -p "summarize this" # print mode (non-interactive) caveman goal start "ship feature X" # autonomous Ralph loop ```
Other install paths β€” pnpm Β· yarn Β· bun Β· Docker ```bash pnpm add -g @juliusbrussee/caveman-code yarn global add @juliusbrussee/caveman-code bun add -g @juliusbrussee/caveman-code # Docker docker run --rm -it -v "$PWD:/work" ghcr.io/juliusbrussee/caveman-code:latest ``` CI / headless install: [docs/getting-started/installation.md](docs/getting-started/installation.md).
--- ## Quick Start ```bash caveman # interactive TUI caveman "fix the failing tests" # start with a prompt caveman -p "summarize this file" # non-interactive: print and exit cat err.log | caveman -p "debug" # pipe stdin caveman -c # continue last session caveman -r # browse + resume sessions caveman /plan # plan mode β€” read-only (slash command) caveman goal start "ship payments v2" # autonomous Ralph loop ``` Type `/` inside the TUI for every slash command. Reference: [docs/reference/slash-commands.md](docs/reference/slash-commands.md). --- ## How It Saves Tokens Four compression layers, always on β€” and they hit **two** separate token sinks: what the model *says* and what the shell *returns*. | Token sink | Layer | What happens | Cut | |---|---|---|---| | **Model reply** | Caveman Mode | Terse technical fragments β€” no filler, no hedging. Levels `lite` Β· `full` Β· `ultra`. | prompt + reply | | **Tool output** | Tool Budgets | Per-tool line caps (bash 80 Β· read 300 Β· grep 120), ANSI strip, blank-line collapse, semantic JSON/XML extraction. | **βˆ’67% to βˆ’94%** | | | Read Dedup | Files fingerprinted per session β€” re-reads return a stub, not the bytes. | **βˆ’99%** on repeats | | | **[RTK](https://github.com/rtk-ai/rtk)** | Optional external Rust binary ("Rust Token Killer") β€” pipes bash output through `rtk` before it enters context. | **βˆ’60% to βˆ’90%** (RTK's own bench) |
Benchmark β€” 10 real tool-output fixtures Β· βˆ’86% aggregate ``` git diff (901 lines) β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆ -94% npm ls (701 lines) β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆ -92% ls recursive (601 ln) β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆ -90% grep results (801 ln) β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆ -89% test output (501 ln) β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆ -88% XML/pom.xml (382 ln) β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆ -79% docker inspect (258) β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆ -68% ANSI colored (97 ln) β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆ -50% read file (429 lines) β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆ -32% build output (19 ln) β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆ -18% ──────────────────────────────────────────────────── AGGREGATE β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆ -86% ``` | Metric | Value | |---|---| | Tokens saved (10 fixtures) | ~72,400 of 337K chars | | System-prompt overhead | 120–195 tokens (lite–ultra) | ```bash npm run bench:offline # compression analysis β€” free, <1s npm run bench:replay # analyze your real sessions β€” free npm run bench:live # A/B with live LLM calls β€” needs API key ```
```bash Use `/caveman [lite|full|ultra|off]` in the TUI to adjust compression aggressiveness. ``` --- ## Why Caveman Code - 4-layer token compression - 20+ providers, API keys or OAuth - Autonomous goal loop - Autopilot, no permission prompts - Repo map (PageRank, Aider-style) - Architect / editor model split - Session branching and shadow-git checkpoints - Persistent semantic memory (cavemem) - MIT licensed --- ## Features | | Feature | Trigger | |---|---|---| | πŸ€– | **Autonomous goal loop** β€” Ralph-style autopilot. Rolling state, per-iteration $/token ledger, shadow-git checkpoints, ranked termination (sentinel Β· iteration cap Β· $-cap Β· no-progress Β· SIGINT). Resume any time. | `caveman goal start` | | 🧠 | **Plan mode** β€” read-only chat. Model sees only `read`/`grep`/`find`/`ls`, produces a written plan, never edits. Subagents inherit the gate. `/act` to execute. | `/plan` | | πŸ‘₯ | **Subagents** β€” up to 7 parallel, worktree-isolated. Frontmatter agents at `.cave/agents/*.md` (Claude Code superset). Five ship by default. | `Task` tool | | πŸͺž | **Architect / editor split** β€” slow model plans, fast model executes. | `--architect` Β· `--editor` | Latest release: plan mode Β· goal loop Β· native memory tools Β· subagent registry. Full history β†’ [CHANGELOG.md](CHANGELOG.md).
More β€” sessions Β· providers Β· MCP Β· memory Β· recipes Β· daemon Β· CLI flags ### 🌳 Sessions, branching, replay JSONL sessions in `~/.cave/agent/sessions/`, organized by working directory. Branching never overwrites history. ```bash caveman -c # continue most recent caveman -r # browse and select caveman --fork # fork into a new file ``` `/tree` navigate + branch in-place (search Β· fold Β· page Β· filter) Β· `/compact` manual compaction Β· `/checkpoint` + `/rollback N` rewind code **and** conversation together. ### 🌐 20+ providers **OAuth** β€” ChatGPT Plus/Pro Β· GitHub Copilot Β· Google Gemini Β· Antigravity Β· Vertex **API keys** β€” Anthropic Β· OpenAI Β· Azure Β· Vertex Β· Bedrock Β· Mistral Β· Groq Β· Cerebras Β· xAI Β· OpenRouter Β· Vercel AI Gateway Β· Hugging Face Β· Kimi Β· MiniMax Β· Z.AI Β· DeepSeek **Custom** β€” any OpenAI-/Anthropic-/Google-compatible endpoint via `~/.cave/agent/models.json`. ### πŸ”Œ MCP, hooks, skills, commands β€” Claude Code-compatible Authoring formats are a **superset** of Claude Code's β€” paste your existing config, it works. | Claude Code | Caveman | Notes | |---|---|---| | `~/.claude/settings.json` | `~/.cave/settings.json` | Hooks identical (run as observers, never block) | | `~/.claude/commands/*.md` | `~/.cave/commands/*.md` | Frontmatter superset | | `~/.claude/skills//SKILL.md` | `~/.cave/skills//SKILL.md` | Identical | | `~/.claude/agents/.md` | `~/.cave/agents/.md` | Frontmatter superset | | `.mcp.json` | `.mcp.json` | Same path, no change | MCP transports: stdio Β· Streamable HTTP Β· in-process. OAuth 2.1 + PKCE; tokens in OS keychain. ```bash caveman mcp add # add a server caveman mcp doctor # health-check + tool listing caveman mcp-server # run caveman itself as an MCP server (Codex-compatible) ``` ### 🧠 Memory via cavemem Persistent memory delegated to [cavemem](https://github.com/JuliusBrussee/cavemem) (MIT, hybrid BM25 + local vectors). Agent has two native tools β€” `memory_search` and `memory_save`; relevant recall is auto-injected each turn. ```bash /memory search "auth migration" /memory consolidate # cluster recent observations into semantic facts /memory sync --from claude # import Claude Code's MEMORY.md ``` ### πŸ› οΈ Recipes Declarative multi-step YAML workflows at `~/.cave/recipes/*.yaml`. Ten built in: `accessibility-audit` Β· `add-feature-flag` Β· `add-tests` Β· `bump-deps` Β· `extract-component` Β· `migrate-deps` Β· `migrate-to-biome` Β· `port-to-typescript` Β· `release` Β· `seo-audit`. ```bash /recipe run add-tests src/auth.ts ``` ### πŸ–₯️ Daemon ```bash caveman serve --port 39245 # start the daemon caveman attach --host localhost:39245 # attach a TUI ``` Sessions live in SQLite and survive SSH drops. Prepend `&` to any prompt to dispatch to a remote `caveman worker`. ### βš™οΈ CLI flags | Flag | Description | |---|---| | `-c` / `-r` | Continue / browse-resume session | | `-p`, `--print` | Non-interactive: print and exit | | `--mode json\|rpc` | Structured output modes | | `--provider` / `--model` | Provider name / model ID (`:` suffix ok) | | `--thinking ` | `off`Β·`minimal`Β·`low`Β·`medium`Β·`high`Β·`xhigh` | | `--architect` / `--editor ` | Architect/editor split | | `--tools ` | Enable specific tools | | `--no-tools` | Disable all built-in tools | | `--extension ` | Load an extension | | `--no-extensions` | Disable extension discovery | ### πŸ“‹ Slash commands (in TUI) | Command | Description | |---|---| | `/plan` | Toggle plan mode (read-only exploration) | | `/act` | Execute a saved plan | | `/caveman [level]` | Adjust token compression (`lite`Β·`full`Β·`ultra`Β·`off`) | | `/login`, `/logout` | OAuth authentication | | `/model` | Switch models | | `/settings` | Configure theme, thinking, compaction | | `/resume` | Browse and resume sessions | | `/tree` | Navigate session history | | `/checkpoint`, `/rollback N` | Git-like version control | ### πŸš€ Subcommands | Command | Description | |---|---| | `caveman goal start ""` | Autonomous Ralph-style loop | | `caveman goal resume [id] [--force]` | Resume a paused goal | | `caveman goal status [id]` | Show goal state and ledger | | `caveman goal cancel [id]` | Mark goal as cancelled | | `caveman goal list` | List all goals in project | | `caveman mcp ` | Manage MCP servers | | `caveman watch [paths]` | File watcher for `// cave!` triggers | | `caveman exec [flags] ""` | Non-interactive CI mode | | `caveman plugin ` | Plugin marketplace | | `caveman run-recipe ` | Run YAML workflow recipes | | `caveman rollback N` | Revert to checkpoint N | | `caveman models ` | Manage model registry | | `caveman serve` / `attach` | Daemon mode | Env: `ANTHROPIC_API_KEY` Β· `OPENAI_API_KEY` Β· `CAVE_CODING_AGENT_DIR` (config dir) Β· `CAVE_CACHE_RETENTION=long` (extended prompt cache).
--- ## SDK ```typescript import { AuthStorage, createAgentSession, ModelRegistry, SessionManager } from "@juliusbrussee/caveman-code"; const { session } = await createAgentSession({ sessionManager: SessionManager.inMemory(), authStorage: AuthStorage.create(), modelRegistry: ModelRegistry.create(AuthStorage.create()), }); session.on("message", (msg) => console.log(msg.role, msg.text)); await session.prompt("Refactor src/auth.ts to use the new TokenStore."); ``` Talk to a running daemon over HTTP / WS via [`@juliusbrussee/caveman-sdk`](packages/sdk). [API reference β†’](docs/api.md) TypeScript monorepo, 9 packages β€” full layout in [CLAUDE.md](CLAUDE.md). --- ## Acknowledgements **Caveman Code is a heavy fork of [pi-code](https://github.com/badlogic/pi-code) by [Mario Zechner](https://github.com/badlogic).** We track upstream and contribute fixes back where generally useful. | From `pi-code` (upstream) | Caveman Code's own work | |---|---| | Agent runtime Β· MCP scaffolding Β· provider OAuth Β· repo map Β· slash-command parser Β· settings manager Β· skills loader Β· edit-format renderers Β· TUI components | Caveman Mode (4-layer compression) Β· goal loop Β· plan mode Β· cavemem integration Β· `/tree` session branching Β· architect/editor split Β· honest-bench harness | Also indebted to [Aider](https://aider.chat) (repo map + edit-format-per-model), [Claude Code](https://www.anthropic.com/news/claude-code) (settings/commands/skills/agents/`.mcp.json` formats β€” adopted verbatim, then extended), [Codex](https://github.com/openai/codex) (cave-as-MCP-server), [RTK](https://github.com/rtk-ai/rtk) (optional bash-output compression layer), and [Biome](https://biomejs.dev) (single-binary lint/format). Missing credit? [Open an issue](https://github.com/JuliusBrussee/caveman-code/issues) β€” we'll fix it fast. --- ## License MIT Β© [Julius Brussee](https://github.com/JuliusBrussee). Forked from [pi-code](https://github.com/badlogic/pi-code) (MIT Β© Mario Zechner).
[Issues](https://github.com/JuliusBrussee/caveman-code/issues) Β· [Releases](https://github.com/JuliusBrussee/caveman-code/releases) Β· [Changelog](CHANGELOG.md) Β· [Docs](docs/index.md) Caveman no waste token. Caveman ship.