docs.caveman.so
Documentation for the parts of Caveman you run yourself.
Caveman is an efficiency stack for AI agents. Four layers sit between an agent you already use and the bill it generates, and three of them run on your machine and are open. A second repository, the Agent SDK, is for the other case: writing an agent whose budget is declared rather than discovered. This site documents both, and says plainly what each can and cannot prove.
in one picture
What happens to a request
The skill shapes what the agent writes. The engine reduces what leaves. The dashed path is the part that makes the rest safe: anything the engine removed can be fetched back exactly.
get going
First three pages
everything there is
Two repositories and one hosted plane
Layers carry a rank and stack bottom to top. Nothing above a layer is required by the one below it, and the Agent SDK needs none of them.
- OverviewA set of instructions that changes how your agent spends tokens. No runtime, no proxy.
- caveman learnProfile a local agent session and rank what is actually eating the budget.
- caveman exploreRead a repository without dragging every file into context.
- Agent profilesThe registry of coding agents the skill knows how to configure.
- OverviewA loopback reverse proxy: point an agent at it, keep your provider key, and it shrinks what leaves.
- Wrap an agentLaunch Claude Code, Codex, Gemini CLI, and seven other agents through the local listener.
- ProvidersThe HTTP routes, credentials, and compatibility mounts the proxy forwards.
- ModesRecord, compress, and pixel, plus the evaluation modes the runtime accepts.
- ConfigureFeature flags, caveman.yaml, local storage, and how mode is chosen.
- SecurityLoopback only, BYOK, SSRF checks, and what stays on disk.
- The engineThe compressor the proxy calls, and the standalone binary behind it.
- CompressorsOne router per content shape: JSON, logs, code, diffs, search results, prose.
- Recoverable compressionWhy lossy stays honest: every removed byte can be fetched back.
- Token countingThe offline counter behind every ratio the engine reports.
- CLIThe command surface: compress, detect, learn, and agent setup.
- TypeScript SDKCompress payloads and read spend from Node.
- Python SDKThe same surface for Python agents.
- MCP serverExpose compression and recall as tools any MCP client can call.
- caveman-shrinkShrink command output before it reaches the model.
- caveman-browseRead web pages as compressed accessibility trees instead of raw HTML.
- OverviewBuild an agent that is efficient by construction.
- InstallBuild 0.2 from source, run doctor, and the gap with the npm 0.1 package.
- Create an agentThe initializer that writes a typechecking project with a starter eval graph.
- Define an agentagent(), context, output, filesystem, and subagents as one frozen definition.
- ToolsInput schemas, effect classes, timeouts, and what happens to a tool result.
- Run a turnrun, stream, receipts, budgets, and durable resume.
- Sandboxrequired, fixture, and host: where tool closures run, and what lock eligibility requires.
- MemoryLocal, opt-in, one-turn-behind recall. Never verified, never in the frozen prefix.
- CompactionA fail-closed ladder: recover, summarise, clamp, then stop. Only inside a declared budget.
- Programmatic toolsOne caveman_code cell instead of a large JSON tool catalog. Nested calls still go through the runtime.
- ConnectPaginated provider data through one stable tool. Fail closed. The daemon is not in this package.
- Evals and buildsProfile, search, freeze, holdout. Failed evals never produce a lock.
- AdaptersExact-pinned framework lanes. Presence is not a grant of execution.
the part worth reading twice
What the numbers are allowed to say
Every local tool reports inferred, meaning a per-run estimate computed on your machine. Nothing here can emit verified, and no setting changes that.
Local figures stay labelled inferred and are never multiplied into a monthly number.
On any error, unsupported input, or result that is not smaller, the original bytes are kept.
Every unknown case resolves toward doing less. Unknown mode means pass-through.
Nothing lossy is emitted until the original is stored and can be fetched back exactly.
for agents
This site is readable without a browser
Every page is also plain text. You do not need to parse the HTML, and there is no separate copy to go stale: the Markdown is generated from the same source the page renders from.
- /llms.txt
- Every page with a one-line summary, grouped by layer.
- /llms-full.txt
- The full text of the whole site in one file.
- /docs/proxy.md
- Any page as plain Markdown. Append .md to the path.
- /sitemap.xml
- Machine-readable index of everything that exists.
the fine print, up front
Licensing and telemetry
Which surfaces are MIT, which are BSL 1.1, and what that means for you.
What the CLI sends, what it never sends, and the three ways to turn it off.
The grader set used to check that compression did not change an answer.
The model price table every cost figure is read from.
The public repository. Everything documented here is in it.