Build your own coding agent (TypeScript) · Chapter 3 of 20
Editing safely
By the end of this chapter Kaarigar changes files the way Claude Code does: it names the exact text to replace, the text must appear once, the file must have been read since it last changed, and the result shows the lines around the change. Whole-file writes are for new files only. You will know why each of those rules exists, because each one stops a real failure you will see first. 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
- TypeScript
- In the all labs plan
The first 2 chapters of Build your own coding agent (TypeScript) are free. This one comes with the all labs plan.
Why you need this
Chapter 2 ended with a warning. Here it is in full: MD-105 (Mumbai's new tariff, on line 51 of the 127-line src/tariff.ts) with 40-line pages and chapter 1's write_file.
1 read_file src/tariff.ts -> lines 1-40 of 127
2 read_file src/tariff.ts offset 41 -> lines 41-80 of 127
3 write_file src/tariff.ts -> ok
4 run_tests -> 6 tests fail
answer: Fixed MD-105 (minimum fare ₹26; ₹17.14 a km) in src/tariff.ts.
Its tests pass; 6 other tests still fail (not this issue).
The model read 80 lines, found Mumbai, and then had to send the whole file back, because write_file is the only way it has to change anything. It wrote the 80 lines it had seen, Mumbai fixed, and then this:
nagpur: {
city: 'Nagpur',
minKm: 1.5,
// ... rest of the file unchanged ...
82 lines for a 127-line file. Most of Nagpur, then Kolhapur, Satara, tariffFor and cities were replaced by a comment. Its own tests passed, so its answer sounds fine; 6 tests broke. Rukhsana: "A fix that breaks six tests is not a fix."
This is not a lab-model quirk. Asked to write out a long file, real models often write the part they are changing and put "rest of the file unchanged" where the rest should be: they are summarising, the way you would in a code review comment. Even when a model copies every line, it pays for it: chapter 1's MD-110 cost 524 completion tokens to change one line. Writing a whole file to change a line is slow, costly and fragile.
What you build: 4 tasks
Each task has tests. You write the code in the lab's editor and press Check.
- Task 1
stamps.ts: read stamps
Write and export a class Stamps with mark(file), which remembers the file as it is now (a sha256 of its bytes), and check(file), which returns null when the file is as it was at the last mark, 'read the file first: ...' when it was never marked, and 'the file changed since you read it: ...' when it differs now. One stamp per file, kept inside each instance.
Export stampedRead(stamps): chapter 2's read_file (readTool) whose run also marks join(ctx.root, path), unless the result starts with error:.
- Task 2
edit-file.ts: edit_file, search and replace
Write and export editFile(root, stamps, path, oldText, newText). Refuse with a result starting error:, in this order: a file that does not exist (error: PATH does not exist); a stamp that is not null (error: and its message); an empty oldText; oldText not in the file (error: old_text was not found in PATH: ...); oldText in N places (error: old_text matches N places in PATH: ...).
Else replace that one place, write the file, mark its stamp, and return ok: PATH changed. The lines around it now: and, on the next lines, readFile(root, path, L - 2, K + 4) without its footer (L: the line the change starts on, at least 1 after the - 2; K: the lines in newText).
Export editTool(stamps): a Tool named edit_file with path, old_text and new_text, all required.
- Task 3
create-file.ts: create_file, for new files only
Write and export writeNewFile(root, path, content). Refuse, writing nothing, a file that exists (error: PATH already exists: change it with edit_file, not by writing it again) and content with a placeholder for lines left out (// ... rest of the file unchanged ...). Else make its folders, write it, and return ok: wrote PATH (N lines).
Export createTool: a Tool named create_file with path and content, both required.
- Task 4 · interview question
Interview: two-hands.ts, whose change survives?
Run runAgent on MD-101 twice, each on a fresh checkout, with SYSTEM: write_file (withRukhsana(readTool), writeTool, testsTool), then edit_file (withRukhsana(stampedRead(stamps)), editTool(stamps), testsTool, with one new Stamps). withRukhsana is given: Rukhsana saves a line to src/night.ts right after Kaarigar's first read of it.
Print one line per way: write_file: fixed, her line kept, N refused (not fixed from grade; lost when src/night.ts no longer has HER_LINE; N: run.calls whose result starts with error:).
What you will learn
- Search and replace: the edit tool every coding agent has, and why the old text must appear exactly once.
- Errors that teach: the result of a failed edit tells the model what to do next.
- Read stamps: never edit a file the model has not read, or one that changed since.
- Two edits in one reply, and why the second one fails.
- New files only: a write tool that cannot overwrite.
More in The tools
Build "Editing safely" 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.
The first 2 chapters of Build your own coding agent (TypeScript) are free. This one comes with the all labs plan.