> ## Documentation Index
> Fetch the complete documentation index at: https://docs.caveman.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Exploration and Delegation with Caveman Subagents

> Use Caveman's read-only explorer and compact delegation guides to keep search transcripts out of the main agent context and return only the evidence needed.

Broad repository search can consume main agent context before editing begins. Caveman offers read-only explorer and compact delegation guides that keep search transcripts separate and return only the evidence needed by the solver.

## FastContext-style explorer

The CLI supplies a Claude Code agent file named `fastcontext`. It is inspired by FastContext research but does not implement the paper's trained model or inherit the paper's reported results.

Install for current project:

```bash theme={"dark"}
cave explore install
```

Install for current user:

```bash theme={"dark"}
cave explore install --user
```

`explore` is a legacy alias for:

```bash theme={"dark"}
caveman tools skills install caveman-explore --no-pixel
```

Current installer supports Claude Code. Codex integration is withheld until transcript isolation has dedicated proof.

### Permission boundary

The explorer agent has only Read, Glob, and Grep tools. It cannot edit files or run commands. Its contract returns one verified citation per line:

```text theme={"dark"}
path/to/file.ext:START-END  reason location matters
```

Line ranges must come from files the explorer read. When nothing relevant exists, the contract requires `no relevant locations found` instead of a guessed citation.

### When to use explorer

Use it for cold-start localization, broad cross-file relationships, or search that would otherwise add many file reads to solver context. Skip it when the task already names an exact file or symbol, or earlier evidence provides a usable location.

Isolation is mechanism, not outcome guarantee. Explorer call adds model usage. Compare total task usage and resolution quality before claiming net benefit.

## Cavecrew

`cavecrew` is a decision guide for three compact Claude Code subagents:

| Subagent | Permission and output | Intended scope |
| - | - | - |
| Investigator | Read-only location list | Definitions, callers, tests |
| Builder | Surgical edit | One or two known files |
| Reviewer | Compact findings | Diff or file review |

Builder refuses scopes of three or more files. Main agent should own larger refactors and cross-component decisions.

### Model overrides

Set environment variables before launching Claude Code to override the default model for each subagent:

| Env var | Agent |
| - | - |
| `CAVECREW_REVIEWER_MODEL` | `cavecrew-reviewer` |
| `CAVECREW_BUILDER_MODEL` | `cavecrew-builder` |
| `CAVECREW_INVESTIGATOR_MODEL` | `cavecrew-investigator` |

Overrides patch only the installed agent frontmatter model line; empty variables do nothing. A plugin update or reinstall can replace the patch. Use the same model name strings you would use in any Claude Code agent frontmatter (for example, `haiku`, `sonnet`, `opus`).

### Example chaining

Locate, fix, verify (most common):

1. `cavecrew-investigator` returns site list (`path:line`, symbol, note)
2. Main thread picks one or two sites, hands paths to `cavecrew-builder`
3. `cavecrew-reviewer` audits the resulting diff

Parallel scout: spawn two or three `cavecrew-investigator` calls in one message with different angles (definitions, callers, tests). Aggregate in main.

## Optional delegate tool

The CLI can register `caveman-delegate` MCP server when `execute.delegate` is enabled. It is opt-in because delegated work consumes separate permissions and model usage.

```bash theme={"dark"}
caveman tools config set execute.delegate true
caveman tools mcp install claude --server caveman-delegate
```

Host agent and server own exact sandbox and approval behavior. Enabling the feature does not grant broader permission than host configuration allows.

## Evidence rules

* Count explorer and delegated calls in total usage.
* Do not infer complete-task savings from shorter returned prose.
* Validate citations before edits when line drift is possible.
* Keep failure and no-result cases in benchmark.
* Treat paper results as external research, not package performance.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.