cavecrew
juliusbrussee/caveman
Three compressed-output subagents for code location, surgical edits, and diff review—save context tokens across delegations.
What is cavecrew?
Cavecrew provides three specialized subagent presets (investigator, builder, reviewer) that emit structured, token-efficient output instead of prose. Use them when you want the same code-navigation or review work as vanilla agents but need to preserve main-thread context for longer sessions.
- cavecrew-investigator: locate definitions, callers, and uses of symbols with file:line output
- cavecrew-builder: execute surgical 1–2 file edits with verification status
- cavecrew-reviewer: audit diffs and branches for bugs, returning severity-tagged findings
- Compress subagent output to ~1/3 typical token cost per delegation
- Chain locate → fix → verify workflows or spawn parallel investigators
How to install cavecrew
npx skills add https://github.com/juliusbrussee/caveman --skill cavecrewHow to use cavecrew
- 1.Install via `npx skills add https://github.com/juliusbrussee/caveman --skill cavecrew`
- 2.For code location: delegate to `cavecrew-investigator` with a symbol or pattern to find
- 3.For edits: provide exact file:line paths to `cavecrew-builder` (do not use if paths are unknown)
- 4.For review: send a diff or branch to `cavecrew-reviewer` to get severity-tagged findings
- 5.Chain results: use investigator output to feed builder, then reviewer to audit the diff
Use cases
- Finding where a symbol is defined or what calls it, then handing exact paths to builder for edits
- Reviewing a branch or diff for bugs without full prose commentary
- Running 20+ delegations in one session without exhausting context budget
- Parallel investigation from multiple angles (defs vs callers vs tests) aggregated in main thread
- Single-shot edits when file paths are already known
- Developers managing long coding sessions with limited context budget
- Teams doing code review or refactoring across many files
- Anyone preferring structured, terse output over prose commentary
cavecrew FAQ
Use cavecrew when you want the same task done but need to save tokens—e.g., locate-fix-verify chains or diff review. Use vanilla agents if you need prose, architecture commentary, or general feedback.
Compressed output (caveman format) uses ~1/3 the tokens of prose. The tradeoff is structure over readability; paraphrase for humans if needed.
Yes, if you already know the exact file:line paths. If paths are unknown, run investigator first or main thread will waste tokens passing context.
It returns `too-big.` (terminal first token). Use main thread or `feature-dev:code-architect` for 3+ files or cross-cutting refactors.
No. Cavecrew-reviewer returns findings only. Use vanilla `Code Reviewer` for architecture feedback and rationale.
Full instructions (SKILL.md)
Source of truth, from juliusbrussee/caveman.
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):
cavecrew-investigatorreturns site list.- Main thread picks 1-2 sites, hands paths to
cavecrew-builder. cavecrew-revieweraudits the diff.
Parallel scout (when investigation is broad):
Spawn 2-3 cavecrew-investigator calls in one message (different angles: defs vs callers vs tests). Aggregate in main thread.
Single-shot edit (when site is already known):
Skip investigator. Hand exact path:line to cavecrew-builder directly.
What NOT to do
- Don't use
cavecrew-builderwhen you don't already know the file. Spawn investigator first or main thread will eat tokens passing context. - Don't chain
cavecrew-investigator → cavecrew-builderfor a 5-file refactor. Builder will returntoo-big.and you'll have wasted a turn. - Don't ask
cavecrew-reviewerfor "general feedback" — it returns findings only, no architecture opinions. UseCode Reviewerfor that. - Don't expect prose. Cavecrew output is structured, sometimes terse to the point of cryptic. If a human will read it directly, paraphrase.
Auto-clarity (inherited)
Subagents drop caveman → normal English for security warnings, irreversible-action confirmations, and any output where fragment ambiguity could be misread. Resume caveman after.
Related skills
More from juliusbrussee/caveman and the wider catalog.
