Course: Master Course — Harness Engineering
Module / Section: 0 / 0.1
Duration: ~15 minutes (target audio)
Target word count: ~2,400 words at 130–150 wpm
Format: Verbatim transcript. Cues [SLIDE N] map to the reveal.js slide deck (03-slide-deck.html). Stage directions in italics. Paragraph breaks ≈ natural pauses.
[SLIDE 1 — Title]
This is Module Zero, Section One: What Is a Harness? It is the first fifteen minutes of a course that ends with you building a production-grade harness from scratch. Everything in the course hangs off the definition we settle here — so we are going to settle it carefully.
A warning before we start. The material in this module is easy to nod along to and hard to actually internalize. The single most common mistake senior engineers make with agents is misattributing behavior — blaming the model for things the harness did, and crediting the model for things the harness did. By the end of these fifteen minutes you should be unable to make that mistake again.
[SLIDE 2 — "When you say 'the AI did X'…"]
Start with a sentence you have said, or heard, a hundred times. "The AI did X." "The AI failed to do Y." "The AI decided to delete the file." "The AI remembered the user's name." Almost every time an engineer says something like this, they are describing behavior that has nothing — nothing — to do with the model weights. They are describing the harness.
Here is what the model actually is. The model is a function. You hand it a sequence of tokens; it hands you back the next token, or a structured output. That is the entire contract. The model has no memory across calls. It cannot run code. It cannot read a file. It does not know what time it is. It does not retry when something fails. It does not stop when a budget runs out. It does not ask a human for permission before it does something destructive.
All of that — every bit of behavior that makes the thing feel like an agent — is the harness. The harness is the product. The model is a powerful component. Get that backwards and the rest of the course will not land.
[SLIDE 3 — The model is 1.6% of the system]
Let me put a number on it. A study out of MBZUAI in May 2026 analyzed production agent systems and found that roughly ninety-eight point four percent of a real harness is infrastructure — loop, tools, memory, sandboxing, permissions, observability — and only about one point six percent is the AI decision logic, the part you would call "the model." And critically: four independently built agents, from different teams, converged on the same harness patterns.
Hold onto that one point six percent. We will come back to it twice more, from two different angles, before this module ends.
[SLIDE 4 — Definition]
So here is the definition we will use for the entire course. A harness is the infrastructure layer that wraps a language model and gives it the capability to act repeatedly in the world until a task is complete.
Break that down. "Infrastructure layer" — it is code, configuration, and runtime scaffolding, not weights. "Wraps a language model" — the model is inside it. "Act repeatedly in the world" — the model alone acts once; the harness makes it act again and again. "Until a task is complete" — there is a stop condition, owned by the harness.
And every harness, no matter how thin or thick, does exactly three jobs. It runs the model in a loop. It provides the model with tools. And it enforces safety and permission boundaries. Loop. Tools. Safety.
Miss any one of those three and what you have is not a harness — it is a prompt. A loop with no tools is a chatbot. Tools with no loop is a function call. A loop with tools and no safety is a loaded weapon pointed at your filesystem. These three are the minimal sufficient set, and every production harness has all three in some form.
[SLIDE 5 — The three jobs]
Job one: the loop. The model is stateless. A single call to model-dot-complete produces one response and terminates. To make the model behave like an agent — something that works toward a goal over multiple steps — you need a loop. point to code Here it is in TypeScript. Call the model. If it says it is done, return. If it asks for a tool, run the tool, push the result back into context, and call the model again. That is the whole loop. Pi's core loop is about eighty lines of TypeScript that does exactly this, plus a max-iterations guard. The model's intelligence is not in this code. The loop is pure orchestration.
Job two: tools. A stateless model can reason about the world but cannot act on it. Tools are the interface between the model's reasoning and real-world effects. A tool has a name, a description, an input schema, an implementation, and a result. And here is the security-critical point, which we will spend all of Module Two on: the model does not execute tools. The model emits a structured request for a tool call. The harness intercepts that request, executes the tool, and returns the result. The model never touches the filesystem, the network, or any external system directly. That indirection is a security boundary, not an implementation detail.
The number of tools a harness provides is one of the most consequential design decisions in harness engineering. Pi gives the model four. Claude Code gives it more than forty. We will come back to that gap.
Job three: safety. A loop with tools, given no constraints, will do whatever the model decides is appropriate to complete the task — including destructive, irreversible, or unauthorized actions. So the safety layer enforces constraints. Permission flags that explicitly enumerate what is enabled. Approval gates that require human confirmation before high-risk actions. Sandboxing that restricts the execution environment. Stop conditions that exit the loop before a bad state gets worse. Trust boundaries that tag world-derived content as untrusted before it enters context. And the thing to internalize: safety is not a feature you add after you build the harness. It is a dimension of every architectural decision.
[SLIDE 6 — The loop as a runnable n8n workflow]
Now. This course has a rule about how we present things visually, and the rule matters here. We use n8n first, diagrams second, code third. So before you read that TypeScript loop as text, look at it as a node graph.
point to workflow Here is the same loop, as an importable n8n workflow. Manual trigger at the top. Assemble context — that is the system prompt, the history, and the tool definitions, all gathered. Then the loop node, with a max-iterations cap — that is stop condition number one. Inside the loop: call the model. The model either says end-turn, in which case we are done and we output, or it asks for a tool — read file, write file, or bash. We route to the right tool, run it, append the result to history, and come back to the top of the loop.
Count the nodes. The model is one node of seven. The turn boundary — the place where one turn of the loop ends and the next begins — is that back-edge from "append tool result" into "loop." When you run this in the lab, you will watch the execution highlight travel that ring of nodes once per turn. That turn boundary is the single most important concept in the entire course, and the node graph makes it visible in a way the code does not. Same loop. Three representations. n8n to see it, Mermaid to reference it, TypeScript to ground it.
[SLIDE 7 — What a harness is not]
Before we move on, kill four common misconceptions.
A harness is not a fine-tuned model. The model inside a harness is typically a general-purpose foundation model. The harness shapes its behavior.
A harness is not a system prompt. The system prompt is one input — a small fraction of the harness's complexity.
A harness is not a framework. LangChain, LangGraph, the OpenAI Agents SDK — these are frameworks that help you build harnesses. The harness is what you build using them, or without them. Treating the framework as the harness is the black-box anti-pattern; you cannot debug, audit, or secure what you do not understand.
And a harness is not an agent. "Agent" refers to the goal-directed behavior of the combined system. The harness is the machinery that produces that behavior.
[SLIDE 8 — Convergent evolution]
Now the most important claim in this module, and the one I want you to push back on if it sounds too strong. In 2025 and 2026, four independent engineering teams — Anthropic with Claude Code and Pi, OpenAI with Codex CLI and the Agents SDK, Google DeepMind with Gemini CLI, and the open-source community with Aider and oh-my-opencode — built production agent harnesses without coordinating their designs. And they produced architecturally identical systems.
Every one of them has a ReAct-derived loop that interleaves model reasoning and tool execution. Every one has a tool registry with named, schema-validated tools. Every one has a permission or safety layer that constrains execution. Every one has a context management system handling token budget and history. Every one has a sandboxed execution environment, or clear documentation of why they omitted one.
This is convergent evolution. The same selection pressure — build a reliable, safe, useful AI agent — produced the same architecture. The design space has a natural attractor.
And here is the payoff for you as an engineer. The core pattern is stable. Learn one harness deeply and every other harness becomes legible. The variation between harnesses is almost entirely in thickness — how much complexity each layer has — not in structure. The structure is the invariant. Thickness is the variable.
[SLIDE 9 — The thickness spectrum]
So let's talk about thickness. The single most useful mental model for comparing harnesses is the thickness spectrum — a continuum from minimal, thin harnesses to fully-featured, thick ones.
At the thin extreme: Pi. Four tools — read, write, bash, search. A system prompt under a thousand tokens. About twelve hundred lines of TypeScript total. Trust-the-model permission. Minimal context management. Pi's designers concluded, deliberately, that adding a fifth tool or a complex permission model would add complexity the model could handle more gracefully on its own. For Pi's use case — a personal coding assistant — that is correct.
At the thick extreme: Claude Code. Forty-plus tools. A system prompt around forty thousand tokens, estimated. Forty discrete capability flags, independently controllable. Active context compaction. Plan mode. Approval gates. Trust boundaries on tool output. Credential isolation. Full multi-session state. Claude Code's complexity exists because its use case demands it — enterprise environments, multi-tenant workloads, auditability. A thin harness would be wrong for that context.
And here is the design question this spectrum gives you. It is not "which is better?" It is: how thick does this harness need to be for its use case? This is an engineering question, not an aesthetic one. Every layer of thickness adds capability, safety, observability, controllability — and it also adds code to maintain, failure modes to handle, attack surface to defend, and cognitive overhead. Pi and Claude Code are both correct. A senior harness engineer can defend why a design decision lives where it does on the spectrum.
Do not leave this slide thinking Claude Code is more advanced than Pi. That is the failure mode. They are differently optimized.
[SLIDE 10 — The 1.6% / 67.6% trap]
Back to that one-point-six-percent figure, from a different angle. Look at where the tokens actually go in a typical production session. Tool outputs are about sixty-seven point six percent of what the model sees in context. Tool definitions are another ten point seven. History and everything else is around seventeen. The system prompt — the thing most teams spend most of their time polishing — is three point four percent. And the model's own decision logic is that one point six.
Here is the trap, and it is the most common senior-engineer mistake in this entire domain. If you are iterating on your system prompt while ignoring how your tool outputs are formatted, you are optimizing three percent of context and neglecting sixty-eight percent. The harness is where the leverage is. Modules Two, Three, and Eleven harvest this insight. For now, just notice the asymmetry.
[SLIDE 11 — Reading a harness from the outside in]
Practical method. Six steps. You will use this for every harness in the course, starting with the lab at the end of this module.
One: find the entry point. Package dot json, main field.
Two: find the loop. Search for the while loop around model-dot-complete. The surrounding code is the loop controller.
Three: find the tool registry. JSON schemas with name, description, and input schema. The list of registered tools defines the capability surface.
Four: find the safety layer. Permission checks, approval prompts, sandbox invocations, stop conditions. This is often the least centralized part of the harness — safety logic gets scattered.
Five: find the context manager. Token counting, history truncation, compaction. In thin harnesses it may not exist. In thick harnesses it is a major subsystem.
Six: write the verdict. One paragraph: what loop architecture, how many tools, what permission model, where on the thickness spectrum, and — most importantly — why the designers put it there.
That six-step method is the same one you will use for all twenty-one deep-dive harnesses later in the course.
[SLIDE 12 — The map ahead]
Where this sits in the course. This module introduced the three-layer architecture — loop, tools, safety. The next twelve modules each go deep on one layer or one cross-cutting concern. Modules One through Six go deep on the layers: the execution loop, tool design, context management, memory, sandboxing, permissions. Modules Seven through Ten handle cross-cutting concerns: error handling, state and checkpointing, verification, observability. Module Eleven is security. And Module Twelve is the capstone, where you build a production harness from scratch and apply this six-step method to your own work.
[SLIDE 13 — Takeaways]
Five things to leave with.
One: the harness is the product. The model is a component. Get that ordering wrong and the rest of the course will not land.
Two: every harness does three jobs — loop, tools, safety. Miss any one and what you have is a prompt.
Three: thickness is a design decision, not a quality score. Pi is not inferior to Claude Code. They are differently optimized.
Four: the structure converged across four independent teams. The variation is in thickness, not in architecture. Learn the invariant and every harness becomes legible.
Five: you can read any harness in six steps, from the outside in. The lab for this module has you do exactly that — but n8n first, so the loop is something you have seen run before you read it as code.
Next: Module Zero point Two — the ecosystem. Then Module One, where we go inside the loop.
End of Module 0.1 teaching script. Approximate word count: 2,410. Approximate runtime at 140 wpm: 17 minutes; trim ~300 words for a strict 15-minute target, or pace at 160 wpm.
# Teaching Script — Module 0.1: What Is a Harness? **Course**: Master Course — Harness Engineering **Module / Section**: 0 / 0.1 **Duration**: ~15 minutes (target audio) **Target word count**: ~2,400 words at 130–150 wpm **Format**: Verbatim transcript. Cues `[SLIDE N]` map to the reveal.js slide deck (`03-slide-deck.html`). Stage directions in italics. Paragraph breaks ≈ natural pauses. --- [SLIDE 1 — Title] This is Module Zero, Section One: What Is a Harness? It is the first fifteen minutes of a course that ends with you building a production-grade harness from scratch. Everything in the course hangs off the definition we settle here — so we are going to settle it carefully. A warning before we start. The material in this module is easy to nod along to and hard to actually internalize. The single most common mistake senior engineers make with agents is misattributing behavior — blaming the model for things the harness did, and crediting the model for things the harness did. By the end of these fifteen minutes you should be unable to make that mistake again. [SLIDE 2 — "When you say 'the AI did X'…"] Start with a sentence you have said, or heard, a hundred times. "The AI did X." "The AI failed to do Y." "The AI decided to delete the file." "The AI remembered the user's name." Almost every time an engineer says something like this, they are describing behavior that has nothing — nothing — to do with the model weights. They are describing the harness. Here is what the model actually is. The model is a function. You hand it a sequence of tokens; it hands you back the next token, or a structured output. That is the entire contract. The model has no memory across calls. It cannot run code. It cannot read a file. It does not know what time it is. It does not retry when something fails. It does not stop when a budget runs out. It does not ask a human for permission before it does something destructive. All of that — every bit of behavior that makes the thing feel like an agent — is the harness. The harness is the product. The model is a powerful component. Get that backwards and the rest of the course will not land. [SLIDE 3 — The model is 1.6% of the system] Let me put a number on it. A study out of MBZUAI in May 2026 analyzed production agent systems and found that roughly ninety-eight point four percent of a real harness is infrastructure — loop, tools, memory, sandboxing, permissions, observability — and only about one point six percent is the AI decision logic, the part you would call "the model." And critically: four independently built agents, from different teams, converged on the same harness patterns. Hold onto that one point six percent. We will come back to it twice more, from two different angles, before this module ends. [SLIDE 4 — Definition] So here is the definition we will use for the entire course. A harness is the infrastructure layer that wraps a language model and gives it the capability to act repeatedly in the world until a task is complete. Break that down. "Infrastructure layer" — it is code, configuration, and runtime scaffolding, not weights. "Wraps a language model" — the model is inside it. "Act repeatedly in the world" — the model alone acts once; the harness makes it act again and again. "Until a task is complete" — there is a stop condition, owned by the harness. And every harness, no matter how thin or thick, does exactly three jobs. It runs the model in a loop. It provides the model with tools. And it enforces safety and permission boundaries. Loop. Tools. Safety. Miss any one of those three and what you have is not a harness — it is a prompt. A loop with no tools is a chatbot. Tools with no loop is a function call. A loop with tools and no safety is a loaded weapon pointed at your filesystem. These three are the minimal sufficient set, and every production harness has all three in some form. [SLIDE 5 — The three jobs] Job one: the loop. The model is stateless. A single call to model-dot-complete produces one response and terminates. To make the model behave like an agent — something that works toward a goal over multiple steps — you need a loop. *point to code* Here it is in TypeScript. Call the model. If it says it is done, return. If it asks for a tool, run the tool, push the result back into context, and call the model again. That is the whole loop. Pi's core loop is about eighty lines of TypeScript that does exactly this, plus a max-iterations guard. The model's intelligence is not in this code. The loop is pure orchestration. Job two: tools. A stateless model can reason about the world but cannot act on it. Tools are the interface between the model's reasoning and real-world effects. A tool has a name, a description, an input schema, an implementation, and a result. And here is the security-critical point, which we will spend all of Module Two on: the model does not execute tools. The model emits a structured request for a tool call. The harness intercepts that request, executes the tool, and returns the result. The model never touches the filesystem, the network, or any external system directly. That indirection is a security boundary, not an implementation detail. The number of tools a harness provides is one of the most consequential design decisions in harness engineering. Pi gives the model four. Claude Code gives it more than forty. We will come back to that gap. Job three: safety. A loop with tools, given no constraints, will do whatever the model decides is appropriate to complete the task — including destructive, irreversible, or unauthorized actions. So the safety layer enforces constraints. Permission flags that explicitly enumerate what is enabled. Approval gates that require human confirmation before high-risk actions. Sandboxing that restricts the execution environment. Stop conditions that exit the loop before a bad state gets worse. Trust boundaries that tag world-derived content as untrusted before it enters context. And the thing to internalize: safety is not a feature you add after you build the harness. It is a dimension of every architectural decision. [SLIDE 6 — The loop as a runnable n8n workflow] Now. This course has a rule about how we present things visually, and the rule matters here. We use n8n first, diagrams second, code third. So before you read that TypeScript loop as text, look at it as a node graph. *point to workflow* Here is the same loop, as an importable n8n workflow. Manual trigger at the top. Assemble context — that is the system prompt, the history, and the tool definitions, all gathered. Then the loop node, with a max-iterations cap — that is stop condition number one. Inside the loop: call the model. The model either says end-turn, in which case we are done and we output, or it asks for a tool — read file, write file, or bash. We route to the right tool, run it, append the result to history, and come back to the top of the loop. Count the nodes. The model is one node of seven. The turn boundary — the place where one turn of the loop ends and the next begins — is that back-edge from "append tool result" into "loop." When you run this in the lab, you will watch the execution highlight travel that ring of nodes once per turn. That turn boundary is the single most important concept in the entire course, and the node graph makes it visible in a way the code does not. Same loop. Three representations. n8n to see it, Mermaid to reference it, TypeScript to ground it. [SLIDE 7 — What a harness is not] Before we move on, kill four common misconceptions. A harness is not a fine-tuned model. The model inside a harness is typically a general-purpose foundation model. The harness shapes its behavior. A harness is not a system prompt. The system prompt is one input — a small fraction of the harness's complexity. A harness is not a framework. LangChain, LangGraph, the OpenAI Agents SDK — these are frameworks that help you build harnesses. The harness is what you build using them, or without them. Treating the framework as the harness is the black-box anti-pattern; you cannot debug, audit, or secure what you do not understand. And a harness is not an agent. "Agent" refers to the goal-directed behavior of the combined system. The harness is the machinery that produces that behavior. [SLIDE 8 — Convergent evolution] Now the most important claim in this module, and the one I want you to push back on if it sounds too strong. In 2025 and 2026, four independent engineering teams — Anthropic with Claude Code and Pi, OpenAI with Codex CLI and the Agents SDK, Google DeepMind with Gemini CLI, and the open-source community with Aider and oh-my-opencode — built production agent harnesses without coordinating their designs. And they produced architecturally identical systems. Every one of them has a ReAct-derived loop that interleaves model reasoning and tool execution. Every one has a tool registry with named, schema-validated tools. Every one has a permission or safety layer that constrains execution. Every one has a context management system handling token budget and history. Every one has a sandboxed execution environment, or clear documentation of why they omitted one. This is convergent evolution. The same selection pressure — build a reliable, safe, useful AI agent — produced the same architecture. The design space has a natural attractor. And here is the payoff for you as an engineer. The core pattern is stable. Learn one harness deeply and every other harness becomes legible. The variation between harnesses is almost entirely in thickness — how much complexity each layer has — not in structure. The structure is the invariant. Thickness is the variable. [SLIDE 9 — The thickness spectrum] So let's talk about thickness. The single most useful mental model for comparing harnesses is the thickness spectrum — a continuum from minimal, thin harnesses to fully-featured, thick ones. At the thin extreme: Pi. Four tools — read, write, bash, search. A system prompt under a thousand tokens. About twelve hundred lines of TypeScript total. Trust-the-model permission. Minimal context management. Pi's designers concluded, deliberately, that adding a fifth tool or a complex permission model would add complexity the model could handle more gracefully on its own. For Pi's use case — a personal coding assistant — that is correct. At the thick extreme: Claude Code. Forty-plus tools. A system prompt around forty thousand tokens, estimated. Forty discrete capability flags, independently controllable. Active context compaction. Plan mode. Approval gates. Trust boundaries on tool output. Credential isolation. Full multi-session state. Claude Code's complexity exists because its use case demands it — enterprise environments, multi-tenant workloads, auditability. A thin harness would be wrong for that context. And here is the design question this spectrum gives you. It is not "which is better?" It is: how thick does this harness need to be for its use case? This is an engineering question, not an aesthetic one. Every layer of thickness adds capability, safety, observability, controllability — and it also adds code to maintain, failure modes to handle, attack surface to defend, and cognitive overhead. Pi and Claude Code are both correct. A senior harness engineer can defend why a design decision lives where it does on the spectrum. Do not leave this slide thinking Claude Code is more advanced than Pi. That is the failure mode. They are differently optimized. [SLIDE 10 — The 1.6% / 67.6% trap] Back to that one-point-six-percent figure, from a different angle. Look at where the tokens actually go in a typical production session. Tool outputs are about sixty-seven point six percent of what the model sees in context. Tool definitions are another ten point seven. History and everything else is around seventeen. The system prompt — the thing most teams spend most of their time polishing — is three point four percent. And the model's own decision logic is that one point six. Here is the trap, and it is the most common senior-engineer mistake in this entire domain. If you are iterating on your system prompt while ignoring how your tool outputs are formatted, you are optimizing three percent of context and neglecting sixty-eight percent. The harness is where the leverage is. Modules Two, Three, and Eleven harvest this insight. For now, just notice the asymmetry. [SLIDE 11 — Reading a harness from the outside in] Practical method. Six steps. You will use this for every harness in the course, starting with the lab at the end of this module. One: find the entry point. Package dot json, main field. Two: find the loop. Search for the while loop around model-dot-complete. The surrounding code is the loop controller. Three: find the tool registry. JSON schemas with name, description, and input schema. The list of registered tools defines the capability surface. Four: find the safety layer. Permission checks, approval prompts, sandbox invocations, stop conditions. This is often the least centralized part of the harness — safety logic gets scattered. Five: find the context manager. Token counting, history truncation, compaction. In thin harnesses it may not exist. In thick harnesses it is a major subsystem. Six: write the verdict. One paragraph: what loop architecture, how many tools, what permission model, where on the thickness spectrum, and — most importantly — why the designers put it there. That six-step method is the same one you will use for all twenty-one deep-dive harnesses later in the course. [SLIDE 12 — The map ahead] Where this sits in the course. This module introduced the three-layer architecture — loop, tools, safety. The next twelve modules each go deep on one layer or one cross-cutting concern. Modules One through Six go deep on the layers: the execution loop, tool design, context management, memory, sandboxing, permissions. Modules Seven through Ten handle cross-cutting concerns: error handling, state and checkpointing, verification, observability. Module Eleven is security. And Module Twelve is the capstone, where you build a production harness from scratch and apply this six-step method to your own work. [SLIDE 13 — Takeaways] Five things to leave with. One: the harness is the product. The model is a component. Get that ordering wrong and the rest of the course will not land. Two: every harness does three jobs — loop, tools, safety. Miss any one and what you have is a prompt. Three: thickness is a design decision, not a quality score. Pi is not inferior to Claude Code. They are differently optimized. Four: the structure converged across four independent teams. The variation is in thickness, not in architecture. Learn the invariant and every harness becomes legible. Five: you can read any harness in six steps, from the outside in. The lab for this module has you do exactly that — but n8n first, so the loop is something you have seen run before you read it as code. Next: Module Zero point Two — the ecosystem. Then Module One, where we go inside the loop. --- *End of Module 0.1 teaching script. Approximate word count: 2,410. Approximate runtime at 140 wpm: 17 minutes; trim ~300 words for a strict 15-minute target, or pace at 160 wpm.*