chapter 26

agent harnesses

claude code, cursor, aider, codex cli — they're all the same four layers wrapped around the same model api. learn what those layers are, what each adds, and what you'd build yourself if you had to. when the harness changes the world, the rollback lives in the repo — a runbook a junior can execute at 3am.claude code, cursor, aider, codex cli — they're all the same four layers wrapped around the same model api. learn what those layers are, what each adds, and what you'd build yourself if you had to. when the harness changes the world, the rollback lives in the repo — a runbook a junior can execute at 3am.claude code, cursor, aider, codex cli — they're all the same four layers wrapped around the same model api. learn what those layers are, what each adds, and what you'd build yourself if you had to. when the harness changes the world, the rollback lives in the repo — a runbook a junior can execute at 3am.

5 live lessons · 37 live steps · 119 XP

The thirty lines you've already written, productized

Every coding agent you use — Claude Code, Cursor, Aider, Continue, Cline, Codex CLI, OpenCode — is the same shape underneath. A user types something, the harness loads context (config files, recent edits, git state, open buffers), calls the model, parses the response, runs any tools the model asked for, sends results back, repeats. Chapter 16 had you write that loop. This chapter asks: what does Claude Code add on top, and could you build it yourself?

The answer to "could you build it yourself" turns out to be yes — minimum viable harnesses are around 200 lines of Python. The interesting questions are which of the additions are load-bearing (you need them) versus which are sugar (your particular workflow doesn't).

The four layers every harness has

Input prep — load the config files (CLAUDE.md, AGENTS.md), gather context (recent diffs, open files, project structure), construct the messages list. This is where most production harnesses spend the most code, because "good context" is what separates Cursor's experience from a raw API call.
Model call — the actual messages.create(...). Boring, but harnesses differ on prompt-cache strategy, retry logic, streaming, and provider routing (some support multiple providers).
Output parsing — read content blocks, dispatch tool_use, accumulate text. Chapter 13 lesson 02 covered the primitive; harnesses wrap it with display logic and incremental rendering.
Tool dispatch — run the model's requested tools. Bash, file edits, web searches, git operations. The tool registry is what makes a harness agentic — the model can change the world, not just describe it.

Different harnesses emphasize different layers. Aider's strength is layer 1 (it's exceptional at gathering relevant context from a codebase). Cursor's strength is layer 4 (its tool palette and edit-application UX). Claude Code's strength is the config layer on top — CLAUDE.md hierarchy, hooks, slash commands.

Why this chapter matters

Three reasons to learn what's in a harness:

You'll build one eventually. Whatever you ship that uses LLMs will at some point need its own harness, even if narrow. The four layers are a checklist for what to build.
You'll choose between them more wisely. Knowing what each tool optimizes lets you pick the right one for the task instead of using "whichever you opened first."
You'll debug them when they fail. Harnesses are leaky abstractions; production failures usually happen between layers (context loaded badly, tool dispatched wrong, parsing missed a block). Knowing the layer model is how you triage.

Layer 4 can change the world, so the failure path has to live next to the harness. A wiki page is not that path. Lesson 04 is the on-call seat's runbook as data — detect, decide rollback versus continue, name a human if the decision cannot run, write the record back to the repo. One role at a time.

What AI specifically gets wrong

Building a "harness" that's actually just a wrapper around messages.create. A harness without a tool registry is a chat client. Useful, but not what people mean.
Hardcoding the tool registry inside the loop. When you want to add a tool, you edit the loop instead of registering one. Three tools later, the loop is unreadable.
Skipping retries. Real provider APIs 429, 503, hit rate limits. A harness without retries crashes on transient errors and the user blames the model.
Loading the world into context "just in case." Some harnesses dump everything in the project as context. Token bill explodes. The fix is retrieval, not stuffing — gather only what the current task needs.
Leaving the rollback in a wiki. "If it looks bad, use your judgment" is a page, not a runbook. The junior at 3am needs detect / decide / named human / writeback as data in the checkout.

What you'll be able to do at the end

By the end of this chapter you'll have:

Written a minimal harness — input prep, model call, output parsing, tool dispatch — in under 200 lines.
Read Cursor's, Claude Code's, and Aider's docs and identified which layer each one optimizes.
Spotted the four common harness bugs by reading code.
Decided which tools to use for which tasks based on layer-level strengths, not feature lists.
Written a 3am incident runbook as data a junior can execute from the repo: detect the signal, decide rollback versus continue, name a human if needed, write the record back.

After this chapter, the difference between "I use an AI coding tool" and "I understand what I'm using" stops mattering. They're the same sentence.

The thirty lines you've already written, productized

The four layers every harness has

Input prep — load the config files (CLAUDE.md, AGENTS.md), gather context (recent diffs, open files, project structure), construct the messages list. This is where most production harnesses spend the most code, because "good context" is what separates Cursor's experience from a raw API call.
Model call — the actual messages.create(...). Boring, but harnesses differ on prompt-cache strategy, retry logic, streaming, and provider routing (some support multiple providers).
Output parsing — read content blocks, dispatch tool_use, accumulate text. Chapter 13 lesson 02 covered the primitive; harnesses wrap it with display logic and incremental rendering.
Tool dispatch — run the model's requested tools. Bash, file edits, web searches, git operations. The tool registry is what makes a harness agentic — the model can change the world, not just describe it.

Why this chapter matters

Three reasons to learn what's in a harness:

You'll build one eventually. Whatever you ship that uses LLMs will at some point need its own harness, even if narrow. The four layers are a checklist for what to build.
You'll choose between them more wisely. Knowing what each tool optimizes lets you pick the right one for the task instead of using "whichever you opened first."
You'll debug them when they fail. Harnesses are leaky abstractions; production failures usually happen between layers (context loaded badly, tool dispatched wrong, parsing missed a block). Knowing the layer model is how you triage.

What AI specifically gets wrong

Building a "harness" that's actually just a wrapper around messages.create. A harness without a tool registry is a chat client. Useful, but not what people mean.
Hardcoding the tool registry inside the loop. When you want to add a tool, you edit the loop instead of registering one. Three tools later, the loop is unreadable.
Skipping retries. Real provider APIs 429, 503, hit rate limits. A harness without retries crashes on transient errors and the user blames the model.
Loading the world into context "just in case." Some harnesses dump everything in the project as context. Token bill explodes. The fix is retrieval, not stuffing — gather only what the current task needs.
Leaving the rollback in a wiki. "If it looks bad, use your judgment" is a page, not a runbook. The junior at 3am needs detect / decide / named human / writeback as data in the checkout.

What you'll be able to do at the end

By the end of this chapter you'll have:

Written a minimal harness — input prep, model call, output parsing, tool dispatch — in under 200 lines.
Read Cursor's, Claude Code's, and Aider's docs and identified which layer each one optimizes.
Spotted the four common harness bugs by reading code.
Decided which tools to use for which tasks based on layer-level strengths, not feature lists.
Written a 3am incident runbook as data a junior can execute from the repo: detect the signal, decide rollback versus continue, name a human if needed, write the record back.

After this chapter, the difference between "I use an AI coding tool" and "I understand what I'm using" stops mattering. They're the same sentence.

The thirty lines you've already written, productized

Every coding agent you use — Claude Code, Cursor, Aider, Continue, Cline, Codex CLI, OpenCode — is the same shape underneath. A user types something, the harness loads context (config files, recent edits, git state, open buffers), calls the model, parses the response, runs any tools the model asked for, sends results back, repeats. The agent loops chapter had you write that loop. This chapter asks: what does Claude Code add on top, and could you build it yourself?

The four layers every harness has

Input prep — load the config files (CLAUDE.md, AGENTS.md), gather context (recent diffs, open files, project structure), construct the messages list. This is where most production harnesses spend the most code, because "good context" is what separates Cursor's experience from a raw API call.
Model call — the actual messages.create(...). Boring, but harnesses differ on prompt-cache strategy, retry logic, streaming, and provider routing (some support multiple providers).
Output parsing — read content blocks, dispatch tool_use, accumulate text. Chapter 7 lesson 02 covered the primitive; harnesses wrap it with display logic and incremental rendering.
Tool dispatch — run the model's requested tools. Bash, file edits, web searches, git operations. The tool registry is what makes a harness agentic — the model can change the world, not just describe it.

Why this chapter matters

Three reasons to learn what's in a harness:

You'll build one eventually. Whatever you ship that uses LLMs will at some point need its own harness, even if narrow. The four layers are a checklist for what to build.
You'll choose between them more wisely. Knowing what each tool optimizes lets you pick the right one for the task instead of using "whichever you opened first."
You'll debug them when they fail. Harnesses are leaky abstractions; production failures usually happen between layers (context loaded badly, tool dispatched wrong, parsing missed a block). Knowing the layer model is how you triage.

What AI specifically gets wrong

Building a "harness" that's actually just a wrapper around messages.create. A harness without a tool registry is a chat client. Useful, but not what people mean.
Hardcoding the tool registry inside the loop. When you want to add a tool, you edit the loop instead of registering one. Three tools later, the loop is unreadable.
Skipping retries. Real provider APIs 429, 503, hit rate limits. A harness without retries crashes on transient errors and the user blames the model.
Loading the world into context "just in case." Some harnesses dump everything in the project as context. Token bill explodes. The fix is retrieval, not stuffing — gather only what the current task needs.
Leaving the rollback in a wiki. "If it looks bad, use your judgment" is a page, not a runbook. The junior at 3am needs detect / decide / named human / writeback as data in the checkout.

What you'll be able to do at the end

By the end of this chapter you'll have:

Written a minimal harness — input prep, model call, output parsing, tool dispatch — in under 200 lines.
Read Cursor's, Claude Code's, and Aider's docs and identified which layer each one optimizes.
Spotted the four common harness bugs by reading code.
Decided which tools to use for which tasks based on layer-level strengths, not feature lists.
Written a 3am incident runbook as data a junior can execute from the repo: detect the signal, decide rollback versus continue, name a human if needed, write the record back.

After this chapter, the difference between "I use an AI coding tool" and "I understand what I'm using" stops mattering. They're the same sentence.

The thirty lines you've already written, productized

Every coding agent you use — Claude Code, Cursor, Aider, Continue, Cline, Codex CLI, OpenCode — is the same shape underneath. A user types something, the harness loads context (config files, recent edits, git state, open buffers), calls the model, parses the response, runs any tools the model asked for, sends results back, repeats. The agent loops chapter had you write that loop. This chapter asks: what does Claude Code add on top, and could you build it yourself?

The four layers every harness has

Input prep — load the config files (CLAUDE.md, AGENTS.md), gather context (recent diffs, open files, project structure), construct the messages list. This is where most production harnesses spend the most code, because "good context" is what separates Cursor's experience from a raw API call.
Model call — the actual messages.create(...). Boring, but harnesses differ on prompt-cache strategy, retry logic, streaming, and provider routing (some support multiple providers).
Output parsing — read content blocks, dispatch tool_use, accumulate text. Chapter 7 lesson 02 covered the primitive; harnesses wrap it with display logic and incremental rendering.
Tool dispatch — run the model's requested tools. Bash, file edits, web searches, git operations. The tool registry is what makes a harness agentic — the model can change the world, not just describe it.

Why this chapter matters

Three reasons to learn what's in a harness:

You'll build one eventually. Whatever you ship that uses LLMs will at some point need its own harness, even if narrow. The four layers are a checklist for what to build.
You'll choose between them more wisely. Knowing what each tool optimizes lets you pick the right one for the task instead of using "whichever you opened first."
You'll debug them when they fail. Harnesses are leaky abstractions; production failures usually happen between layers (context loaded badly, tool dispatched wrong, parsing missed a block). Knowing the layer model is how you triage.

What AI specifically gets wrong

Building a "harness" that's actually just a wrapper around messages.create. A harness without a tool registry is a chat client. Useful, but not what people mean.
Hardcoding the tool registry inside the loop. When you want to add a tool, you edit the loop instead of registering one. Three tools later, the loop is unreadable.
Skipping retries. Real provider APIs 429, 503, hit rate limits. A harness without retries crashes on transient errors and the user blames the model.
Loading the world into context "just in case." Some harnesses dump everything in the project as context. Token bill explodes. The fix is retrieval, not stuffing — gather only what the current task needs.
Leaving the rollback in a wiki. "If it looks bad, use your judgment" is a page, not a runbook. The junior at 3am needs detect / decide / named human / writeback as data in the checkout.

What you'll be able to do at the end

By the end of this chapter you'll have:

Written a minimal harness — input prep, model call, output parsing, tool dispatch — in under 200 lines.
Read Cursor's, Claude Code's, and Aider's docs and identified which layer each one optimizes.
Spotted the four common harness bugs by reading code.
Decided which tools to use for which tasks based on layer-level strengths, not feature lists.
Written a 3am incident runbook as data a junior can execute from the repo: detect the signal, decide rollback versus continue, name a human if needed, write the record back.

After this chapter, the difference between "I use an AI coding tool" and "I understand what I'm using" stops mattering. They're the same sentence.

The thirty lines you've already written, productized

Every coding agent you use — Claude Code, Cursor, Aider, Continue, Cline, Codex CLI, OpenCode — is the same shape underneath. A user types something, the harness loads context (config files, recent edits, git state, open buffers), calls the model, parses the response, runs any tools the model asked for, sends results back, repeats. Chapter 9 had you write that loop. This chapter asks: what does Claude Code add on top, and could you build it yourself?

The four layers every harness has

Input prep — load the config files (CLAUDE.md, AGENTS.md), gather context (recent diffs, open files, project structure), construct the messages list. This is where most production harnesses spend the most code, because "good context" is what separates Cursor's experience from a raw API call.
Model call — the actual messages.create(...). Boring, but harnesses differ on prompt-cache strategy, retry logic, streaming, and provider routing (some support multiple providers).
Output parsing — read content blocks, dispatch tool_use, accumulate text. Chapter 7 lesson 02 covered the primitive; harnesses wrap it with display logic and incremental rendering.
Tool dispatch — run the model's requested tools. Bash, file edits, web searches, git operations. The tool registry is what makes a harness agentic — the model can change the world, not just describe it.

Why this chapter matters

Three reasons to learn what's in a harness:

You'll build one eventually. Whatever you ship that uses LLMs will at some point need its own harness, even if narrow. The four layers are a checklist for what to build.
You'll choose between them more wisely. Knowing what each tool optimizes lets you pick the right one for the task instead of using "whichever you opened first."
You'll debug them when they fail. Harnesses are leaky abstractions; production failures usually happen between layers (context loaded badly, tool dispatched wrong, parsing missed a block). Knowing the layer model is how you triage.

What AI specifically gets wrong

Building a "harness" that's actually just a wrapper around messages.create. A harness without a tool registry is a chat client. Useful, but not what people mean.
Hardcoding the tool registry inside the loop. When you want to add a tool, you edit the loop instead of registering one. Three tools later, the loop is unreadable.
Skipping retries. Real provider APIs 429, 503, hit rate limits. A harness without retries crashes on transient errors and the user blames the model.
Loading the world into context "just in case." Some harnesses dump everything in the project as context. Token bill explodes. The fix is retrieval, not stuffing — gather only what the current task needs.
Leaving the rollback in a wiki. "If it looks bad, use your judgment" is a page, not a runbook. The junior at 3am needs detect / decide / named human / writeback as data in the checkout.

What you'll be able to do at the end

By the end of this chapter you'll have:

Written a minimal harness — input prep, model call, output parsing, tool dispatch — in under 200 lines.
Read Cursor's, Claude Code's, and Aider's docs and identified which layer each one optimizes.
Spotted the four common harness bugs by reading code.
Decided which tools to use for which tasks based on layer-level strengths, not feature lists.
Written a 3am incident runbook as data a junior can execute from the repo: detect the signal, decide rollback versus continue, name a human if needed, write the record back.

After this chapter, the difference between "I use an AI coding tool" and "I understand what I'm using" stops mattering. They're the same sentence.

The thirty lines you've already written, productized

Every coding agent you use — Claude Code, Cursor, Aider, Continue, Cline, Codex CLI, OpenCode — is the same shape underneath. A user types something, the harness loads context (config files, recent edits, git state, open buffers), calls the model, parses the response, runs any tools the model asked for, sends results back, repeats. The agent loops chapter had you write that loop. This chapter asks: what does Claude Code add on top, and could you build it yourself?

The four layers every harness has

Input prep — load the config files (CLAUDE.md, AGENTS.md), gather context (recent diffs, open files, project structure), construct the messages list. This is where most production harnesses spend the most code, because "good context" is what separates Cursor's experience from a raw API call.
Model call — the actual messages.create(...). Boring, but harnesses differ on prompt-cache strategy, retry logic, streaming, and provider routing (some support multiple providers).
Output parsing — read content blocks, dispatch tool_use, accumulate text. Chapter 7 lesson 02 covered the primitive; harnesses wrap it with display logic and incremental rendering.
Tool dispatch — run the model's requested tools. Bash, file edits, web searches, git operations. The tool registry is what makes a harness agentic — the model can change the world, not just describe it.

Why this chapter matters

Three reasons to learn what's in a harness:

You'll build one eventually. Whatever you ship that uses LLMs will at some point need its own harness, even if narrow. The four layers are a checklist for what to build.
You'll choose between them more wisely. Knowing what each tool optimizes lets you pick the right one for the task instead of using "whichever you opened first."
You'll debug them when they fail. Harnesses are leaky abstractions; production failures usually happen between layers (context loaded badly, tool dispatched wrong, parsing missed a block). Knowing the layer model is how you triage.

What AI specifically gets wrong

Building a "harness" that's actually just a wrapper around messages.create. A harness without a tool registry is a chat client. Useful, but not what people mean.
Hardcoding the tool registry inside the loop. When you want to add a tool, you edit the loop instead of registering one. Three tools later, the loop is unreadable.
Skipping retries. Real provider APIs 429, 503, hit rate limits. A harness without retries crashes on transient errors and the user blames the model.
Loading the world into context "just in case." Some harnesses dump everything in the project as context. Token bill explodes. The fix is retrieval, not stuffing — gather only what the current task needs.
Leaving the rollback in a wiki. "If it looks bad, use your judgment" is a page, not a runbook. The junior at 3am needs detect / decide / named human / writeback as data in the checkout.

What you'll be able to do at the end

By the end of this chapter you'll have:

Written a minimal harness — input prep, model call, output parsing, tool dispatch — in under 200 lines.
Read Cursor's, Claude Code's, and Aider's docs and identified which layer each one optimizes.
Spotted the four common harness bugs by reading code.
Decided which tools to use for which tasks based on layer-level strengths, not feature lists.
Written a 3am incident runbook as data a junior can execute from the repo: detect the signal, decide rollback versus continue, name a human if needed, write the record back.

After this chapter, the difference between "I use an AI coding tool" and "I understand what I'm using" stops mattering. They're the same sentence.

The thirty lines you've already written, productized

Every coding agent you use — Claude Code, Cursor, Aider, Continue, Cline, Codex CLI, OpenCode — is the same shape underneath. A user types something, the harness loads context (config files, recent edits, git state, open buffers), calls the model, parses the response, runs any tools the model asked for, sends results back, repeats. The agent loops chapter had you write that loop. This chapter asks: what does Claude Code add on top, and could you build it yourself?

The four layers every harness has

Input prep — load the config files (CLAUDE.md, AGENTS.md), gather context (recent diffs, open files, project structure), construct the messages list. This is where most production harnesses spend the most code, because "good context" is what separates Cursor's experience from a raw API call.
Model call — the actual messages.create(...). Boring, but harnesses differ on prompt-cache strategy, retry logic, streaming, and provider routing (some support multiple providers).
Output parsing — read content blocks, dispatch tool_use, accumulate text. Chapter 11 lesson 02 covered the primitive; harnesses wrap it with display logic and incremental rendering.
Tool dispatch — run the model's requested tools. Bash, file edits, web searches, git operations. The tool registry is what makes a harness agentic — the model can change the world, not just describe it.

Why this chapter matters

Three reasons to learn what's in a harness:

You'll build one eventually. Whatever you ship that uses LLMs will at some point need its own harness, even if narrow. The four layers are a checklist for what to build.
You'll choose between them more wisely. Knowing what each tool optimizes lets you pick the right one for the task instead of using "whichever you opened first."
You'll debug them when they fail. Harnesses are leaky abstractions; production failures usually happen between layers (context loaded badly, tool dispatched wrong, parsing missed a block). Knowing the layer model is how you triage.

What AI specifically gets wrong

Building a "harness" that's actually just a wrapper around messages.create. A harness without a tool registry is a chat client. Useful, but not what people mean.
Hardcoding the tool registry inside the loop. When you want to add a tool, you edit the loop instead of registering one. Three tools later, the loop is unreadable.
Skipping retries. Real provider APIs 429, 503, hit rate limits. A harness without retries crashes on transient errors and the user blames the model.
Loading the world into context "just in case." Some harnesses dump everything in the project as context. Token bill explodes. The fix is retrieval, not stuffing — gather only what the current task needs.
Leaving the rollback in a wiki. "If it looks bad, use your judgment" is a page, not a runbook. The junior at 3am needs detect / decide / named human / writeback as data in the checkout.

What you'll be able to do at the end

By the end of this chapter you'll have:

Written a minimal harness — input prep, model call, output parsing, tool dispatch — in under 200 lines.
Read Cursor's, Claude Code's, and Aider's docs and identified which layer each one optimizes.
Spotted the four common harness bugs by reading code.
Decided which tools to use for which tasks based on layer-level strengths, not feature lists.
Written a 3am incident runbook as data a junior can execute from the repo: detect the signal, decide rollback versus continue, name a human if needed, write the record back.

After this chapter, the difference between "I use an AI coding tool" and "I understand what I'm using" stops mattering. They're the same sentence.

The thirty lines you've already written, productized

Every coding agent you use — Claude Code, Cursor, Aider, Continue, Cline, Codex CLI, OpenCode — is the same shape underneath. A user types something, the harness loads context (config files, recent edits, git state, open buffers), calls the model, parses the response, runs any tools the model asked for, sends results back, repeats. The agent loops chapter had you write that loop. This chapter asks: what does Claude Code add on top, and could you build it yourself?

The four layers every harness has

Input prep — load the config files (CLAUDE.md, AGENTS.md), gather context (recent diffs, open files, project structure), construct the messages list. This is where most production harnesses spend the most code, because "good context" is what separates Cursor's experience from a raw API call.
Model call — the actual messages.create(...). Boring, but harnesses differ on prompt-cache strategy, retry logic, streaming, and provider routing (some support multiple providers).
Output parsing — read content blocks, dispatch tool_use, accumulate text. Chapter 8 lesson 02 covered the primitive; harnesses wrap it with display logic and incremental rendering.
Tool dispatch — run the model's requested tools. Bash, file edits, web searches, git operations. The tool registry is what makes a harness agentic — the model can change the world, not just describe it.

Why this chapter matters

Three reasons to learn what's in a harness:

You'll build one eventually. Whatever you ship that uses LLMs will at some point need its own harness, even if narrow. The four layers are a checklist for what to build.
You'll choose between them more wisely. Knowing what each tool optimizes lets you pick the right one for the task instead of using "whichever you opened first."
You'll debug them when they fail. Harnesses are leaky abstractions; production failures usually happen between layers (context loaded badly, tool dispatched wrong, parsing missed a block). Knowing the layer model is how you triage.

What AI specifically gets wrong

Building a "harness" that's actually just a wrapper around messages.create. A harness without a tool registry is a chat client. Useful, but not what people mean.
Hardcoding the tool registry inside the loop. When you want to add a tool, you edit the loop instead of registering one. Three tools later, the loop is unreadable.
Skipping retries. Real provider APIs 429, 503, hit rate limits. A harness without retries crashes on transient errors and the user blames the model.
Loading the world into context "just in case." Some harnesses dump everything in the project as context. Token bill explodes. The fix is retrieval, not stuffing — gather only what the current task needs.
Leaving the rollback in a wiki. "If it looks bad, use your judgment" is a page, not a runbook. The junior at 3am needs detect / decide / named human / writeback as data in the checkout.

What you'll be able to do at the end

By the end of this chapter you'll have:

Written a minimal harness — input prep, model call, output parsing, tool dispatch — in under 200 lines.
Read Cursor's, Claude Code's, and Aider's docs and identified which layer each one optimizes.
Spotted the four common harness bugs by reading code.
Decided which tools to use for which tasks based on layer-level strengths, not feature lists.
Written a 3am incident runbook as data a junior can execute from the repo: detect the signal, decide rollback versus continue, name a human if needed, write the record back.

After this chapter, the difference between "I use an AI coding tool" and "I understand what I'm using" stops mattering. They're the same sentence.

The thirty lines you've already written, productized

Every coding agent you use — Claude Code, Cursor, Aider, Continue, Cline, Codex CLI, OpenCode — is the same shape underneath. A user types something, the harness loads context (config files, recent edits, git state, open buffers), calls the model, parses the response, runs any tools the model asked for, sends results back, repeats. The agent loops chapter had you write that loop. This chapter asks: what does Claude Code add on top, and could you build it yourself?

The four layers every harness has

Input prep — load the config files (CLAUDE.md, AGENTS.md), gather context (recent diffs, open files, project structure), construct the messages list. This is where most production harnesses spend the most code, because "good context" is what separates Cursor's experience from a raw API call.
Model call — the actual messages.create(...). Boring, but harnesses differ on prompt-cache strategy, retry logic, streaming, and provider routing (some support multiple providers).
Output parsing — read content blocks, dispatch tool_use, accumulate text. Chapter 7 lesson 02 covered the primitive; harnesses wrap it with display logic and incremental rendering.
Tool dispatch — run the model's requested tools. Bash, file edits, web searches, git operations. The tool registry is what makes a harness agentic — the model can change the world, not just describe it.

Why this chapter matters

Three reasons to learn what's in a harness:

You'll build one eventually. Whatever you ship that uses LLMs will at some point need its own harness, even if narrow. The four layers are a checklist for what to build.
You'll choose between them more wisely. Knowing what each tool optimizes lets you pick the right one for the task instead of using "whichever you opened first."
You'll debug them when they fail. Harnesses are leaky abstractions; production failures usually happen between layers (context loaded badly, tool dispatched wrong, parsing missed a block). Knowing the layer model is how you triage.

What AI specifically gets wrong

Building a "harness" that's actually just a wrapper around messages.create. A harness without a tool registry is a chat client. Useful, but not what people mean.
Hardcoding the tool registry inside the loop. When you want to add a tool, you edit the loop instead of registering one. Three tools later, the loop is unreadable.
Skipping retries. Real provider APIs 429, 503, hit rate limits. A harness without retries crashes on transient errors and the user blames the model.
Loading the world into context "just in case." Some harnesses dump everything in the project as context. Token bill explodes. The fix is retrieval, not stuffing — gather only what the current task needs.
Leaving the rollback in a wiki. "If it looks bad, use your judgment" is a page, not a runbook. The junior at 3am needs detect / decide / named human / writeback as data in the checkout.

What you'll be able to do at the end

By the end of this chapter you'll have:

Written a minimal harness — input prep, model call, output parsing, tool dispatch — in under 200 lines.
Read Cursor's, Claude Code's, and Aider's docs and identified which layer each one optimizes.
Spotted the four common harness bugs by reading code.
Decided which tools to use for which tasks based on layer-level strengths, not feature lists.
Written a 3am incident runbook as data a junior can execute from the repo: detect the signal, decide rollback versus continue, name a human if needed, write the record back.

After this chapter, the difference between "I use an AI coding tool" and "I understand what I'm using" stops mattering. They're the same sentence.

The thirty lines you've already written, productized

Every coding agent you use — Claude Code, Cursor, Aider, Continue, Cline, Codex CLI, OpenCode — is the same shape underneath. A user types something, the harness loads context (config files, recent edits, git state, open buffers), calls the model, parses the response, runs any tools the model asked for, sends results back, repeats. Chapter 13 had you write that loop. This chapter asks: what does Claude Code add on top, and could you build it yourself?

The four layers every harness has

Input prep — load the config files (CLAUDE.md, AGENTS.md), gather context (recent diffs, open files, project structure), construct the messages list. This is where most production harnesses spend the most code, because "good context" is what separates Cursor's experience from a raw API call.
Model call — the actual messages.create(...). Boring, but harnesses differ on prompt-cache strategy, retry logic, streaming, and provider routing (some support multiple providers).
Output parsing — read content blocks, dispatch tool_use, accumulate text. Chapter 10 lesson 02 covered the primitive; harnesses wrap it with display logic and incremental rendering.
Tool dispatch — run the model's requested tools. Bash, file edits, web searches, git operations. The tool registry is what makes a harness agentic — the model can change the world, not just describe it.

Why this chapter matters

Three reasons to learn what's in a harness:

You'll build one eventually. Whatever you ship that uses LLMs will at some point need its own harness, even if narrow. The four layers are a checklist for what to build.
You'll choose between them more wisely. Knowing what each tool optimizes lets you pick the right one for the task instead of using "whichever you opened first."
You'll debug them when they fail. Harnesses are leaky abstractions; production failures usually happen between layers (context loaded badly, tool dispatched wrong, parsing missed a block). Knowing the layer model is how you triage.

What AI specifically gets wrong

Building a "harness" that's actually just a wrapper around messages.create. A harness without a tool registry is a chat client. Useful, but not what people mean.
Hardcoding the tool registry inside the loop. When you want to add a tool, you edit the loop instead of registering one. Three tools later, the loop is unreadable.
Skipping retries. Real provider APIs 429, 503, hit rate limits. A harness without retries crashes on transient errors and the user blames the model.
Loading the world into context "just in case." Some harnesses dump everything in the project as context. Token bill explodes. The fix is retrieval, not stuffing — gather only what the current task needs.
Leaving the rollback in a wiki. "If it looks bad, use your judgment" is a page, not a runbook. The junior at 3am needs detect / decide / named human / writeback as data in the checkout.

What you'll be able to do at the end

By the end of this chapter you'll have:

Written a minimal harness — input prep, model call, output parsing, tool dispatch — in under 200 lines.
Read Cursor's, Claude Code's, and Aider's docs and identified which layer each one optimizes.
Spotted the four common harness bugs by reading code.
Decided which tools to use for which tasks based on layer-level strengths, not feature lists.
Written a 3am incident runbook as data a junior can execute from the repo: detect the signal, decide rollback versus continue, name a human if needed, write the record back.

After this chapter, the difference between "I use an AI coding tool" and "I understand what I'm using" stops mattering. They're the same sentence.

The thirty lines you've already written, productized

Every coding agent you use — Claude Code, Cursor, Aider, Continue, Cline, Codex CLI, OpenCode — is the same shape underneath. A user types something, the harness loads context (config files, recent edits, git state, open buffers), calls the model, parses the response, runs any tools the model asked for, sends results back, repeats. The agent loops chapter had you write that loop. This chapter asks: what does Claude Code add on top, and could you build it yourself?

The four layers every harness has

Input prep — load the config files (CLAUDE.md, AGENTS.md), gather context (recent diffs, open files, project structure), construct the messages list. This is where most production harnesses spend the most code, because "good context" is what separates Cursor's experience from a raw API call.
Model call — the actual messages.create(...). Boring, but harnesses differ on prompt-cache strategy, retry logic, streaming, and provider routing (some support multiple providers).
Output parsing — read content blocks, dispatch tool_use, accumulate text. Chapter 7 lesson 02 covered the primitive; harnesses wrap it with display logic and incremental rendering.
Tool dispatch — run the model's requested tools. Bash, file edits, web searches, git operations. The tool registry is what makes a harness agentic — the model can change the world, not just describe it.

Why this chapter matters

Three reasons to learn what's in a harness:

You'll build one eventually. Whatever you ship that uses LLMs will at some point need its own harness, even if narrow. The four layers are a checklist for what to build.
You'll choose between them more wisely. Knowing what each tool optimizes lets you pick the right one for the task instead of using "whichever you opened first."
You'll debug them when they fail. Harnesses are leaky abstractions; production failures usually happen between layers (context loaded badly, tool dispatched wrong, parsing missed a block). Knowing the layer model is how you triage.

What AI specifically gets wrong

Building a "harness" that's actually just a wrapper around messages.create. A harness without a tool registry is a chat client. Useful, but not what people mean.
Hardcoding the tool registry inside the loop. When you want to add a tool, you edit the loop instead of registering one. Three tools later, the loop is unreadable.
Skipping retries. Real provider APIs 429, 503, hit rate limits. A harness without retries crashes on transient errors and the user blames the model.
Loading the world into context "just in case." Some harnesses dump everything in the project as context. Token bill explodes. The fix is retrieval, not stuffing — gather only what the current task needs.
Leaving the rollback in a wiki. "If it looks bad, use your judgment" is a page, not a runbook. The junior at 3am needs detect / decide / named human / writeback as data in the checkout.

What you'll be able to do at the end

By the end of this chapter you'll have:

Written a minimal harness — input prep, model call, output parsing, tool dispatch — in under 200 lines.
Read Cursor's, Claude Code's, and Aider's docs and identified which layer each one optimizes.
Spotted the four common harness bugs by reading code.
Decided which tools to use for which tasks based on layer-level strengths, not feature lists.
Written a 3am incident runbook as data a junior can execute from the repo: detect the signal, decide rollback versus continue, name a human if needed, write the record back.

After this chapter, the difference between "I use an AI coding tool" and "I understand what I'm using" stops mattering. They're the same sentence.

agent harnesses

agent harnesses

agent harnesses

The thirty lines you've already written, productized

The four layers every harness has

Why this chapter matters

What AI specifically gets wrong

What you'll be able to do at the end

The thirty lines you've already written, productized

The four layers every harness has

Why this chapter matters

What AI specifically gets wrong

What you'll be able to do at the end

The thirty lines you've already written, productized

The four layers every harness has

Why this chapter matters

What AI specifically gets wrong

What you'll be able to do at the end

The thirty lines you've already written, productized

The four layers every harness has

Why this chapter matters

What AI specifically gets wrong

What you'll be able to do at the end

The thirty lines you've already written, productized

The four layers every harness has

Why this chapter matters

What AI specifically gets wrong

What you'll be able to do at the end

The thirty lines you've already written, productized

The four layers every harness has

Why this chapter matters

What AI specifically gets wrong

What you'll be able to do at the end

The thirty lines you've already written, productized

The four layers every harness has

Why this chapter matters

What AI specifically gets wrong

What you'll be able to do at the end

The thirty lines you've already written, productized

The four layers every harness has

Why this chapter matters

What AI specifically gets wrong

What you'll be able to do at the end

The thirty lines you've already written, productized

The four layers every harness has

Why this chapter matters

What AI specifically gets wrong

What you'll be able to do at the end

The thirty lines you've already written, productized

The four layers every harness has

Why this chapter matters

What AI specifically gets wrong

What you'll be able to do at the end

The thirty lines you've already written, productized

The four layers every harness has

Why this chapter matters

What AI specifically gets wrong

What you'll be able to do at the end

lessons in this chapter