Caveman Code and the case for a coding agent that spends fewer tokens

A terminal coding agent that treats token spend as the budget

Caveman Code is a terminal coding agent whose central idea is that most of the tokens an agent burns are not needed. The project describes itself as the terminal coding agent that talks like a caveman and burns half the tokens doing it, and the claim it leads with is that the same model on the same task uses about half the tokens of Codex CLI.

The mechanism is visible in the README's side-by-side example. Asked why a component re-renders on every keystroke, an ordinary agent answers in about 290 tokens with a hedged opening and several paragraphs, and the README notes the remaining paragraphs in the original. The caveman version answers in 31 tokens: new object reference on each render, inline prop means a new reference means a re-render, wrap it in useMemo. Same answer, same model, and the README's argument is that the agent reads its own context back on every turn, so a cheaper answer to read compounds across a session.

That framing matters for who should use it. This is for people running agents where the context window is the constraint: long autonomous loops, CI steps, and any workflow where tool output floods the transcript. It is not a code generation quality project, and the README is candid that the pass rate is close to the comparison tool rather than better.

The primary language is TypeScript, the licence field on the repository says MIT, and the repository has no GitHub releases. The last push was on 2026-08-14.

Four compression layers aimed at two different token sinks

The engineering is in a table of four layers, and the useful framing is that they attack two separate sinks: what the model says and what the shell returns.

Caveman Mode handles the model reply. It asks for terse technical fragments with no filler and no hedging, and it has three levels, lite, full and ultra. Because it changes what the model produces, the saving lands on both the prompt and the reply.

Tool Budgets handle tool output, with per-tool line caps of 80 lines for bash, 300 for read and 120 for grep, plus ANSI stripping, blank-line collapse and semantic extraction of JSON and XML. The README quotes a cut of between 67 and 94 percent for this layer.

Read Dedup sits under it. Files are fingerprinted per session, so a re-read returns a stub rather than the bytes, and the README quotes 99 percent on repeats. In a loop where an agent re-reads the same file after every edit, that layer is the one that does the heavy lifting.

The fourth layer is optional and external. RTK, the Rust Token Killer, is a separate binary that pipes bash output through it before the output enters the context, and the README attributes the 60 to 90 percent figure there to RTK's own bench rather than to this project. A second fixture table in the README lists ten real tool outputs, from a 901 line git diff down to a 258 line docker inspect, and reports a 86 percent aggregate reduction.

The division of labour is what makes the design interesting. A prompt-level trick only shrinks what the model writes. Compressing what the shell returns addresses the part of the bill that usually dominates in a real session.

The MicroBench result, and what a single comparison cannot tell you

The proof section of the README reports a 25 task MicroBench run on 2026-05-18 with the gpt-5.5 model at xhigh reasoning. On fresh tokens, the caveman tool is reported at 524k against 1,010k for codex, which is the 1.93x figure. Pass rates are 14 out of 25 and 15 out of 25 respectively, and the README describes that gap as within one task.

The methodological claims are specific and unusual enough to check. It says there are no marketing-deck baselines, that each tool was spawned as a real child process, that each task was verified by a task-specific verify.sh, and that the raw CSV and per-task logs are published. The repository layout backs that up: a research directory with results, a README for methodology, and a tasks directory holding the 25 task prompts.

The reproduction command is a single line.

npx tsx research/evals/run-honest-bench.ts --tools caveman,codex   # reproduce in one command

Two cautions. First, this is one model, one reasoning level, one date and one 25 task suite, so the ratio is a measurement of that setup rather than a law. Second, and more important for an evaluator, token counts and pass rate are different axes. A tool that makes answers terser can also make them less complete, and the 14 against 15 result is the number to watch, since it is the price paid for the 1.93x.

Installing the package, and the binary it puts on your PATH

Installation is a global npm install, and the package is scoped.

npm install -g @juliusbrussee/caveman-code

It installs two binaries, caveman as the primary and caveman-code as an alias, and the README notes that either name works for the same command. Setting a provider key and launching looks like this.

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 are documented behind a collapsed section: pnpm, yarn and bun globals, a Docker image, and an OAuth login path. The Docker route mounts the working directory.

docker run --rm -it -v "$PWD:/work" ghcr.io/juliusbrussee/caveman-code:latest

The login path covers subscriptions rather than API keys, and the README lists Claude Pro, ChatGPT Plus, Copilot, Gemini and Antigravity, reachable from inside the running agent with /login.

There is one warning to take seriously, and the README puts it at the very top. This package installs a caveman binary that shadows the caveman CLI from the caveman repository, so you must uninstall one before installing the other. Two packages owning the same command name on the same PATH is a routine source of confusing behaviour, and since the active project now lives in the other repository, that collision is likely to be hit by anyone following the pointer at the top of the README.

Slash commands, plan mode and the goal loop

The daily surface is small. A prompt can be passed on the command line, piped in on standard input, or typed into the interactive TUI, where typing a slash opens the command list.

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 goal start "ship payments v2"   # autonomous Ralph loop

Three of those deserve attention. The -c flag continues the last session and -r browses and resumes sessions, so the tool keeps a session history rather than being a one-shot process. The /plan slash command is read-only, which is the sensible mode for exploration in an agent that can otherwise edit files. And goal start launches an autonomous Ralph loop, the named-iteration pattern where the agent works against a goal statement without a human in the loop.

The package also advertises 20 plus providers and an autopilot loop, and there is an SDK. A full reference for the slash commands lives at docs/reference/slash-commands.md, and the CI and headless install path is documented separately at docs/getting-started/installation.md, which is where to look if you are wiring this into a pipeline rather than a terminal.

Frozen in August 2026, with the idea moved to a wrapper

The status line at the top of the README is the most important fact for anyone planning around this package. Caveman Code is frozen as of August 2026 and is no longer in active development. It still installs and works, but the README says to expect no new features or fixes.

The direction of travel is stated too. The lesson moved into the caveman repository, where caveman wrap makes the agent you already use cheaper instead of replacing it. That is a meaningful change of approach. Caveman Code is a full coding agent that owns the loop, the TUI, the providers and the compression. caveman wrap is a layer that sits around an existing agent and cuts the tokens it burns. For a team that already standardised on another terminal agent, the wrapper is the smaller bet, and it is where the maintenance now is.

The two also collide by name, as noted earlier, because the frozen package still installs a caveman binary.

The repository shows the scale of what was built. It is an npm workspaces monorepo with packages for tui, ai, agent, coding-agent, sdk, mom, web-ui and pods, plus research, rfcs, registry, installers, scripts, docs, a Dockerfile, an install.sh and an install.ps1, and a.cave directory, and a Dockerfile that copies a docker-rootfs directory holding the extracted cave-linux-x64.tar.gz with theme, export-html and photon_rs_bg.wasm beside the binary. The repo also carries llms.txt, AGENTS.md, CLAUDE.md, biome.json and per-package build scripts, which is a lot of surface for a project that is now frozen.

The monorepo checks and the practical upgrade cost

Two details in package.json are worth knowing if you plan to build from source rather than install the tarball. The workspace list includes the packages plus several example extensions, one of them with dependencies, and the build script compiles each package in sequence: tui, ai, agent, coding-agent, sdk, mom, web-ui and pods. The check script is stricter than a plain type check, running biome with --write and --error-on-warnings, then tsgo --noEmit, then a browser smoke check script, and then the web-ui package check.

That means a contributor cannot just typecheck one package, and a fork inherits a formatter that rewrites files during check. For an install user none of this matters, which is the point: the published package is a consumer of this monorepo, not the other way round.

The Dockerfile in the repository is not the same artefact as the npm Docker image. It starts from debian:bookworm-slim, installs ca-certificates and git, copies docker-rootfs into /opt/cave, and symlinks the binary to /usr/local/bin/cave with the cave binary as the entrypoint. The comments explain that the binary and its companions must live together because the binary resolves theme, export-html and photon_rs_bg.wasm relative to its own executable path. If you are packaging this yourself, that coupling is the detail that breaks first.

The licence field on the repository says MIT, which is the simplest part of the decision. The upgrade cost is not the licence, it is the frozen branch and the name collision with the successor project.

Editorial conclusion

Caveman Code is worth looking at for engineers who run a coding agent in a loop where tool output dominates the context, especially in CI or headless runs where a smaller prompt is cheaper per turn, and for anyone who wants to see the compression techniques in isolation. It is the wrong choice for new work, because the README states the project is frozen as of August 2026 with no new features or fixes expected, and the package installs a caveman binary that shadows the one from the caveman repository. If you install it, verify the binary name collision before you install the other package, and read the MicroBench methodology in research/README.md before you treat the 1.93x figure as a general result.

Frequently asked questions

Official sources

1. Issues
2. JuliusBrussee/caveman-code on GitHub
3. License: MIT
4. Project website
5. README