There's a repo called learn-claude-code that walks you through building a Claude Code-like coding agent from scratch in bash and TypeScript. No frameworks. No SDKs. Just raw API calls, tool definitions, and a conversation loop.
I spent an afternoon going through it, and I think every developer who works with AI should do the same. Not because you need to build your own coding agent - you don't. But because understanding how these things work under the hood changes how you think about them.
Here's what you learn when you build a coding agent from zero:
It's simpler than you think. The core loop of a coding agent is embarrassingly simple. Send a message to an LLM. Get back a response that might include tool calls. Execute the tool calls (read file, write file, run command). Send the results back. Repeat. That's it. The entire Claude Code experience, the thing that feels like magic, is fundamentally a while loop with tool execution.
The tools are everything. The LLM is the brain, but the tools are the hands. A coding agent with a great model but poor tool definitions will underperform one with a decent model and excellent tools. The precision of your tool descriptions, the clarity of your parameter schemas, the quality of your error messages - these determine agent behavior more than the model itself.
Context management is the real engineering. The conversation grows with every turn. File contents, command outputs, error messages - they all accumulate. Managing what stays in context and what gets truncated is where the actual difficulty lives. It's not glamorous work, but it's what separates a demo from a useful tool.
System prompts are programming. When you write the system prompt for a coding agent, you're programming its behavior in natural language. "Always read a file before editing it." "When a test fails, read the error output carefully before attempting a fix." "Never modify files outside the project directory." These instructions shape agent behavior as directly as code shapes program behavior.
The learn-claude-code project strips away all the abstraction and shows you the raw mechanism. And once you see it, you can't unsee it. Every AI coding tool you use afterward becomes transparent. You understand why it makes certain mistakes. You understand why it asks for confirmation at certain points. You understand the tradeoffs the builders made.
I think there's a broader lesson here about AI literacy. Most developers use AI tools as black boxes. They know the inputs (their prompt) and the outputs (the generated code), but the middle is opaque. Building a coding agent - even a simple one - makes the middle visible.
Some specific things that surprised me going through the project:
The file reading strategy matters enormously. Agents that read entire files waste context. Agents that read too little miss important context. The sweet spot - reading relevant sections with enough surrounding context - is harder to get right than it sounds.
Error recovery is where agents shine or fail. When a command fails, a good agent reads the error, understands it, and adjusts. A bad agent retries the same thing or gives up. The difference comes down to how you prompt the agent to handle failures.
The conversation history itself is a form of memory. The agent can "remember" what it tried before because those attempts are in the context. This is both a feature (it learns from mistakes within a session) and a limitation (once the context fills up, it forgets).
If you're building with AI or leading teams that build with AI, I'd strongly recommend going through learn-claude-code or building something similar yourself. The investment is an afternoon. The return is a fundamentally better understanding of the tools you're depending on.
Demystification is underrated. Build the thing once, and you'll never be confused by it again.