# Caveman > Documentation for the open Caveman stack: the agent skill, the local proxy and its compression engine, cavemem, and the Agent SDK. What each part does, what it costs, and how every number is counted. Caveman is an efficiency stack for AI agents, in four layers. Skill (00) shapes what the agent writes. Proxy (01) is a loopback listener plus the engine it calls, which compresses payloads and keeps the originals recoverable. Memory (02) stores context so it is not resent. Cloud (03) is the managed plane and is the only paid layer. Layers 00 to 02 run on the reader's own machine and their source is public. The engine is not a separate product and has no top-level route. It is documented under the proxy. Two repositories, plus a hosted plane. github.com/JuliusBrussee/caveman holds the skill, the proxy and its engine, memory, and the CLI, SDK, MCP and standalone-command adoption surfaces: these make an agent you already run cheaper. github.com/JuliusBrussee/agent-sdk holds the Agent SDK, which is for building a new agent whose context, tools and budget are declared up front. Neither requires the other. Caveman Cloud is hosted and has no repository. Each `##` section below names which of the three it belongs to. Measurement vocabulary. These three words are fixed and are not interchangeable: - `inferred`: A local, per-run estimate computed on your own machine from an offline token counter. Every public Caveman tool emits this and nothing else. Not a saving, not a dollar figure, and never valid to multiply into a monthly or annual total. - `measured`: Traffic that was actually observed, rather than estimated from bytes. Not proof that a dollar was saved. Observing a request is not comparing it to its alternative. - `verified`: A saving confirmed against a real bill by a hosted rollout system that ran both arms of the comparison. No tool documented on this site can emit it. There is no configuration, flag or account tier that upgrades a local number to this. Every tool documented here emits `inferred`. None of them can emit `verified`, and no setting changes that. Local figures are never multiplied into a monthly total and never converted to money. How to read this site without HTML: - Append `.md` to any page URL, for example https://docs.caveman.so/docs/proxy.md - Or send `Accept: text/markdown` to the page URL itself and get the same thing back - https://docs.caveman.so/llms-full.txt is every page in one file - https://docs.caveman.so/llms-index.json is a machine index: headings, anchors, licences and last-changed dates Last changed: 2026-08-30T15:24:20+02:00 ## Start - [Overview](https://docs.caveman.so/docs): What Caveman is, which parts are open, which repository each one ships from. - [Quickstart](https://docs.caveman.so/docs/quickstart): Install the skill and compress a real payload in about five minutes. - [Architecture](https://docs.caveman.so/docs/architecture): The path a request takes through the stack, and where the open-core line falls. - [How numbers are counted](https://docs.caveman.so/docs/counting): Inferred against verified, per run against per month, and the four rules the code follows. ## 00 Skill Ships from https://github.com/JuliusBrussee/caveman. What the agent does before it calls out. - [Skill](https://docs.caveman.so/docs/skill) [MIT]: A set of instructions that changes how your agent spends tokens. No runtime, no proxy. - [caveman learn](https://docs.caveman.so/docs/skill/learn) [MIT]: Profile a local agent session and rank what is actually eating the budget. - [caveman explore](https://docs.caveman.so/docs/skill/explore) [MIT]: Read a repository without dragging every file into context. - [Agent profiles](https://docs.caveman.so/docs/skill/profiles) [MIT]: The registry of coding agents the skill knows how to configure. ## 01 Proxy Ships from https://github.com/JuliusBrussee/caveman. What the payload weighs when it leaves. - [Proxy](https://docs.caveman.so/docs/proxy) [BSL-1.1]: A loopback reverse proxy: point an agent at it, keep your provider key, and it shrinks what leaves. - [Wrap an agent](https://docs.caveman.so/docs/proxy/wrap) [BSL-1.1]: Launch Claude Code, Codex, Gemini CLI, and seven other agents through the local listener. - [Providers](https://docs.caveman.so/docs/proxy/providers) [BSL-1.1]: The HTTP routes, credentials, and compatibility mounts the proxy forwards. - [Modes](https://docs.caveman.so/docs/proxy/modes) [BSL-1.1]: Record, compress, and pixel, plus the evaluation modes the runtime accepts. - [Configure](https://docs.caveman.so/docs/proxy/configure) [BSL-1.1]: Feature flags, caveman.yaml, local storage, and how mode is chosen. - [Security](https://docs.caveman.so/docs/proxy/security) [BSL-1.1]: Loopback only, BYOK, SSRF checks, and what stays on disk. - [The engine](https://docs.caveman.so/docs/proxy/engine) [BSL-1.1]: The compressor the proxy calls, and the standalone binary behind it. - [Compressors](https://docs.caveman.so/docs/proxy/compressors) [BSL-1.1]: One router per content shape: JSON, logs, code, diffs, search results, prose. - [Recoverable compression](https://docs.caveman.so/docs/proxy/recoverable) [BSL-1.1]: Why lossy stays honest: every removed byte can be fetched back. - [Token counting](https://docs.caveman.so/docs/proxy/tokens) [BSL-1.1]: The offline counter behind every ratio the engine reports. ## 02 Memory Ships from https://github.com/JuliusBrussee/caveman. What you never have to send twice. - [Memory](https://docs.caveman.so/docs/memory) [MIT]: cavemem holds the context you would otherwise paste into every session. - [Recall and offload](https://docs.caveman.so/docs/memory/offload) [MIT]: Moving a heavy instruction file out of the prompt and into recall. ## Build with it Ships from https://github.com/JuliusBrussee/caveman. - [CLI](https://docs.caveman.so/docs/cli) [MIT]: The command surface: compress, detect, learn, and agent setup. - [TypeScript SDK](https://docs.caveman.so/docs/sdk/typescript) [MIT]: Compress payloads and read spend from Node. - [Python SDK](https://docs.caveman.so/docs/sdk/python) [MIT]: The same surface for Python agents. - [MCP server](https://docs.caveman.so/docs/mcp) [MIT]: Expose compression and recall as tools any MCP client can call. - [caveman-shrink](https://docs.caveman.so/docs/shrink) [MIT]: Shrink command output before it reaches the model. - [caveman-browse](https://docs.caveman.so/docs/browse) [BSL-1.1]: Read web pages as compressed accessibility trees instead of raw HTML. ## Agent SDK Ships from https://github.com/JuliusBrussee/agent-sdk. - [Overview](https://docs.caveman.so/docs/agent-sdk) [MIT]: Build an agent that is efficient by construction. - [Install](https://docs.caveman.so/docs/agent-sdk/install) [MIT]: Build 0.2 from source, run doctor, and the gap with the npm 0.1 package. - [Create an agent](https://docs.caveman.so/docs/agent-sdk/create) [MIT]: The initializer that writes a typechecking project with a starter eval graph. - [Define an agent](https://docs.caveman.so/docs/agent-sdk/define) [MIT]: agent(), context, output, filesystem, and subagents as one frozen definition. - [Tools](https://docs.caveman.so/docs/agent-sdk/tools) [MIT]: Input schemas, effect classes, timeouts, and what happens to a tool result. - [Run a turn](https://docs.caveman.so/docs/agent-sdk/run) [MIT]: run, stream, receipts, budgets, and durable resume. - [Sandbox](https://docs.caveman.so/docs/agent-sdk/sandbox) [MIT]: required, fixture, and host: where tool closures run, and what lock eligibility requires. - [Memory](https://docs.caveman.so/docs/agent-sdk/memory) [MIT]: Local, opt-in, one-turn-behind recall. Never verified, never in the frozen prefix. - [Compaction](https://docs.caveman.so/docs/agent-sdk/compaction) [MIT]: A fail-closed ladder: recover, summarise, clamp, then stop. Only inside a declared budget. - [Programmatic tools](https://docs.caveman.so/docs/agent-sdk/code) [MIT]: One caveman_code cell instead of a large JSON tool catalog. Nested calls still go through the runtime. - [Connect](https://docs.caveman.so/docs/agent-sdk/connect) [MIT]: Paginated provider data through one stable tool. Fail closed. The daemon is not in this package. - [Evals and builds](https://docs.caveman.so/docs/agent-sdk/build) [MIT]: Profile, search, freeze, holdout. Failed evals never produce a lock. - [Adapters](https://docs.caveman.so/docs/agent-sdk/adapters) [MIT]: Exact-pinned framework lanes. Presence is not a grant of execution. ## 03 Cloud Hosted. There is no repository to clone. What a fleet can put in front of finance. - [Cloud](https://docs.caveman.so/docs/cloud) [Commercial]: The managed plane: fleet visibility, spend attribution, and verified numbers. - [Model router](https://docs.caveman.so/docs/router) [Commercial]: One model id: classify the task, apply a cost tier, route to measured evidence, fall back to your baseline. ## Reference - [Licensing](https://docs.caveman.so/docs/licensing) [MIT]: Which surfaces are MIT, which are BSL 1.1, and what that means for you. - [Telemetry](https://docs.caveman.so/docs/telemetry) [MIT]: What the CLI sends, what it never sends, and the three ways to turn it off. - [Eval graders](https://docs.caveman.so/docs/evals) [MIT]: The grader set used to check that compression did not change an answer. - [Provider catalog](https://docs.caveman.so/docs/provider-catalog) [MIT]: The model price table every cost figure is read from. ## Optional - [Caveman](https://caveman.so): the product site, pricing, and the Cloud waitlist. - [Product index for machines](https://caveman.so/llms.txt): that site's own llms.txt. - [Source](https://github.com/JuliusBrussee/caveman): the public repository behind everything documented here.