File of the day
A Claude Code subagent that finds code without eating your context
Slava Sazhin 24 September 2026 2 min read 0 views
A Claude Code subagent that searches unfamiliar code in its own context and hands back only paths and line numbers. One file, a minute to install.
Today's file is a subagent for Claude Code. You ask where something lives in code the session has never seen, the search runs in a separate agent, and what comes back is addresses rather than file contents.
Why a separate agent
Everything the main session reads stays in its context. To find where a function is defined and who calls it, it may open a dozen files, and by the time the real edit starts a good part of the context is taken up by text it no longer needs. A subagent reads in its own context, and only its answer comes back, in lines like these:
app/Services/Billing.php:142 - charge() is defined here app/Http/Controllers/CheckoutController.php:58 - the only caller
Plus two or three lines on how the thing is built. Its prompt calls retelling a file instead of giving addresses a failed job.
What to change
Ours runs on opus with effort: high, because a wrong address costs more than the search. Put sonnet or haiku in the model line for a cheaper search, or inherit to run it on whatever the main session runs on.
It has no Edit or Write tool, so it cannot change a file through them. It does have Bash, for grep and find, which makes read only a rule in its prompt rather than a lock. If you want the lock, take Bash out of the tools line.
Install
One file goes into ~/.claude/agents/, and a new session picks it up. The word PROACTIVELY at the start of its description nudges Claude to call it on its own before an edit. The command and a one-line check are in the note below.
The files
---
name: code-scout
description: PROACTIVELY. Call BEFORE an edit when you need to understand where things live in unfamiliar code: find the definition, all calls, similar patterns, how a section is built. Searches the code in its own context and returns only a short answer with paths and line numbers, without retelling files. Read only, decides nothing and edits nothing. Not needed for a single known path - such a file is opened directly.
tools: Read, Grep, Glob, Bash
model: opus
effort: high
---
You are a code scout. You are called so that the search runs in your context, not in the main conversation.
Your job is to find the places and name them by address.
## What you do
- You search for what the prompt asks: where it is defined, where it is called, how it is built, whether there is
a similar pattern. Tools - `grep`, `find`, `Glob`, reading files.
- You read exactly as much as needed to name the place and briefly say what happens
there. You read a whole file only when there is no answer without it.
## What you return
A short answer from which the caller goes straight to editing. For each finding:
path:line_number - what is there (one line)
Plus 2-3 lines of summary: how the found thing is built and what the caller should know before editing.
Do not copy file contents into the answer: a quote only when the finding is unclear without these 1-3
lines. Retelling a file instead of addresses is a failed job: the caller called you precisely
so that the contents stay with you and the addresses go to them.# How to install the code scout agent
The agent searches code in its own context and returns only addresses to the main session: the path and the line number. The main session does not spend its context on reading files, and the search itself runs on the model you assign to the agent.
Where to put it:
```
mkdir -p ~/.claude/agents
cp agent-code-scout.md ~/.claude/agents/
```
What to fill in: in the `model` line, the model the search will run on: `haiku`, `sonnet`, `opus`, `fable`, a full model ID or `inherit` (the main session's model). In the `effort` line, the effort level: `low`, `medium`, `high`, `xhigh` or `max`; which levels are available depends on the model.
How to check that it works: open a new Claude Code session and ask:
```
Using the code-scout agent, find where the function <name> is defined in this project
```
While the agent is running, the `/tasks` command shows its row and the model it runs on. The answer will come as lines like `path:line_number - what is there`, not as file contents.Was this article worth your time?
Give Claude a computer of its own
Your own Linux machine with Claude Code on it, working around the clock while your laptop is shut. From €2.99 a month.