Skip to content

Claude Code — How It Actually Works (Agent Harness Deep Dive)

Overview

Claude Code is one of the most popular AI coding tools in the world, yet most users have no idea what happens under the hood. This article distills a 31-minute technical deep-dive that opens up the backend of Claude Code and explains — with a fully functional minimal Python re-implementation — exactly how an agent harness works.

Two goals drive the source material:

  1. Understand every moving piece inside Claude Code: the model, tools, memory, context window, and guardrails — and how they fit together.
  2. Build your own: walk through the code of a minimal working agent to see the architecture in practice.

[!NOTE] Source: YouTube video "How Claude Code Actually Works" — https://www.youtube.com/watch?v=vp6Dlx5aHDU (31:04). The mini agent demo uses Opus 4.8 with a Sonnet fallback option.

The Core Idea: LLM + Agentic Harness

Claude Code is an agent: an LLM that runs in a loop, calls tools, and interacts with the world, wrapped in an agentic harness — the software around the model that handles the loop, tool implementations, and the permission system.

Component Role
LLM The "brain". Predicts what should happen next. Can only output text.
The loop Tools, memory, context assembly — the cycle of predict → act → observe.
The harness Software that controls the loop and executes actions on the model's behalf.

The model predicts; the harness takes over and takes control.

The Five Building Blocks

1. The Model

An LLM is not a magic black box — it is a text predictor. Given a sequence of tokens, it predicts the most likely next token (e.g. "My favorite programming language is…" → 71% "Python"). Those predicted tokens can be plain text, JSON, or a structured tool call.

[!WARNING] The model has no memory, no state, and no goals. It "remembers" only because everything relevant is stuffed into its input prompt on every request.

2. Tools

Tools are how the agent actually does things. The model never runs a tool itself — it only reads a menu of available tools and announces which one it wants.

  • Built-in IO tools: read, write, edit files, run bash, search the filesystem.
  • Additional tools: MCP servers (external tools) and plugins (which can bundle multiple tools, MCP servers, commands, and skills together).

[!TIP] Fewer, targeted tools beat thousands of options: with too many tools, the model is more likely to pick the wrong one. Five or six precise tools outperform a sprawling tool library.

Analogy: the model is a customer ordering from a menu; the harness is the kitchen that actually cooks and serves the dish.

3. Memory

Memory is persistent information the agent can consult across sessions — it is not stored inside the model:

  • Memory files (e.g. CLAUDE.md, user_preferences.md) — plain files on disk, loaded when needed.
  • Skills — markdown files that can be loaded to perform a specific type of task.

The flow: the model requests a memory lookup as a tool call → the harness reads the file → the content is injected back into the context. Nothing is remembered unless it is in context.

4. Context Window

The context window is everything the model "sees" for one prediction — one very long prompt assembled by the harness. A typical distribution:

Content Typical share
System prompt (rules, identity) ~1–2%
Memory files small
Tool definitions (schemas) can be large
Conversation history large
Skill definitions variable
Tool calls and results can be large

[!WARNING] As the context window fills (80–100%), model performance typically degrades — too much information to process. Context engineering — deciding what goes into the window — is the real craft of building good agents.

5. Guardrails

Guardrails are enforced by the software, not the model. Examples:

  • Human-in-the-loop: a destructive command (e.g. rm) triggers a permission prompt; the tool is not executed unless the user approves.
  • Limits: e.g. a cap on tool calls per turn to prevent infinite loops.

Because the guardrail is code in the harness, the model cannot override it — it can only output text asking for the action.

How Tool Calling Actually Works

  1. The model outputs structured text — a JSON tool-call object, e.g.:
{
  "type": "tool_call",
  "name": "read_file",
  "arguments": {
    "path": "src/main"
  }
}
  1. The harness parses the response, executes the tool, and captures the result.
  2. The result is appended to the conversation history and sent back to the model.
  3. The loop repeats until the model produces a final text answer.

The model never touches the filesystem or shell — it writes a request, and the harness implements it.

Building a Minimal Agent in Python

The source video walks through a complete minimal Claude Code clone, split into small single-purpose files. This is the architecture that all major AI agents share.

mini-claude-code/
├── model.py        # The ONLY file that talks to an LLM
├── context.py      # Assembles the prompt (system + memory + history + tools)
├── memory.py       # Loads memory files (e.g. CLAUDE.md)
├── tools.py        # Tool name → Python function mappings + read-only list
├── guardrails.py   # Permission prompts + tool-call limits
├── agent.py        # The agentic loop (imports model, tools, guardrails, context)
└── main.py         # CLI: user prompt → agent → response; /clear, /model commands

model.py

~52 lines, and the only file interacting with a large language model:

  • Defines the available models and a default model.
  • Loads the API key from an environment variable.
  • Creates a client and makes a completion request with: max tokens, system message, previous messages, and tool definitions.
  • The framework combines these into one large system prompt internally.

context.py

Assembles what gets sent to the model:

  • A base prompt defining the agent ("you are a mini Claude Code CLI coding agent" + rules).
  • A load_memory() step that reads memory files and injects them, e.g. as "here's the project memory".

memory.py

Loads the memory file from disk (checks for a CLAUDE.md), returns its contents, and merges it into the context.

tools.py

  • Function mappings: tool name → actual Python function (e.g. bash → shell runner, write_file → file writer).
  • A read-only tools list: tools the agent may call automatically.
  • A run_tool(name, args) dispatcher that invokes the mapped function.

guardrails.py

  • If the requested tool is in the read-only list → run automatically.
  • Otherwise → ask the user "do you want to allow this to run?" (yes/no).
  • Caps the run at 25 tool calls per turn to prevent runaway loops.

agent.py

The heart of the harness:

  1. Imports the building blocks (model, tools, guardrails, context).
  2. Defines the model, builds the system prompt, and tracks conversation history.
  3. Per turn: append the user message → loop up to max_tool_calls_per_turn:
  4. Send the request to the model.
  5. If the model requests a tool call → run it through guardrails → append the tool result (or "user denied the tool call") to history.
  6. If the model answers in text → return it.
  7. Keep looping until done.

main.py

A thin CLI: let the user type any prompt, pass it to the agent, print the response. Plus session commands:

  • /clear — wipes conversation history (the agent genuinely forgets).
  • /model <name> — switch models, e.g. /model sonnet.

Running the Agent (Demo Walkthrough)

In the source video's live demo, the mini agent:

  1. Is prompted: "Can you write me a simple tic-tac-toe game in Python, please?"
  2. Prints token counts, then calls the list files tool to inspect the directory.
  3. Calls the write tool — blocked by a guardrail prompt: "do you want to write this?" → user approves.
  4. Creates the tic-tac-toe file, ready to execute.

Key observations:

  • /clear resets the history — asking "what did you just do?" afterwards correctly gets "I haven't done anything yet".
  • The full loop is visible: tool call → guardrail → execution → result → next prediction.

Key Takeaways

  • The model is a text predictor. Everything else — tools, memory, context, guardrails — is orchestrated by ordinary software in the harness.
  • Tool calling is text I/O: the model writes JSON, the harness executes it.
  • Memory is injected, not innate: information only matters if it reaches the context window.
  • Context engineering is the discipline of deciding what to put in the window — and keeping it from overflowing.
  • Guardrails are software-enforced — the model cannot bypass a permission prompt.
  • Claude Code itself is ~500,000 lines of code, but this minimal ~7-file harness reproduces its core architecture and loop.