Public Caveman docs
These pages cover the public, local Caveman stack: the compression engine, standalone proxy, CLI, SDKs, MCP tools, browser extension, memory, kit, and shrink tools. Everything here builds from the public source in this repo, runs on your machine, and labels local numbers as inferred.
The caveman skill changes how an agent answers. The stack documented here changes what an agent sends: tool output, logs, code, diffs, search results, memory recall, and tool catalogs can be compressed before they reach a model.
The public rule is simple: local, single-operator, BYOK tools report inferred results. They do not certify savings, do not claim hosted rollout proof, and do not need an account.
Honesty rule
Offline Caveman never claims verified savings. Ratios come from local counting and are labeled inferred. They are not projected to a month and not presented as proof of saved spend. Read the honesty rules →
Start here
Install the skill, compress a payload, and wrap an agent in five minutes.
5 minHow engine, proxy, CLI, SDKs, and MCP tools fit together.
Why local output stays inferred, recoverable, and conservative.
MIT packages, BSL packages, and the hosted-service restriction.
What's in the box
Each public package has one job and its own license.
| Component | What it does | License |
|---|---|---|
| Compression engine | Detects content type and routes it to a safety-classed compressor | BSL 1.1 |
| Proxy | Base-URL-swap reverse proxy that meters truthful spend | BSL 1.1 |
cave CLI | Builds local binaries, wraps agents, delegates to the proxy and engine | MIT |
| TypeScript SDK · Python SDK | The same gateway contract, in two languages | MIT |
| MCP server | Compression and retrieval as Model Context Protocol tools | BSL 1.1 |
| Cavemem · Cavekit · Shrink | Local memory, provenance UI, and tool-catalog compression | mixed |
| Browser extension | Caveman Mode in the chat box of ChatGPT, Claude, and Gemini | MIT |
The number
A committed tool-output JSON fixture currently compresses like this:
16,0981,091tok−93%inferredSixteen thousand inferred tokens down to about eleven hundred. Dropped detail is recoverable through a content-addressed handle. This is a local engine measurement, not a billing claim.
Install names aren't live yet
Public binaries and packages build from source here. Do not assume npm, PyPI, Docker, or Homebrew names work until they resolve to this project from a clean machine. The live one-line install is the skill: curl -fsSL …/install.sh | bash.