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

> Understand Cavecrew and its Caveman sub-agents Investigator, Builder, and Reviewer. Learn how these agents optimize token usage for efficient task delegation.

- Repository: [Julius Brussee/caveman](https://github.com/JuliusBrussee/caveman)
- Tags: deep-dive
- Published: 2026-07-08

---

**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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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:

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

```

The investigator returns:

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

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

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

```

### Diff Review with the Reviewer

To review a pull request:

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

```

The reviewer produces findings:

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

```text
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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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.