Claude Code Nano

Build your own Claude Code. A guided project: you implement a working ~350-line agent in TypeScript — the same core loop the real Claude Code runs — yourself, problem by problem, against a provided read-only test harness.

There is no planner, no graph, no framework hiding the trick. An agent is a model that can ask for things, plus a harness that runs them and reports back, looped until the model stops asking. Six required lectures plus a bonus, one file (index.ts), five sections, ten points. By the end you run your own agent against a real API and watch it find and fix a planted bug in a JavaScript file.

Who this is for

A fluent programmer who is newer to TypeScript / Node specifically: async/await, promises, and the Node APIs this uses (fs, child_process, readline) are explained as they appear, and TypeScript syntax gets light scaffolding. The lectures are direct technical prose — they state how the harness works plainly, without analogies.

What you’ll be able to do

Explain and implement the agent loop from memory: call model → execute tool_use requests → append tool_results → repeat until no tool calls.
Implement the 5 core tools (read / list / write / edit / bash) and explain why edits use unique-string replacement.
Explain how permissions, denials, and tool errors flow back to the model as ordinary messages — and watch a model self-correct.
Run your own agent end-to-end: it finds and fixes a planted bug in fixtures/convert.js.
Read real Claude Code / agent-harness discussions and know exactly what the harness is doing.

The lectures

The course builds one file in dependency order. Each lecture fills exactly one region of index.ts, using the identifiers already declared in the skeleton. index.ts is the only editable file; tests/, fixtures/, and solution/ are read-only harness.

#	Lecture	Builds	Points
01	The Shape of an Agent	The whole spec, hand-traced; environment; Problem 0 warm-up	1
02	Tools I: Eyes	`runTool` dispatch for `read_file`, `list_files`	2
03	Tools II: Hands	`write_file`, `edit_file` (the uniqueness invariant), `bash`	2
04	The Permission Gate	`preview` + `confirm`; async/await for real	1.5
05	The Agent Loop	`callModel` + `agentLoop` — the boss level	2.5
06	The REPL and the Endgame	`main()` REPL, crash recovery, live acceptance run	1
07	Subagents: The Task Tool bonus	The `task` tool — `agentLoop` recurses on itself	+1

Points (10 + 1 bonus)

Self-graded — points exist for pacing, not stakes. Each lecture is earned by its ./ok NN suite going green plus checking your unlock-question answers against the appendix (spoilers, collapsed by default, on each lecture page). Lectures 01–06 are the graded 10; the bonus lecture 07 takes you to 11 out of 10.

Lecture	Points	Earned by
01	1	Problem 0 green (`./ok 00`) + unlock answers
02	2	`./ok 02` green + unlocks
03	2	`./ok 03` green + unlocks — checkpoint: all five tools done
04	1.5	`./ok 04` green + unlocks
05	2.5	`./ok 05` green + unlocks (the boss level)
06	1	`./ok 06` green + unlocks; the live fixture-bug run is the payoff
07 bonus	+1	`./ok 07` green + unlocks — the bonus point (11/10)
Extra	0	`NANO.md` / `/context` viz — bragging rights only

Getting the starter files

Download starter.zip and unpack it. It contains the skeleton index.ts (fully-typed signatures with YOUR CODE HERE stubs), the read-only test harness (tests/, fixtures/), the ok runner, and the Node project files. It does not contain the reference solution — the appendix snippets on each lecture page are the only answer key.

First run:

unzip starter.zip
cd claude-code-nano
npm install
./ok 00

Expect ./ok 00 to fail on one test:

× Problem 0: warmup() must return 61001 (fix the off-by-two in index.ts)
AssertionError: expected 60999 to be 61001

That failure is the shipped, pre-course state — it’s Problem 0 in Lecture 01. The other two setup tests (Node version, importing index.ts doesn’t crash) already pass. Fixing warmup() so ./ok 00 goes green confirms your toolchain works end to end, and you’re off.

No API key is needed for any ./ok run — every test scripts a fake model, so the whole suite runs offline and free. You only need an ANTHROPIC_API_KEY once, for Lecture 06’s live acceptance run.