Skip to main content
Caveman has two local adoption paths. Install the response skill when you want shorter answers. Install the runtime when you want to reduce context sent to a model, keep local measurements, or give an agent recovery tools. They can run independently.

​
Layer map

The whole repository is Apache-2.0. See LICENSING.md.

​
Response compression

The caveman skill changes response style. It removes filler, shortens common phrasing, and permits fragments at stronger levels. Code blocks, exact errors, commands, identifiers, and technical detail stay intact. This path affects model output. Its instruction text also consumes input tokens. A short task can cost more total tokens with the skill enabled. The correct comparison is provider-reported usage for equivalent tasks. See Honest numbers.

​
Context compression

The local runtime changes selected model inputs. An agent may repeatedly send old tool results and logs plus files, schemas or history. Engine classifies each candidate and applies a content-specific compressor. Every lossy result follows this sequence:
  1. Store exact original bytes in Caveman Context Recovery (CCR).
  2. Return a smaller model-visible representation.
  3. Include a handle that can recover the original.
  4. Pass original bytes through if storage, parsing, or size checks fail.
The local proxy listens on loopback and forwards requests with the caller’s provider credential. It records usage in a local SQLite database. Local token reductions carry basis inferred, because Engine uses an offline tokenizer rather than provider billing counters.

​
Keep your existing agent

The CLI wraps an installed coding agent by changing its provider endpoint for the child process. It does not replace the agent loop. Declarative profiles describe seven current launch targets: Claude Code, Codex, Gemini CLI, Aider, Hermes, OpenClaw and opencode. Applications can use the same proxy by changing a provider SDK base URL. Copy-ready recipes cover Anthropic, OpenAI, Google Gen AI, Vercel AI SDK, LangChain, LiteLLM, CrewAI, Pydantic AI, OpenAI Agents SDK, and raw HTTP. Run:

​
Local and connected boundaries

Local compression requires no Caveman account. Signing in adds connected commands and can persist a hosted gateway URL. Command discovery keeps these surfaces separate:
Managed traffic has a different data flow from local wrap. Local wrap sends request content to the selected model provider and keeps CCR on disk. A hosted gateway necessarily receives request and response content while proxying it. SECURITY.md lists both flows.

​
Evidence labels

Caveman uses labels that identify how a number was produced:
  • inferred: local estimate, usually from the offline o200k_base tokenizer or catalog list prices
  • provider-reported: usage counters returned by a model provider
  • benchmark_counterfactual: paired benchmark result under a pinned method
  • verified: a connected evidence state that local tools never mint
These labels do not convert into one another through wording. A local estimate stays inferred even when its result looks plausible.

​
Choose the smallest path

Start with one layer. Add another only when its measured result clears its overhead for your workload.