# Internal Architecture of Cavecrew Subagents: 3-Agent Pipeline for Context Efficiency > Explore the internal architecture of Cavecrew subagents. Learn how the 3-agent pipeline optimizes context efficiency, reducing token usage by 60% with specialized roles and compressed output. - Repository: [Julius Brussee/caveman](https://github.com/JuliusBrussee/caveman) - Tags: internals - Published: 2026-07-12 --- **TLDR:** The cavecrew meta-skill deploys three specialized subagents—investigator, builder, and reviewer—that use compressed, line-oriented output formats to reduce token consumption by approximately 60% compared to standard exploration agents. The cavecrew subagents in the JuliusBrussee/caveman repository implement a delegation pattern that splits complex coding tasks across three purpose-built agents. By constraining each subagent to specific tools and enforcing a terse **caveman-compressed** output format, the architecture minimizes context window usage while maintaining high-precision code operations. ## The Three Subagents and Their Specialized Roles The cavecrew architecture divides work into three distinct pipelines, each defined in its own agent markdown file within the `agents/` directory. ### cavecrew-investigator **cavecrew-investigator** is a read-only code locator defined in [`agents/cavecrew-investigator.md`](https://github.com/JuliusBrussee/caveman/blob/main/agents/cavecrew-investigator.md). It answers "where is X defined?" and "what calls Y?" using a restricted toolset: - **Tools:** `Read`, `Grep`, `Glob`, `Bash` - **Model:** `haiku` (specified in front-matter) - **Output format:** ` — `symbol` — <≤ 6‑word note>` This compressed format yields approximately 60% fewer tokens than a plain Explore call, delivering results like `src/pages/render.ts:12 — `renderPage` — renders the homepage` instead of verbose prose. ### cavecrew-builder **cavecrew-builder** handles surgical edits on 1-2 files, as defined in [`agents/cavecrew-builder.md`](https://github.com/JuliusBrussee/caveman/blob/main/agents/cavecrew-builder.md). It is architecturally constrained to small-scale modifications: - **Tools:** `Read`, `Edit`, `Write`, `Grep`, `Glob` - **Model:** Inherits the session default (no explicit override in front-matter) - **Output format:** ` — ` plus a verification line Attempting to delegate a 5-file refactor to this agent wastes tokens because it returns `too-big.` per its contractual constraints. ### cavecrew-reviewer **cavecrew-reviewer** performs diff, branch, and file reviews according to [`agents/cavecrew-reviewer.md`](https://github.com/JuliusBrussee/caveman/blob/main/agents/cavecrew-reviewer.md): - **Tools:** `Read`, `Grep`, `Bash` - **Model:** `haiku` - **Output format:** `path:line: : . .` This emits one-line findings with severity emojis (e.g., `src/api/auth.ts:82: 🔴 bug: missing auth check before token refresh.`), enabling rapid scanning without prose overhead. ## How Context Reduction Works The **caveman-compressed** front-matter declared in each agent file instructs the main thread to treat tool results as raw tokens. When a subagent finishes, its compressed result is injected verbatim into the main context. Because the output is already a compact, line-oriented table rather than free-form prose, the main thread avoids allocating extra tokens for parsing. According to the source documentation in [`skills/cavecrew/SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/cavecrew/SKILL.md), a 2,000-token Explore call costs approximately 2,000 tokens of context, while the same investigation from `cavecrew-investigator` costs only ~700 tokens. This **3× token reduction** scales across multiple delegations, preventing context exhaustion during complex sessions (e.g., 20 delegations avoid window limits). ## Configuration and Model Overrides The architecture supports per-agent model selection without rebuilding the repository. The hook [`src/hooks/cavecrew-model-overrides.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/cavecrew-model-overrides.js) injects environment variables into the agent front-matter at install time: - `CAVECREW_INVESTIGATOR_MODEL` - `CAVECREW_BUILDER_MODEL` - `CAVECREW_REVIEWER_MODEL` This allows fine-tuning of model costs and capabilities for each specific pipeline stage while maintaining the compressed output contracts defined in the agent files. ## Chaining Patterns for Complex Workflows The meta-skill defined in [`skills/cavecrew/SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/cavecrew/SKILL.md) documents standard chaining patterns that maximize context efficiency: - **Locate → Fix → Verify:** The most common pattern spawns investigator to locate code, builder to apply the fix, and reviewer to verify the change. - **Parallel Scout:** Spawn 2-3 investigator calls simultaneously to gather definitions, callers, and tests, then aggregate results before proceeding to the next phase. These patterns ensure that context-intensive work happens in parallel subagents rather than accumulating in the main thread's context window. ## Practical Examples ### Spawning an Investigator ```yaml # User prompt to main thread Delegate to subagent: locate where the function `renderPage` is defined. ``` **Injected result** (~700 tokens instead of ~2,000): ```text Defs: - src/pages/render.ts:12 — `renderPage` — renders the homepage - src/components/header.ts:45 — `renderPage` — used in header component 2 defs, 0 callers. ``` *This output follows the contract defined in [`agents/cavecrew-investigator.md`](https://github.com/JuliusBrussee/caveman/blob/main/agents/cavecrew-investigator.md) (lines 38-44).* ### Surgical Edit with Builder ```yaml # Prompt to main thread Spawn builder: fix typo in src/utils/helpers.ts line 27. ``` **Compressed receipt**: ```text src/utils/helpers.ts:27-27 — replace `recieve` with `receive`. verified: re-read OK ``` *Matches the format specified in [`agents/cavecrew-builder.md`](https://github.com/JuliusBrussee/caveman/blob/main/agents/cavecrew-builder.md) (lines 28-34).* ### Diff Review with Reviewer ```yaml # Prompt Run reviewer on the latest PR diff. ``` **One-line findings**: ```text src/api/auth.ts:82: 🔴 bug: missing auth check before token refresh. src/api/auth.ts:115: 🟡 risk: no timeout on external request. totals: 1🔴 1🟡 ``` *Exactly the output contract in [`agents/cavecrew-reviewer.md`](https://github.com/JuliusBrussee/caveman/blob/main/agents/cavecrew-reviewer.md) (lines 24-30).* ## Summary - **Three specialized subagents** split work into read-only location (`cavecrew-investigator`), surgical editing (`cavecrew-builder`), and review (`cavecrew-reviewer`) phases. - **Compressed output formats** deliver approximately 60% token reduction versus vanilla exploration by using line-oriented tables instead of prose. - **Model overrides** via [`src/hooks/cavecrew-model-overrides.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/cavecrew-model-overrides.js) enable per-agent configuration through environment variables without repository rebuilds. - **Chaining patterns** like Locate → Fix → Verify and Parallel Scout distribute context load across subagents to prevent window exhaustion. ## Frequently Asked Questions ### How much token reduction do cavecrew subagents provide? The cavecrew subagents achieve approximately **60% token reduction** compared to standard exploration agents, representing roughly 3× more efficient context usage. For example, a code location task consuming ~2,000 tokens in a vanilla Explore agent requires only ~700 tokens when handled by `cavecrew-investigator`. ### What is the difference between cavecrew-investigator and cavecrew-builder? **cavecrew-investigator** is strictly read-only, utilizing tools like `Grep`, `Glob`, and `Bash` to locate definitions and callers without modifying files. **cavecrew-builder** performs surgical edits using `Edit` and `Write` tools but is architecturally constrained to 1-2 file modifications; it returns `too-big.` if delegated larger refactoring tasks. ### Can I configure different LLM models for each subagent? Yes. The repository includes [`src/hooks/cavecrew-model-overrides.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/cavecrew-model-overrides.js), which injects environment variables (`CAVECREW_INVESTIGATOR_MODEL`, `CAVECREW_BUILDER_MODEL`, `CAVECREW_REVIEWER_MODEL`) into each agent's front-matter at install time. This allows you to assign cheaper models like `haiku` to investigators while using more capable models for builders, without modifying the core agent definitions. ### What happens if I delegate a large refactoring task to cavecrew-builder? The agent will return `too-big.` and refuse the task. According to the skill documentation in [`skills/cavecrew/SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/cavecrew/SKILL.md), attempting to use the builder for 5-file refactors wastes tokens because the agent is explicitly designed for surgical edits on 1-2 files. Large refactors should be broken into smaller chunks or handled directly by the main thread.