Claude Code

Claude Code Subagents: Delegate Repo-Wide Search Without Poisoning the Main Context Window

Sahil Kathpal

• 4 min read

Repo-wide search is one of the easiest ways to ruin an agent session. The main thread reads dozens of files, follows dead ends, and keeps all that intermediate context around while trying to implement a focused change.

Claude Code subagents are a useful escape hatch. They run in isolated context, inspect the codebase, and return a concise summary to the main session.

The short version

  • Use subagents for read-heavy exploration, not as a default replacement for normal work.
  • A search subagent should return file paths, symbols, confidence, and next actions—not long transcripts.
  • Restrict tools: most search subagents need Read, Grep, and Glob, not write access.
  • Write task-shaped subagents, not vague role-shaped ones.
  • Subagents save main-context quality but can increase token use if over-spawned.

The problem: search creates context debt

A typical agent implementation flow starts with exploration:

  • find all call sites of a function;
  • inspect nearby tests;
  • check whether a similar pattern exists;
  • read configuration and generated types;
  • discard half the leads.

Humans forget the dead ends. Agent sessions often do not. Once the main context contains unrelated files and speculative reasoning, later implementation steps can anchor on the wrong details.

Subagents help because their intermediate work happens in a separate context window. Claude Code's extension overview describes subagents as isolated execution contexts that return summarized results. That is exactly the shape repo-wide search needs.

Define a search subagent

Create a project-scoped subagent when the workflow is repo-specific:

.claude/agents/repo-search.md

Example:

---
name: repo-search
description: Use for read-only repo-wide investigation. Finds relevant files, symbols, call sites, tests, and conventions, then returns a concise implementation-oriented summary. Do not edit files.
tools: Read, Grep, Glob
---

You are a read-only repository search agent.

Given a focused question, inspect the repository and return:

1. The likely files to modify.
2. Important call sites and tests.
3. Existing conventions or similar implementations.
4. Risks, unknowns, and confidence level.
5. A short recommended next step.

Do not include long file excerpts unless necessary. Prefer paths, symbol names, and line references. Do not modify files.

The description matters. Claude Code uses it when deciding whether to delegate. "Helps with code" is too vague. "Read-only repo-wide investigation" is specific enough to invoke only when useful.

Ask for summaries that support decisions

A bad search result is a wall of copied code. A good result is a decision aid.

Prompt the subagent like this:

Use @repo-search to find how billing plan limits are enforced.
Return the central policy module, call sites that check limits, tests that cover limit failures, and any migration/config files that define plan values.

The main session should receive something like:

Likely edit targets:
- packages/billing/src/limits.ts: central limit lookup
- packages/api/src/routes/projects.ts: checks limit before project creation

Tests:
- packages/billing/test/limits.test.ts covers plan lookup
- packages/api/test/projects.test.ts has failure case for project limit

Convention:
- Route handlers call assertWithinPlanLimit() rather than reading plan config directly.

Risk:
- Enterprise overrides come from org_features table; do not hard-code plan names.

That is much more useful than importing ten files into the main thread.

Use subagents for parallel hypotheses

Subagents are especially effective when the search space branches:

  • "Find frontend validation path."
  • "Find backend authorization path."
  • "Find tests and fixtures."
  • "Find old implementation removed in previous migration."

Each branch can run in isolation and return a compact summary. The main session then merges the findings into a plan.

Do not confuse this with full parallel development. If two workers will edit files, use separate sessions and worktrees. A search subagent should be mostly read-only.

Keep write access out

Search agents do not need Write or Edit. Restricting tools has two benefits: it reduces accidental modifications, and it makes the subagent's result easier to trust. If the summary says "likely edit target," you know it did not already mutate the code.

For security-sensitive repositories, also consider separate subagents for:

  • dependency documentation lookup;
  • database schema discovery;
  • test discovery;
  • security-sensitive path review.

Each can have a smaller tool surface.

When not to use a subagent

Subagents are not free. Each one has its own context and token usage. Do not spawn ten subagents to answer a question that one rg command can answer.

Avoid subagents when:

  • the relevant file is already known;
  • the search result must remain fully visible in the main transcript;
  • the task needs continuous back-and-forth rather than a single summary;
  • the repository is tiny;
  • the subagent would need to reread the same huge file as several other subagents.

A good heuristic: use a subagent when the investigation may read more context than the final answer should keep.

Gotchas

Subagents can miss project context. Put durable conventions in CLAUDE.md or in the subagent prompt so the search worker knows how to interpret the repo.

Summaries can be lossy. Ask for line references and confidence levels so the main agent can verify before editing.

Over-delegation can increase cost and latency. Task-shaped subagents are better than role-shaped swarms.

We're building Grass for teams that want this kind of separation at the task level, not just inside one context window. Grass runs coding agents in isolated sandboxes and brings back the useful result, so the main workflow stays focused on review and decision-making. You can try it at https://codeongrass.com.

Conclusion

Claude Code subagents are a context-management primitive. Use them to isolate repo-wide search, dead-end exploration, and parallel investigation. Keep them read-only, ask for concise decision-oriented summaries, and let the main session spend its context budget on planning and implementation.

Sources

  • Claude Code feature overview: subagents as isolated execution contexts returning summaries
  • Claude Code subagent documentation and community reports on context management