# Caveman

> Caveman is a token-efficiency stack for AI agents: an MIT output-compression skill (74k+ GitHub stars), a local proxy that compresses eligible context with byte-exact recovery, a TypeScript agent SDK with per-run cost guards, and Caveman Cloud — a managed LLM gateway that attributes spend, applies eval-gated optimizations, and proves what it saved.

Caveman Cloud is in private development; the waitlist is open. The local skill, proxy, extension and SDK are usable today.

## 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 MIT 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: `curl -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.sh | bash`
- **Compress context an agent already sends** — tool output, logs, JSON, tables, diffs, search results. Run `caveman wrap <agent>`; 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 Cloud control API.
- **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.
- **Give a production agent a budget** — the Agent SDK declares tools, context and evals, and keeps a cheaper context plan only after the declared checks pass.

Do **not** reach for Caveman when you need an inference provider, a model, a vector database, or a general-purpose observability platform. Caveman sits beside your provider; it never replaces it, and prompts go from your machine straight to the provider you chose.

## How an agent calls Caveman

- Base URL: `https://api.caveman.so/api/v1`
- Specification: [OpenAPI 3.1](https://caveman.so/openapi.json) — 238 operations, each with a unique `operationId`, a description, and the scopes it requires.
- Authentication: one access token, sent as `Authorization: Bearer <token>`. 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.so/.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.so/openapi.json): the control-plane API surface (OpenAPI 3.1).
- [/api](https://caveman.so/api): JSON index of base URLs, auth, and the unauthenticated endpoints.
- [/.well-known/oauth-authorization-server](https://caveman.so/.well-known/oauth-authorization-server): RFC 8414 authorization server metadata.
- [/sitemap.xml](https://caveman.so/sitemap.xml): every public page.
- [/schemas/eval-case.schema.json](https://caveman.so/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.

## Products

- [Caveman Skill](https://caveman.so/products/caveman): the MIT output-compression skill for Claude Code and 30+ agents.
- [Caveman Proxy](https://caveman.so/products/caveman-proxy): recoverable local context compression for agents you already run.
- [Caveman Agent SDK](https://caveman.so/products/caveman-agent): TypeScript controls for what an agent run can spend.
- [Caveman Browse](https://caveman.so/products/caveman-browse): token-efficient browser automation with byte-exact recovery.
- [Caveman Cloud](https://caveman.so/products/caveman-cloud): the byte-safe managed LLM gateway.
- [CaveGemma](https://caveman.so/products/cavegemma): Caveman compression fine-tuned into Gemma's weights.

## Company

- [About](https://caveman.so/about): what Caveman is, who builds it, and how it counts.
- [Contact](https://caveman.so/contact): every route in, including security reports.
- [Pricing](https://caveman.so/pricing): Free, Indie ($29/mo), Team ($349/mo), Enterprise.
- [Developers](https://caveman.so/developers): the local tools and where data goes.
- [Enterprise](https://caveman.so/enterprise): governance, deployment models, verified evidence.

## Optional

- [News](https://caveman.so/news): field reports on measurement and token economics.
- [Labs](https://caveman.so/labs): research write-ups and benchmark methodology.
- [CaveBench](https://caveman.so/cavebench): savings at held quality, cost per correct task.
- [Data use](https://caveman.so/data-use): exactly what leaves your machine.
- [GitHub](https://github.com/JuliusBrussee/caveman): the open-source skill, extension and benchmarks.