# What Are Cavecrew Subagents and How Do They Help?

> Explore Cavecrew subagents, specialized LLM delegates for efficient code analysis. They reduce token usage by 60% via token-efficient pipelines for read-only code location, editing, and diff review.

- Repository: [Julius Brussee/caveman](https://github.com/JuliusBrussee/caveman)
- Tags: how-to-guide
- Published: 2026-07-11

---

**Cavecrew subagents are specialized LLM delegates that handle read-only code location, surgical editing, and diff review in a token-efficient pipeline, reducing token usage by approximately 60% compared to monolithic exploration requests.**

The Caveman project introduces **Cavecrew subagents** as a tactical solution for managing large codebase interactions without exhausting context windows. These specialized helpers transform monolithic LLM requests into a delegated workflow that slashes token consumption while accelerating code exploration, editing, and review tasks.

## The Three Cavecrew Subagents Explained

The Cavecrew suite comprises three distinct agents defined in the `agents/` directory, each optimized for a specific phase of the development workflow.

### cavecrew-investigator (Read-Only Locator)

The **cavecrew-investigator** acts as a read-only scanner that locates code across the repository without proposing edits. According to [`agents/cavecrew-investigator.md`](https://github.com/JuliusBrussee/caveman/blob/main/agents/cavecrew-investigator.md), this agent utilizes a restricted toolset including `Read`, `Grep`, `Glob`, and `Bash` to search the codebase and return concise findings formatted as `<path:line> — `symbol` — note` tables.

Use this agent when you need to answer questions like *"Where is X defined?"*, *"What calls Y?"*, or *"List all uses of Z"*. The output is heavily compressed—approximately 700 tokens versus 2,000 tokens for a naive exploration—making it ideal for initial discovery phases.

### cavecrew-builder (Surgical Editor)

The **cavecrew-builder** defined in [`agents/cavecrew-builder.md`](https://github.com/JuliusBrussee/caveman/blob/main/agents/cavecrew-builder.md) serves as a surgical editor that operates on strictly limited scope—typically **1–2 files** at a time. This agent receives exact file:line targets from the investigator and returns compressed diffs showing precise modifications.

Deploy this agent when you already know the exact locations requiring changes and the edit scope is constrained to a couple of files. The builder's focused context window prevents token bloat from irrelevant surrounding code.

### cavecrew-reviewer (Diff Auditor)

The **cavecrew-reviewer** functions as a diff auditor that produces one-line findings with severity emojis. Based on [`agents/cavecrew-reviewer.md`](https://github.com/JuliusBrussee/caveman/blob/main/agents/cavecrew-reviewer.md), this agent audits diffs produced by the builder or existing changes in the repository, emitting terse findings like `⚠️ Changed flag may affect cross-process semantics`.

Use this agent after modifications are made to perform quick sanity checks or bug hunts on specific diffs or branches without loading the entire codebase into context.

## How the Subagent Pipeline Works

The three agents cooperate in a sequential pipeline that optimizes token efficiency at each stage:

1. **Locate**: The investigator scans the repository and returns a compact table of relevant symbols and locations.
2. **Edit**: The main thread selects the most promising 1–2 entries and delegates to the builder, which returns a compressed diff.
3. **Review**: The diff is sent to the reviewer, which emits concise findings that are injected back into the main context.

Because each sub-agent's output is **caveman-compressed**, the main thread consumes roughly **60% fewer tokens** than a single monolithic LLM request. This efficiency allows you to chain multiple delegations in one session without exhausting the context window.

## Architecture and Configuration

### Model Overrides via Environment Variables

You can customize which AI model powers each subagent by setting environment variables defined in [`src/hooks/cavecrew-model-overrides.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/cavecrew-model-overrides.js). The system checks for:

- `CAVECREW_INVESTIGATOR_MODEL`
- `CAVECREW_BUILDER_MODEL`
- `CAVECREW_REVIEWER_MODEL`

This configuration lets you select cheaper models for simple read operations and more capable models for complex surgical edits, optimizing both cost and performance.

### Specialized Toolsets

Each agent declares its own tool list in front matter, ensuring the LLM only accesses capabilities it needs. For example, the investigator explicitly lists `Read, Grep, Glob, Bash` in [`agents/cavecrew-investigator.md`](https://github.com/JuliusBrussee/caveman/blob/main/agents/cavecrew-investigator.md), while the builder and reviewer have different tool restrictions appropriate to their roles.

### Front-Matter-Driven Execution

The agents are regular Markdown files with front matter that the Caveman runtime reads to spin up appropriate LLM sessions. This design keeps agents portable, version-controlled, and easy to modify without changing core application code.

## Practical Usage Examples

Caveman automatically triggers subagent delegation when detecting phrases like **"delegate to subagent"**, **"use cavecrew"**, or **"spawn investigator/builder/reviewer"** as documented in [`skills/cavecrew/SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/cavecrew/SKILL.md).

Locate a symbol before editing:

```bash

# Spawn investigator to find all definitions of safeWriteFlag

caveman use cavecrew "where is safeWriteFlag defined?"

# Returns: hooks/caveman-config.js:81 — `safeWriteFlag` — atomic write w/ O_NOFOLLOW

```

Perform surgical edits on specific lines:

```bash

# Delegate to builder with exact location

caveman use cavecrew-builder "replace O_NOFOLLOW with O_CLOEXEC at hooks/caveman-config.js:81"

# Returns compressed diff of the edit

```

Review changes immediately:

```bash

# Audit the produced diff

caveman use cavecrew-reviewer "review the last diff"

# Returns: ⚠️ Changed flag may affect cross-process semantics

```

Refer to [`skills/cavecrew/README.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/cavecrew/README.md) for a tabular cheat-sheet of available commands and triggers.

## Summary

- **Cavecrew subagents** split monolithic code exploration into three specialized phases: investigation, building, and review, cutting token usage by approximately 60%.
- Each agent maintains a focused toolset defined in its front matter, with the investigator using `Read, Grep, Glob, Bash` for safe, read-only operations.
- Configure individual models per agent via `CAVECREW_INVESTIGATOR_MODEL`, `CAVECREW_BUILDER_MODEL`, and `CAVECREW_REVIEWER_MODEL` environment variables in [`src/hooks/cavecrew-model-overrides.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/cavecrew-model-overrides.js).
- Automatic delegation triggers recognize natural language phrases like "use cavecrew" or "spawn investigator" as defined in [`skills/cavecrew/SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/cavecrew/SKILL.md).

## Frequently Asked Questions

### What exactly are Cavecrew subagents?

Cavecrew subagents are specialized LLM delegates within the Caveman ecosystem that handle specific tasks—code location, surgical editing, and diff review—allowing the main agent to delegate heavyweight work while conserving context window tokens.

### How do Cavecrew subagents reduce token usage?

By compressing outputs at each pipeline stage (investigator returns ~700 tokens instead of 2,000+ for full exploration, builder returns compressed diffs, reviewer returns one-line findings), the system reduces total token consumption by roughly 60% compared to monolithic requests that load entire file contents repeatedly.

### Can I use different AI models for each subagent?

Yes. The [`src/hooks/cavecrew-model-overrides.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/cavecrew-model-overrides.js) file enables model customization via environment variables. Set `CAVECREW_INVESTIGATOR_MODEL`, `CAVECREW_BUILDER_MODEL`, or `CAVECREW_REVIEWER_MODEL` to assign specific models to each role, allowing you to use cheaper models for simple reads and more powerful models for complex edits.

### When should I use the investigator versus the builder?

Use **cavecrew-investigator** when you need to locate code or understand repository structure without making changes. Use **cavecrew-builder** only after you have exact file:line targets and need to modify 1–2 files. The investigator handles discovery; the builder handles execution.