Caveman Token-Saving Toolkit
Reduce coding-agent token use by compressing what agents read and shortening what they say.
- Source repo
- JuliusBrussee/caveman
- Stars
- ★ 114k
- Last updated
- today
- License
- Apache-2.0
- Primary language
- Go
- FA score
- 75/100 · Good
At a glance
- How it runs
- Works with
- Universal · cross-platformCodex · Claude CodeClaude.ai · OpenAI API · Claude API (Partial support)
- Cost
- Free tier plus a paid hosted plan
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- A developer using Claude Code, Codex, or Gemini CLI who wants shorter explanations while keeping code and commands intact.
- Not a fit if
- Teams that require all data to stay on the machine
- Developers who do not use a documented coding agent
- Teams that need a stable Blocks code mode
- Source review
- 75/100 · Good
What does this agent do, and when should you use it?
Caveman is a local CLI that installs and manages token-saving features for coding agents including Claude Code, Codex, Gemini CLI, and OpenCode. Its /caveman skill shortens replies, while input compression reduces logs, JSON, CSV, and test output before an agent reads them. After sign-in, Auto can choose a model and effort level per request; Blocks provides reusable scripts to avoid repeatedly writing and reading the same code. The main installer requires Node.js 22.13+ and configures agents from the terminal, with individual features that can be switched on or off. The CLI sends usage statistics by default, and Auto sends some conversation context to Caveman Cloud, so teams with strict data-handling needs should review those flows before adoption.
Run npx @caveman-ai/cli@latest to launch the installer, select agents, and review the proposed changes; then use caveman status, caveman on, or caveman off to inspect or toggle features. The installed skill uses /caveman and related modes to shorten agent replies while preserving code, commands, paths, and error messages verbatim. Input compression produces smaller versions of logs, JSON, CSV, YAML, or test output for the agent to read while keeping originals on disk. After sign-in and selection, Auto routes each request to a model and effort level; Blocks checks for repeated script use and suggests an existing block when one applies. The CLI also supports caveman learn for analyzing local agent history, caveman browse <url> for compressed web pages, and caveman stats for token usage.
- A developer using Claude Code, Codex, or Gemini CLI who wants shorter explanations while keeping code and commands intact.
- An engineer who often sends large logs, JSON, CSV, or test output to a coding agent and wants to reduce input tokens.
- A team using Claude Code, OpenCode, or Codex that wants Auto to select model and effort per request.
- A developer who repeatedly runs tests or processes JSON and wants to reuse small scripts through Blocks.
- A team using Vercel AI SDK, LangChain, OpenAI, or Anthropic calls that wants to add compression middleware to existing requests.
How do you install or deploy this agent?
The main CLI installer requires Node.js 22.13+. Run the command and review and confirm the proposed configuration changes. The README does not require an API key for the main installation. Auto requires a free account; adding other model providers can use your own keys.
npx @caveman-ai/cli@latestHow do you use this agent?
After installation, inspect status and enable features as needed. Start an agent with caveman claude, or use /caveman inside a supported agent. Auto requires signing in and selecting it in the model picker; adding the OpenAI provider is optional.
caveman status
caveman on browse
caveman claudecaveman login
caveman providers add openai/cavemanWhat are this agent's strengths and limitations?
- One CLI installs and manages integrations for more than 30 agents, with per-feature switches.
- The skill rules preserve code, commands, paths, and error messages verbatim, and allow full sentences for security warnings or irreversible actions.
- The README reports 33.2% fewer session input tokens across 54 Claude Code runs with all 18 answers correct, while also disclosing worse HTML results and benchmark limits.
- Includes compression for test output, JSON, logs, and other inputs, plus TypeScript and Python middleware.
- The main installation requires Node.js 22.13+ and terminal use.
- The CLI sends command and token-count usage statistics by default;
caveman telemetry offorDO_NOT_TRACK=1disables them. - Auto requires sign-in and sends recent requests and some context to Caveman Cloud; the Free plan may retain it to improve routing.
- Blocks is marked pre-release v0.1.0-rc.5, supports Python only, and has no sandbox yet.
- Some benchmarks use an older engine or incomplete task sets, and the README says results can vary by use case.
How does this agent compare with similar options?
The README compares reply length for /caveman, /ultracave, and /megacave, and reports baselines with no instruction and Answer concisely. The Auto benchmark uses Opus 5.5 at xhigh effort as its comparison.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Caveman Token-Saving Toolkit This agent | 75 · Good | CLIFreemium | ★ 114k | today | Go | Codex · Claude Code |
| Code Abyss: Persona and Engineering Skills for Coding Agents | 66 · Some gaps | CLI | ★ 242 | 3mo ago | JavaScript | Codex · Claude Code |
| OSpec | 50 · Major gaps | CLIFree + model costs | ★ 396 | 1mo ago | JavaScript | Codex · Claude Code |
| Plannotator | 78 · Good | CLIFreemium | ★ 9.6k | today | TypeScript | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
The files describe local proxy, cloud routing, telemetry, credentials, SSRF, and browser behavior in detail, with telemetry opt-out, explicit routing controls, and deployment guidance. The installer offers dry-run and some confirmation, but telemetry is on by default, Auto sends request context, and compression can alter context, so least privilege, sensitive-data handling, and external effects are not fully established. Signed artifact checks, backups, and uninstall guidance support rollback, though some integrations can leave host settings or depend on host plugin flows. Author attribution and a vulnerability channel are clear; registry identity is unverified, and response commitments are targets rather than an SLA.
The documentation consistently describes components, configuration defaults, fallback behavior, and diagnostic commands. However, the dependency surface is broad: installation relies on Node/npm, host plugin systems, and in some paths downloaded companion binaries; native loading is unverified for some hosts. Failure messages and safe fallbacks are documented, but static material cannot establish runtime behavior.
The repository covers many coding agents, operating systems, local and shared deployments, and skill-only, proxy, SDK, and middleware use. It distinguishes these capabilities and documents validation boundaries. Skill activation may be automatic or manual depending on the host; the boundaries are clear, but native automatic invocation is not established for every integration.
README, install matrix, technical and security documentation, configuration reference, and install/uninstall examples are substantial. Limitations, privacy, and the Apache-2.0 license are explicit. Version and update guidance exists, though multiple components and release lines make naming/version relationships less simple; maintenance responsibility is described mainly as a solo maintainer and security response targets. Unknown registry identity is not itself a deduction.
Examples illustrate possible gains from shorter answers, input compression, routing, and reusable scripts, while also disclosing negative or unmeasured results and benchmark limits. Output remains free text, and much of the benefit evidence is repository-reported; usefulness and savings vary by workload and billing model, so effectiveness and cost-benefit are only partly supported.
Several numerical claims point to methods, benchmarks, or external research, and the files label interim, unmeasured, inferred, and limited results. The supplied materials cite external evidence but do not include its source contents or independent replication, so cross-source corroboration remains limited.
- CLI telemetry is enabled by default and sends usage events and IP; Auto sends recent request context to Caveman Cloud, where the Free plan may retain it to improve routing. Review SECURITY.md and disable telemetry or routing when appropriate.
- Compression and other lossy transforms can hide original details from the model; use the documented record mode for byte-sensitive workflows. Shared proxies require authentication and restricted network exposure.
FAQ
Does Caveman require payment?
What data leaves my machine?
/caveman-compress sends the file being compressed to the configured model provider. The CLI sends usage statistics by default. When enabled after sign-in, Auto sends recent requests and some agent context to Caveman Cloud.Can I install only the reply-shortening skill?
npx skills add JuliusBrussee/caveman -g; use /caveman, or $caveman in Codex.Is Auto or Blocks ready for production use?
How do I disable telemetry or a feature?
caveman telemetry off or set DO_NOT_TRACK=1 to disable telemetry. Use caveman off browse to turn off Browse and caveman status to inspect current settings.