What Are the Cavecrew Subagents? A Technical Guide to Caveman’s AI Agent Architecture

The cavecrew subagents are three lightweight, purpose-built AI agents—reviewer, builder, and investigator—that extend the Caveman toolchain with focused code analysis, safe editing, and symbol navigation capabilities.

The JuliusBrussee/caveman repository implements a modular agent system where these cavecrew subagents operate as markdown-defined specialists in the agents/ directory. Each subagent declares its own toolset, output format, and execution constraints, allowing the Caveman runtime to invoke the right capability for specific development tasks without interactive prompting.

The Three Cavecrew Subagents Explained

The cavecrew suite consists of three distinct agents, each defined in its own markdown file and optimized for a narrow scope of operations.

cavecrew-reviewer: Automated Code Review

The cavecrew-reviewer subagent performs line-level code analysis and categorizes findings by severity. According to the source definition in agents/cavecrew-reviewer.md, it tags issues as bug, risk, nit, or question, providing actionable feedback on pull requests and file diffs.

Typical invocation targets PR audits and problem detection:

caveman "review this pull request" --agent cavecrew-reviewer

The agent outputs structured findings with line references and severity indicators:

src/utils.ts:42: 🔴 bug: token expiry uses `<` not `<=`. Off-by-one allows expired tokens 1 tick.
src/api.js:118: 🟡 risk: pool not closed on error path. Add `try/finally`.
totals: 1🔴 1🟡

cavecrew-builder: Safe Single-File Edits

The cavecrew-builder subagent handles targeted, non-destructive modifications within agents/cavecrew-builder.md. It restricts operations to safe, single-file changes—typos, small refactors, and comment removal—returning a diff receipt rather than applying changes silently.

Use this agent for precise surgical edits:

caveman "fix typo in src/main.js line 10" --agent cavecrew-builder

The receipt format confirms the change and verification:

src/main.js:10-10 — replace `recieve` with `receive`.
verified: re-read OK

cavecrew-investigator: Read-Only Code Navigation

The cavecrew-investigator subagent, defined in agents/cavecrew-investigator.md, executes read-only location queries across the codebase. It maps symbol definitions, locates call sites, and traces imports without modifying files.

Query symbol locations with:

caveman "where is `safeWriteFlag` defined?" --agent cavecrew-investigator

Output appears in compressed tabular format:

Defs:
- hooks/caveman-config.js:81 — `safeWriteFlag` — atomic write w/ O_NOFOLLOW
- hooks/caveman-config.js:160 — `readFlag` — paired reader
Callers:
- hooks/caveman-mode-tracker.js:33,87
- hooks/caveman-activate.js:40

Integration Architecture and Model Overrides

The Caveman runtime dynamically configures these subagents through the src/hooks/cavecrew-model-overrides.js hook. During session initialization, this hook reads environment variables to inject custom LLM configurations into each agent’s frontmatter.

Three environment variables control model selection:

• CAVECREW_REVIEWER_MODEL
• CAVECREW_BUILDER_MODEL
• CAVECREW_INVESTIGATOR_MODEL

When set, the patchFrontmatterModel function within the hook patches the corresponding markdown file (e.g., agents/cavecrew-reviewer.md) with a model: directive, allowing users to swap from the default haiku to alternatives like gemma or claude-2:

export CAVECREW_REVIEWER_MODEL=gemma
export CAVECREW_BUILDER_MODEL=claude-2
caveman

This mechanism respects both installed plugin layouts and source checkouts, ensuring the repository remains unmodified while customizing agent behavior.

Practical Implementation Examples

Customizing Agent Intelligence

Override the default LLM for specific tasks without editing source files:

# Configure specialized models per subagent

export CAVECREW_REVIEWER_MODEL=gemma
export CAVECREW_INVESTIGATOR_MODEL=claude-2

# Launch Caveman with patched configurations

caveman

The hook injects model: gemma into agents/cavecrew-reviewer.md runtime without altering the git-tracked file.

Executing a Security Audit

Invoke the reviewer to audit authentication logic:

caveman "audit src/auth.ts for security issues" --agent cavecrew-reviewer

The agent utilizes the Read, Grep, and Glob tools to analyze scope while respecting its constraint against destructive commands.

Tracing Symbol Dependencies

Use the investigator to map dependency chains:

caveman "list all uses of config loader" --agent cavecrew-investigator

This leverages read-only tools (Read, Grep) to generate definition tables without filesystem modifications.

Summary

• Three specialized agents comprise the cavecrew suite: reviewer (diagnostics), builder (safe edits), and investigator (symbol navigation).
• Markdown-defined architecture places agent configurations in agents/cavecrew-reviewer.md, agents/cavecrew-builder.md, and agents/cavecrew-investigator.md.
• Dynamic model injection via src/hooks/cavecrew-model-overrides.js allows LLM swapping through environment variables without repository mutations.
• Safety-first design restricts the builder to single-file edits and the investigator to read-only operations, while the reviewer provides severity-graded analysis.
• Test coverage in tests/test_cavecrew_model_overrides.js validates that model overrides work correctly across installation types.

Frequently Asked Questions

How do I switch the LLM backend for a specific cavecrew subagent?

Set the corresponding environment variable before launching Caveman. For the reviewer, export CAVECREW_REVIEWER_MODEL=gemma (or your preferred model identifier). The cavecrew-model-overrides.js hook patches the agent’s frontmatter at runtime without modifying the source repository.

Can cavecrew subagents modify multiple files at once?

No. The cavecrew-builder subagent is explicitly scoped to safe, single-file edits as defined in agents/cavecrew-builder.md. For multi-file refactoring, use Caveman’s interactive mode rather than the constrained cavecrew subagents.

What tools do the cavecrew subagents have access to?

Each subagent declares its toolset in its markdown definition. The reviewer and investigator typically use Read, Grep, Bash, and Glob, while the builder adds Edit and Write capabilities. The Caveman runtime selects the appropriate toolset based on the agent’s declared requirements.

Where is the cavecrew integration tested?

The model override logic is validated in tests/test_cavecrew_model_overrides.js, which confirms that environment-driven model injection works correctly for both installed plugin layouts and direct source checkouts.

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