How Claude Code Was Built, and What It Teaches Agent Builders

The central design decision: a thin harness around a strong model

Most agent projects start by writing orchestration. Planners, routers, state machines, task decomposers, retry graphs. Claude Code went the other way. The runtime is close to the simplest thing that can work: a conversation loop with tool calls, a permission gate in front of side effects, and a terminal for input and output.

That is a bet about where capability lives. If the model is the part that gets better every few months, then every line of harness code that exists to compensate for a model limitation is a liability. It was written against a weakness that will be fixed, and when the fix lands the scaffolding keeps forcing the old behavior.

The practical test is simple. Ask of any component you are about to write: does this exist because the task genuinely requires it, or because the model could not be trusted to do it? The first kind survives model upgrades. The second kind becomes something you delete later, usually after it has quietly capped your agent's ceiling for months.

Few general tools beat many specialized ones

A coding agent could ship a tool per operation: rename symbol, extract function, add dependency, run migration. Claude Code instead exposes a small set of primitives, roughly read a file, edit a file, search the codebase, run a command. Everything else is composition.

The reason is coverage. Specialized tools only handle the cases their author imagined. A model with a shell and a file editor handles cases nobody imagined, because it can read the situation and assemble a response. The cost is that the model must understand the environment well enough to compose correctly, which is exactly the capability that keeps improving.

There is a second effect that matters for cost. Every tool you register consumes context in the system prompt, in every request, forever. Twenty narrow tools can eat a meaningful slice of the window before the user has typed anything. A small toolset keeps that overhead low and leaves room for the thing that actually determines output quality: the code and knowledge you put in front of the model.

The terminal was a product decision

Running in the terminal is not an implementation shortcut. It puts the agent inside the environment where the work already happens: the repository, the shell history, the test runner, the version control state, the credentials the developer already has. An agent in a browser tab has to be handed all of that. An agent in the terminal is already standing in it.

It also makes the trust model legible. The developer sees each command before it runs, approves or denies it, and can interrupt mid-stream. Permissioning is the part of an agent that cannot be delegated to the model, because the whole point is that a human retains the veto. Building that into the interface, rather than bolting it on, is what makes an autonomous tool usable on a real codebase.

Context is the real budget

Once the harness is thin and the tools are general, the remaining variable is what goes into the context window. This is where agent quality is actually decided, and where cost is decided along with it.

An agent working on an unfamiliar codebase spends most of its early tokens rediscovering facts: what the module layout is, how the build runs, which conventions the team follows, why a past decision was made. None of that is novel reasoning. It is retrieval, performed badly, by paying a language model to read files and summarize them again on every session.

This is the point where retrieval stops being an optimization and becomes architecture. If the knowledge already exists as indexed chunks, the agent fetches the relevant passages and spends its reasoning budget on the actual task. RDK exists for this layer: files from local vaults, docs, and code are indexed as encrypted private chunks, and the agent searches those chunks before it queries a model. Token spend drops 80 to 90 percent because the answer is retrieved instead of regenerated.

What to copy if you are building your own agent

Start with the loop and resist adding to it. Give the agent a handful of general tools and let composition cover the long tail. Put the permission gate in the interface, not in a config file nobody reads. Then treat the context window as a budget with a line item for every token, and move anything repetitive out of generation and into retrieval.

The failure mode to avoid is building a framework that encodes today's model limits. The teams that shipped durable agents in the last two years mostly wrote less code than they expected to, and spent the saved effort on tool ergonomics and knowledge plumbing. That ordering is the actual lesson.