What Are Cavecrew Subagents and How Do They Help?

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, 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 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, 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. 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, 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.

Locate a symbol before editing:

# 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:

# 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:

# 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 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.
• Automatic delegation triggers recognize natural language phrases like "use cavecrew" or "spawn investigator" as defined in 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 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.

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