Caveman

Install

npx skills add JuliusBrussee/caveman

This is third-party code. Review the repository files before installing.

What it does

Caveman has two parts. The skill makes the agent answer tersely while code, commands, paths and error messages stay intact, with levels set by /caveman lite, full or ultra. The proxy runs locally between the agent and the provider, compresses logs, test output and diffs before sending, and keeps originals in a local SQLite file. The CLI can also analyze session history with caveman learn and compress command output with caveman shrink.

Who it is for. Developers who pay for tokens and want to cut costs on long sessions.

Example request

/caveman full, why does this React component re-render every time

Limitations

The skill only shortens output tokens, and its rules add about 1 to 1.5k input tokens per turn, so terse work can cost more. The CLI sends anonymous usage stats by default. The engine and proxy are BSL-1.1, the skill and CLI are MIT.

How to disable. Say /caveman off or normal mode. To uninstall: npx -y github:JuliusBrussee/caveman -- --uninstall. Turn off telemetry with caveman telemetry off or DO_NOT_TRACK=1.

Security check

• The proxy sits in the traffic between the agent and the provider
• The full installer wires Claude Code hooks and runs via curl | bash
• The CLI sends anonymous telemetry by default

README in short

The README explains the difference between the skill and the proxy and gives benchmarks with caveats, including cases with no gain. The skill installs via npx skills or as a Claude Code plugin, the proxy via the @caveman-ai/cli npm package. It covers CLI commands, a mode that renders skills as images, wrappers for various agents and MCP tools. A separate section covers telemetry and the split license.

SKILL.md

---
name: cavecrew
description: >
  When to delegate to `cavecrew-investigator` (locate code), `cavecrew-builder`
  (1-2 file edit) or `cavecrew-reviewer` (diff review) instead of working inline
  or using `Explore`. Their output is compressed, so main context lasts longer.
---

Cavecrew = three subagent presets that emit caveman output. Same job as Anthropic defaults (`Explore`, edit-style agents, reviewer); difference is the tool-result they return is compressed, so main context shrinks per delegation.

## When to use cavecrew vs alternatives

| Task | Use |
|---|---|
| "Where is X defined / what calls Y / list uses of Z" | `cavecrew-investigator` |
| Same but you also want suggestions/architecture commentary | `Explore` (vanilla) |
| Surgical edit, ≤2 files, scope obvious | `cavecrew-builder` |
| New feature / 3+ files / cross-cutting refactor | Main thread or `feature-dev:code-architect` |
| Review diff, branch, or file for bugs | `cavecrew-reviewer` |
| Deep code review with rationale + alternatives | `Code Reviewer` (vanilla) |
| One-line answer you already know | Main thread, no subagent |

Rule of thumb: **if you'd want the subagent's output in 1/3 the tokens, pick cavecrew. If you'd want prose, pick vanilla.**

## Why this exists (the real win)

Subagent tool results get injected into main context verbatim. A vanilla `Explore` that returns 2k tokens of prose costs 2k tokens of main-context budget every time. The same finding from `cavecrew-investigator` returns ~700 tokens. Across 20 delegations in one session that's the difference between context exhaustion and finishing the task.

## Output contracts

What main thread can rely on per agent:

**`cavecrew-investigator`**
```
<Header>:
- path:line — `symbol` — short note
totals: <counts>.
```
Or `No match.` Always file-path-first, line-number-attached, backticked symbols. Safe to grep with `path:\d+`.

**`cavecrew-builder`**
```
<path:line-range> — <change ≤10 words>.
verified: <re-read OK | mismatch @ path:line>.
```
Or one of: `too-big.` / `needs-confirm.` / `ambiguous.` / `regressed.` (terminal first token).

**`cavecrew-reviewer`**
```
path:line: <emoji> <severity>: <problem>. <fix>.
totals: N🔴 N🟡 N🔵 N❓
```
Or `No issues.` Findings sorted file → line ascending.

## Chaining patterns

**Locate → fix → verify** (most common):
1. `cavecrew-investigator` returns site list.
2. Main thread picks 1-2 sites, hands paths to `cavecrew-builder`.
3. `cavecrew-reviewer` audits the diff.

Related