Build your own coding agent · Chapter 2 of 20
Tools to find code
By the end of this chapter Kaarigar can find code that nobody pointed it to: it lists the repository's files, reads a file a page at a time with line numbers, and searches the code the way you would with grep. And you can say, with numbers, what each of those tools is worth. Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.
- Part: The tools
- 4 tasks
- Python
- Free chapter
Free with a Google or GitHub sign-in, like the first 2 chapters of every lab.
Why you need this
Some issues name their file. MD-101 says "is_night in meterdown/night.py decides it", and chapter 1's loop went straight there. Most issues do not. MD-102 is a rider's complaint about waiting charges, and all it gives is a name: "See waiting_charge." Which file is that in? A developer would search for it. Chapter 1's Kaarigar has three tools, read_file, write_file and run_tests, and none of them can search or even list what files exist.
Here is MD-102 with those tools:
1 read_file meterdown/waiting_charge.py
-> error: [Errno 2] No such file or directory: '/tmp/meterdown-runs/MD-102-6mqa7617/meterdown/meterdown/waiting_charge.py'
answer: I could not find `waiting_charge`: I tried meterdown/waiting_charge.py,
and I have no way to search the code or list its files.
The model guessed a path from the name, and the guess was wrong. A model that cannot see the repository makes up a file name that sounds right, the way you might guess a URL. Real models guess better than this one, and they still guess: a repository has its own names, and nothing in an issue says what they are. The run cost two requests and fixed nothing. And look at the error: Python's own message, with the full path of the checkout on this machine. The model now knows where the lab keeps its files, and still not where waiting_charge is.
Kedar puts it plainly: "Before an agent can fix code, it has to find it. That is most of what a coding agent does all day."
The lesson
Tools as objects
From this chapter on, every tool is an object of the same shape, and the loop from chapter 1 is given to you in agent.py:
@dataclass
class Tool:
name: str
description: str
parameters: dict # JSON Schema
run: Callable[[Args, Ctx], str] # run(args, ctx) -> the result's text
run_agent(root, task, Agent(SYSTEM, tools)) offers each tool's name, description and parameters to the model, and when the model asks for one, calls its run(args, ctx) (where ctx.root is the checkout) and sends back what it returns. The run comes back as a Run: answer, stop, steps, messages, calls (the trail of chapter 1, ready made) and usage (usage.prompt adds up the prompt tokens of every request). agent.py also gives chapter 1's three tools as objects: raw_read_tool, write_tool and tests_tool, and obj(properties, required), which writes a JSON Schema object for a tool's parameters.
Listing the files
The simplest way to find a file is to look at all of them. A listing for a model is not ls -R. Some things never belong in it:
.git: git's own files. A fresh MeterDown checkout has 57 of them, and not one is code.__pycache__and.pytest_cache: Python's compiled files and pytest's notes to itself. Machine-made, binary or noise, and never what an issue is about. (In a JavaScript project the same rule leaves outnode_modules; in yours, maybe.venv.)- Symlinks: a checkout's
configis a link to../fleet-config, the ops team's folder outside the repository. A listing that follows it shows the model files it must never touch. (Chapter 6 is about that folder.)
What is left, sorted, relative to the repository, is 27 files:
.gitignore
AGENTS.md
README.md
meterdown/__init__.py
meterdown/distance.py
...
vendor/meter_sdk/README.md
vendor/meter_sdk/__init__.py
Paths relative to the repository matter: they are what the model will send back in its next read_file. With a listing on offer, MD-102 goes like this:
1 list_files
2 read_file meterdown/receipt.py
3 read_file meterdown/waiting.py
4 write_file meterdown/waiting.py
5 run_tests
answer: Fixed MD-102 (free minutes first) in meterdown/waiting.py. The tests pass (44 passed).
Fixed, in 6 requests. But look at request 2: the model read meterdown/receipt.py first. A listing gives the model names, and it picks by name. MD-102 says "receipts charge waiting from the first minute", so receipt.py looked like a good bet. It was wrong, and a wrong read costs a request and a whole file in every request after it. A model with a listing is a person in a new codebase opening the files whose names sound right.
Reading a page, with line numbers
Chapter 1's read_file sent the whole file. That is fine for meterdown/waiting.py (13 lines) and costly for meterdown/tariff.py (134 lines, the whole of it sent again with every request after). A coding agent reads a page: a range of lines.
print(read_file(root, "meterdown/fare.py", 33, 4))
33 def fare_for(trip: Trip) -> Fare:
34 t = tariff_for(trip.city)
35 km = round_km(trip.km)
36 bags = trip.bags
[lines 33-36 of 43: use offset 37 to read on]
Two things on that page are not in the file, and both are for the model:
- Line numbers: each line starts with its number and a tab. The model can now say "line 35" and mean it. Chapter 4's patches name lines by number, and a model counting lines by itself gets them wrong.
- The footer: when the page ends before the file does, one more line says so, and says how to read on. Without it, the model cannot tell a short file from a cut one.
The footer is not decoration. Here is MD-105 (Mumbai's tariff, on line 55 of meterdown/tariff.py) with 40-line pages, first with the footer:
1 read_file meterdown/tariff.py -> ... [lines 1-40 of 134: use offset 41 to read on]
2 read_file meterdown/tariff.py offset 41 -> ... 55 "mumbai": Tariff(city="Mumbai", ...
and then with the same pages and no footer:
1 read_file meterdown/tariff.py -> ... 40 revised="2025-02-01",
answer: I read meterdown/tariff.py but could not find the line to change.
Same pages, same model. With the footer it read on and found Mumbai. Without it, line 40 looked like the end of the file, and it gave up.
Errors are results. A tool that raises hands the model a traceback, or, like chapter 1's read_file, Python's message with the machine's full path in it. A short line that starts with error: and says what went wrong is what the model can act on: error: meterdown/fares.py does not exist, error: meterdown/waiting.py has 13 lines: offset 40 is past the end, error: assets/logo.png is a binary file (a file with a NUL character in it is not text, and its bytes would be noise in the model's context).
Searching the code
The fastest way to find waiting_charge is the way you would do it: search for it. search_code prints every line that has the text, as path:line: text, the shape grep -rn prints:
print(search(root, "round_fare"))
AGENTS.md:11: - `meterdown/money.py`: rounding and showing rupees (`round_fare`, `format_inr`)
AGENTS.md:26: - Money is rounded once, at the end, with `round_fare`.
meterdown/fare.py:7: from meterdown.money import round_fare
meterdown/fare.py:42: total = round_fare(base + distance + night + waiting + luggage)
meterdown/money.py:7: def round_fare(rupees: float) -> int:
meterdown/receipt.py:4: from meterdown.money import format_inr, round_fare
...
tests/test_money.py:9: assert round_fare(36) == 36
(Trimmed: 13 hits in all.) The model reads every hit and picks the one that defines the name (def round_fare) over the ones that use it. That is why the line's text is there, not only its place. With search, MD-102 starts with search_code("waiting_charge"), and its next request reads meterdown/waiting.py: no listing, no wrong guess, 5 requests.
Three rules keep a search useful:
- Search what the listing shows: no
.git(its commit message has text in it too), no caches, no binary files. - Cut long lines: Mumbai's tariff line is 211 characters, and a generated file can be one line of a megabyte. 160 characters of a line are enough to see what it is.
- Cap the hits:
assertmatches 68 lines in MeterDown. Forty hits and a line saying how many more ([28 more matches: search for something more exact]) tell the model to search better, without flooding its context. A search with no hits says so:no matches for "surge pricing". An empty result looks like a tool that did not run.
Claude Code, Cursor and Codex all give their models tools like these three: a way to list or glob files, a way to read a range of lines, and a search built on grep or ripgrep. Some add more (a map of the repository's symbols, or a search by meaning); the harness labs teach those. The three here are the ones every coding agent has.
What finding costs
Finding is not free. Every listing, every wrong read and every search result goes into the conversation, and the conversation is sent again with every request. So the right way to judge a finding tool is the same as the right way to judge the agent: fixed, steps, and tokens (the prompt tokens of every request, added up: run.usage.prompt). The interview task measures it: MD-102 and MD-104, each with three tool sets, read only, a listing, and a search.
One more thing to notice before chapter 3. Pages solve one problem and make another. MD-105 with the 120-line pages and chapter 1's write_file: the model read lines 1 to 120, then wrote the whole file back from what it had seen, and the 14 lines it never read were gone. Its own tests passed, it said; 6 test files could no longer import the tariff, and broke. A model that writes whole files writes only what it saw. Chapter 3 gives Kaarigar a way to change a file without rewriting it.
Your turn
Write list_files in task 1, the paged read_file in task 2, and search_code in task 3, each a function and a Tool. Then answer the interview question with six runs: what is a search worth?
What you build: 4 tasks
Each task has tests. You write the code in the lab's editor and press Check.
- Task 1
list_files.py: list the files
Write files_of(root): every file under root as a path relative to root (meterdown/fare.py), sorted, leaving out the .git folder, __pycache__, .pytest_cache and symlinks (config is a symlink to a folder outside the repository: never walk into it).
Make list_tool: a Tool named list_files with no parameters whose run returns files_of(ctx.root), one path a line.
Under if __name__ == "__main__":, print every path of a checkout of MD-102, one a line, then N files.
- Task 2
read_file.py: read a page, with line numbers
Write read_file(root, path, offset=1, limit=120): lines offset to offset + limit - 1, each as its number right-aligned in 4 characters, a tab, then the text. When lines are left after the page, add [lines A-B of N: use offset B+1 to read on].
Errors are results starting with error: (never an exception): error: PATH does not exist; error: PATH has N lines: ... for an offset past the end; error: PATH is a binary file for a file with a NUL character.
Make read_tool: a Tool named read_file with path (required) and offset parameters that calls read_file. Under if __name__ == "__main__":, print lines 53 to 56 of meterdown/tariff.py in a checkout of MD-105.
- Task 3
search_code.py: search the code
Write search(root, pattern, limit=40): every line containing pattern (plain text) in the files files_of(root) lists, skipping binary files, as path:line: text (line numbers from 1, the text stripped and cut to 160 characters), files in files_of's order.
No hits: no matches for "PATTERN". More than limit: the first limit lines, then [N more matches: search for something more exact].
Make search_tool: a Tool named search_code with a required pattern parameter. Under if __name__ == "__main__":, print the hits for luggage_per_bag in a checkout of MD-108.
- Task 4 · interview question
Interview: find_code.py, what is a search worth?
For MD-102, then MD-104, run run_agent on a fresh checkout with issue_text(id) and Agent(SYSTEM, tools) three times, with these tools: read only (read_tool, write_tool, tests_tool); + list (list_tool first, then the same); + search (search_tool first, then the same). Grade each run.
Print one line per run, two spaces apart: MD-102 read only fixed N steps T tokens (not fixed when it was not; N is run.steps, T is run.usage.prompt).
What you will learn
- Listing files for a model: which files to show, and which to leave out.
- Reading a page of a file, with line numbers and a footer that says what is left.
- Searching the code: path:line: text, capped.
- Errors as results: short error: lines instead of exceptions and tracebacks.
- What finding costs: the steps and the tokens each way of finding takes.
More in The tools
Build "Tools to find code" yourself
MeterDown, a Pune app for auto-rickshaw fares, has eleven open issues. You build Kaarigar, an agent that fixes them without breaking tests, running risky commands or touching files outside the repository. A real editor and terminal in your browser, AI that explains, and a Check that says when it works.
Free with a Google or GitHub sign-in, like the first 2 chapters of every lab.