How Cavecrew Subagents (Investigator, Builder, Reviewer) Work in the Caveman AI Coding Agent

Cavecrew subagents are three lightweight specialist agents—investigator, builder, and reviewer—that the Caveman AI coding agent loads via src/hooks/cavecrew-model-overrides.js to perform targeted code search, surgical edits, and concise reviews while minimizing token consumption.

The cavecrew subagent suite extends the JuliusBrussee/caveman repository with a delegation pattern that keeps the main agent's context window lean. Each subagent is defined in its own Markdown file within the agents/ directory and specializes in a narrow task, returning only essential data rather than verbose prose. This design allows the main agent to orchestrate complex workflows—such as parallel code investigation followed by surgical editing—without exhausting the token budget.

What Are Cavecrew Subagents?

Cavecrew subagents are tiny specialist agents that handle specific, constrained operations within the Caveman ecosystem. Unlike the main agent, which maintains broad context, each cavecrew subagent focuses on a single responsibility and outputs raw, structured data that the main agent can consume programmatically.

The Investigator Subagent

The cavecrew-investigator is a read-only code location agent defined in agents/cavecrew-investigator.md. When invoked, it answers questions like "Where is X defined?" or "List callers of Y" by returning a concise list formatted as path:line — symbol — note.

According to the source code in skills/cavecrew/README.md, this approach reduces token costs from approximately 2,000 tokens (for a standard Explore result) to roughly 700 tokens. The investigator never modifies code; it only scouts and reports locations, making it ideal for parallel scouting operations where you fire multiple searches simultaneously.

The Builder Subagent

The cavecrew-builder handles surgical edits limited to two files or fewer, as defined in agents/cavecrew-builder.md. It accepts prompts like "Edit foo.js to use bar instead of baz" and returns a short diff of the changes.

Notably, the builder configuration omits a model: line, which means it uses the session's default LLM rather than a specialized model. Because it returns only the diff without narrative explanation, it keeps the main context budget low while performing precise modifications.

The Reviewer Subagent

The cavecrew-reviewer performs one-line diff reviews according to agents/cavecrew-reviewer.md. When asked to review changes, it emits single-line findings such as "L42 🔴 bug: null user" rather than prose paragraphs.

This format is approximately 70% cheaper than a full prose review, as documented in skills/cavecrew/README.md. The reviewer inspects code changes and flags issues with minimal token overhead, allowing the main agent to decide whether to accept, reject, or refine the edits.

How Cavecrew Subagents Are Loaded

When the main caveman skill initializes, it executes src/hooks/cavecrew-model-overrides.js to install the three subagents. This hook performs two critical functions:

1. Reads environment variables for model overrides:

   • CAVECREW_REVIEWER_MODEL → agents/cavecrew-reviewer.md
   • CAVECREW_BUILDER_MODEL → agents/cavecrew-builder.md
   • CAVECREW_INVESTIGATOR_MODEL → agents/cavecrew-investigator.md

2. Inserts each file into the agent's "plugins" directory so the host agent can invoke them as normal skills.

All three agents inject their raw output verbatim into the main thread, as implemented in JuliusBrussee/caveman. The main agent then decides the next step—such as selecting specific investigator results to feed to the builder, then asking the reviewer to audit the resulting diff.

Using Cavecrew Subagents in Practice

Invoke subagents during a Caveman session using slash commands followed by specific instructions:

# Launch the main caveman agent

caveman

# Ask the investigator to locate code

/cavecrew-investigator "where is the function calculateScore defined?"

# Returns:

# src/utils/math.js:23 – calculateScore – used by scoreBoard

# Hand specific results to the builder for surgical edits

/cavecrew-builder "replace src/utils/math.js:23 with the new algorithm"

# Returns a short diff

# Audit the changes with the reviewer

/cavecrew-reviewer "review the diff"

# Returns one-line findings, e.g., "L23 🔴 bug: missing edge-case"

Parallel Scouting

You can fire multiple investigator calls in a single message to aggregate results before any builder invocation:

/cavecrew-investigator "list definitions of User"
/cavecrew-investigator "list callers of User.getProfile"
/cavecrew-investigator "list tests exercising User"

The main agent receives all three results and can synthesize them before deciding which files require modification.

Configuring Model Overrides

If you require a specific LLM for a particular subagent, export the corresponding environment variable before starting the host agent:

export CAVECREW_REVIEWER_MODEL="claude-3-5-sonnet-20240620"
export CAVECREW_INVESTIGATOR_MODEL="gpt-4o"

The cavecrew-model-overrides.js hook applies these overrides at install time and persists them in the generated agents/*.md files. This allows you to use high-capability models for complex reviews while keeping faster models for simple investigations.

Summary

• Cavecrew subagents are three specialist agents (investigator, builder, reviewer) defined in agents/cavecrew-*.md files that extend the Caveman AI coding agent.
• Token efficiency is the primary benefit: the investigator cuts search costs from ~2k to ~700 tokens, while the reviewer delivers 70% savings over prose reviews.
• Surgical precision characterizes the builder, which handles edits of ≤2 files and returns only the diff.
• Raw output injection allows the main agent to consume structured data directly and orchestrate complex workflows like parallel scouting.
• Model overrides via CAVECREW_*_MODEL environment variables let you customize which LLM powers each subagent.

Frequently Asked Questions

How do I invoke a cavecrew subagent during a session?

Use the slash command syntax /cavecrew-investigator, /cavecrew-builder, or /cavecrew-reviewer followed by a quoted instruction. For example, /cavecrew-investigator "list callers of fetchData" executes the investigator and returns a concise list of code locations.

What token savings do cavecrew subagents provide compared to standard agent queries?

The investigator subagent reduces token consumption from approximately 2,000 tokens (for a verbose Explore result) to roughly 700 tokens by returning structured location data. The reviewer subagent achieves approximately 70% cost savings by emitting single-line findings instead of prose paragraphs.

Can I use different LLM models for each cavecrew subagent?

Yes. Export the environment variables CAVECREW_REVIEWER_MODEL, CAVECREW_BUILDER_MODEL, or CAVECREW_INVESTIGATOR_MODEL before starting the session. The src/hooks/cavecrew-model-overrides.js hook reads these values and inserts the specified model into the corresponding agent definition.

Why does the builder subagent not specify a model in its configuration?

The builder intentionally omits a model: line in agents/cavecrew-builder.md to default to the session's active LLM. This design ensures surgical edits use the same model context as the main agent unless you explicitly override it via CAVECREW_BUILDER_MODEL.

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