# Caveman's three license tracks, its BSL-1.1 proxy runtime, and the version gap between the installer and the CLI

> Caveman compresses agent text in three different places: a rule file the agent reads, a local proxy that sits between the agent and the provider, and a middleware for your own code. Those three surfaces carry three different licenses, and the root npm package is only the installer.

**JuliusBrussee/caveman** — Caveman rewrites verbose command output into a compact format so Claude Code can spend fewer tokens on routine tool results.

- Repository: https://github.com/JuliusBrussee/caveman
- Website: https://caveman.so/
- Stars: 108,342 · Forks: 6,276
- Language: JavaScript
- License: MIT
- Published: 2026-08-08 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/juliusbrussee-caveman

## Three install paths, three licenses, and the free forever badge covers the smallest one

The Quick Start hands out three products and gives each a different license line. The rule file is MIT, free forever. The proxy is MIT CLI, BSL-1.1 runtime. The middleware is MIT client, alpha today. The root agrees, in a way that is easy to skim past: LICENSE, LICENSE.BSL, LICENSING.md and TRADEMARKS.md all sit at the top level. So the piece that is free forever is the piece that only changes how the agent talks, and the piece that rewrites everything crossing your network is the one under a Business Source License with a trademark file next to it. Consequence for a reader: the badge you see next to the free one-command install does not describe the runtime that `npm install -g @caveman-ai/cli` puts between you and the provider. Read LICENSING.md and TRADEMARKS.md before the proxy, not after.

## The proxy sits on the path to the provider, and keeps a copy of what it squeezes

The big rock is described plainly: it runs on your machine, between your agent and the AI provider, and shrinks what the agent reads before every call. That placement is the whole mechanism and the whole exposure. The container image is distroless static, and the build comment names the reason it carries CA roots, outbound provider TLS, which means the binary is terminating a connection you would otherwise terminate elsewhere. The same paragraph promises a backup, every squeezed byte gets a backup so the agent can pull the original back, and the image creates a /data directory for exactly that. Consequence: the savings are paid for with a local store of your logs, test output, JSON, diffs and search results, on a process that sees every prompt and answer. Nothing in the visible text says what it logs or how to audit a rewrite.

## Savings are quoted in tokens, and your bill is not counted in tokens

The unit of the claim is explicit: a token is what AI billing counts, roughly three quarters of a word. The worked example is a React re-rendering diagnosis that reads 69 tokens in normal prose and 19 after the rewrite, and the point being made is that the diagnosis and the fix, useMemo, are identical. One example is one example, and the project's own larger claims are attributed elsewhere: an Adobe Research paper named CAVEWOMAN measured caveman-style output cutting cost 1.4 to 2.4x, up to 3x, and a JetBrains test on 86 real coding tasks is quoted as costing you nothing measurable in quality. The Go module requires tiktoken-go/tokenizer v0.8.0, so the counting is done in code. Consequence: every ratio here is a token ratio. Turning one into a saving on your invoice depends on the provider's tokenizer and rates, which the visible text does not give you.

## Code, commands, file paths and error messages are carved out of the rewrite

There is an exclusion list, and it is the most useful paragraph in the file: code, commands, file paths, and exact error messages never get cavemanned, only the prose around them does. Security warnings and are you sure? confirmations come back in full sentences on their own, then caveman resumes. The stated principle is that the skill makes the mouth smaller, not the brain. That is reassuring, but it is a promise in prose, and a promise about an output filter is exactly the kind of thing you want a test for. The repository does carry tests/, benchmarks/ and evals/ directories, and the visible text does not say which of them assert these exclusions. Consequence: any transcript you keep will mix two registers, full sentences where it matters and fragments everywhere else, and a reviewer skimming a log has to know that the fragments are the intended form.

## The root package is the installer, and it depends on a CLI a major version behind it

The package.json at the root is named caveman-installer, carries version 2.7.0, exposes a single binary at ./bin/install.js, declares engines node >=18, and depends on @caveman-ai/cli at ^1.1.0. The release list agrees: v2.7.0 and bin-v1.1.7 both landed on 2026-09-15. Two version numbers for one project, and the one that does the work is on the 1.x line while the installer wrapping it is on 2.x. The Node floor disagrees with the docs as well, since the manifest says >=18 while the full installer section says it needs Node.js 22.13+. Consequence: a version string you see in a log does not tell you which piece produced it, and an install on Node 18 or 20 can pass the engines check and still miss the documented requirement for the full installer.

## npm test runs two JavaScript suites and none of the Go binary

The test script is short enough to read in one line.

```json
"test": "node --test --test-force-exit --test-concurrency=2 tests/installer/*.test.mjs tests/hooks/*.test.mjs"
```

That covers the installer and the hooks, and there is a separate Windows compatibility script at scripts/test-windows-compat.mjs. Meanwhile the repository also holds engine/, proxy/, rewriter/, shrink/, mem/, benchmarks/ and evals/, and a Go module pinned at go 1.26.5 whose dependency list includes tiktoken, go-tree-sitter, a JSON experiment library, SQLite and a Chrome DevTools Protocol driver. The Go side is where the actual compression lives, and it is built as a separate binary, ./proxy/cmd/caveman-proxy. Consequence: a passing npm test is not evidence about the proxy, and running the published test command tells you nothing about whether your logs are being rewritten correctly.

## A bind mount does not inherit uid 65532, and the image has no shell to fix it

The Dockerfile spells out the ownership trap in a comment. The runtime stage is distroless static-debian12:nonroot, which already runs as uid 65532, and the build creates an empty, correctly-owned /data so that a named or anonymous volume inherits that uid. The next line is the warning: a BIND mount does NOT inherit it, and the instruction is to chown the host directory. The rest of the image is described as no shell, no package manager, nothing to exploit, which is good for attack surface and bad for recovery. Consequence: `docker run` with a host directory mapped into /data gives you a root owned host folder and a process that cannot write to it, and you cannot repair it from inside the container. Chown the host directory to 65532 before the first run, not after the first failed write.

## A binary you build yourself reports its version as dev

The build stamps the version through an argument, and the default is not a version. The Dockerfile declares ARG VERSION=dev and passes -ldflags "-s -w -X main.version=$VERSION" when linking, which writes into `var version = "dev"` in proxy/cmd/caveman-proxy/main.go. The build also sets -buildvcs=false, and the comment gives the reason: .dockerignore keeps .git out of the build context, so there is no VCS information for the toolchain to embed. CGO_ENABLED=0 and -trimpath are set to match scripts/build-release-binaries.mjs, and the build stage cross-compiles from $BUILDPLATFORM so multi-arch images need no QEMU. Consequence: compile this yourself without passing VERSION and the binary will tell you it is dev, with no commit hash behind that claim, so when two of your own builds behave differently you have no built-in way to tell which is running.

## Conclusion

Reach for Caveman when token cost on routine tool output is a real line on your bill and you are willing to route provider traffic through a process you operate yourself. Skip the proxy if a Business Source License on the runtime is a problem for your deployment, and stay on the rule file alone if you only want the writing style change. Before installing, work out which of the three surfaces you actually need, note that the middleware is labelled alpha, and check the Node version against the documented installer floor rather than the manifest floor.

## FAQ

### how to use caveman

Three surfaces are documented: a rule file that shrinks what the agent says, a local proxy that shrinks what the agent reads, and a middleware for your own code. The rule file installs with npx skills add JuliusBrussee/caveman -g.

### how to install caveman in claude code

Three routes are shown: claude plugin marketplace add JuliusBrussee/caveman && claude plugin install caveman@caveman for the plugin, the full installer curl -fsSL piped to bash, or the global skills add. The full installer is documented as needing Node.js 22.13+.

### how to use caveman in codex

Codex is named both among the agents the rule file works in and in the skills-compatible group, where the documented command is npx skills add JuliusBrussee/caveman --skill '*' -a codex --yes -g. It is also one of the agent names the caveman CLI accepts after setup.

### how to use caveman in cursor

Cursor appears in the list of agents the rule file works in and again among the skills-compatible agents, so the skills add path is the one documented for it. The per-agent command list shown for the caveman CLI does not include cursor.

### how to use caveman in copilot

Copilot is one of the named agents the rule file is said to work in, inside a group counted as 30+ agents, and no per-agent wrapper command is documented for it. No install route beyond the global skills add and the full installer is given for Copilot.

## Sources

- [Official documentation](https://caveman.so/)
- [Official README](https://github.com/JuliusBrussee/caveman#readme)
- [Project repository](https://github.com/JuliusBrussee/caveman)
- [Release notes](https://github.com/JuliusBrussee/caveman/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/juliusbrussee-caveman