# Caveman > Caveman is a token-efficiency stack for AI agents: an open-source output-compression skill (74k+ GitHub stars), a local proxy that compresses eligible context with byte-exact recovery, TypeScript and Python middleware for local tool-result compression, and Caveman Cloud for spend analysis, evaluations, and agent investigations. Teams can connect native LiteLLM traces while keeping their existing inference gateway. Anyone can sign up for Caveman Cloud at https://app.caveman.so/signup. Free is for one person and needs no card; Team is for a whole team and starts with a 7-day free trial; plans at https://caveman.ac/pricing. The local skill, proxy, and extension are available now; middleware is available in alpha. ## When to use Caveman Reach for Caveman when the job is about **what an agent's tokens cost, and proving a change actually made them cheaper**. Specifically: - **Cut an agent's output tokens** — install the open-source skill so a coding agent answers tersely. Measured anchor: 65% fewer output tokens across 10 prompts, with code, commands and errors byte-for-byte exact. Start: `npx skills add JuliusBrussee/caveman -g` - **Compress context an agent already sends** — tool output, logs, JSON, tables, diffs, search results. Run `caveman wrap `; originals are stored locally and are always recoverable. No account required. - **Find out where AI spend actually goes** — per member, per key, per workflow, per model, priced from provider-reported usage against the public catalog. Use the Caveman Platform control API. - **Keep LiteLLM and add Caveman Platform** — export native OpenTelemetry traces for usage analysis, debugging, and investigations. [Connect LiteLLM](https://caveman.ac/solutions/litellm). - **Apply an optimization safely** — caching hints, compression, or model routing behind record → replay → shadow → canary → active gates, with automatic rollback on regression. - **Prove a saving to a finance owner** — the verified ledger only books provider-causal evidence, signed with Ed25519. It starts at $0.00 and stays there until a change is live on real traffic. - **Compress tool results in your own app** — Caveman Middleware adds local compression and original recovery to supported TypeScript and Python frameworks. Inference stays with your provider. Alpha quickstarts: https://docs.caveman.so/docs/sdk/middleware Do **not** reach for Caveman when you need an inference provider, a model, a vector database, or a general-purpose observability platform. LiteLLM integrations keep their existing provider traffic path. Exported traces travel to Caveman separately. Imported trace content is stored, redacted and encrypted, by default; an exporter can refuse with `x-cave-capture-content: false`. ## How an agent calls Caveman - Base URL: `https://api.caveman.so/api/v1` - Specification: [OpenAPI 3.1](https://caveman.ac/openapi.json) — 238 operations, each with a unique `operationId`, a description, and the scopes it requires. - Authentication: one access token, sent as `Authorization: Bearer `. Mint it with the RFC 8628 device-authorization grant — `POST /auth/device/code`, then poll `POST /auth/device/token` — or with `caveman login`. Metadata: [/.well-known/oauth-authorization-server](https://caveman.ac/.well-known/oauth-authorization-server). - Scopes: a token can be narrowed to a subset of the caller's role permissions (for example `trace:read_metadata`, `policy:draft`, `billing:read`). Authorization is the intersection of role and scope, so request only what you need. The full catalogue is in the OpenAPI `securitySchemes`. - Errors: every failure returns `{"error":{"type","code","message","request_id"}}`. Match on `error.code`; it is stable. `request_id` is echoed in the `x-cave-request-id` header. - Without credentials: `GET https://api.caveman.so/api/v1/system/version` and `GET https://api.caveman.so/api/v1/providers/catalog` are unauthenticated, as are `GET /health/live` and `GET /health/ready`. - Rate limits: authentication endpoints are per-IP rate limited; a limited request returns 429 with the same error envelope. ## Machine-readable endpoints - [/openapi.json](https://caveman.ac/openapi.json): the control-plane API surface (OpenAPI 3.1). - [/api](https://caveman.ac/api): JSON index of base URLs, auth, and the unauthenticated endpoints. - [/.well-known/oauth-authorization-server](https://caveman.ac/.well-known/oauth-authorization-server): RFC 8414 authorization server metadata. - [/.well-known/oauth-protected-resource](https://caveman.ac/.well-known/oauth-protected-resource): RFC 9728 protected-resource metadata for the API. - [/auth.md](https://caveman.ac/auth.md): the prose walkthrough for obtaining and using an access token. - [/pricing.md](https://caveman.ac/pricing.md): the free agent and SDK, Caveman Cloud and Enterprise, with a feature comparison. - [/mcp](https://caveman.ac/.well-known/mcp/server-card.json): the site MCP server (Streamable HTTP, no auth) — search, page fetch, product list, API lookup. - [/ask](https://caveman.ac/ask): NLWeb natural-language search over this site (JSON or SSE). - [/.well-known/ard.json](https://caveman.ac/.well-known/ard.json): Agentic Resource Discovery catalog of everything above. - [/.well-known/agent-skills/index.json](https://caveman.ac/.well-known/agent-skills/index.json): the Caveman SKILL.md for coding agents. - [/products/llms.txt](https://caveman.ac/products/llms.txt) and [/developers/llms.txt](https://caveman.ac/developers/llms.txt): scoped indexes. - [/sitemap.xml](https://caveman.ac/sitemap.xml): every public page. - [/schemas/eval-case.schema.json](https://caveman.ac/schemas/eval-case.schema.json): published contract JSON Schemas (`$id` targets for eval cases, policies, receipts, plans and traces). Most pages on this site also serve a Markdown representation. Send `Accept: text/markdown`, or append `.md` to the path; a page without one answers 406 rather than mislabelling its HTML. ## Documentation Full documentation for the open stack is on its own origin, https://docs.caveman.so. It is readable without HTML: every page is also Markdown at its URL plus `.md`, or by sending `Accept: text/markdown` to the page itself. - [Python and TypeScript](https://docs.caveman.so/docs/sdk): choose middleware, thin SDKs, or the proxy. - [Framework middleware](https://docs.caveman.so/docs/sdk/middleware): local tool-result compression, compatibility, recovery, and deployment. - [Documentation](https://docs.caveman.so): the skill, the compression engine, and cavemem. - [Quickstart](https://docs.caveman.so/docs/quickstart): install the skill, then the local tools. - [How numbers are counted](https://docs.caveman.so/docs/counting): what `inferred` means, and why nothing local says `verified`. - [Licensing](https://docs.caveman.so/docs/licensing): Apache-2.0 and MIT licences for the local tools. - [Docs index for machines](https://docs.caveman.so/llms.txt): that site's own llms.txt. - [Docs routing index](https://docs.caveman.so/llms-index.json): every page with headings, anchors and licences. ## Products - [Caveman Skill](https://caveman.ac/products/caveman): the open-source output-compression skill for Claude Code and 30+ agents. - [Caveman Proxy](https://caveman.ac/products/caveman-proxy): recoverable local context compression for agents you already run. - [Caveman Middleware](https://caveman.ac/products/caveman-middleware): Local tool-result compression for existing TypeScript and Python agents. Available in alpha. - [Caveman Browse](https://caveman.ac/products/caveman-browse): token-efficient browser automation with byte-exact recovery. - [Caveman Platform](https://caveman.ac/products/platform): spend analysis, evaluations, and investigations, with native LiteLLM trace support. - [CaveGemma](https://caveman.ac/products/cavegemma): Caveman compression fine-tuned into Gemma's weights. ## Company - [About](https://caveman.ac/about): what Caveman is, who builds it, and how it counts. - [Contact](https://caveman.ac/contact): every route in, including security reports. - [Developers](https://caveman.ac/developers): the local tools and where data goes. - [Enterprise](https://caveman.ac/enterprise): governance, deployment models, verified evidence. ## Guides Plain answers to the questions people ask about agent token costs. Each page is also Markdown at its URL plus `.md`. - [How to cut Claude Code costs](https://caveman.ac/news/how-to-cut-claude-code-costs): seven levers, the measured number behind each, and where they lose. - [What Claude Code bills you for](https://caveman.ac/news/what-claude-code-bills-you-for): the four token counters and why input dominates. - [MCP servers cost tokens before you type](https://caveman.ac/news/mcp-tool-overhead-in-claude-code): measure tool-schema overhead and bring it down. - [How Caveman works with LiteLLM](https://caveman.ac/news/caveman-and-litellm): native platform traces, optional model routing, and local compression. - [Headroom vs Caveman, measured](https://caveman.ac/news/headroom-vs-caveman): 54 runs, exact-answer gate, 33.2 percent against 6.7. - [Benchmarking Sonnet 5.5](https://caveman.ac/news/benchmarking-sonnet-5-5): 48 code-graded tasks at every effort level, Sonnet 5.5 against Sonnet 5, and where the bill does not move. - [Does the Caveman skill save money?](https://caveman.ac/news/does-the-caveman-skill-save-money): when it wins, when it loses, how to check. - [Cursor, Codex CLI and Gemini CLI costs](https://caveman.ac/news/cut-token-costs-in-cursor-codex-and-gemini-cli): the install for each agent and the meters where tokens do not matter. - [How to measure a token optimization](https://caveman.ac/news/how-to-measure-agent-token-savings): paired tasks, provider counters, a correctness gate, four labels. ## Comparisons and switching guides - [Compare Caveman](https://caveman.ac/compare): choose by gateway, compression, routing, or observability needs. - [Caveman guides](https://caveman.ac/guides): implementation steps and measurement methods. - [Switching guides](https://caveman.ac/switch): setup, validation, and rollback for your current stack. - [Caveman vs AgentOps: agent replays plus token compression](https://caveman.ac/compare/agentops): Comparisons. AgentOps records and replays agent sessions and tracks cost. Caveman Middleware shrinks tool output before each model call. How they fit and what a span shows. - [Caveman vs Arize Phoenix: traces, evals and compression](https://caveman.ac/compare/arize-phoenix): Comparisons. Arize Phoenix traces and evaluates LLM apps. Caveman Middleware shrinks tool output before the model call. How they fit, and which copy a Phoenix span records. - [Caveman vs Bifrost: fast AI gateway, fewer tool tokens](https://caveman.ac/compare/bifrost): Comparisons. Bifrost adds microseconds to each LLM call. Caveman Middleware cuts the tool-result tokens inside the call. What each does and how to run both together. - [Caveman vs Braintrust: evals plus token compression](https://caveman.ac/compare/braintrust): Comparisons. Braintrust scores and traces your AI app. Caveman Middleware shrinks the tool output your model calls send. How they fit and how to prove quality held. - [Caveman vs Cloudflare AI Gateway: add compression](https://caveman.ac/compare/cloudflare-ai-gateway): Comparisons. Cloudflare AI Gateway gives you caching, rate limits and logs at the edge. Caveman Middleware compresses agent tool output before it gets there. Use both. - [Caveman vs Headroom: context compression compared](https://caveman.ac/compare/headroom): Comparisons. Headroom and Caveman both compress agent context by content type and keep originals recoverable. Compare recovery, store lifetime, integrations and license. - [Caveman vs Helicone: LLM logs plus token compression](https://caveman.ac/compare/helicone): Comparisons. Helicone logs, caches and routes LLM calls through its AI gateway. Caveman Middleware shrinks tool output before the call leaves your app. How the two fit. - [Caveman vs Langfuse: tracing plus token compression](https://caveman.ac/compare/langfuse): Comparisons. Langfuse traces, evaluates and prices your LLM calls. Caveman Middleware shrinks the tool output those calls send. How to run both and check quality held. - [Caveman vs LangGraph: compress tool results in LangGraph](https://caveman.ac/compare/langgraph): Comparisons. Keep LangGraph and add Caveman Middleware through the LangChain adapter: shrink large tool results in create_agent graphs, keep originals, recover on demand. - [Caveman vs LangSmith: traces, evals, fewer tokens](https://caveman.ac/compare/langsmith): Comparisons. LangSmith traces and evaluates LangChain and other agents. Caveman Middleware cuts the tool-output tokens they send. What each does and how they work together. - [Caveman vs LiteLLM: tool output compression in LiteLLM](https://caveman.ac/compare/litellm): Comparisons. Keep LiteLLM. Caveman Middleware runs inside it as a native callback and shrinks large tool results before LiteLLM sends them, with originals recoverable. - [Caveman vs LLMLingua: prompt compression compared](https://caveman.ac/compare/llmlingua): Comparisons. LLMLingua prunes low-value tokens with a small model. Caveman compresses agent tool output by format and keeps every original recoverable. When to use each. - [Caveman vs Martian: model gateway, routing, compression](https://caveman.ac/compare/martian): Comparisons. Martian Gateway gives one API over 200+ models, backed by routing research. See how it compares with Caveman Router and how Caveman compression runs through it. - [Caveman vs Mastra: token compression for Mastra agents](https://caveman.ac/compare/mastra): Comparisons. Keep Mastra and add Caveman Middleware: withCavemanMastra wraps your agent, shrinks large tool results before each model call, and keeps originals recoverable. - [Caveman vs Not Diamond: AI model router comparison](https://caveman.ac/compare/not-diamond): Comparisons. Not Diamond routes each prompt or agent step to the best-value model. Compare it with Caveman Router, and see how Caveman compression cuts tokens on any route. - [Caveman vs OpenRouter: compression and auto routing](https://caveman.ac/compare/openrouter): Comparisons. OpenRouter gives one API for hundreds of models plus an Auto Router. Caveman Middleware cuts the tool-output tokens you send through it. What each one does. - [Caveman vs Portkey: AI gateway plus tool-token compression](https://caveman.ac/compare/portkey): Comparisons. Portkey governs and observes your LLM traffic. Caveman Middleware shrinks large tool results before requests reach it. How they fit, and when to add it. - [Caveman vs PromptLayer: prompt registry plus compression](https://caveman.ac/compare/promptlayer): Comparisons. PromptLayer versions, ships and evaluates prompts. Caveman Middleware shrinks the tool output around them. How they fit, and which copy PromptLayer logs. - [Caveman vs Pydantic AI: token compression for agents](https://caveman.ac/compare/pydanticai): Comparisons. Keep Pydantic AI and add Caveman Middleware as a capability: CavemanCapability shrinks large tool returns before each model request, originals recoverable. - [Caveman vs RouteLLM: open-source LLM router compared](https://caveman.ac/compare/routellm): Comparisons. RouteLLM is an open-source framework that routes between a strong and a weak model. Compare it with Caveman Router, and add Caveman compression to routed calls. - [Caveman vs RTK (Rust Token Killer): which to use](https://caveman.ac/compare/rtk): Comparisons. RTK filters shell command output before your coding agent reads it. Caveman compresses every tool result and keeps originals recoverable. Where each one wins. - [Caveman vs Vercel AI Gateway: fewer tokens per call](https://caveman.ac/compare/vercel-ai-gateway): Comparisons. Vercel AI Gateway gives one key, budgets and fallbacks across 200+ models. Caveman Middleware wraps the AI SDK model to shrink tool output. How they fit. - [Caveman vs Vercel AI SDK: tool-result compression](https://caveman.ac/compare/vercel-ai-sdk): Comparisons. Keep the Vercel AI SDK and add Caveman Middleware: a native withCaveman adapter that shrinks large tool results before each model call, originals recoverable. - [How to evaluate an AI agent optimization before rollout](https://caveman.ac/guides/agent-evaluations): Guides. Build an acceptance test that a cheaper but subtly wrong answer still fails. Write the rejections first, hold back tuning cases, count retries, read the losing runs. - [Agent observability: join a trace to money and to finished work](https://caveman.ac/guides/agent-observability): Guides. Your tracer counts calls; only your app knows the job finished. Stamp a task ID and a verdict on every call, reconcile one hour, then read cost per completed task. - [Add Caveman Middleware to your existing agent](https://caveman.ac/guides/agent-sdk-migration): Guides. Set up local tool-result compression and original recovery in a TypeScript or Python application without replacing its framework. - [How to choose an AI gateway for agents](https://caveman.ac/guides/choose-ai-gateway): Guides. A decision path instead of a feature matrix. Name the one problem you have now, key sprawl, model access, spend limits, caching or context size, then buy for that. - [Set up Caveman with Claude Code, Codex, and Gemini CLI](https://caveman.ac/guides/coding-agent-setup): Guides. The skill and the proxy are two separate installs. Put the skill in for shorter replies, the proxy in for smaller input context, then test both on one real coding task. - [AI gateway migration: a reversible test plan for agent traffic](https://caveman.ac/guides/gateway-migration): Guides. Move agent traffic to a new gateway without betting the product on it. Run both paths, diff the request shapes that break, cut over one caller, keep rollback tested. - [Cut the MCP token overhead you pay on every request](https://caveman.ac/guides/mcp-token-overhead): Guides. MCP tool definitions ride along on every turn whether you use them or not. Measure that floor with a one word prompt, then cut it without breaking tool selection. - [How to measure AI agent cost per completed task](https://caveman.ac/guides/measure-agent-cost): Guides. Count every attempt, including the failed ones, into one number. Set the task boundary, record the right fields per attempt, and divide by the tasks that passed. - [When routing to a cheaper model actually saves money](https://caveman.ac/guides/model-routing): Guides. A cheaper model loses money two ways: it breaks a warm cache prefix, and a failed cheap attempt gets retried on the expensive one. Price both before you build a router. - [Prompt caching and compression: reduce agent cost without losing reuse](https://caveman.ac/guides/prompt-caching): Guides. Check cache reads before you shorten a prompt. How stable prefixes, cache writes and compression interact, and why cold and warm runs need separate numbers. - [What prompt compression does to your bytes, and how to check it](https://caveman.ac/guides/prompt-compression): Guides. Caveman stores the original before it sends a smaller view, and passes the original through whenever anything fails. Verify that yourself with one file and one cmp. - [How to reduce LLM costs in an agent that already works](https://caveman.ac/guides/reduce-llm-costs): Guides. Pick the one change worth testing first from your own usage data. A symptom to experiment map for caching, compression, tool output, model choice, and retries. - [Add Caveman to AgentOps: compress a CrewAI crew](https://caveman.ac/switch/agentops): Switching. Keep AgentOps recording your crew. Wrap one CrewAI agent with Caveman Middleware, compare two tagged AgentOps sessions, and roll back by removing one wrapper. - [Add Caveman to Arize Phoenix: trace and grade compression](https://caveman.ac/switch/arize-phoenix): Switching. Keep Arize Phoenix tracing your agent. Wrap it with Caveman Middleware, run one Phoenix experiment per mode, and check that quality held before you roll it out. - [How to add Caveman to Bifrost: step by step setup](https://caveman.ac/switch/bifrost): Switching. Keep Bifrost as your AI gateway and wrap one agent's client with Caveman Middleware to send fewer tool-result tokens. Setup, checks, and a one-line rollback. - [Add Caveman to Braintrust: run it as an Eval](https://caveman.ac/switch/braintrust): Switching. Add Caveman Middleware to a Vercel AI SDK agent logged to Braintrust, then run one Braintrust Eval in record and compress mode to check quality before shipping. - [Add Caveman to Cloudflare AI Gateway](https://caveman.ac/switch/cloudflare-ai-gateway): Switching. Wrap your OpenAI client with Caveman Middleware, keep the Cloudflare AI Gateway compat URL, and compare token counts in gateway analytics. Rollback included. - [Switch from Headroom to Caveman: step by step guide](https://caveman.ac/switch/headroom): Switching. Move a coding agent or a Vercel AI SDK app from Headroom to Caveman: free port 8787, swap the wrapper or adapter, check recovery, compare, and roll back. - [Add Caveman to Helicone: compress tool output](https://caveman.ac/switch/helicone): Switching. Keep your Helicone AI gateway and session logs. Wrap the OpenAI client with Caveman Middleware, compare two tagged sessions, and roll back in one line. - [Add Caveman to Langfuse: setup and quality check](https://caveman.ac/switch/langfuse): Switching. Keep Langfuse tracing and add Caveman Middleware to a Python agent, then run one Langfuse dataset experiment in record and compress mode to confirm quality. - [How to add Caveman Middleware to a LangGraph agent](https://caveman.ac/switch/langgraph): Switching. Add token compression to a LangGraph agent through LangChain middleware: install caveman-middleware, start the runtime, wrap create_agent, scope by thread_id. - [Add Caveman to LangSmith: setup and eval check](https://caveman.ac/switch/langsmith): Switching. Add Caveman Middleware to a LangChain or LangGraph agent traced in LangSmith, then compare a record and a compress experiment to confirm answers held up. - [How to add Caveman to LiteLLM: SDK, Router and proxy](https://caveman.ac/switch/litellm): Switching. Add the Caveman callback to LiteLLM step by step: start the runtime, wrap one agent's calls, confirm tool results shrink, and turn it off with one setting. - [Switch from LLMLingua to Caveman for tool output](https://caveman.ac/switch/llmlingua): Switching. Move agent tool-result compression from LLMLingua to Caveman Middleware in a LangChain app, keep LLMLingua on RAG passages, check recovery, and roll back fast. - [Use Caveman with Martian Gateway: compress tool output](https://caveman.ac/switch/martian): Switching. Keep your Martian Gateway key and base URL, wrap the OpenAI client with Caveman Middleware, and send fewer input tokens from tool output. Setup and rollback. - [How to add token compression to a Mastra agent](https://caveman.ac/switch/mastra): Switching. Add Caveman Middleware to an existing Mastra agent with withCavemanMastra: install, start the local runtime, wrap the agent, check the reports and roll back. - [Use Caveman with Not Diamond: add token compression](https://caveman.ac/switch/not-diamond): Switching. Keep Not Diamond choosing the model and wrap the provider call with Caveman Middleware so tool output costs fewer input tokens. Setup, checks and rollback. - [Add Caveman to OpenRouter: wrap the OpenAI client](https://caveman.ac/switch/openrouter): Switching. Keep your OpenRouter key, models and headers. Wrap the OpenAI client with Caveman Middleware, pin one model to measure fairly, then compare usage or roll back. - [How to add Caveman to Portkey without changing configs](https://caveman.ac/switch/portkey): Switching. Keep Portkey as your gateway and wrap one agent's OpenAI client with Caveman Middleware. Step by step setup, how to confirm it in Portkey logs, and rollback. - [Add Caveman to PromptLayer without touching prompts](https://caveman.ac/switch/promptlayer): Switching. Keep PromptLayer's registry, labels and logs. Call through a Caveman-wrapped OpenAI client, log both arms with tags, and score them in one PromptLayer Table. - [How to add token compression to Pydantic AI agents](https://caveman.ac/switch/pydanticai): Switching. Add Caveman Middleware to a Pydantic AI agent as one capability: install the extra, start the local runtime, add CavemanCapability, check reports, roll back. - [Use Caveman with RouteLLM: route, then compress](https://caveman.ac/switch/routellm): Switching. Keep RouteLLM choosing between your strong and weak model, and send the routed call through Caveman's LiteLLM adapter so tool output costs fewer tokens. - [RTK alternative: try Caveman shrink and the proxy](https://caveman.ac/switch/rtk): Switching. Compare RTK and Caveman on one real command, check exit codes and byte-exact recovery, then swap the shell hook or add the proxy. Includes a one-step rollback. - [Add Caveman to Vercel AI Gateway with the AI SDK](https://caveman.ac/switch/vercel-ai-gateway): Switching. Wrap your Vercel AI Gateway model with withCaveman, keep budgets and fallbacks, and compare input tokens in the gateway logs. Covers Functions and rollback. - [How to add token compression to the Vercel AI SDK](https://caveman.ac/switch/vercel-ai-sdk): Switching. Add Caveman Middleware to a Vercel AI SDK app in one wrap: install, start the local runtime, wrap streamText with withCaveman, read the reports, roll back. ## Legal Published by Caveman Labs, Inc.. Each is Markdown at its URL plus `.md`, and the frontmatter carries its version and status. Questions and privacy requests: contact@caveman.ac. - [Privacy Policy](https://caveman.ac/privacy.md): what personal data we collect, why, who receives it, how long we keep it and how to control it, for the website, Caveman Cloud, the CLI and local tools, and the browser extension. - [Terms of Service](https://caveman.ac/terms.md): the contract for Caveman Cloud and the website. - [What we collect](https://caveman.ac/data-use.md): the same facts as a table, by plan and by local tool. - [Cookie Policy](https://caveman.ac/legal/cookies.md): every cookie and browser storage key. - [Acceptable Use Policy](https://caveman.ac/legal/acceptable-use.md): what the service may not be used for. - [Sub-processors](https://caveman.ac/legal/subprocessors.md): who processes data for us, and where. - [Data Processing Agreement](https://caveman.ac/legal/dpa.md): GDPR Article 28 terms and transfer clauses. ## Optional - [News](https://caveman.ac/news): field reports on measurement and token economics. - [Labs](https://caveman.ac/labs): research write-ups and benchmark methodology. - [CaveBench](https://caveman.ac/cavebench): savings at held quality, cost per correct task. - [GitHub](https://github.com/JuliusBrussee/caveman): the open-source skill, extension and benchmarks.