How Claude Code Works

What changed between coding agents that struggled to finish a task and agents useful enough to reorganize an engineering team around? That is the practical question behind Jared Zoneraich’s workshop. His account is an independent investigation, not an Anthropic-endorsed description of Claude Code’s internals.

At the time of the talk, Zoneraich was building PromptLayer with a small team in New York. He reports that the product had launched three years earlier and was processing millions of LLM requests daily. Its organizing principle was collaboration: engineers and product managers should build with domain experts, just as an AI lawyer should involve lawyers. His own work alternated between using agents and using his company’s tools to build them.

That experience led to a concrete engineering rule: if a task could be completed with Claude Code in less than an hour, do it without putting it through prioritization. Small platform problems—an upload that fails, an awkward edge case—otherwise accumulate faster than a small team can schedule them. Understanding why agents became useful therefore matters beyond choosing a coding assistant: it suggests how to build agents for other work.

The workflow changed in stages. First, developers copied code into ChatGPT and pasted answers back into their editor. Cursor brought that interaction inside a VS Code fork with Command+K. Its assistant then handled a longer back-and-forth, followed by Claude Code’s terminal-oriented workflow, where a developer could delegate work without touching each edit. Each step transferred more of the execution process to the agent.

Zoneraich attributes the improvement to two connected changes: simpler architecture and better models. Tool calling gives the model a structured way to request actions, extending earlier efforts to obtain reliable JSON such as Jsonformer. As models improve at selecting tools and recovering from mistakes, the application needs fewer branching prompts designed to compensate for particular model weaknesses. Give the model useful tools, then let it choose the next step.

This changes the expected lifetime of scaffolding. A classifier, special-case prompt, or routing branch may solve a real problem today but become unnecessary as the model improves. In Zoneraich’s interpretation, Claude Code exemplifies this shift by relying on runtime searches such as grep rather than making an embedding index and a complex retrieval pipeline the center of its architecture. He contrasts that with Cursor’s mixture of retrieval approaches; this is a preference for simpler exploration, not a claim that retrieval has no place.

The engineering philosophy is familiar from Python’s import this: prefer simple designs, avoid unnecessary nesting, and distinguish complexity inherent in the problem from complications introduced by the implementation. Agent architecture does not escape those principles just because the component making decisions is a language model.

CLAUDE.md, and the analogous AGENTS.md used by other agents, provide a simple place for repository instructions. Instead of requiring a separate system to infer every convention, a Markdown file can state how the project works. Users can edit it; agents can update it when appropriate. Zoneraich contrasts this with his description of Cursor 1.0 building a local vector database to understand a repository. Both approaches supply context, but the file makes an important part of that context explicit and editable.

The control flow is equally direct: ask the model what to do, execute its tool calls, append the results, and ask again. When the model returns without tool calls, return control to the user. Zoneraich tentatively calls the internal loop N0; the related PromptLayer architecture analysis spells it nO. These names come from an analysis of the implementation, rather than a stable public interface.

A Python harness can express that control flow without hard-coding a route through the tools. Here model_turn returns a dictionary containing text and tool_calls; each call carries an id, name, and arguments. The host supplies tool handlers, including their permission checks.

def run_agent(model_turn, tools, messages):
    history = list(messages)

    while True:
        reply = model_turn(history)
        history.append({"role": "assistant", **reply})
        calls = reply.get("tool_calls", [])

        if not calls:
            return reply.get("text", ""), history

        for call in calls:
            try:
                handler = tools[call["name"]]
                result = handler(**call["arguments"])
            except Exception as error:
                result = {"error": str(error)}

            history.append({
                "role": "tool",
                "tool_call_id": call["id"],
                "content": result,
            })

Returning an error as a tool result gives the model information it can use to correct its next action. The loop does not need a separate branch for every possible failed search, malformed command, or mistaken assumption. That flexibility is the central mechanism, although the host still controls what actions its tools permit.

The tool inventory changes frequently, but each tool in the workshop’s snapshot has a reason to exist beyond merely exposing a command.

A dedicated read tool can reject an oversized file rather than dump it into the conversation. Search tools reproduce what a developer would do at a terminal. An edit tool can describe the few lines that change, avoiding the burden of generating every unchanged line again. Zoneraich compares that to crossing out parts of a slide deck instead of recopying the entire deck to revise it.

Bash is a universal adapter to existing software. An agent can create a Python file, run it, inspect its output, and delete it afterward. It can compose shell utilities, generate tests, or work out how to start a local development environment. That replaces the fragile practice of keeping a small list of startup commands in a note that gradually becomes stale. Zoneraich also attributes Bash’s usefulness to the abundance of familiar command-line patterns in training data; he uses less common languages such as Rust as a contrasting example.

Versatility does not eliminate the need for operational guidance. The system prompt can tell the agent to read before editing, prefer the dedicated Grep tool for searches, run independent operations in parallel, and quote paths containing spaces. Zoneraich suggests that security, sandboxing, and output limits help explain the dedicated-tool preference. These are small corrections informed by repeated use, rather than an attempt to precompute the agent’s entire workflow.

To-do lists occupy an interesting middle ground: the data is structured, but the workflow rules need not be enforced in code. Zoneraich describes instructions to keep one task in progress, mark completed tasks, and leave a task in progress when it encounters a blocker or error. In his account, the model follows those rules because they appear in the prompt and tool descriptions, not because the client rejects every invalid transition. A schema can organize state without enforcing the policy for changing it.

The agent emits a function call carrying task data. The example structure includes a version, an identifier, a human-readable title, and potentially evidence blobs. Zoneraich describes the identifiers as hashes that can be referenced later. Those fields make a plan addressable and legible; they do not by themselves prove that the underlying work has happened. His suggestion that this might have been a quick implementation is speculation, not an account of Anthropic’s development process.

The benefits extend beyond planning. Recorded task state helps resume interrupted work, gives the user a way to see progress, and provides something concrete to redirect. A long agent run with no visible signal may be capable but difficult to supervise. The to-do list improves the working relationship between user and agent even when it does not change the model’s coding ability.

A simple loop can still drown in its own history. Every terminal log, file read, and intermediate investigation competes for the model’s attention. Zoneraich describes an AsyncBuffer, tentatively called H2A in the talk and h2A in the related analysis, that decouples I/O from reasoning. He also describes a compressor that drops middle material and summarizes the head and tail of accumulated context. These are his account of the internals, rather than a public contract for how every release compacts a conversation.

Zoneraich estimates that compression begins at roughly 92% context capacity; he does not identify a tested release or measurement procedure. The broader design problem survives any particular threshold: the agent needs somewhere to keep useful material without carrying all of it in every model request. A sandbox filesystem supplies that storage. For deep research, he explicitly asks the agent to save Markdown files that it can consult later, and predicts that ordinary chat interfaces will increasingly include sandboxes for the same reason.

The alternative to an exploratory loop is often a directed acyclic graph, or DAG, of prompts and routing rules. Zoneraich describes customer-support systems built over the preceding two to two-and-a-half years with hundreds of nodes: classify the request, route refund questions to one prompt, route another intent somewhere else, and keep subdividing the workflow. Narrow classifiers and discarded context can restrict what each step is able to do.

He argues that an X/Y classification step with discarded context can prevent certain unwanted refunds and injection paths. That should be read as a claim about restricting a particular workflow, not as a general guarantee that DAGs solve prompt injection. Replacing those restrictions with a flexible agent restores an attack surface along with the ability to explore. Zoneraich characterizes loops as 10× easier to develop and 10× more maintainable, without supplying measurements.

Even apparently helpful guidance can interfere with exploration. In a PromptLayer browser-agent experiment, he added button titles and prescriptive navigation instructions to help the agent operate the dashboard. It navigated worse: the instructions seemed to distract it when the prescribed sequence did not fit. He explicitly allows that the experiment could have been flawed and worth rerunning. The useful lesson is to test whether additional guidance helps the actual task, rather than assuming more instructions must improve it.

An audience member raises the obvious objection: even if scaffolding becomes obsolete in a few months, what if it solves a problem now? Zoneraich’s answer is use-case dependent. A bank chatbot warrants more care than an open-ended development assistant. His preferred compromise is a flexible master loop with rigorous tools. Put the edge-case workflow inside a tool that can be evaluated and versioned, while leaving discovery and navigation to the model. A tool may contain substantial deterministic logic without forcing the entire agent into a predetermined graph.

This preference also explains Zoneraich’s skepticism about embedding intent classifiers and regex rules throughout an agent. PromptLayer prototyped a non-LLM classifier for prompt pipelines but never released it. He recognizes that classifiers can work and may still make sense when cost dominates; his concern is their diminishing value as smaller models become cheaper and more capable. The point is not to ban regex from software, but to avoid making brittle intent routing the agent’s organizing principle.

Reasoning effort supplies another control. The workshop shows the historical trigger phrases think, think hard, think harder, and ultrathink as ways to request more reasoning. Its slide lists 4,000 tokens for think, 10,000 for think hard, and 31,999 for both think harder and ultrathink. Treat this as the keyword ladder shown in the recording, not current configuration guidance. Architecturally, the distinction is between adjusting the reasoning budget of the ongoing agent and dispatching a separate hard-planning tool.

Shell access makes mistakes consequential. Zoneraich jokes about using YOLO mode, then gives the counterexample: teammates had dropped their local databases. He says enterprise customer workflows do not use that approach. The more dangerous combination is an agent that can both fetch untrusted internet content and execute commands; instructions encountered on the web may influence actions on the machine.

He describes URL approval, isolated web work, containerization, and a command-gating pipeline that considers Bash prefixes. These belong to related but distinct layers: permissions decide whether an action is allowed; sandboxing limits what execution can affect. His later contrast with Codex should not imply that OS-enforced isolation was exclusive to Codex: Anthropic had already documented Claude Code filesystem and network sandboxing using macOS Seatbelt and Linux bubblewrap. Much of a production agent’s complexity can live in these execution boundaries while its reasoning loop remains small.

Sub-agents address the context problem by giving a bounded task its own conversation. A researcher, documentation reader, test runner, or reviewer can consume detailed material without adding every intermediate step to the parent’s history. Only the result needs to return. In the dashboard experiment, for example, Zoneraich asked the coding agent to read the documentation before changing the site; a documentation sub-agent could perform that preparation separately.

The Task interface shown in the talk has two important arguments: a short description that the user sees and a longer prompt that tells the sub-agent what to do. An example description is finding the default chat-context instantiation. The parent is therefore not merely selecting a predefined specialist: it is writing instructions for another agent. If a task fails, it can try again with more information. Zoneraich suggests that some applications may benefit from a structured object instead of one long prompt string.

The audience asks where those instructions come from. The clarification is that the main agent has the tool schema in its context and generates the description and prompt dynamically when it calls Task. The task call itself is part of the main interaction; the delegated investigation has its own context. Independent task calls can run in parallel and return their results.

Published system-prompt leaks form part of Zoneraich’s research. The instructions he highlights are pragmatic: keep output concise, avoid announcing the work instead of doing it, use tools rather than merely propose commands, match existing code, avoid unnecessary comments, run independent commands in parallel, and maintain to-dos. He notes that the comment instruction does not reliably work for him. Prompting is useful here because these are often preferences discovered through repeated use, not invariants that must reject an operation whenever they are violated.

Skills extend the available instructions without loading everything at once. A documentation-update skill can contain product knowledge and writing style; a design skill can carry a style guide. Zoneraich also describes seeing skills used to edit Word and Excel documents, though that is not his own workflow. For deep research, he supplied an article or repository explaining the process and asked Claude Code to turn it into a skill. The common mechanism is selective context: load the detailed instructions when the task needs them.

Unified diffing applies the same economy to output. Revising an essay with red lines requires less reproduction than rewriting the entire essay; editing code through a patch similarly concentrates generation on the intended change. Unified diff is an established format, although some agents use variations that omit details such as line numbers when their editing mechanism does not need them.

For example, a proposed correction to a Python predicate can preserve the surrounding function while identifying the exact replacement:

--- a/eligibility.py
+++ b/eligibility.py
@@ -1,2 +1,2 @@
 def is_eligible(age):
-    return age > 18
+    return age >= 18

The patch says what should change; applying it and checking the resulting behavior remain separate operations. The unchanged function signature provides context while the deletion and addition identify the edit.

On-demand instructions introduce a different failure mode: a skill that never loads cannot help. An audience member reports seeing a warning when CLAUDE.md exceeded roughly 40K characters, splitting it into skills, and then finding those skills ignored. Zoneraich explains that short skill descriptions should help the model select the relevant instructions, but says he generally invokes skills manually. Better prompting, explicit workflow rules, and model post-training are possible remedies; the exchange does not demonstrate a fix.

Two possible directions follow from this architecture. One is a master loop with hundreds of increasingly well-selected tools. Zoneraich favors the other: a small tool set centered on Bash, with scripts in the local directory extending what the agent can do. His preference for one broad tool is not absolute; he considers the earlier core inventory a reasonable boundary.

Model choice can also become part of the agent’s workflow. Zoneraich proposes a hypothetical default model that is 20× faster but somewhat weaker, with a stronger reasoning model available as a tool. Planning may deserve the stronger model first—he names GPT-5.1-Codex and Opus as possibilities—while cheaper or faster models execute more routine work. To-dos and skills suggest another direction: new first-class structures that help an agent organize work without prescribing every action.

Zoneraich calls this the AI therapist problem: there may be several useful approaches without one global best answer. His examples—meditation, CBT, and ayahuasca—illustrate different approaches rather than recommendations. The analogy carries into product design: taste, domain knowledge, and the desired interaction matter alongside capability. He personally uses Claude Code for local environments and Git, Codex for harder problems, and Cursor’s Composer for speed. He explicitly lacks evidence that his impression of Codex’s greater power establishes comparative superiority.

His comparison is a map of product emphases, not a leaderboard:

These differences leave room to combine ideas across products rather than copy one architecture wholesale.

Codex’s public repository makes the agent itself available for investigation. Zoneraich describes a Rust core with the same broad master-loop pattern, but more explicitly event-driven concurrency: submission queues carry work in, and event outputs carry progress and results out. In his comparison, threading, permissions, and the underlying model distinguish it more than the high-level loop does.

The workshop names macOS Seatbelt and Linux Landlock as Codex sandbox mechanisms. Its architecture slide also includes persistent state and resume/fork workflows. These details explain how an agent can manage ongoing sessions and concurrent activity around a small decision loop; they do not make OS isolation unique to Codex. Zoneraich then shows Claude Code researching Codex through Explore sub-agents—using one coding agent to inspect another, with delegated investigations keeping the parent’s context focused.

In the workshop’s snapshot, Sourcegraph’s Amp offers a free tier supported by advertising and what Zoneraich describes as excess provider tokens; PromptLayer is an advertiser. Amp also avoids making a model selector the center of the experience. That lets its developers change the underlying models without promising users the behavior of one fixed model.

The more consequential design question is whether the repository is a good environment for an agent. A self-contained project with runnable tests gives the agent a feedback loop: change something, run the checks, inspect the failure, and improve the result. Zoneraich connects this to Factory’s thinking and wants an equivalent loop for frontend design, where an agent can inspect its own output and revise it. Better autonomy depends partly on making success observable.

Handoff addresses accumulated context by starting a fresh thread with information selected for the next task. Compaction, by comparison, summarizes an existing conversation so work can continue within it. Zoneraich likens Handoff to switching weapons instead of reloading in Call of Duty: change to a fresh working context rather than keep repairing the old one. He allows that both approaches may be useful. Amp’s fast, smart, and oracle choices extend the same product philosophy to model routing, with oracle reserved for difficult problems and its underlying model replaceable.

Cursor’s distinction begins with the IDE experience. Zoneraich finds Composer fast enough to change his daily preferences and sees its specialization as evidence that product data can support defensibility through model training. He calls Composer distilled, although Cursor’s original report describes a mixture-of-experts model trained with reinforcement learning and does not establish that characterization. The practical appeal is shorter interaction cycles; the corresponding hazard appears in his anecdote about accidentally pushing to master on a personal project.

Cursor’s gradual improvement from a rough VS Code fork matters to this account: it accumulated a useful product while improving its models and interaction design. Zoneraich also describes Codex models as distilled and optimized for coding agents, and predicts faster OpenAI models; those are his characterization and forecast. Cursor meanwhile continues to offer alternative models alongside Composer. The blog screenshot discussed in the talk includes GPT-5, while he names GPT-5.1 as a newer possible planning choice. Specialization and access to other frontier models can coexist in one product.

How should a team choose an architecture or know that a change helped? Zoneraich distrusts public benchmark marketing, but the more useful problem is local: a flexible loop may solve the same task through several valid paths. Testing one exact sequence risks rejecting good behavior, while testing only the final answer can conceal expensive or fragile execution.

He separates several evaluation approaches:

A point-in-time test can begin halfway through a conversation where the next action is known. Backtesting replays historical inputs and can reveal changes in tool selection. Tool-call counts, retries, and elapsed time are what Zoneraich calls agent smell: useful indicators that warrant investigation, not substitutes for correctness. His recommended starting point is to capture historical data and rerun it.

The concrete example uses PromptLayer’s evaluation product as a batch runner. Each row runs headless Claude Code, with a provider supplied through file variables. The instruction is to search the web, find that provider’s most recent and largest released model, and return its name. The internal search path is left open. This makes it an end-to-end task: assess the returned result, then inspect row-level statistics such as tool calls to understand how the agent got there.

The flexible loop does not remove the value of function-level tests. A tool with a clear input and output can be tested rigorously. If the tool is itself a sub-agent, evaluation becomes recursive: test that sub-agent’s end-to-end behavior as a component of the larger agent. This is where Zoneraich puts work that must conform to a specific voice, email format, or blog structure.

His email workflow first checks whether the message meets the required standards. A satisfactory email proceeds to revision; an unsatisfactory one first gets missing parts, such as a header, added and then undergoes revision. The displayed workflow makes those branches visible through nodes labeled check-email-parts, add-email-parts, revise new email, and revise good email. Exploration is useful for deciding what to write, but this tool constrains how the deliverable is prepared.

A related SEO workflow has roughly twenty nodes, including deep research, outline generation, conclusion repair, and adding links. That degree of structure makes sense when the desired output is specific. To evaluate the email version, Zoneraich runs sample emails through the workflow and uses heuristics and an LLM judge to check for a greeting such as Hi, Jared,, an email body, and a signature. Code-based checks are another option. He reports an evaluation result of “a hundred” for this example; the sample size, scoring scale, and held-out status are not supplied.

A headless coding agent can supply an existing harness instead of requiring every application to build its own. Zoneraich describes a daily GitHub Action for documentation maintenance:

1. Pull the relevant repositories and inspect newly pushed commits.
2. Determine what changed.
3. Read CLAUDE.md to decide whether those changes warrant documentation updates.
4. Make the updates and create a pull request.

An audience member asks whether he reviews the results. He confirms that the agent creates the PR but does not merge it. The automation therefore ends with a reviewable proposal, not an unattended publication.

This is a higher level of abstraction: an application can delegate repository navigation, tools, and orchestration to an existing agent. Zoneraich also imagines a team that combines Claude Code, Codex, and other agents, possibly exchanging messages through Slack. That is an aspiration, not a system demonstrated in the workshop. Its motivation is that different agent perspectives may complement one another, while context management and a restrained tool set remain important within each agent.

The slide deck itself is a smaller example of composition. Zoneraich asked Claude Code to research Slidev and build a skill for it. A deep-research skill investigated the coding agents, while a design skill helped refine boxes and accent colors. He supplied visual judgment—whether something looked good—without needing to specify every design operation himself.

The closing questions sharpen the limits of the simple-loop approach. If customer support must collect a name and then an email, how is that order enforced without a DAG? Zoneraich distinguishes general-purpose problem solving from a repeatable deliverable. Coding has no universal sequence. A travel itinerary has a more consistent output, but researching each city may require different actions. He would let the agent explore during research, then use a DAG-backed tool to create the standardized plan or output file. A prompt can request that the agent finish with that output; ordering that must be guaranteed belongs inside the constrained tool.

Another question asks whether direct model calls will give way to agent SDKs: instead of one LLM call per document, could a Claude Code loop process documents, save files, and produce a final summary? The attraction is simpler development through an existing harness. Zoneraich compares this, at a deliberately simplified level, to reasoning models such as o1 moving more work behind the provider’s interface. He can imagine providers exposing agentic endpoints, but direct model access remains useful when a task requires tighter control. His analogy to the move beyond completions interfaces is a forecast about abstraction, not a claim that every pipeline should become a coding-agent session.

For coding with agents, good tests provide the feedback loop emphasized by Amp and Factory. Zoneraich relies heavily on planning and specifications for substantial work, but skips that phase for very simple edits. He does not prescribe test-driven development for every task. The useful question is whether the specification and checks make the desired result clear enough for the agent to improve its own work.

The final technical exchange also corrects the workshop’s research framing. An audience member asks whether Claude Code’s system prompt can be found in the downloaded JavaScript bundle or lives behind a server endpoint. Zoneraich initially speculates that it is hidden and mentions an account of modifying open-source Codex to send a custom prompt before its model was separately available. Pressed on Claude Code’s prompt location, he admits he does not know. He then relays Nico’s statement that it is on the local machine and acknowledges that the leaked prompt he used may be old. That leaves the workshop’s internal names and prompt-derived details as a historical investigation, rather than an authoritative implementation specification.

Asked how people can help, Zoneraich closes with an invitation to the New York team, which was hiring. He identifies PromptLayer as the source of the evaluation screenshots and describes its scope: prompt management, logging, evaluations, auditability, and governance, with collaboration among engineers, product managers, and nontechnical experts. That collaboration is the practical setting for the architecture: people define the result they need, the agent explores how to produce it, and tools and evaluations make the important requirements inspectable.