Homeโ€บBlogโ€บAgentic AI System Designs
Agentic AI System Designs ยท Harness teardown

Claude Code, Taken Apart

Anthropic's coding agent, dismantled the way its architects might draw it: eight layers from the interfaces down to the model, one task traced through all of them, how the layers connect, where it fails, and what it would take to build one yourself.

FL
FrontierAGI Team
โš ๏ธ How to read this (as of 7 Nov 2026)Facts come from Claude Code's official documentation (code.claude.com). Its internals are not public: the architecture is inferred from documented behaviour, and items marked โš ๏ธ could not be confirmed on the pages we could reach. Build times, team sizes and costs are our estimates. Disclosure: Claude, made by Anthropic, helps write this site, and this series covers Anthropic, Google and OpenAI products.

1. Case file

MakerAnthropic
CategoryAgent harness
First releasedFeb 2025, research preview โš ๏ธ
Where it runsTerminal, IDE, desktop, web
Open sourceNo (the Agent SDK is a library)
Extends withCLAUDE.md, MCP, skills, hooks, subagents

2. The whole system in one picture

๐Ÿ›๏ธ The whole system, layer by layer, with one task traced

โ” control (who calls whom)โ”… data (what comes back)โ–ญ solid border: runs on your machineโ”… dashed border: runs in the vendor's cloud
Press play to follow one task down through the layers and back, or tap any component.

Same eight-layer reference stack in every article of the series. Components and calls are drawn from the project's documentation and code; where internals are not public the drawing is inferred from documented behaviour. The monospace box shows what actually moves between layers at each step (simplified).

3. Layer by layer

L1๐Ÿ–ฅ๏ธ Interfaces ยท Where people (or other agents) talk to it

What it does
Gives people (and programs) a way in: a terminal session, an editor panel, a browser tab, or code.
How it is built here
Terminal CLI first, then IDE extensions, desktop and web apps; the Agent SDK exposes the same agent to your own programs.
Design choice
Many front ends, one engine. Every surface drives the same loop, so behaviour is consistent and features ship everywhere at once.
Without it
Each surface would grow its own agent, and a fix in one would not reach the others.

L2๐Ÿงญ Sessions & orchestration ยท Who owns a task: sessions, background tasks, subagents

What it does
Decides who owns a piece of work and for how long: sessions, resuming, background work, helpers.
How it is built here
Sessions with transcripts that can be resumed; subagents spawned and coordinated by a lead agent; cloud sessions for long tasks started from the web.
Design choice
Subagents isolate context, not just parallelise: exploration stays out of the main conversation, so the lead agent keeps room to think.
Without it
A single conversation fills up with search results, and long tasks either stop or forget their own beginning.

L3๐Ÿ” Agent loop ยท How it decides the next step

What it does
The engine: ask the model for the next action, run it, feed back the result, repeat.
How it is built here
One general gather-context โ†’ act โ†’ verify loop for every task; no fixed workflow. The model emits tool calls; the harness executes them and returns results.
Design choice
Generality over workflows. The loop is deliberately simple; capability comes from the model and from what the other layers add.
Without it
You would have to draw every workflow in advance, which breaks on open-ended work like debugging.

๐Ÿ” How this loop compares with the other four, dial by dial, and its RSI level: Inside the Agent Loop

L4๐Ÿง  Context engine ยท What the model sees on each turn

What it does
Decides what the model sees on every turn, inside a fixed context window.
How it is built here
CLAUDE.md files (user, project, folder), auto memory, skills loaded on demand, subagent summaries, and compaction of older turns.
Design choice
Load little, fetch on demand. Instructions are short files; detail arrives through tools and skills only when needed.
Without it
Either the model forgets project rules, or the window fills with irrelevant text and quality drops.

L5๐Ÿ› ๏ธ Tools ยท What it can do

What it does
Turns intentions into actions: reading, editing, running, searching, calling outside systems.
How it is built here
Built-in file, shell and search tools; MCP servers for outside tools and data; skills that bundle instructions with scripts.
Design choice
A small set of powerful built-in tools (a shell can do almost anything) plus an open protocol for everything else.
Without it
Every integration would need custom code inside the harness, and the agent could not use your existing tools.

L6๐Ÿ›ก๏ธ Policy & safety ยท What it may do

What it does
Decides what the agent may do without asking, and enforces your own rules.
How it is built here
Allow / ask / deny permission rules per tool and pattern; session modes such as planning without edits โš ๏ธ; hooks that run your commands before or after actions; administrator-managed settings โš ๏ธ.
Design choice
Two kinds of control: probabilistic (instructions the model usually follows) and deterministic (permissions and hooks it cannot skip). Anything that must happen goes in the second kind.
Without it
The agent either asks about everything (approval fatigue) or nothing (risk), and "always run the formatter" depends on the model remembering.

L7๐Ÿ“ฆ Execution ยท Where actions actually run

What it does
Where commands actually run, with whose access.
How it is built here
Locally: your shell, your working directory, your user's permissions, with optional sandboxing โš ๏ธ. Web sessions run in Anthropic's cloud.
Design choice
Run where the developer already works, so the agent sees the real build, tests and tools, then add limits on top.
Without it
An agent in a separate environment cannot reproduce your bugs; an unrestricted one can damage your machine.

L8๐Ÿงฌ Model & telemetry ยท Which model, and what gets logged

What it does
The model that decides, and the records of what happened.
How it is built here
Claude models over the API (or through cloud providers โš ๏ธ); session transcripts, cost and usage reporting, organisation telemetry โš ๏ธ.
Design choice
The model is a dependency the harness is designed around; the harness keeps the record.
Without it
No way to review what the agent did, attribute cost, or debug a bad run.

4. Connecting the dots

๐Ÿงฌ Design DNA: the three decisions that define it

One general loopno fixed workflows; the model decides the steps
Configuration over codemarkdown files, rules, hooks, skills, MCP
Context is the scarce resourcesubagents, on-demand skills and compaction protect it

๐Ÿ’ธ Where the tokens go in the traced task (our estimate)

Instructions, tool schemas, memory (re-sent each turn)35% ยท ~105k
Tool results (files read, test output)30% ยท ~90k
Subagent work15% ยท ~45k
Model output (reasoning, edits)10% ยท ~30k
Retries and repeated turns10% ยท ~30k

An illustrative split for a ~300k-token task: about $1.20 at an assumed blended $4 per million tokens. Real numbers vary widely with the repo, the model and caching; the shape (context re-sent every turn dominates) is the point.

5. How it evolved

Feb 2025 Research preview released alongside Claude 3.7 Sonnet โš ๏ธ.
May 2025 General availability with Claude 4 and IDE integrations โš ๏ธ.
Mid 2025 Hooks added: deterministic commands before or after actions โš ๏ธ.
Jul 2025 Custom subagents โš ๏ธ.
Sep 2025 The Claude Code SDK renamed the Claude Agent SDK โš ๏ธ.
Oct 2025 Skills; Claude Code on the web; plugins โš ๏ธ.

6. Where it breaks, and what it does about it

FailureLayerWhat happensWhat this system does about it
Context overflowL4Long tasks fill the window; early instructions get lost.Compaction, subagents, short CLAUDE.md files, skills loaded on demand.
Going in circlesL3The agent retries the same failing approach.You can interrupt and redirect at any turn; planning before acting helps โš ๏ธ.
Wrong or destructive editsL6Edits the wrong file or runs a harmful command.Ask/deny rules, reviewing diffs, version control as the safety net.
Prompt injectionL5A file, web page or tool result contains instructions that hijack the agent.Permission prompts for risky tools, trusted MCP servers only, sandboxing โš ๏ธ.
Approval fatigueL6Too many prompts, so people approve without reading.Allow rules for safe commands; ask only for what matters.
Rules ignoredL4The model forgets a convention in CLAUDE.md.Move must-do rules into hooks (deterministic).
Cost surprisesL8Long sessions re-send large contexts many times.Usage reporting; smaller contexts; choosing the model per task.

7. Security and threat model

๐Ÿงฑ Trust boundaries

Leaves your machinethe context sent to the model on every turn (code you show it, tool results)
Untrusted inputsrepository files, web pages, MCP server responses, tool output: any can carry injected instructions
Powerful actionsshell commands and file writes with your user's access; network calls; MCP tools that act in other systems
Controlspermission rules and modes, hooks, sandboxing โš ๏ธ, administrator-managed settings โš ๏ธ, reviewing every diff and PR

Our summary of the threat model implied by the documented features.

8. Standards it shares, and benchmarks

9. What people use it for

IndividualDebuggingReproduce a failure, find the cause, fix it, re-run tests.
IndividualLearning a codebaseAsk how a system works; it reads and explains the code.
TeamRefactors and migrationsMulti-file changes with tests as the check.
TeamPull requests and reviewsOpen PRs, respond to review comments, fix CI.
TeamRepeatable workflowsSkills and hooks turn team conventions into automatic steps.
EnterpriseGoverned rolloutAdministrator settings, permission policies and usage reporting โš ๏ธ.
EnterpriseCustom agentsThe Agent SDK runs the same loop inside internal tools.
Beyond codeData and ops tasksAnything a shell and files can do: scripts, data cleaning, documentation (typical uses, not vendor case studies).

10. How to build one from scratch

mini_claude_code.py ยท Python 3, standard library only; scripted stub model
"""mini_claude_code.py โ€” a toy harness in the style of Claude Code (illustrative).

One general agent loop + configuration: an instructions file loaded every session,
built-in tools, permission rules, a post-edit hook and a subagent with its own
context. The "model" is a scripted stub so the run is repeatable; a real harness
calls an LLM API at the marked line. Standard library only.
"""
REPO = {"dates.py": "def parse(s):\n    d, m, y = s.split('/')\n    return (int(y), int(m), int(d))\n",
        "test_dates.py": "from dates import parse\nassert parse('2026-11-07') == (2026, 11, 7)\n"}
MEMORY = "Run tests with: python test_dates.py\nKeep diffs minimal."          # CLAUDE.md
PERMS = {"read": "allow", "search": "allow", "edit": "ask", "bash": "allow:tests"}
APPROVE = {"edit"}                                                         # the human says yes to edits

def run_tests():
    try:
        ns = {}; exec(REPO["dates.py"], ns)
        y = ns["parse"]("2026-11-07"); return "PASS" if y == (2026, 11, 7) else f"FAIL got {y}"
    except Exception as e:
        return f"FAIL {type(e).__name__}: {e}"

def tool(name, arg):
    rule = PERMS.get(name, "deny")
    if rule == "ask" and name not in APPROVE: return "denied by user"
    if name == "read": return REPO[arg]
    if name == "search": return [f for f, t in REPO.items() if arg in t]
    if name == "bash": return run_tests()
    if name == "edit":
        REPO[arg[0]] = arg[1]; return "edited " + arg[0] + " | hook: formatted"   # PostToolUse-style hook
    return "unknown tool"

def subagent(task):                     # own context: only the summary returns to the main loop
    hits = tool("search", "parse")
    return f"subagent summary: '{task}' -> parse() lives in {hits[0]}, test expects ISO dates"

SCRIPT = [("subagent", "find the failing test and the code it covers"), ("bash", None),
          ("edit", ("dates.py", "def parse(s):\n    y, m, d = s.split('-')\n    return (int(y), int(m), int(d))\n")),
          ("bash", None), ("done", "fixed parse() for ISO dates; tests pass; PR ready")]

def model(turn, context):               # <- a real harness calls the LLM here
    return SCRIPT[turn]

def main():
    context = ["system: " + MEMORY.splitlines()[0], "user: the date test fails, fix it and open a PR"]
    for turn in range(10):
        act, arg = model(turn, context)
        if act == "done": print(f"turn {turn + 1}: DONE  {arg}"); break
        out = subagent(arg) if act == "subagent" else tool(act, arg)
        context.append(f"{act} -> {out}")
        print(f"turn {turn + 1}: {act:8} [{PERMS.get(act, 'allow')}] -> {str(out).splitlines()[0]}")
    print(f"context lines: {len(context)} (the subagent's search stayed out of the main context)")

if __name__ == "__main__":
    main()
$ python3 mini_claude_code.py turn 1: subagent [allow] -> subagent summary: 'find the failing test and the code it covers' -> parse() lives in dates.py, test expects ISO dates turn 2: bash [allow:tests] -> FAIL ValueError: not enough values to unpack (expected 3, got 1) turn 3: edit [ask] -> edited dates.py | hook: formatted turn 4: bash [allow:tests] -> PASS turn 5: DONE fixed parse() for ISO dates; tests pass; PR ready context lines: 6 (the subagent's search stayed out of the main context)
PhaseWhat you buildTime*Team*Cost*
0 ยท PrototypeLoop, file and shell tools, one model API, an instructions file1โ€“2 weeks1 engineer$15โ€“40k
1 ยท Usable CLIDiff-based edits, permission prompts, test running, session resume1โ€“3 months2โ€“3$150โ€“400k
2 ยท ReliableContext compaction, retries, transcripts, evaluation suite, sandboxing3โ€“6 months4โ€“8$0.5โ€“1.5M
3 ยท ExtensibleMCP client, skills, hooks, subagents, settings hierarchy+3โ€“4 months6โ€“10$0.5โ€“1M
4 ยท ProductIDE extensions, web and cloud sessions, accounts, admin policies, telemetry, security review6โ€“12 months15โ€“40+$3โ€“10M+ a year

*Our estimates, not vendor figures: fully loaded engineer cost assumed at $250k a year (US-style salaries; lower elsewhere), plus model API and infrastructure. Treat as orders of magnitude.

๐Ÿงฎ What would running your own cost a month?

Our model: model cost = tasks ร— tokens ร— price ร— 30 days; people = engineers ร— $250k รท 12; infrastructure (sandboxes, storage, logs) assumed at 15% of model cost. A blended price mixes cached input, fresh input and output; check your provider's current prices.

11. When to choose it

โœ… Choose it when

  • Open-ended, multi-step work in a real codebase.
  • You want one agent across terminal, IDE and web.
  • You extend with MCP, skills and hooks rather than writing orchestration code.

โš ๏ธ Think twice when

  • You need a fixed, auditable workflow with known steps: use a framework.
  • You need to modify the harness itself: choose an open-source one.
  • You must serve agents to thousands of users: add a runtime (wave 3).

12. How it compares, layer by layer

HarnessL1InterfacesL2Sessions & orchestrationL3Agent loopL4Context engineL5ToolsL6Policy & safetyL7ExecutionL8Model & telemetry
Claude CodeTerminal, IDE, desktop, web, Slack; Agent SDKSessions with resume; subagents; cloud sessions on the webOne general think โ†’ act โ†’ observe loopCLAUDE.md, auto memory, compactionBuilt-in file/shell/search tools, MCP, skillsPermission rules and modes, hooksYour machine (optional sandboxing โš ๏ธ); cloud for web sessionsClaude models; transcripts, cost and usage telemetry
CodexTerminal, IDE, web (chatgpt.com/codex)Parallel cloud tasks; local sessionsAgent loop per taskAGENTS.md, repo contextShell, file edits, MCPApproval modes โš ๏ธOS sandbox locally โš ๏ธ; container per cloud taskOpenAI models; task logs and diffs
Gemini CLI / JulesTerminal (CLI); browser + GitHub (Jules)Interactive session vs asynchronous taskAgent loop (CLI); plan-then-execute (Jules โš ๏ธ)GEMINI.md context filesBuilt-in tools, MCPConfirmations in the CLI; plan approval in Jules โš ๏ธYour machine (CLI); cloud VM (Jules โš ๏ธ)Gemini models (CLI "not optimized for Gemini 4+")
Deep AgentsYour own app (library)LangGraph threads; sub-agentsPlanning loop on LangGraphFilesystem as memory; offloadingYour tools, MCP, skillsHuman-in-the-loop interruptsPluggable backends: local, sandboxed, remoteAny chat model; LangGraph state and tracing
Hermes AgentTerminal + Telegram, Discord, Slack, WhatsApp, Signal, emailGateway, subagents, cron schedulerAgent loop (details on its docs site โš ๏ธ)Curated memory, FTS5 session search, user modelTools, self-written skills (agentskills.io), Python RPC scriptsDepends on backend and configuration โš ๏ธSix backends: local, Docker, SSH, Modal, Daytona, Vercel SandboxModel you configure โš ๏ธ

One line per layer; our reading of each project's documentation and code as of 7 Nov 2026.

HarnessRuns whereOpen sourceSubagentsPersistent memorySkillsMCPSandboxHuman approvalAsync / cloud tasks
Claude CodeTerminal, IDE, desktop, webโ€”โœ“โœ“โœ“โœ“โ—โœ“โœ“
CodexTerminal, IDE, cloudโœ“ (CLI)โ—โ—โ—โœ“โœ“โœ“โœ“
Gemini CLI / JulesTerminal (CLI), cloud VM (Jules)โœ“ (CLI)โ—โ—โ—โœ“โ—โœ“โœ“
Deep AgentsYour Python / JS appโœ“โœ“โ—โœ“โœ“โ—โœ“โ€”
Hermes AgentTerminal + chat appsโœ“โœ“โœ“โœ“โ—โœ“โ—โœ“

โœ“ built in ยท โ— partial or via add-ons ยท โ€” not a feature. Our reading of each project's documentation as of 7 Nov 2026; check before relying on it.

13. The series

Agentic AI System Designs: four kinds of agent system, one teardown each

Start here๐Ÿงญ Four ways to build an agentHarness๐Ÿงฐ Claude Code (this article)Harness๐Ÿงฐ CodexHarness๐Ÿงฐ Gemini CLI, Antigravity & JulesHarness๐Ÿงฐ Deep AgentsHarness๐Ÿงฐ Hermes AgentFramework๐Ÿงฑ OpenAI Agents SDK ยท comingFramework๐Ÿงฑ Google ADK ยท comingFramework๐Ÿงฑ LangChain / LangGraph ยท comingFramework๐Ÿงฑ CrewAI ยท comingFramework๐Ÿงฑ Claude Agent SDK & Microsoft Agent Framework ยท comingRuntimeโš™๏ธ Amazon Bedrock AgentCore ยท comingRuntimeโš™๏ธ LangSmith Deployment ยท comingRuntimeโš™๏ธ Temporal ยท comingRuntimeโš™๏ธ Vertex AI Agent Engine & Azure AI Foundry ยท comingBuilder๐Ÿงฉ n8n ยท comingBuilder๐Ÿงฉ Zapier Agents ยท comingBuilder๐Ÿงฉ Microsoft Copilot Studio ยท comingBuilder๐Ÿงฉ Make ยท coming

All of them on one page: Agentic Systems at a Glance.

๐Ÿ“– Glossary: 15 terms used across the series
Agent loop
The repeat cycle: the model picks an action, the harness runs it, the result goes back to the model.
Harness
Everything around the model that turns it into a working agent: loop, tools, context, policy, execution.
Context window
The text the model can see at once. Everything the agent knows on a turn has to fit in it.
Context compaction
Summarising older conversation so a long task keeps fitting in the context window.
Tool schema
A machine-readable description of a tool (name, inputs) that tells the model how to call it.
MCP
Model Context Protocol: an open standard for connecting agents to outside tools and data.
Subagent
A second agent with its own context, used for a side task; only its summary comes back.
Skill
A packaged set of instructions (and sometimes scripts) the agent loads when relevant.
Hook
Your own command that runs automatically before or after an agent action.
Sandbox
A restricted place to run commands so mistakes or attacks cannot reach the rest of the system.
Approval mode
The rule for what the agent may do without asking you first.
Prompt injection
Instructions hidden in data the agent reads (a file, a web page) that try to hijack it.
Trace
The full record of a run: every model call, tool call and result.
AGENTS.md / CLAUDE.md / GEMINI.md
Plain markdown files of project instructions that harnesses read at the start of a session.
Asynchronous agent
An agent you hand a task to and leave; it returns a result (often a pull request) later.

14. Sources