Quickstart

There are two things worth doing first, and they are independent. The skill changes how your agent writes and takes about thirty seconds. The CLI installs the local tools and gives you a report on where your tokens actually go.

Install the skill#

1. 1

   This works for most agents:

   npx skills add JuliusBrussee/caveman

   Without -g this writes into ./.agents/skills under the directory you are standing in, not into a global config. That is usually what you want for a project, and surprising if you expected otherwise.

2. 2

   Some agents have a native path that wires up more than the skill file:

   # Claude Code
   claude plugin marketplace add JuliusBrussee/caveman
   claude plugin install caveman@caveman
   
   # Gemini CLI
   gemini extensions install https://github.com/JuliusBrussee/caveman
   
   # Codex CLI
   npx skills add JuliusBrussee/caveman -a codex
   
   # Cursor, which needs the global flag
   npx skills add JuliusBrussee/caveman -a cursor -g

3. 3

   Check it took. In your agent, run:

   /caveman

   You should get a confirmation that the mode is active. /caveman off turns it back off, and so does saying "normal mode".

Install the local tools#

The CLI is published on npm under a scoped name.

npm i -g @caveman-ai/cli
caveman setup --install

caveman setup --install downloads the companion binaries into ~/.caveman/bin. It checks a key-signed manifest first, then verifies each artefact against its own SHA-256 before installing it.

Then start your agent through the CLI so it picks up the local tools:

caveman claude

The same works for codex, gemini, opencode, aider, hermes and openclaw. Seven agent profiles ship today, and each is one JSON file in the registry.

Find out where your tokens go#

caveman learn

This reads your local agent sessions and ranks what is actually consuming the budget. It measures and does nothing else. Applying a fix is a separate, consent-gated step:

caveman learn report --json
caveman learn apply <sink_id> --dry-run
caveman learn apply <sink_id>

Every applied fix is checked for being net token negative. If an edit does not make the thing smaller, it is reverted.

What you should expect to see#

On the committed benchmark suite, the skill cuts output tokens by about 65 percent on average, with a range from 22 to 87 percent across ten prompts. That is a per-run inferred estimate measured on that suite, not a promise about your bill.

Nothing you run locally will ever report a dollar figure or a monthly total. That is deliberate and the reasoning is here.