Claude Code is one of the most impressive coding agents available today. It reads your codebase, understands context, executes commands, edits files, and iterates on solutions. It feels like magic. But it is not magic - it is a well-engineered system of prompts, tool definitions, context management, and execution loops. And now you can learn exactly how it works by building a clone from scratch.
The learn-claude-code project is an educational repository that walks you through building a Claude Code-like agent step by step. Not a toy demo. A functional coding agent with file reading, editing, command execution, context management, and iterative problem-solving. The implementation uses bash for the shell integration and TypeScript for the agent logic, and the whole thing is surprisingly concise.
What You Actually Build
The project is structured as a series of progressive lessons, each adding a capability:
Lesson 1: The REPL Loop. You start with the simplest possible agent - a loop that reads user input, sends it to an LLM, and prints the response. This is the skeleton that everything else builds on.
Lesson 2: Tool Definitions. You add tool-use capability - the agent can now call functions. You define tools for reading files, listing directories, and searching text. The lesson teaches how tool definitions work, how the LLM decides when to use them, and how to parse tool-use responses.
Lesson 3: File Editing. The trickiest part. You implement a file editing tool that can make precise changes to existing files. The lesson covers different editing strategies (full file replacement, search-and-replace, line-based edits) and why search-and-replace with exact matching is the sweet spot for reliability.
Lesson 4: Command Execution. Your agent can now run shell commands and read the output. This adds sandboxing, timeout handling, and output truncation - the practical details that turn a dangerous "eval arbitrary code" into a safe, useful tool.
Lesson 5: Context Management. The hardest lesson. You build a system that tracks which files the agent has read, summarizes large outputs, manages the context window budget, and decides what to keep and what to drop as the conversation grows. This is where the real engineering happens.
Lesson 6: The Agent Loop. You tie it all together into an autonomous loop where the agent can plan, execute, observe results, and iterate. Given a task like "fix the failing test in auth.test.ts," the agent reads the test, reads the implementation, identifies the bug, makes an edit, runs the test, and iterates if it fails.
Why Building from Scratch Matters
You could just use Claude Code (or Cursor, or Copilot). Why build your own? Because understanding how these systems work changes how you use them and how you think about AI agents in general.
After building through learn-claude-code, I understood why Claude Code sometimes makes weird editing decisions (the context window is full and it is working with compressed file summaries). I understood why it occasionally re-reads files it already read (the context management dropped that file to make room for something else). I understood why giving it a clear, specific task works better than a vague request (the agent loop converges faster with constrained objectives).
This understanding makes you a better user of existing tools and a better builder of new ones.
The Bash Parts Are Surprisingly Good
I expected the bash components to be hacky glue code, but they are actually clean and instructive. The shell integration shows how to capture command output, handle signals, manage child processes, and deal with the messy reality of running commands in a user's environment. There is a particularly elegant section on PTY management that I have already reused in my own projects.
The TypeScript parts handle the LLM interaction, tool parsing, and agent logic. The split makes sense - bash for system interaction, TypeScript for the brain.
Who Should Do This
If you use AI coding agents daily but have never built one, this project is your weekend. It takes about 8-10 hours to work through all six lessons, and you come out the other side with a functional coding agent and a deep understanding of how the commercial ones work.
If you are building your own agent tools or framework, the lessons on context management and file editing alone are worth the time. These are the hardest problems in coding agent design, and seeing clean implementations makes your own design decisions much easier.
The whole thing is open source and well-documented. No excuses.