Rebuild the engine behind Claude Code in pure TypeScript — the tool-using agent loop that reads, writes, and edits files on its own. Start with a sandboxed workspace, end by wiring the real Anthropic API, with the LLM as a pluggable, testable dependency.
AI coding agents feel like magic. You type "bump the version and update the changelog," and something reads your files, makes edits, runs commands, and reports back. But the loop at the core of every one of them — Claude Code included — is surprisingly small. The magic is mostly engineering: a sandbox, a set of tools, a message protocol, a loop, and a safety layer. In this project you build that engine from scratch — a mini Claude Code you can actually run — one small, fully-tested piece at a time.
You start at the foundation: a sandboxed virtual workspace, an in-memory filesystem with path-traversal protection, because a model is untrusted input and must never escape its root. On top of it you build a registry of tools the agent can call — read, write, list, and a surgical str_replace edit that refuses ambiguous changes the way real agents do. Then the part that turns text into action: the message protocol of text / tool_use / tool_result blocks, and the agent loop that ties everything together — model → tool call → tool result → model, repeating until the task is done. Finally you add the layer production agents can't ship without: a permission policy that gates every dangerous action as allow / deny / ask with a full audit trail, and a real Anthropic adapter that talks to the live Messages API.
The one decision that makes the whole thing testable is the key insight behind every serious agent harness: the LLM is a dependency, injected behind a tiny Model interface. A deterministic ScriptedModel drives the agent in tests — no API key, no network, fully reproducible — and a real AnthropicModel drops into the exact same slot. Same loop, same tools; only the brain changes. Everything is strict TypeScript on Bun, graded by real bun test suites where each challenge keeps the earlier ones green. By the end you won't hand-wave about how agentic coding tools work — you'll know, line by line, because you wrote the loop yourself, and you'll have a portfolio piece that proves it.