---
title: Quickstart
summary: Install the skill and compress a real payload in about five minutes.
canonical: https://docs.caveman.so/docs/quickstart
updated: 2026-08-26T03:57:26+02:00
basis: inferred
---

# Quickstart

> Install the skill and compress a real payload in about five minutes.
<DocSchema slug="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

<Steps>
<div>
This works for most agents:

```bash
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.
</div>

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

```bash
# 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
```
</div>

<div>
Check it took. In your agent, run:

```text
/caveman
```

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

<Note title="What it changes, and what it does not">
The skill drops articles, filler and narration from your agent's replies. It is explicit about what stays
byte for byte: code blocks, function and API names, CLI commands, and exact error strings. It also steps
aside on its own for security warnings, irreversible actions, and any moment where being terse would make
an instruction ambiguous.
</Note>

## Install the local tools

The CLI is published on npm under a scoped name.

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

<Note tone="warning" title="Two package names, one of them is not ours">
The bare `caveman` package on npm is an unrelated JavaScript templating library. Install
`@caveman-ai/cli`. On PyPI the same applies: our SDK is `caveman-sdk`, imported as `caveman_cloud`.
</Note>

`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.

<Note tone="honest" title="The CLI sends anonymous counts, and says so on first run">
Command names, version, platform, duration, exit class, and aggregate token counts from local sessions.
Never prompts, code, file paths, arguments, model names or dollar figures. It is how we see which
commands people use and which ones break, and it is a large part of why the local tools can stay free.
Turn it off with `caveman telemetry off`, `CAVEMAN_TELEMETRY=0`, or `DO_NOT_TRACK=1`. The full payload is
listed on [Telemetry](/docs/telemetry).
</Note>

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

```bash
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

```bash
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:

```bash
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](/docs/counting).