What Is Cavecrew and How Do Caveman’s Sub‑Agents (Investigator, Builder, Reviewer) Work?

Cavecrew is a decision‑guide skill that tells the main Caveman thread when to hand off work to one of three lightweight sub‑agents—investigator, builder, or reviewer—instead of processing the request inline, keeping token usage to roughly one‑third of a standard Explore call.

Cavecrew is a specialized skill within the Caveman repository (JuliusBrussee/caveman) designed to optimize context window management. When the conversation triggers specific phrases, the main thread delegates discrete tasks to compressed sub‑agents that return structured, compact results. This architecture prevents the main context from bloating with verbose intermediate steps while maintaining high precision for code location, surgical edits, and diff reviews.

What Is Cavecrew?

Cavecrew functions as a routing layer in the Caveman ecosystem. According to the skill definition in skills/cavecrew/README.md, it acts as a decision guide that determines when to spawn a sub‑agent versus handling a request directly. The skill is optimized for scenarios requiring concrete data retrieval or micro‑edits rather than architectural prose or multi‑file refactoring.

The system targets token efficiency: each sub‑agent operates on approximately ⅓ the token budget of a standard Explore call. This compression is achieved by strict output contracts, limited tool access, and the haiku model default (unless overridden by environment variables).

The Three Cavecrew Sub‑Agents

Cavecrew coordinates three distinct agents, each with a narrowly defined scope and forbidden operations.

Investigator (Read‑Only Code Locator)

The investigator is a read‑only search agent defined in agents/cavecrew-investigator.md. Its sole purpose is to locate code definitions, references, callers, and imports without modifying files.

• Model: Pinned to haiku (configurable via CAVECREW_INVESTIGATOR_MODEL)
• Allowed Tools: Read, Grep, Glob, Bash
• Forbidden Operations: Editing, writing, or deleting files
• Output Format: A compact table grouped under headers like Defs:, Refs:, or Tests:, followed by a totals line. Each entry follows the pattern path:line — symbol — note.

When you ask "Where is myFunction defined?" or "List all callers of UserService", the investigator returns structured location data rather than narrative explanation.

Builder (Surgical Edit Agent)

The builder handles precise, small‑scale code modifications. Defined in agents/cavecrew-builder.md, it performs surgical edits limited to one or two files.

• Model: Pinned to haiku (configurable via CAVECREW_BUILDER_MODEL)
• Allowed Tools: Read, Edit, Write, Grep, Glob
• Critical Restriction: No Bash tool access to prevent destructive shell commands
• Scope Limit: One file preferred; two files maximum. If a request exceeds this scope, the builder returns too-big. and suggests splitting the work.
• Verification: After editing, the builder re‑reads the modified file to verify the change.
• Output Format: A receipt line: path:line-range — <change ≤10 words>. followed by verified: re-read OK.

Typical use cases include fixing typos, renaming variables, or cleaning up comments in specific locations.

Reviewer (Diff and File Reviewer)

The reviewer scans diffs or individual files and emits concise findings with severity indicators. Its specification lives in agents/cavecrew-reviewer.md.

• Model: Pinned to haiku (configurable via CAVECREW_REVIEWER_MODEL)
• Allowed Tools: Read, Grep, Bash (restricted to git diff‑style commands)
• Output Format: One line per finding: path:line: <emoji> <severity>: <problem>. <fix>.
• Severity Emojis:
  • 🔴 bug: Critical functional errors
  • 🟡 risk: Potential issues or security concerns
  • 🔵 nit: Minor style or formatting issues
  • ❓ question: Request for clarification

The reviewer does not offer broad refactoring suggestions; if context is missing, it explicitly asks for clarification rather than hallucinating assumptions.

How Cavecrew Sub‑Agents Operate

Trigger Mechanism

The cavecrew skill activates when the conversation contains specific trigger phrases listed in skills/cavecrew/README.md. These include:

• "delegate to sub‑agent"
• "use cavecrew"
• "spawn investigator"

When detected, the skill's front‑matter in skills/cavecrew/SKILL.md selects the appropriate agent based on the request type.

Model Overrides

While each sub‑agent defaults to the haiku model for speed and cost efficiency, you can override these via environment variables:

• CAVECREW_INVESTIGATOR_MODEL
• CAVECREW_BUILDER_MODEL
• CAVECREW_REVIEWER_MODEL

Valid values include sonnet, opus, or other Claude model identifiers supported by the Caveman framework.

Result Injection

After a sub‑agent completes its task, the output is inserted verbatim into the main thread. This injection preserves the main context window by avoiding the need to re‑process verbose intermediate results. The main thread receives only the compact, structured data or receipt from the sub‑agent.

Practical Examples

Locating Code with the Investigator

When you need to find where a function is defined:

User: Where is the function parseConfig defined?
Caveman (cavecrew triggers):
  → spawn cavecrew-investigator

The investigator returns:

Defs:
src/config/loader.js:27 — `parseConfig` — parses JSON config
Tests:
tests/config/loader.test.js:12 — `parseConfig` — exercised in unit test
2 defs, 1 test file.

Surgical Edits with the Builder

For typo fixes or small renames:

User: Fix the typo on line 42 of src/utils.js (change "funtion" → "function").
Caveman:
  → spawn cavecrew-builder with path src/utils.js:42

The builder returns a receipt:

src/utils.js:42 — replace "funtion" with "function".
verified: re-read OK.

Diff Review with the Reviewer

To review a pull request:

User: Review the diff for the recent PR.
Caveman:
  → spawn cavecrew-reviewer on the PR diff

The reviewer produces findings:

src/auth.js:58: 🔴 bug: token expiry uses `<` not `<=`. Off-by-one allows expired tokens 1 tick.
src/db.js:112: 🟡 risk: pool not closed on error path. Add `try/finally`.
src/helpers.js:7: ❓ question: why duplicate `.trim()` here?
totals: 1🔴 1🟡 1❓

Chaining Sub‑Agents

You can sequence multiple sub‑agents for complex workflows:

User: Find where handleRequest is defined, fix a typo there, then review the change.
Caveman:
  1️⃣ spawn cavecrew-investigator → returns src/handler.js:33 — `handleRequest`
  2️⃣ spawn cavecrew-builder on src/handler.js:33 → edits typo
  3️⃣ spawn cavecrew-reviewer on the resulting diff → produces findings

When to Use Cavecrew vs. Vanilla Agents

According to the decision guide in skills/cavecrew/README.md, prefer cavecrew when:

• You need a concrete piece of data (definitions, specific locations, small edits)
• You want to minimize token usage and keep outputs under ⅓ of a standard Explore call
• The task fits within the one‑file or read‑only constraints of the sub‑agents

Use vanilla Explore or Code Reviewer when:

• You need extensive prose explanations
• You require architectural commentary across multiple files
• The task involves complex multi‑file refactoring

The rule of thumb from the source code: "if you'd want the sub‑agent's output in 1/3 the tokens, pick cavecrew; if you need prose, pick vanilla."

Summary

• Cavecrew is a decision‑guide skill in JuliusBrussee/caveman that routes tasks to three specialized sub‑agents to preserve the main context window.
• Investigator (agents/cavecrew-investigator.md) handles read‑only code location using Read, Grep, Glob, and Bash, returning compact tables of definitions and references.
• Builder (agents/cavecrew-builder.md) performs surgical edits on 1‑2 files using Read, Edit, Write, Grep, and Glob, returning a receipt line and verification status.
• Reviewer (agents/cavecrew-reviewer.md) scans diffs and files, emitting one‑line findings with severity emojis (🔴 bug, 🟡 risk, 🔵 nit, ❓ question).
• All sub‑agents default to the haiku model but support overrides via CAVECREW_*_MODEL environment variables.
• Trigger phrases like "delegate to sub‑agent" or "use cavecrew" activate the skill defined in skills/cavecrew/SKILL.md.

Frequently Asked Questions

What is the difference between Cavecrew and the standard Explore agent?

Cavecrew sub‑agents are optimized for token efficiency and structured outputs, using approximately ⅓ the token budget of a standard Explore call. While Explore provides narrative prose and handles complex multi‑file analysis, Cavecrew agents return compact, machine‑readable formats (tables, receipts, or emoji‑tagged findings) for discrete tasks like locating a symbol or fixing a typo.

Can I use a different model than Haiku for Cavecrew sub‑agents?

Yes, you can override the default haiku model using environment variables. Set CAVECREW_INVESTIGATOR_MODEL, CAVECREW_BUILDER_MODEL, or CAVECREW_REVIEWER_MODEL to any valid Claude model identifier (such as sonnet or opus) to use a more capable model for specific sub‑agents when precision is critical.

Why does the Builder agent lack Bash tool access?

The builder explicitly excludes Bash from its allowed tools to prevent destructive shell commands and maintain security. According to agents/cavecrew-builder.md, restricting the builder to Read, Edit, Write, Grep, and Glob ensures it can only modify source code through controlled editing operations, eliminating risks of accidental file deletion or system command execution.

What happens if I ask the Builder to edit more than two files?

The builder will refuse the request and return too-big. As specified in agents/cavecrew-builder.md, the builder's scope is strictly limited to one file (with two files tolerated in edge cases). If your request exceeds this limit, the agent will suggest splitting the work into smaller chunks rather than attempting a broad modification that would violate its design constraints.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}