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

> Discover Cavecrew subagents: reviewer, builder, and investigator. Learn how these AI agents enhance Caveman's code analysis, editing, and navigation for developers.

- Repository: [Julius Brussee/caveman](https://github.com/JuliusBrussee/caveman)
- Tags: technical-guide
- Published: 2026-08-22

---

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

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

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

```bash
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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/agents/cavecrew-reviewer.md)) with a `model:` directive, allowing users to swap from the default *haiku* to alternatives like *gemma* or *claude-2*:

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

```bash

# 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`](https://github.com/JuliusBrussee/caveman/blob/main/agents/cavecrew-reviewer.md) runtime without altering the git-tracked file.

### Executing a Security Audit

Invoke the reviewer to audit authentication logic:

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

```bash
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`](https://github.com/JuliusBrussee/caveman/blob/main/agents/cavecrew-reviewer.md), [`agents/cavecrew-builder.md`](https://github.com/JuliusBrussee/caveman/blob/main/agents/cavecrew-builder.md), and [`agents/cavecrew-investigator.md`](https://github.com/JuliusBrussee/caveman/blob/main/agents/cavecrew-investigator.md).
- **Dynamic model injection** via [`src/hooks/cavecrew-model-overrides.js`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/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`](https://github.com/JuliusBrussee/caveman/blob/main/tests/test_cavecrew_model_overrides.js), which confirms that environment-driven model injection works correctly for both installed plugin layouts and direct source checkouts.