> **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.
---
## π₯ 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.