DEV Community: Fikayo Adepoju

Harness Engineering - Part 10: Decomposing Claude Code

Fikayo Adepoju — Sat, 15 Aug 2026 18:36:33 +0000

Welcome back to the Harness Engineering series — a 10-part journey from raw language model to production-ready agentic system. Made by builders. For builders.

In Part 9, I promised the last article would be where the whole series pays off. Nine articles laying out a taxonomy — six components, three verbs, one architectural picture. This article points all of that at a real, working, publicly-known agent: Claude Code.

We're not going to speculate about how Claude Code works. We're going to walk through it the way you'll walk through any agent from here forward — component by component, asking six specific questions, and putting the answers in the six boxes we've been carrying around this whole series.

What's ahead:

Part 1: The Raw Model Problem
Part 2: Defining the Harness — The Six Components
Part 3: The Control Loop
Part 4: The Tool Layer
Part 5: Context Engineering
Part 6: The Filesystem & Environment
Part 7: The Memory Layer
Part 8: Observability
Part 9: The Harness Architecture
Decomposing Claude Code ← You are here

By the end of this article, you'll have seen the six-component framework applied to a real agent from start to finish — and you'll have a repeatable method you can use on any agent you encounter from now on.

Let's get started.

The Setup

We've spent nine articles laying out a shared vocabulary and framework. Now we point that framework at something concrete.

The picture below is what a full decomposition looks like when you draw it out on a whiteboard.

Every component we've named has a box. Every arrow between them is a coupling we've discussed. And in the middle sits Claude Code — the agent we're pulling apart to see what fills each of those boxes when the theory meets a real, shipping product.

This is the exercise you can now do with any agent. What you're about to read is one worked example.

The Six-Component Decomposition

Here's Claude Code, broken down component by component using the framework from the rest of this series.

1. The Loop

Claude Code's Loop is a classic ReAct loop — the shape we identified in Part 3 as the default for most modern agents. It cycles through call the model → decide an action → execute the tool → inspect the result → back to the model, and it keeps going until either:

The model indicates the task is done
A step budget is hit

Two clear termination conditions, both explicit, both mechanical. Exactly the pattern Part 3 argued for.

2. The Tools

Claude Code has the small, sharp tool surface we made a big deal of in Part 4: read, edit, bash, glob, grep, plus a task-management tool and an MCP connector for extending the tool set.

That's it. No refactor_python_function. No run_pytest_and_summarize. No open_pr_with_generated_summary. Every specialized job a bloated toolset would have its own function for is composed instead from the general primitives.

This is the "compose, don't enumerate" principle from Part 4, made real. When Claude Code needs to do something novel, it doesn't need a new tool — it reaches for bash and grep and read and figures it out.

3. The Context

On every turn, Claude Code assembles the Context from four ingredients:

The system prompt (built into the agent)
CLAUDE.md files and other repo-level context
The conversation history so far
All prior tool results

And on top of those, any files the user explicitly references with @ get pulled in for that turn.

Notice how this maps directly to Part 5. The system prompt is the built-in control plane. CLAUDE.md is the user-layered instruction file we called out by name. Conversation history is the short-term memory feeding forward. Tool results are outputs of previous turns being made available to the next. And @ references are an explicit-attachment mechanism the user drives.

Different names on the whiteboard, but every ingredient came from the vocabulary in Part 5.

4. The Environment

Claude Code's Environment is your local machine — the actual thing sitting on your desk.

The read and edit tools touch your real filesystem. bash runs commands in your real shell. Network calls hit the real network. This is a bounded but not sandboxed environment: bounded because Claude Code doesn't reach outside the working directory casually, and gated by a permissioning system that prompts you before destructive operations — deleting files, running risky commands, and so on.

Compare that to Codex from Part 6, which runs in a fully sandboxed disposable container. Claude Code makes a different trade: less isolation, more directness, safety enforced through permissioning rather than through walls. Same component, different design choice. Both defensible for their respective use cases.

5. The Memory Layer

Claude Code has the exact two-flavor design from Part 7:

Short-term memory is the running conversation — the messages exchanged so far, replayed on every turn.
Long-term memory lives in CLAUDE.md files at the repo and user level, plus the user's ~/.claude directory.

Short-term is full-fidelity. Long-term is compressed and structured — files, not raw history. And critically, the long-term memory is user-managed: the user writes into CLAUDE.md; Claude Code reads from it. That's a very deliberate design choice — the write triggers for long-term memory are essentially "the user decided to write something down." No auto-summarization guessing what to remember. An explicit gate, controlled by a human.

6. Observability

Claude Code's Observability shows up as a visible tool-call log in the UI. Every read, every edit, every bash invocation is shown to the user as it happens, in real time.

That's not just a UI feature. That's the exact observability principle from Part 8 made visible: the user (and, by extension, an engineer debugging the agent) can see what the agent is doing as a stream of concrete events. Nothing important happens in the dark.

The user-visible tool log is essentially a real-time trace, presented as UX rather than as a debugging tool. That's a signal about how much Claude Code's designers trust the value of observability — enough to put it on the surface of the product, not hide it behind a --verbose flag.

What This Decomposition Shows Us

Three things stand out once the whole picture is on the wall.

First, every box has something in it. No component is missing. Every one of the six we've talked about has a concrete implementation in Claude Code. This is what a complete harness looks like — a real product where all six concerns have been thought through, not left to chance.

Second, the design choices are internally consistent. The small-sharp tool surface fits the general-purpose model bet. The direct-not-sandboxed environment fits the coding-in-your-real-repo use case. The user-managed long-term memory fits a product where the user is a technical operator, not a passive consumer. Nothing feels bolted on.

Third, none of this required insider knowledge to see. Every observation we just made is available to anyone who uses Claude Code and knows what to look for. That's the whole point of a taxonomy — it turns opaque products into readable systems.

Every real agent decomposes into these six components. That's the claim this series has been driving toward. Claude Code is one worked example of what it looks like when you actually do the decomposition.

Do This to Any Agent

The exercise we just did with Claude Code — six questions, six answers, one honest whiteboard — is now a tool you own. You can point it at anything.

Try it on Cursor. What's Cursor's Loop like when a completion fires? What's on its tool surface? What does it assemble into context on every keystroke? What's its environment? Where does memory live? What's its observability story?

Try it on a framework you're evaluating. If you can't quickly answer all six questions about it, that's a signal — either the framework is genuinely lightweight (and expects you to fill in the missing components), or its design isn't as thought-through as its marketing suggests.

Try it on your own work. If you're prototyping an agent, sketch out the six-component picture before you write any code. Which pieces are you designing deliberately? Which are you leaving to chance? Which ones already exist in libraries you're using, and which ones will you have to write yourself?

That kind of thinking — the ability to look at any agent, sketch its six components, and reason about the tradeoffs at each — is what a good taxonomy buys you.

That's a Wrap

And that brings us to the end.

Ten articles. Six components. Three verbs. One raw model problem, and the entire discipline of engineering that sits around it to make agentic systems actually work.

Thank you for reading through the whole series. If it made the fog around AI agents feel more like structure, then it did what it was meant to do. Whether you go on to build your own harness, evaluate someone else's, or just have sharper conversations about agents from here on out — the vocabulary you've picked up is yours to keep.

If you want to go deeper — actually build a harness end-to-end, or work through the material with peers and direct feedback — the course and the workshop linked at the top of every article in this series are where that happens.

Until then: use what you've learned. Point it at real systems. Notice what fits the framework and what doesn't. That's the whole game.

This was the final article in a 10-part series that walked through every component of an agentic harness.

Here's the full roadmap you just completed:

Part 1: The Raw Model Problem
Part 2: Defining the Harness — The Six Components
Part 3: The Control Loop
Part 4: The Tool Layer
Part 5: Context Engineering
Part 6: The Filesystem & Environment
Part 7: The Memory Layer
Part 8: Observability
Part 9: The Harness Architecture
Decomposing Claude Code ← You just finished this one — and the series.

That's the series. Thanks for coming along.

Happy coding :)

Harness Engineering - Part 9: The Harness Architecture

Fikayo Adepoju — Sat, 15 Aug 2026 18:36:02 +0000

Welcome back to the Harness Engineering series — a 10-part journey from raw language model to production-ready agentic system. Made by builders. For builders.

In Parts 3 through 8, I walked through the six components of an agentic harness one at a time — the Loop, the Tools, the Context, the Environment, the Memory Layer, and Observability. But naming the parts isn't the same as understanding how they fit together.

In this article, we zoom out. We look at the whole architecture at once, trace the flow of a single agent turn through it, and see what shape a real harness has when you draw it as a system.

This shape isn't unique to any one framework. It's the canonical shape — the picture every real agent, from Claude Code to Cursor to whatever custom harness a company is building for its own internal use — is some variation of. Once you can see it clearly, you can look at any agent and spot which pieces are present, which are missing, and where the interesting design decisions were made.

What's ahead:

Part 1: The Raw Model Problem
Part 2: Defining the Harness — The Six Components
Part 3: The Control Loop
Part 4: The Tool Layer
Part 5: Context Engineering
Part 6: The Filesystem & Environment
Part 7: The Memory Layer
Part 8: Observability
The Harness Architecture ← You are here
Part 10: Decomposing Claude Code

By the end of this article, you'll have a mental picture of the whole harness as a system — how the six components connect, why the shape looks the way it does, and where the tightest coupling and cleanest seams are. That picture is the tool you'll use to look at any real-world agent and see through it.

Let's get started.

The Architecture at a Glance

Before we go further, take a moment to look at the diagram below.

That's the whole picture. Six components, arranged as a system: Observability wraps the outside; the Loop drives everything inside it; Context sits at the assembly point between memory and the model; the Model emits either an answer or a tool call; Tools dispatch through the loop into the Environment; and results flow back into Memory, which feeds the next Context.

The rest of this article walks through what that picture is telling us.

How a Single Turn Flows Through It

Follow the arrows in the diagram, and here's the flow of one agent turn:

The Loop starts a turn. It's the outermost control structure — the piece that decides "keep going" or "stop." Every step below happens inside one iteration of the Loop.
The Loop assembles a Context. It pulls from short-term memory (the conversation so far), from long-term memory (things the agent should remember across sessions), from the environment (files being worked on, tool results from prior turns), and from anywhere else that might be relevant. That assembled payload becomes the input for this turn.
The Context goes to the Model. The model reads it and produces a response. That response is either a final answer (in which case the Loop terminates) or a request to call a Tool.
The Loop dispatches the Tool. Not the model — the Loop. The model emits a structured request; the Loop is the piece of code that reads that request, looks up the actual tool implementation, and runs it.
The Tool executes in the Environment. Whatever side effect the tool has — reading a file, hitting an API, running a shell command — lands inside the harness's Environment, with its bounded filesystem, shell, and network.
The result flows into Memory and back into Context. The tool result gets recorded in short-term memory (always) and may get promoted into long-term memory (if a write trigger fires). Then the Loop starts a new turn, which begins with assembling the next Context — now including the fresh result.
Observability watches all of it. Every model call is logged. Every tool invocation is traced. Every state transition is recorded. Observability wraps the whole cycle without participating in it.

That's one turn. Every capable agent you've ever seen is doing some version of this, over and over, until either the task is done, the budget runs out, or an error threshold is hit.

What This Architecture Tells Us

Once you can see the shape clearly, a few structural facts about the design become obvious.

The Loop Is Outermost Because It's the Only Thing That Runs Continuously

Everything else in the diagram fires in response to a Loop step. The Model doesn't drive anything on its own. Neither do the Tools. Neither does Memory or the Environment. They all wait to be invoked. The Loop is the piece that keeps the cycle moving, and it's why it sits on the outside of everything else.

If you removed the Loop, every other component would still exist — but nothing would ever happen. There'd be a filesystem no one is touching, tool functions no one is calling, a model no one is sending payloads to. The Loop is what turns a collection of parts into a running system.

The Context Is Where Everything Converges

Look at where the arrows meet in the diagram. Memory feeds Context. Tool results feed Context. Retrieval feeds Context. Environmental state feeds Context. Then Context feeds the Model.

The Context isn't a component that does things — it's the surface where everything else's decisions get packaged and handed to the model, freshly, on every turn. That's why Part 5 argued context engineering is "the deepest engineering discipline in the whole harness." It's not that context is more important than the other components. It's that context is the point where every other component's contribution has to actually get expressed in something the model can read.

Get context assembly wrong, and even a beautifully-designed set of tools and a spotless environment don't help — the model never sees the right things at the right time.

Observability Is Intentionally Decoupled

Notice that Observability wraps the outside of the diagram, not the inside. It doesn't participate in the cycle. It doesn't decide anything. It just watches and records.

That decoupling is a design choice. An observability system that's tangled up with the components it observes ends up being unreliable when those components fail — exactly when you need it most. If Observability lives outside the cycle, it can keep working when the cycle breaks. And that's what makes it usable as the tool you reach for when something goes wrong.

The Canonical Shape

The picture in the diagram isn't a specific framework's architecture. It's not opinionated toward LangChain or LangGraph or any particular library. It's the underlying shape that any agent capable of multi-step work has to have — because each component solves a real problem, and none of them are optional in a real production system.

Different agents put their engineering effort into different parts of the same shape:

Cursor puts most of its differentiation in Context. Its architecture has the same shape as this diagram, but Cursor's innovation lives inside the Context box — what it assembles, how it retrieves, what it prioritizes on every keystroke.
Codex puts most of its differentiation in Environment. Same shape as everyone else, but Codex's innovation lives in that sandboxed container per task, and everything else is designed to defer to what the environment enables.
Claude Code distributes its differentiation across Tools and Observability. A small, sharp tool surface; visible live tool logging that doubles as a real-time trace.

Once you can look at an agent and spot which box it's investing engineering effort in, you understand what makes it different. And, more importantly, you know where to look when it fails, or when you want to reason about the tradeoffs in your own design.

Where This Leaves Us

We've now named the six components, walked through each one, and seen how they fit together into a coherent architecture. That's the theoretical spine of the series done.

The last article is where it all pays off. In Part 10, we take a real, working, publicly-known agent — Claude Code — and decompose it component by component using the exact framework we've built up here. What's Claude Code's Loop shape? What's on its tool surface? How does it engineer context? What does its environment look like? How does it handle memory? Where's its observability?

By the end of that decomposition, you'll be able to look at any agent — any framework, any product, any research demo — and slice it up the same way. That's the payoff of a good taxonomy: you don't just understand the parts, you can take apart any real system into them.

Remember that this article is part of a longer 10-part series that walks you through every component of an agentic harness.

Here's the roadmap:

Part 1: The Raw Model Problem
Part 2: Defining the Harness — The Six Components
Part 3: The Control Loop
Part 4: The Tool Layer
Part 5: Context Engineering
Part 6: The Filesystem & Environment
Part 7: The Memory Layer
Part 8: Observability
The Harness Architecture ← You just finished this one.
Part 10: Decomposing Claude Code ← Move to this one.

See you in the next one.

Happy coding :)

Harness Engineering - Part 8: Observability

Fikayo Adepoju — Sat, 15 Aug 2026 18:35:30 +0000

Welcome back to the Harness Engineering series — a 10-part journey from raw language model to production-ready agentic system. Made by builders. For builders.

In Part 7, I closed on a line worth expanding: "I built an agent" vs "I built an agent I can actually operate." The difference between those two sentences is the sixth and final component of the harness. It's called Observability, and without it, everything else you've read in this series is a bet you can't check.

Every previous component in this series does something the agent needs to work. Observability does something the engineer needs — to see what happened, to know when things are going wrong, and to have any hope of making the harness better over time.

What's ahead:

Part 1: The Raw Model Problem
Part 2: Defining the Harness — The Six Components
Part 3: The Control Loop
Part 4: The Tool Layer
Part 5: Context Engineering
Part 6: The Filesystem & Environment
Part 7: The Memory Layer
Observability ← You are here
Part 9: The Harness Architecture
Part 10: Decomposing Claude Code

By the end of this article, you'll know what Observability actually is, why non-deterministic multi-step systems can't be operated without it, and the three properties — full-fidelity logs, session-level traces, and fixed evals — that separate a real observability setup from an aspirational one.

Let's get started.

What Observability Is

Observability is the instrumentation that exposes what the agent is doing. Concretely, it includes:

Logs of each model call — what went in, what came out, how long it took, how many tokens it cost
Traces of each tool execution — which tool ran, with what arguments, with what result, in what order
Latency and token metrics — the operational health of the agent, tracked over time
Evals — a fixed set of tasks you can run the agent against to score its behavior and catch regressions

Together, this instrumentation lets you answer basic operational questions about your agent: What happened on this run? Why did it fail? Is it getting better or worse over time? Without instrumentation, none of those questions have an answer.

Why Observability Exists

Agents are hard to operate. Three properties make them so:

They're non-deterministic — the same input can produce different outputs on different runs
They're multi-step — a single task can involve dozens of model calls and tool invocations
They run for minutes or hours — long enough that you often can't watch every step live

Now stack those three properties on top of each other. When something goes wrong — and something always goes wrong — you need to be able to answer:

You can't answer any of that without instrumentation. If your agent burned $12 in tokens producing a plausible-looking but wrong result, and you have no logs, then you have no way to know whether the failure was a bad tool call, a bad retrieval, a bad prompt, or the model just getting it wrong. Every failure becomes a mystery you can't investigate.

There's a second reason observability matters, and it's forward-looking rather than reactive: you can't improve a harness you can't measure. If you change the system prompt, or reshape the tools, or swap in a new model, and you have no way to compare "before" and "after" on a real set of tasks — then you're not iterating on the harness. You're rearranging deck chairs and hoping.

Observability is what turns agentic work from a black-box guessing game into an engineering discipline.

What a Good Observability Design Looks Like

Three properties separate a real observability setup from an aspirational one.

Log Every Call — Model and Tool

Both kinds of calls need to be logged in full, but the data you capture is slightly different for each.

For every model call, log the full context sent to the model, the full response returned, the latency of the call, and the token counts (in and out, and by whatever model tier the call hit). Model calls are the most expensive thing the agent does and the source of most surprising behavior — you'll want everything.

For every tool call, log the tool name, the arguments passed in, the result returned, and the duration of the execution. Tool calls are where the model's decisions meet the environment, so their logs are where you'll find the story of what actually happened in the world during a run.

The word "log" here is doing a lot of work. It doesn't just mean "print to stdout." It means: persisted, structured, queryable. If you can't go back a week later, filter by task ID, and pull up the exact prompt-response pair that caused a failure — you don't have logs. You have console output.

Traces That Tie a Session Together

Logs alone tell you what happened at each step. Traces tell you the shape of the run.

A trace stitches together every event in a single agent session — every model call, every tool invocation, every retry, every error — in a single timeline. With a good trace, you can replay an agent run end-to-end and see exactly what the agent tried, in what order, and how each step led to the next.

This is the difference between "I have 200 log lines" and "I have a story of one agent run." Debugging a multi-step failure without traces is like trying to diagnose a car accident from only the odometer readings of every car involved. You have data. You don't have narrative.

Evals That Let You Measure Regressions

The first two properties are about understanding runs that already happened. Evals are the proactive side — a fixed set of tasks you run the agent against to measure its behavior over time.

Evals don't need to be complicated. Ten to fifty representative tasks with known-good answers is often plenty. What matters is that they're fixed — the same tasks, run the same way, so that the numbers are comparable across changes.

Then, whenever you change something in the harness — a new system prompt, a reshaped tool, a different model, a memory-layer tweak — you re-run the eval set. If the score drops, you introduced a regression. If the score climbs, the change was probably good.

Without evals, you cannot tell whether the harness is getting better or worse. You can only tell whether the last thing you tested by hand worked or not. And "worked by hand" is not a reliable signal for a non-deterministic system.

Example: Claude Code

Watch Claude Code work, and you'll see observability baked into the surface itself.

Every tool call Claude Code makes is visible in the UI, live, as it happens. You can see exactly what file it read, what it edited, what shell command it ran, in what order. When it makes a decision that surprises you, you can scroll back and see the sequence of events that led there.

That's not just a UX choice. It's an observability decision that makes the agent debuggable. The visible tool log is essentially a trace, presented to the user in real time.

Compare that to a black-box agent that just hands you a result at the end. Something magical happened in the middle, and either it worked or it didn't, and you have no idea what actually went on. When it fails, you can't investigate. When it succeeds, you can't verify.

You can't trust what you can't see. That principle applies to human coworkers, and it applies double to AI agents. Observability is what makes trust possible — not in the sense of hoping the agent is right, but in the sense of being able to check.

Where This Leaves Us

We now have all six components. The Loop drives the cycle. The Tools give the model reach. The Context decides what the model sees on each call. The Environment provides where side effects land. The Memory Layer lets the agent carry state forward. And Observability makes the whole thing debuggable, measurable, and improvable.

Six components. Three verbs — action, persistence, measurable behavior — from the formal definition all the way back in Part 2. Every piece we've walked through serves at least one of those verbs, and together they add up to what an agentic harness actually is.

But naming the pieces is only half the job. So how do these six components fit together in practice? What does the architecture of a real harness look like when you draw it as a whole? That's what Part 9 is about: The Harness Architecture. We zoom out from individual components to see how they compose, where the seams are, and how a well-designed harness holds together as a system.

Remember that this article is part of a longer 10-part series that walks you through every component of an agentic harness.

Here's the roadmap:

Part 1: The Raw Model Problem
Part 2: Defining the Harness — The Six Components
Part 3: The Control Loop
Part 4: The Tool Layer
Part 5: Context Engineering
Part 6: The Filesystem & Environment
Part 7: The Memory Layer
Observability ← You just finished this one.
Part 9: The Harness Architecture ← Move to this one.
Part 10: Decomposing Claude Code

See you in the next one.

Happy coding :)

Harness Engineering - Part 7: The Memory Layer

Fikayo Adepoju — Sat, 15 Aug 2026 18:32:49 +0000

Welcome back to the Harness Engineering series — a 10-part journey from raw language model to production-ready agentic system. Made by builders. For builders.

In Part 6, we closed on a limitation the previous four components can't solve on their own: the agent forgets.

Once a session ends — or the context window fills up mid-task — everything the agent learned, discovered, or decided vanishes. Next time the user comes back, the agent greets them like a stranger. Next time the token budget runs out, earlier turns get truncated away, and the agent's earlier reasoning is just gone.

That's the gap this article closes. The Memory Layer is how the harness gives the agent persistence — inside a task, and across sessions.

What's ahead:

Part 1: The Raw Model Problem
Part 2: Defining the Harness — The Six Components
Part 3: The Control Loop
Part 4: The Tool Layer
Part 5: Context Engineering
Part 6: The Filesystem & Environment
The Memory Layer ← You are here
Part 8: Observability
Part 9: The Harness Architecture
Part 10: Decomposing Claude Code

By the end of this article, you'll know what a Memory Layer actually is, why short-term and long-term memory are two different systems (not one with a dial), and the three design decisions — flavor, write triggers, and bounded retrieval — that separate a real memory system from a naive one.

Let's get started.

What The Memory Layer Is

The Memory Layer is state that persists beyond a single model call.

That's the one-line definition. But memory in an agent isn't one thing — it's two things, and the difference between them is critical enough to name upfront.

Short-Term Memory

Short-term memory is state within a task.

It's the conversation history so far, intermediate scratchpads the agent has scribbled on, tool results from calls it's already made, files it's read or written during this session. It's everything the agent has generated or observed since the current task began, and it's what lets the agent stay coherent from one Loop iteration to the next.

If you asked the agent "what did we just try?" — the answer lives in short-term memory.

Long-Term Memory

Long-term memory is state across tasks.

It's the stuff the agent should remember beyond the end of a session — things about the user, the codebase, its own past behavior, patterns it learned last week that are still relevant this week. It's what lets the agent stop feeling like a stranger every time you come back to it.

If you asked the agent "what did we decide last time?" — the answer, if there is one, lives in long-term memory.

These two flavors have very different lifecycles, very different budgets, and — importantly — very different designs. A single "memory system" that tries to do both usually does neither well.

Why The Memory Layer Exists

Because the model itself remembers nothing.

We've noted this in every previous article, but it's worth restating in this specific frame: without an explicit memory layer in the harness, every interaction starts cold. The model has no idea what happened in this conversation five turns ago (unless the harness resent those turns). It has no idea what happened in the last conversation you had with it. It doesn't remember the user's name, the codebase's conventions, or the mistake it made yesterday that you patiently corrected.

Anything that feels like "the agent is learning over time" — anything that feels like "the agent recalls our previous work" — is harness work, not model work. There is no "the model remembers." There is only "the harness put the right stuff back in the context."

That's why designing this layer well matters. The Memory Layer is what turns a stateless-per-call system into something that behaves, from the outside, like a system with continuity.

What a Good Memory Design Looks Like

Three design decisions separate a real memory system from a naive one.

The Two Flavors Are Designed Differently

Short-term and long-term memory should not be built as one system with a dial. They have different natures and different constraints.

Short-term is usually full-fidelity. Within a task, you generally want the actual messages, the actual tool results, the actual file contents. Fidelity matters because the agent is reasoning over recent events step by step — losing detail here means losing coherence.

Long-term is usually compressed. Summaries, extracted facts, embeddings. This isn't a style choice; it's a budget one. Look at what already competes for the context window on any given turn: the system prompt, the active conversation, current tool definitions, tool results just returned, files being worked on right now. All of that has priority. Whatever slice is left for "things pulled from the long-term store" is small — and it's small for a reason: those slots are competing with things the model needs right now.

So long-term memory is designed around fitting useful information into a small slice. That means aggressive compression up front, precise retrieval at query time, and a willingness to leave things out. A long-term memory that tries to be full-fidelity ends up either useless (nothing gets retrieved because there's no room) or destructive (it pushes out the things the model needed for the current turn).

Write Triggers Are an Explicit Harness Decision

Long-term memory needs a rule for when something gets saved. This rule lives in the harness, not in the model's reasoning.

There are several places you can put the trigger:

At the end of every session — you sweep the conversation for anything worth remembering and write it to the long-term store
When an explicit tool is called — you expose a remember tool the model can invoke deliberately
When a specific event happens — a user correction, a successful task completion, an error the agent learned from

Whichever rule you pick, it should be a clear mechanism in the harness code, not a vibe the model is expected to observe as part of its normal output. If you leave "decide what to remember" up to the model as an implicit part of every response, you get a memory system that saves different things on different runs and is impossible to debug.

The clean division: the model contributes the content, the harness controls the gate. The model can propose "here's a fact worth saving" — but the harness decides whether that proposal actually results in a write.

Retrieval from Memory Is Bounded

The mirror image of the write triggers is the retrieval logic. When you're pulling from long-term memory into the current context, you don't dump the whole store — you pull what's relevant to the task at hand.

This is essentially the retrieval problem from Part 5 all over again, applied to memory. Rank aggressively. Filter conservatively. Send less than the context window can hold. The same design principle applies: if your long-term memory is filling half the context, it probably isn't memory — it's a hoarder.

Example: Cursor

Cursor is a nice example because it treats short-term and long-term memory as two different systems — and you can feel the difference.

Short-term memory in Cursor is the chat history within a single conversation. Full fidelity, live, growing turn by turn. You can scroll back through it, reference earlier things, hand messages back into the context. That's the short-term flavor at work.

Long-term memory shows up somewhere else entirely. It's the project rules you configure (things like "this codebase uses snake_case" or "always add type hints to new Python functions"), and the @-memory feature that lets you tell Cursor to remember specific things across sessions. This layer isn't in the chat history at all — it's stored separately, retrieved when relevant, and injected into future contexts.

Two very different systems. Different UIs. Different lifecycles. Different retrieval mechanisms. Both correctly called "memory." That separation isn't cosmetic — it reflects the fact that the two flavors have genuinely different jobs, and treating them as one thing would leave both jobs poorly done.

Where This Leaves Us

We now have five of the six components. The Loop drives the cycle. The Tools give the model reach. The Context decides what the model sees on each call. The Environment provides where side effects land. And the Memory Layer lets the agent carry state forward.

Together, those five turn a raw language model into something that can take multi-step action, work inside bounds, and remember what it's done — the shape of what most people mean when they say "agent."

But there's one more component, and it's the one that turns "I built an agent" into "I built an agent I can actually operate." Without it, when the agent misbehaves — and it will misbehave — you have no way to figure out why. That's Part 8: Observability.

Remember that this article is part of a longer 10-part series that walks you through every component of an agentic harness.

Here's the roadmap:

Part 1: The Raw Model Problem
Part 2: Defining the Harness — The Six Components
Part 3: The Control Loop
Part 4: The Tool Layer
Part 5: Context Engineering
Part 6: The Filesystem & Environment
The Memory Layer ← You just finished this one.
Part 8: Observability ← Move to this one.
Part 9: The Harness Architecture
Part 10: Decomposing Claude Code

See you in the next one.

Happy coding :)

Harness Engineering - Part 6: The Filesystem & Environment

Fikayo Adepoju — Sat, 15 Aug 2026 18:32:09 +0000

Welcome back to the Harness Engineering series — a 10-part journey from raw language model to production-ready agentic system. Made by builders. For builders.

In Part 5, we looked at the Context — the payload the model sees on every call. Now we look at what happens after the model, having seen that Context, decides to do something.

The model calls a tool. The tool has to execute somewhere. That somewhere is the Environment.

It's easy to under-appreciate. The Environment feels like plumbing — the filesystem, the shell, the network, the machine underneath. But it's where every side effect the model requests actually lands, and how you design it is what separates "an AI agent doing things on your behalf" from scary to routine.

What's ahead:

Part 1: The Raw Model Problem
Part 2: Defining the Harness — The Six Components
Part 3: The Control Loop
Part 4: The Tool Layer
Part 5: Context Engineering
The Filesystem & Environment ← You are here
Part 7: The Memory Layer
Part 8: Observability
Part 9: The Harness Architecture
Part 10: Decomposing Claude Code

By the end of this article, you'll know what the Environment actually is, why every tool with side effects depends on it, and the three properties (bounded, reproducible, inspectable) that separate a production-ready environment from a demo one.

Let's get started.

What The Environment Is

The Environment is the runtime that tools operate inside. Concretely, it includes:

The filesystem they read from and write to
The shell they exec commands in
The network they can reach
The compute resources they're permitted to consume — CPU, memory, disk, wall-clock time, API quotas

If a tool has any kind of side effect, the Environment is where that side effect materializes. When your read_file tool opens a file, it's opening a file in an environment. When your bash tool runs ls, it's running that in some shell, on some filesystem. When your fetch_url tool fires an HTTP request, it's doing so from some network stack, subject to some rules about what it can reach.

None of this is exotic. If you've ever set up a CI pipeline, you've made environment decisions — what OS the runner uses, what dependencies are pre-installed, what secrets are exposed, what artifacts persist between steps. The Environment for an agent is the same kind of concern, applied to the same kind of question: inside what world does this thing run?

Why The Environment Exists

Because tools can't exist in a vacuum.

A read_file tool is meaningless without a filesystem to read from. A bash tool is meaningless without a shell to run in. A fetch_url tool is meaningless without a network to reach out through. Every tool with side effects needs a target for those side effects, and the Environment is that target.

Put another way: the Tools (Part 4) are the model's reach, but the Environment is what they reach into. You can't separate the two. A well-designed tool set embedded in a poorly-designed environment produces an agent that either can't act (because the environment blocks it) or acts too freely (because the environment doesn't).

What a Good Environment Design Looks Like

Three properties separate a production-ready Environment from a demo one.

Bounded

The Environment defines the scope within which the agent can operate. Good environments are bounded — the agent can do the things it needs to do, and nothing else.

That means:

The agent can't accidentally rm -rf the host machine
The agent can't reach across into networks it shouldn't touch — production databases, internal services, and so on
The agent can't quietly exfiltrate data through unexpected channels
The agent can't burn through cloud credits by spinning up resources unchecked
The agent can't stay running forever if it gets stuck

Boundedness isn't about not trusting the model. It's about containing blast radius. Even a perfectly-behaved model, working on a legitimate task, will occasionally make mistakes — hallucinate a filename, misread an argument, run a command with unintended flags. In an unbounded environment, one of those mistakes can wreck real things. In a bounded environment, the same mistake gets caught by the walls.

Reproducible

Every run starts from a clean, identical state. The Environment is recreated cleanly per task, not reused across tasks.

This one takes a moment to appreciate. In a reproducible environment, the agent doesn't inherit anything from previous work — no leftover files, no mutated database rows, no dirty processes, no stale caches. Every task begins from the same known baseline.

Why does this matter? Two reasons:

When something goes wrong, you can re-run it and see the same failure. That means the failure is the agent's, not the environment's. Debugging becomes possible. Without reproducibility, "it worked yesterday" becomes an unanswerable question, and you spend hours chasing environmental drift instead of actual bugs.
Runs don't contaminate each other. An agent that made a mess in Task A doesn't ship that mess into Task B.

Reproducibility is what makes agentic behavior testable. Without it, every run is bespoke, and the whole system stops being an engineering artifact and starts being an unpredictable pet.

Inspectable

Engineers need to be able to see what the agent did to the Environment after a run.

What files changed?
What commands ran?
What processes were spawned?
What network calls were made?
What resources were consumed?

Inspectability is the Environment's contribution to observability (which we look at in Part 8). It's not enough to know what the model said; you need to see what actually happened in the world as a result. Those two things do not always agree.

The model can claim it "successfully updated the config" while the config file, on inspection, hasn't been touched. Or it can claim to have "cleaned up temporary files" while /tmp is stuffed with leftovers. An inspectable environment gives you ground truth to check the model's story against.

Example: Codex

Codex is a clean example of what a well-designed Environment enables.

When you hand Codex a task, it runs inside a sandboxed container that gets a fresh clone of your repository. Inside that container, the agent can do essentially anything — read files, edit them, run tests, spin up services, execute arbitrary code, hit the network. And critically, it does all of that without ever touching your real machine.

When the task is done, the container is destroyed. The agent's changes come back to you as a pull request you can review before anything real changes.

That environment is why engineers trust Codex to run code they didn't write.

Notice the trade the sandbox enables. Inside the sandbox, the agent has a lot of freedom — it can delete files, run wild bash, hit external services. The freedom is what makes it useful. But the blast radius is bounded to a disposable container. Whatever damage the agent could theoretically do stays inside walls that get torn down at the end of the task.

Without the sandbox, the same agent doing the same work would be touching your real filesystem, your real credentials, your real repositories. The tools would be identical. The model would be identical. But the risk profile would be completely different.

The sandbox is what turns "let an AI run arbitrary code" from a reckless idea into a routine engineering practice. That's the Environment doing the load-bearing work.

Where This Leaves Us

The Environment is the runtime that everything else takes place inside. The Loop drives the cycle. The Tools define what the model can request. The Context defines what the model sees when it decides. And the Environment defines where the doing happens and what the doing is allowed to touch.

Together, those four components already give you an agent that can act on the world within bounds. But there's still something missing — something you feel the absence of the moment a session ends or the context window fills up. The agent forgets. Everything it learned, discovered, or decided during a task disappears.

That's what Part 7 is about: the Memory Layer. How to give the harness persistence — within a task, and across sessions.

Remember that this article is part of a longer 10-part series that walks you through every component of an agentic harness.

Here's the roadmap:

Part 1: The Raw Model Problem
Part 2: Defining the Harness — The Six Components
Part 3: The Control Loop
Part 4: The Tool Layer
Part 5: Context Engineering
The Filesystem & Environment ← You just finished this one.
Part 7: The Memory Layer ← Move to this one.
Part 8: Observability
Part 9: The Harness Architecture
Part 10: Decomposing Claude Code

See you in the next one.

Happy coding :)

Harness Engineering - Part 5: Context Engineering

Fikayo Adepoju — Sat, 15 Aug 2026 18:31:14 +0000

Welcome back to the Harness Engineering series — a 10-part journey from raw language model to production-ready agentic system. Made by builders. For builders.

In Part 4, we looked at the Tools — the set of functions the model can call. But there's still one big open question hanging over every turn of the Loop: what does the model actually see when the Loop calls it?

The answer is: whatever the harness put in the payload. That payload — the entire package of instructions, history, retrieved documents, tool definitions, and everything else — is called the Context.

Some readers know this territory under an older name: prompt engineering. That name isn't wrong, but it's narrow. A prompt sounds like something you write once and ship. The reality of running an agent is that the payload changes every turn, and designing what goes in it is an ongoing discipline. Hence the newer, more accurate term: context engineering.

What's ahead:

Part 1: The Raw Model Problem
Part 2: Defining the Harness — The Six Components
Part 3: The Control Loop
Part 4: The Tool Layer
Context Engineering ← You are here
Part 6: The Filesystem & Environment
Part 7: The Memory Layer
Part 8: Observability
Part 9: The Harness Architecture
Part 10: Decomposing Claude Code

By the end of this article, you'll know what the Context actually is, why every turn forces you to answer "what should the model know right now?" from scratch, and the three moving pieces (system prompt, history, retrieval) that make up a well-designed context.

Let's get started.

What The Context Is

The Context is everything fed into the model on a given API call. All of it.

Concretely, on any single turn, the payload sent to the model typically includes:

The system prompt — the model's persona and instructions
The conversation history — the messages exchanged so far
Any retrieved documents relevant to the current turn
The tool definitions — what tools the model can call, and how
Prior tool results — from calls the model made earlier
Any attached files or images
Anything else the harness thinks the model needs to know right now

That entire package goes over the wire. The model reads all of it. Then it produces one response. Then, on the next iteration of the Loop, the harness assembles a new package — probably with the previous response added, maybe with new tool results appended, maybe with different retrieved content — and sends that.

Every turn is a new context. Every turn.

Why The Context Exists

Because the model is stateless. We noted this back in Part 1: every API call is independent on the model's side. Nothing persists between calls unless something outside the model puts it there.

Which means the question "what should the model know right now?" turns into a very different question:

And that question has to be answered on every single turn.

There is no shortcut. You can't tell the model "remember what I said five minutes ago." You can't say "reference the file we discussed earlier." Every relevant thing — every fact, every prior message, every result, every document — has to physically be in the payload for the current call, or the model doesn't know about it.

This is why context engineering is arguably the deepest engineering discipline in the whole harness. Deciding what to include, what to compress, what to leave out, and when — that's the work. And it's ongoing. The context is a moving target, different every turn. There is no version to "ship." There's only the version being assembled right now, for this call.

What a Good Context Design Looks Like

There are three moving pieces in any context, and each is worth being deliberate about: the system prompt, the history, and any retrieved knowledge.

The System Prompt

The system prompt is the top layer of the context — the part that gets prepended to every turn and stays roughly the same throughout the conversation. It tells the model who it is, what tools it has, and what good behavior looks like.

Think of the system prompt as the control plane of the agent. It's set by the agent's builder — the person designing the harness — and it defines the model's role, constraints, and preferred style.

There's a related but distinct pattern worth noting: files like AGENTS.md (or .cursorrules, or CLAUDE.md) that let the user — not the agent builder — inject their own instructions into the context. These are user-controlled additions layered on top of the built-in system prompt. Same mechanism, different owner. When you're designing a harness, you have to decide whether to support this and how the two layers interact.

A History Strategy

The conversation history — every message the user and the model have exchanged — is the second big chunk of the context. And here's where things get interesting: you can't just send all of it forever.

Context windows are finite. Every token you spend re-sending old messages is a token you can't spend on the current turn. So a history strategy is a decision about how much of the past to include, and in what shape.

The common strategies:

Full replay — send every message from the start of the conversation. Simple. Works fine for short sessions. Falls over on long ones.
Truncation — keep the most recent N messages and drop the rest. Cheap. Loses long-range context.
Compaction / summarization — periodically replace older messages with a compressed summary. Preserves the gist without the token cost. Requires care to not summarize away critical details.
Structured memory — pull historical content out of the message stream entirely and store it in a separate memory layer that the Loop can query on demand. We look at this in Part 7.

The right strategy depends on the task's time horizon — what the model needs to remember for the sub-step it's currently on, versus what can safely be forgotten. A quick lookup doesn't need much history. A long-running refactor needs a strategy that keeps the model coherent across hundreds of turns.

Retrieval

The third piece is retrieval — pulling in relevant outside knowledge and injecting it into the context. Documentation, code snippets, database records, prior conversations, whatever the task requires.

The design principle here is simple to state and hard to do: bring in just enough to be useful, without burying the model.

Too little retrieval, and the model is missing information it needs. Too much retrieval, and the important stuff is drowning in noise. The model has to find the relevant part of what you injected, which uses attention budget it could have spent actually answering the question.

Good retrieval systems rank aggressively and are willing to send less than the context window can hold. If your retrieval is filling half the context on every call, it probably isn't retrieval — it's a hedge.

Example: Cursor

Cursor's context engineering is most of why it feels different from using raw ChatGPT — even when the underlying model is the same.

Look at what Cursor is quietly assembling into the context on every keystroke that triggers a completion:

Cursor rules (the system prompt layer — user-defined, layered on top of the built-in system prompt)
Codebase indexing (retrieval — searching across your files for relevant context)
The file you have open (focus — the model gets the current file, in full or in relevant windows)
The files you've @-mentioned (explicit attachment — you telling Cursor "make sure the model sees this")
Your recent edits (short-term history — what you were just doing)

That's five distinct context sources, all being packaged into a single API call, every time you trigger a completion. And the API call itself is going to a foundation model that anyone with an API key can call.

The model is the same model anyone can call. The context is the product.

That's the punchline of this whole article. When you compare two agents built on the same foundation model, the differences you feel between them are almost always context-engineering differences. What each one puts in the context, how much of it, in what order, at what moments — that's the design surface where agents differentiate themselves.

Where This Leaves Us

The Context is what the model gets to see on any given call. The Loop drives the cycle. The Tools define what the model can request. The Context defines what state the model has when it decides what to request. Three components, tightly coupled, each depending on the others.

But context engineering has one dependency the other components don't: it depends on something being available to inject. The system prompt is easy — you wrote it. Recent history is easy — the harness holds it. But retrieval? Memory? Files that came from somewhere? Those all need a place to live. That "somewhere" is what the next few articles are about: the Environment (Part 6) that files and tool outputs live in, and the Memory Layer (Part 7) that lets the harness carry state forward across turns and sessions.

Remember that this article is part of a longer 10-part series that walks you through every component of an agentic harness.

Here's the roadmap:

Part 1: The Raw Model Problem
Part 2: Defining the Harness — The Six Components
Part 3: The Control Loop
Part 4: The Tool Layer
Context Engineering ← You just finished this one.
Part 6: The Filesystem & Environment ← Move to this one.
Part 7: The Memory Layer
Part 8: Observability
Part 9: The Harness Architecture
Part 10: Decomposing Claude Code

See you in the next one.

Happy coding :)

Harness Engineering - Part 4: The Tool Layer

Fikayo Adepoju — Sat, 15 Aug 2026 18:29:15 +0000

Welcome back to the Harness Engineering series — a 10-part journey from raw language model to production-ready agentic system. Made by builders. For builders.

In Part 3, we looked at the Loop — the outermost machinery of a harness, the piece that drives everything else. But a Loop on its own is a hollow shell. It calls the model. The model responds. And then, if the model wants to affect anything outside the text it just produced, it needs to reach for a tool.

That's what this article is about: the Tool Layer. The set of functions the harness makes available to the model, and the design decisions that separate a tool surface a model can actually use from one that constantly frustrates it.

What's ahead:

Part 1: The Raw Model Problem
Part 2: Defining the Harness — The Six Components
Part 3: The Control Loop
The Tool Layer ← You are here
Part 5: Context Engineering
Part 6: The Filesystem & Environment
Part 7: The Memory Layer
Part 8: Observability
Part 9: The Harness Architecture
Part 10: Decomposing Claude Code

By the end of this article, you'll know what tools actually are, why they exist, and — more usefully — how to tell a well-designed tool surface from a badly-designed one the moment you look at one.

Let's get started.

What The Tools Are

The Tools are the set of functions the harness exposes to the model.

Concretely: the harness tells the model "here are the functions you can call, here are their names, here are the parameters they take, here's what they do." Then on any given turn, the model can decide to emit a structured request to call one of them. Something like:

{
  "tool": "read_file",
  "parameters": {
    "path": "/etc/hosts"
  }
}

The harness sees this request in the model's response, runs the actual function (in this case, opens /etc/hosts and reads its contents), and feeds the result back into the model on the next Loop iteration.

That's the whole mechanic. Two-way traffic: the model requests, the harness executes, the harness returns.

If you're coming from traditional software, think of the Tool Layer as the API the harness offers to the model — the same way an operating system offers system calls to a running program. Same shape, different consumer.

Why The Tools Exist

Tools are the model's surface area into the world. Without them, the model produces text and that text goes nowhere. With them, the model can decide to do a thing and have the thing actually happen.

Look back at Part 1 — the raw model problem. Three of the five gaps we named there close through tools:

No execution → tools that run code, touch files, hit APIs
No fresh knowledge → tools that search, retrieve, or query external data
No environment → tools are how the model reaches into whatever environment the harness sets up

(The other two gaps — persistence and verification — are addressed by different components, which we look at in later parts.)

Every capability you've ever seen an agent exercise came through a tool. When Claude Code writes a file, that's an edit tool. When a research agent searches the web, that's a search tool. When a customer-support agent looks up an order, that's a get_order tool. The Loop drives the cycle; the Tools are what the model asks for inside each turn.

What a Good Tool Design Looks Like

If you look at ten agent frameworks, you'll see ten different opinions on how many tools an agent "needs" and how they should be shaped. The good ones share three properties.

A Small Set That Composes Well

There's a design failure mode where every use case gets its own bespoke tool. You end up with fifteen or fifty tools:

read_python_file
read_javascript_file
read_config_file
list_files_in_directory
list_files_matching_pattern
run_python_script
run_shell_script
…and on it goes

That surface is almost always worse than two well-named tools:

read_file(path)
bash(command)

You can express everything in the first list using the second — and a great many things the first list doesn't cover. The model doesn't have to memorize fifteen names and their subtle differences; it just has to think "I want to read this thing" or "I want to run this command."

The rule of thumb: compose, don't enumerate. A small set of sharp, general-purpose tools almost always outperforms a large set of specialized ones. Not always — sometimes a specific business action deserves its own named tool — but as a default posture, composition wins.

Clear, Structured Outputs — Including Errors

The model has to be able to tell success from failure from the tool result alone. It doesn't get to inspect your logs. It doesn't get to look at your stack traces. Whatever came back in the tool result is all the information it has to work with.

Which means:

Success and failure need to look different, unambiguously.
Errors should be structured, not just "Something went wrong."
Whenever possible, errors should hint at how to recover.

A tool that returns null on both "file not found" and "file is empty" is a tool the model can't reason about. A tool that returns {"error": "file_not_found", "path": "/foo/bar"} for one case and {"content": ""} for the other is a tool the model can actually use to correct course.

Tools Sized So The Model Can Use Them Well

There's a Goldilocks zone for tool granularity, and it's easy to miss on both sides.

Too small: each tool does a trivial thing, so the model needs twenty tool calls to accomplish what could have been one. You spend money, you spend time, and — worse — you spend context. Every tool call bloats the conversation with request-and-result pairs the model then has to keep re-reading.

Too big: a single tool does five things internally, so when it fails you can't tell which of the five failed. The model gets back "operation failed" and has no way to isolate the problem. It'll usually respond by trying the same thing again, or by giving up entirely.

The right size is: each call does enough meaningful work to be worth the round trip, but each failure is diagnosable. If you look at a tool's design, imagine the model getting an error from it, and can imagine the model figuring out what to do next — the tool is probably right-sized. If you look at it and think "the model would just be confused," it's probably wrong-sized in one direction or the other.

Example: Claude Code

Claude Code's tool surface is famously small: read, edit, bash, glob, grep, plus a handful of others. That's it. No refactor_python_function tool. No run_pytest_and_summarize tool. No open_pr_with_generated_summary tool.

Compare that to an agent framework that ships with fifty specialized tools out of the box.

The Claude Code design bet is that a competent model with sharp, general-purpose tools beats a constrained model with many specialized ones. That's a tools-design decision, and it shapes the entire feel of the product. When Claude Code needs to do something novel — refactor across files, run a specific test harness, generate a summary of a diff — it doesn't need a new tool. It composes what it already has: bash to run the test, grep to find the failing pattern, read to look at the file, edit to fix it.

When Claude Code can't do something well, the fix is usually not "add more tools." The fix is usually somewhere else in the harness — better context, better memory, better prompting. The tool surface stays lean on purpose.

Where This Leaves Us

The Tools are the harness's contract with the model. They define what the model is allowed to request. They don't decide when the model gets to request them (that's the Loop, from Part 3), and they don't decide what state the model has when deciding what to request (that's coming in Part 5, on Context). But the shape of the tool surface constrains everything downstream.

A great Loop with a badly-designed tool set produces an agent that flails. A modest Loop with a well-designed tool set produces an agent that composes its way to solutions. Tools are that important.

Remember that this article is part of a longer 10-part series that walks you through every component of an agentic harness.

Here's the roadmap:

Part 1: The Raw Model Problem
Part 2: Defining the Harness — The Six Components
Part 3: The Control Loop
The Tool Layer ← You just finished this one.
Part 5: Context Engineering ← Move to this one.
Part 6: The Filesystem & Environment
Part 7: The Memory Layer
Part 8: Observability
Part 9: The Harness Architecture
Part 10: Decomposing Claude Code

See you in the next one.

Happy coding :)

Harness Engineering - Part 3: The Control Loop

Fikayo Adepoju — Sat, 15 Aug 2026 18:28:34 +0000

Welcome back to the Harness Engineering series — a 10-part journey from raw language model to production-ready agentic system. Made by builders. For builders.

In Part 2, I named the six components that make up a harness. Time to dig into the first one — and it's not an accident that it's first. The Loop is the outermost machinery of a harness. It's the piece everything else plugs into. Without it, none of the other components have anything to do.

Every agent you've ever seen — whether it's Claude Code fixing a bug, a research agent skimming papers, or a customer support bot pulling up account data — has a Loop at its core. Sometimes it's obvious. Sometimes it's tucked away inside a framework. But it's always there, and how it's designed shapes what the agent is capable of.

What's ahead:

Part 1: The Raw Model Problem
Part 2: Defining the Harness — The Six Components
The Control Loop ← You are here
Part 4: The Tool Layer
Part 5: Context Engineering
Part 6: The Filesystem & Environment
Part 7: The Memory Layer
Part 8: Observability
Part 9: The Harness Architecture
Part 10: Decomposing Claude Code

By the end of this article, you'll know what the Loop is, why every agent needs one, what separates a robust loop from a fragile one, and the common shapes you'll see loops take in the wild.

Let's get started.

What The Loop Is

The Loop is the control flow that wraps the model. It's the piece of code that turns a one-shot API call into something that can take multiple steps, react to intermediate results, and eventually stop when the job is done.

At its minimum, a loop does three things, in a cycle:

Call the model with the current context.
Parse the response.
If the model asked for a tool, run the tool and call the model again with the results attached. Otherwise, stop.

In pseudocode, that looks like:

while True:
    response = model.call(context)
    context.append(response)

    if response.has_tool_call:
        result = run_tool(response.tool_call)
        context.append(result)
    else:
        break  # model is done

That's it. Three steps, running in a cycle. Every fancy orchestration pattern you've heard of — multi-agents, sub-agents, planning phases, self-reflection — is a variation of this shape. Sometimes with extra bells, sometimes with recursion, sometimes with parallelism. But underneath, the same core cycle.

Another way to say it: the Loop is where the model does its work, and where the harness decides what to do with that work. Without the Loop, the model produces one message and the process ends. With the Loop, the model gets to iterate — respond to tool results, revise its plan, keep going until something is done.

Why The Loop Exists

We established in Part 1 that a raw language model can't act. But the Loop solves a subtler problem: a single model call produces text and then exits.

Even if you gave the model tools, without a loop all it could do is say "I'd call this tool now." The moment it finishes generating that message, control returns to your program. If your program isn't set up to look for tool requests, run them, and re-call the model, no tool actually runs. The model's request just sits there in the response object.

Everything that resembles agency — taking multiple steps, reacting to results, deciding to keep going or stop — has to come from a loop around the model. Not from the model itself. The model doesn't know it's in a loop. Every time it's called, it just responds to whatever context it's given.

The model proposes; the Loop decides whether to keep going.

That sentence is worth writing on a Post-it. Every design decision about the Loop follows from it.

What a Good Loop Design Looks Like

If you're evaluating a harness — or someone else's — three things separate a good Loop from a bad one.

Clear Termination Conditions

A Loop that doesn't know when to stop is not an agent. It's a bill from your model provider. Good loops have explicit, multiple termination conditions:

The model signals it's done — a stop phrase in the response, a specific stop_reason from the API, or a done tool call the model can invoke on itself
A step budget runs out — a max-iterations counter that prevents runaway loops
An error threshold is hit — too many consecutive tool failures, too many parse errors, too many empty responses in a row

You want all of these, not one. Relying on the model alone to say "I'm done" is how you end up with agents that run for 200 iterations because the model keeps thinking of one more thing to check.

Sensible Error Handling

When a tool call fails — invalid parameters, network timeout, the file doesn't exist — the Loop should not crash. It should catch the error and feed it back to the model as an observation.

This turns errors into information. The model reads "the file you tried to open doesn't exist," realizes it hallucinated the filename, and tries a different one. That's the whole game. A Loop that crashes on the first tool failure has no way to recover. A Loop that treats errors as inputs to the next model call learns to steer around them.

A Loop Has a Shape

The two points above are about the quality of a Loop. But loops also come in different shapes — architectures, patterns, whatever you want to call them. And the shape determines what kinds of tasks the loop can handle.

Some of the common shapes you'll run into:

ReAct — the model alternates between "reasoning" (thinking out loud) and "acting" (calling tools), with tool observations feeding back into the next reasoning step. The default shape for most modern agents.
Plan-then-Act — the model produces a plan up front, then the Loop executes the plan step by step. Good for tasks with a knowable structure; brittle when the world doesn't cooperate.
Multi-Agent — multiple agents (each with their own Loop) coordinate on a task, often passing messages between one another. Useful when different sub-tasks call for different tools, models, or personas.
Deep Recursion — the Loop is intentionally allowed to spawn sub-loops that dig into a task. The Ralph Loop and Orchestrator/Worker patterns are two variants. Powerful for tasks that decompose naturally into sub-tasks.

None of these shapes is objectively "best." The right shape depends on the task, the reliability requirements, and how much you're willing to spend per invocation. Getting the shape wrong is one of the most common ways an otherwise well-built harness fails to do the thing it was designed to do.

Example: Claude Code

If you've used Claude Code, you've already watched the Loop at work.

When you ask Claude Code to fix a bug, it doesn't make one model call. It makes many. It reads a file. It edits the file. It runs the tests. It reads the failure output. It edits the file again. It re-runs the tests. It reads the diff. It might read a different file to check an import. It keeps going, iteration after iteration.

The Loop is what makes that possible.

And critically, the Loop is also what decides when to stop — when the tests pass, or when Claude Code is confident the task is done. Without termination conditions, the same Loop that fixes bugs would keep going forever, "improving" code long after the user's actual request was satisfied.

So when you see Claude Code do something impressive across ten or twenty steps, remember: the model doesn't know it's doing ten or twenty steps. Every time it's called, it just sees the current state and produces the next response. The sense of coherent, multi-step problem-solving — the thing that makes it feel like an agent — comes entirely from the Loop wrapping it.

Where This Leaves Us

The Loop is the first component of the harness because nothing else works without it. Tools have nowhere to be invoked from. Context has nothing driving its accumulation. Memory has no cycle to write into. Observability has no execution path to trace. Every other component plugs into the Loop.

That's why we started here. From Part 4 onward, every component we look at slots into the Loop somewhere — and understanding the Loop is what lets you see where.

Remember that this article is part of a longer 10-part series that walks you through every component of an agentic harness.

Here's the roadmap:

Part 1: The Raw Model Problem
Part 2: Defining the Harness — The Six Components
The Control Loop ← You just finished this one.
Part 4: The Tool Layer ← Move to this one.
Part 5: Context Engineering
Part 6: The Filesystem & Environment
Part 7: The Memory Layer
Part 8: Observability
Part 9: The Harness Architecture
Part 10: Decomposing Claude Code

See you in the next one.

Happy coding :)

Harness Engineering - Part 2: Defining the Harness — The Six Components

Fikayo Adepoju — Sat, 15 Aug 2026 18:27:10 +0000

Welcome back to the Harness Engineering series — a 10-part journey from raw language model to production-ready agentic system. Made by builders. For builders.

In Part 1, we landed on a definition of a harness that was true but a little too broad to work with: everything that is not the model is the harness. Fine. But if a harness is everything that isn't the model, then the word "harness" covers a lot of ground — from the loop that calls the model to the logging library that writes what happened to disk.

You can't reason about "everything." You need parts.

So here's the promise for this article: I'll give you the six parts. Six components, each with a name, each with a job, each corresponding to a specific class of agent failure when it's missing or broken. Once these six names are in your head, every conversation you have about agents — debugging, design reviews, comparing frameworks, reading papers — gets sharper.

What's ahead:

Part 1: The Raw Model Problem
Defining the Harness — The Six Components ← You are here
Part 3: The Control Loop
Part 4: The Tool Layer
Part 5: Context Engineering
Part 6: The Filesystem & Environment
Part 7: The Memory Layer
Part 8: Observability
Part 9: The Harness Architecture
Part 10: Decomposing Claude Code

By the end of this article, you'll have a formal definition of a harness, a three-verb specification of what it has to do, and a six-component vocabulary you can carry into every conversation about agents from here on out.

Let's get started.

The Harness Isn't One Thing

In Part 1, we saw that a raw language model can't act on the world — it can only produce text that describes acting. We called the wrapper that closes this gap a harness, and we defined it as everything that is not the model.

That definition is true. It's also too broad to reason about.

Because a harness isn't one thing. It's a stack of six concerns, each of which can be designed well or badly, and each of which corresponds to a specific class of agent failure when it's missing or broken. Part 1 named the gap. This article names the parts that close it.

Why bother naming them? Because once you have this vocabulary, every conversation you have about agents changes. When someone shows you a failing agent, you can point at the specific component that's broken. When a framework claims to be "an agentic runtime," you can ask which of the six? When you read a paper about a new technique, you can slot it into the layer it belongs to. Without the vocabulary, "agent stuff" is a fog. With it, you can navigate.

A Formal Definition

Let's tighten the working definition from Part 1 into something more precise.

Three verbs are doing the load-bearing work in that sentence. Let's unpack each one.

Action

The harness gives the model surface area beyond text — a filesystem, a code sandbox, web access, an API. It doesn't just let the model describe things happening. It executes the things the model describes.

This is the direct answer to the surface area problem from Part 1. A model that can only produce text is stuck in the pure-description layer of reality. A harness reaches into the execution layer, the data layer, and the network layer, and closes the loop between "the model said to do X" and "X actually happened."

Persistence

The harness retains state the model itself cannot. Within a single task, that means holding onto tool results, intermediate reasoning, and running notes. Across sessions, it means remembering who you are, what you've been working on, and what worked before.

Persistence is a harness feature, not a model feature. Every "memory" you've ever experienced from an LLM was built by something outside the model — quietly holding state and replaying it back into the prompt when the model needs to "recall" something.

Measurable Behavior

The harness exposes what the agent is doing so engineers can debug it, evaluate it, and improve it. This is easy to skip when you're prototyping and painful to add later when you're not. And without it, you can't tell a working agent from a lucky one.

The Six Components

Every component in the taxonomy below serves at least one of the three verbs above. Most serve more than one.

#	Component	One-line definition
1	The Loop	The control structure that calls the model, dispatches tool calls, and decides when to stop
2	The Tools	The functions the model can invoke to have side effects in the world
3	The Context	Everything fed into the model on a given call — system prompt, history, retrieved knowledge, tool results
4	The Environment	The runtime the tools operate inside — filesystem, shell, network, sandbox boundaries
5	The Memory	State that persists across loop iterations and across sessions — short-term and long-term
6	The Observability	How the harness exposes what it's doing — logs, traces, evals, debuggability

Each of these six components gets its own dedicated article in the rest of this series — the Loop in Part 3, the Tools in Part 4, the Context in Part 5, the Environment in Part 6, the Memory in Part 7, and Observability in Part 8.

Where This Leaves Us

Six components. Three verbs. One insight worth carrying forward: the harness is not a thing — it's a stack of concerns, and getting each one right is its own discipline.

From Part 3 onward, we take each of these six components in turn and ask the same set of questions of it: What is it? What does it do? What does it look like when it's designed well? What breaks when it's missing? Different articles, same underlying method — because the harness itself has that shape.

Remember that this article is part of a longer 10-part series that walks you through every component of an agentic harness.

Here's the roadmap:

Part 1: The Raw Model Problem
Defining the Harness — The Six Components ← You just finished this one.
Part 3: The Control Loop ← Move to this one.
Part 4: The Tool Layer
Part 5: Context Engineering
Part 6: The Filesystem & Environment
Part 7: The Memory Layer
Part 8: Observability
Part 9: The Harness Architecture
Part 10: Decomposing Claude Code

See you in the next one.

Happy coding :)

Harness Engineering - Part 1: The Raw Model Problem

Fikayo Adepoju — Sat, 15 Aug 2026 18:25:35 +0000

Welcome to the Harness Engineering series — a 10-part journey from raw language model to production-ready agentic system. Made by builders. For builders.

Everyone's talking about AI agents. But when you strip away the demos, the hype, and the tweets — what actually is an agent? Where does the "model" end and the "agent" begin? And why do so many prototypes that look magical in a Jupyter notebook fall apart the moment you try to ship them?

Here's the uncomfortable truth: a language model, by itself, cannot do anything at all. It can't touch a file. It can't call an API. It can't remember what you told it yesterday. It can't check its own work. It can't install pandas. What we call "AI agents" are not made of models — they are made of everything wrapped around the model that closes those gaps.

That wrapper has a name. It's called a harness. And harness engineering is the discipline of building that wrapper well.

To help you understand what really goes into one, I've put together a 10-article series that walks straight through every component of a production-grade agentic harness — no framework hand-waving, no vibes-based tutorials. Each article breaks down one component and connects to the next.

What's ahead:

The Raw Model Problem <- You're here
Part 2: Defining the Harness — The Six Components
Part 3: The Control Loop
Part 4: The Tool Layer
Part 5: Context Engineering
Part 6: The Filesystem & Environment
Part 7: The Memory Layer
Part 8: Observability
Part 9: The Harness Architecture
Part 10: Decomposing Claude Code

By the end, you'll have a clear mental model of every component in an agentic harness — what each piece does, why it's there, and how they fit together. Enough to architect your own instead of copying somebody else's stack.

Let's get started.

What Is a Harness?

Plain English first. A harness is a support system for a thing — a person, an animal, or an object — that lets it do work it couldn't do on its own. A climber's harness lets a body hang safely off a rope. A horse's harness lets it pull a cart. A wiring harness lets electrical current flow through a car without frying it.

In agentic engineering, the "thing" being harnessed is the language model. And the work it can't do on its own turns out to be… almost everything you'd want an agent to do.

Everything we break down from Part 2 onward is a response to this one limitation. So before we go any further, we need to see the limitation clearly — because if you don't understand what you're working around, you can't tell whether your harness is any good.

What a Raw Model Actually Is

Most developers coming from traditional software engineering carry a mental model of the LLM as a function in a library. You call it, it does something, and it returns a result. Something like:

result = ai.do_thing("summarize this file and save it to disk")

That mental model is wrong. And I don't mean "wrong in some pedantic way" — I mean it's wrong at the level that will silently break every agent you try to build.

Under the hood, a language model is a text transformer. That's it. Its full job description is:

Input: a sequence of tokens
Output: a probability distribution over the next token
Repeat until done.

No side effects. No memory between calls. No access to anything outside the prompt. The intelligence is real — genuinely, remarkably real — but the surface area is limited to "tokens in, tokens out."

The raw model cannot do anything. It can only describe doing things.

Read that sentence again. It's the load-bearing insight for this entire series.

The 5 Gaps

If we take that insight and expand it into concrete deficiencies, we get five gaps that a harness has to close.

#	Gap	What the raw model cannot do
1	No execution	Run code, call APIs, touch files, hit the network
2	No durable state	Remember anything between sessions, or across context limits
3	No fresh knowledge	Know anything past its training cutoff, or anything private
4	No self-verification	Check whether its own output is correct
5	No environment	Install dependencies, configure a runtime, set up a workspace

Let's walk through each one.

Gap 1: No Execution

The model cannot read or write a file, run a script, query a database, or make an HTTP request. If the agent needs to act on the world, something other than the model has to do the acting. That "something" is the harness.

Gap 2: No Durable State

Every API call to a language model is stateless on the model's side. What you experience as "conversation memory" in ChatGPT is an illusion — the client is replaying the full message history in every call. Once the context window fills up, or the session ends, the model remembers nothing. Persistence is a harness feature, not a model feature.

Gap 3: No Fresh Knowledge

The model's knowledge is frozen at its training cutoff. It doesn't know:

What happened in the world last week
Anything about your codebase, your company's docs, or your private data
The current version of any library that has shipped updates since it stopped learning

The only way to give it this knowledge is to inject it into the prompt — which means something has to retrieve it first. That's a harness job.

Gap 4: No Self-Verification

The model can generate code, but it cannot run the code to see if it works. It can produce a summary, but it cannot compare the summary to the source to check fidelity. It can claim correctness — often very confidently — but claiming and verifying are different operations, and only one of them is available to the raw model.

The harness is what builds a verification system around the agent's outputs.

Gap 5: No Environment

The model is not sitting inside a Linux box with Python and git installed. It's not sitting anywhere — it's a mathematical function being evaluated on a GPU somewhere in a data center.

If we want the agent to use pandas, something has to install pandas. If we want it to use a browser, something has to give it a browser. Environments are harness-provided.

Demo: The Surface Area Problem

Enough theory. Let's watch a raw model bump into these gaps in the wild.

The plan is simple: we'll give a model the smallest possible task that requires it to reach outside itself — read a file, summarize it, and write the summary to disk — and see what happens.

Setting Up

Create a folder for the project and drop into it:

mkdir harness-project
cd harness-project

Create a Python virtual environment and activate it:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Install the OpenAI Python package:

pip install openai

Now create a file called article.txt at the root of the project and paste the following text into it:

Before Gutenberg's fifteenth-century printing press, books were rare, hand-copied treasures chained to monastery libraries, accessible only to clergy and scholars. That changed irrevocably in Mainz around 1440. By combining movable metal type, oil-based inks, and an adapted screw press, Gutenberg enabled the rapid, uniform production of texts. His famous Bible of 1455 was not merely a beautiful artifact but a declaration: knowledge could now be manufactured. The consequences were explosive. For the first time, information could spread faster than political or religious authorities could suppress it. Within decades, printing shops erupted across Europe, producing millions of books. Humanist ideas, scientific observations, and navigational charts circulated widely. Most critically, the press democratized scripture and criticism; Martin Luther's vernacular pamphlets reached a literate public, igniting the Reformation. Beyond religion, it standardized languages, elevated vernacular literature, and allowed scholars to build upon corrected, shared knowledge—catalyzing the Scientific Revolution. The printing press did not merely make books; it unmoored authority from the few and anchored it in the hands of the many, laying the very groundwork for our modern world of mass media, public education, and individual conscience.

Then create demo.py at the root of the project and add the following code:

from openai import OpenAI

client = OpenAI()

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {
            "role": "user",
            "content": (
                "Read the file article.txt in this directory, "
                "summarize it in 3 bullets, and save the summary "
                "to summary.md."
            ),
        }
    ],
)

print(response.choices[0].message.content)

Look at what this script is asking for. Three concrete actions:

Read a file — a filesystem operation
Summarize it — a text operation, which the model actually can do
Write a file — another filesystem operation

Two out of three are things the model has no way to perform. Watch what it does about that.

Add your OpenAI API key to the environment:

export OPENAI_API_KEY=<your-key-here>

And run the demo:

python demo.py

What Actually Happens

The model responds with something close to this:

I don't have the ability to read files or access directories 
directly. However, I can help you with instructions on how to 
summarize the content of a file. If you provide the text or 
key points from the article, I can assist you in creating a 
summary. Once you have the summary, you can save it to a file 
named summary.md. Would you like to proceed with that?

Give it credit — this is a well-behaved response. The model:

Accurately reports its limitation — it knows it can't access files
Offers the capability it does have — summarizing, if you paste the text
Routes the I/O back to the user — "you can save it to a file"

Now look at your directory after the call:

ls
# article.txt   demo.py   venv/

The contents are identical to before. No summary.md. The Python script exits with code 0. Everything ran cleanly. And yet…

What This Demonstrates

Nothing happened.

That's the lesson. Not "the model failed" — the model did exactly what it could do, and did it gracefully. But the world outside the prompt is completely unchanged. The directory doesn't care how politely the model declined.

This is the surface area problem in its purest form. The model's only output channel is text. And text can describe action, recommend action, decline action, or claim action — but text is not action. The gap between describing a file write and writing a file has to be closed by something other than the model.

Look at what the model itself suggested we do:

"Provide the text" → manual file read
"I can assist you in creating a summary" → the model's actual capability
"You can save it to a file" → manual file write

That's a workflow with three steps, where the model handles the middle one and a human handles the bookends.

A harness is what automates the bookends so the human doesn't have to be the file system.

Gaps Exposed by This Demo

Three of our five gaps just showed up on stage:

No execution — the model couldn't read or write, and correctly said so
No environment — there's no filesystem available to it in the first place
No durable state — even the summary it offered to help with would vanish the moment the API call ended, unless something outside the model persisted it

Gaps 3 (fresh knowledge) and 4 (self-verification) don't show up here — this task didn't require the model to fetch anything past its training cutoff, and it didn't ask the model to check its own work. Different tasks would surface those gaps just as clearly.

Summary

Let's tighten this down into two definitions to carry into the rest of the series.

The long one:

The short one:

The harness is what closes the gap between description and action. And starting in Part 2, we're going to break one open — piece by piece, gap by gap — until you can see exactly how a raw model turns into an agent capable of doing the file-summary task your model just apologized for.

Remember that this article is part of a longer 10-part series that walks you through every component of an agentic harness.

Here's the roadmap:

The Raw Model Problem ← You just finished this one.
Part 2: Defining the Harness — The Six Components ← Move to this one.
Part 3: The Control Loop
Part 4: The Tool Layer
Part 5: Context Engineering
Part 6: The Filesystem & Environment
Part 7: The Memory Layer
Part 8: Observability
Part 9: The Harness Architecture
Part 10: Decomposing Claude Code

See you in the next one.

Happy coding :)

File Uploads with HTMX and Golang

Fikayo Adepoju — Mon, 19 Aug 2024 22:15:34 +0000

Ofcourse you have already heard about the awesomeness of HTMX (you haven’t? well, good thing you’re here 😃)

Today, we will be combining the simplicity of HTMX with the power of Golang to upload files to our server. Yeah, we are going to be building another exciting web feature with HTMX and Go.

So, let’s begin.

Setting Up the Go Project

The first step is to setup a simple Go project. We can do that by creating a folder, going into it and initialising it as a Go project using the commands below:

mkdir go-htmx-file-uploads
cd go-htmx-file-uploads
go mod init go-htmx-file-uploads

Once we have the project initialized, let’s now install some dependencies we will be requiring within our project.

This will be a simple server that will contain a single page with our upload form and also an endpoint that will be used to upload the file.

For routing, we will be using the Gorilla Mux routing library, but feel free to use any routing solution of your choice. We will also be using Google’s UUID library for Go to generate random names for our files when we upload them. This is a personal preference as you can generate file names in different ways.

Install these two with the commands below:

Gorillla Mux

go get -u github.com/gorilla/mux

Google UUID

go get github.com/google/uuid

With these two installed, our project is fully set up, and we can move to the next step.

Creating our Templates

We will be creating two HTML templates for this little project.

The first template will be an HTML fragment that simply takes a slice of string messages that we can send from the server to the client.

This fragment will take this slice of messages and loop through it to create an HTML list to be returned to the client (remember how HTMX works with Hypermedia APIs, pretty cool huh 😎).

So, let’s create that first.

At the root of the Go project, first create a templates folder inside which we will be storing all our templates.

Next, create a file messages.html inside the templates folder and add the following code to it:

{{define "messages"}}
<ul>
    {{range .}}
        <li>{{ . }}</li>
    {{end}}
</ul>
{{end}}

This defines a messages template and loops through the incoming slice of string messages to form an HTML list.

For our next template, we will be creating the file upload page itself.

Inside the templates folder, create a new file upload.html and paste in the code below:

{{define "upload"}}
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.1.3/dist/css/bootstrap.min.css" rel="stylesheet">
    <script src="https://unpkg.com/htmx.org@1.9.12"></script>
    <title>Upload File</title>
</head>
<body>

    <div class="row">
        <div class="col-md-6 p-5 mt-5">
            <h4>Upload File</h4>
            <form  class="form">
                <div id="messages"></div>
                <div class="mb-3">
                    <label for="avatarInput" class="form-label">Select Image</label>
                    <input type="file" class="form-control" id="avatarInput" name="avatar" required>
                </div>
                <button 
                    hx-post="/upload" 
                    hx-encoding="multipart/form-data" 
                    hx-target="#messages" 
                    type="submit" class="btn btn-primary">Upload</button>
            </form>
        </div>
    </div>



</body>
</html>
{{end}}

Perfect!

Now let’s go through the code in this file.

First, we have defined the template with the name upload, this is the name we will use to reference it later in our route handlers.

We then have some boilerplate HTML code in the head section, but I have included two important libraries here (well, just one is really important, the other is just for CSS vibes).

The HTMX library has been included with the <script> tag to bring in HTMX, just the library, no dependencies required.

Then I have also brought in the Bootstrap CSS library, this is just to give our page elements some nice styling. It is not compulsory for this demo.

In the page itself, we have a form that does the upload. Let’s break down what is within the <form> tags.

First we have a <div> with an id of messages , this is the container where we will be loading all our server messages that come in as HTML. Remember the messages template, yeah, this is where the list of messages will be going into.

After that, we have the form input element that is set to file to ensure that it displays a file upload widget. We have given it the name avatar to reference it at the backend, but you can give this any name you want. I gave it avatar because i was using it to upload profile images.

Finally, we have the button which has been supercharged with HTMX. I have displayed it again below so we can go through it

<button 
                    hx-post="/upload" 
                    hx-encoding="multipart/form-data" 
                    hx-target="#messages" 
                    type="submit" class="btn btn-primary">Upload</button>

First, I have added hx-post="/upload" , this tells it to submit the form to the /upload endpoint that we will be creating very soon and will handle the file upload.

Next is hx-encoding="multipart/form-data", this is compulsory for uploading files with HTMX to let the server know you’re sending along a file with the request.

Then we have hx-target="#messages" which tells the button to insert any response from the server into the <div> with an id of messages.

These three define our configuration for uploading the file to our backend.

Below is a preview of what our page looks like:

Processing the File Upload

Now that we have our templates, it’s time to write the code that will display our upload page and also handle our file uploads.

To begin, at the root of the Go project, create a uploads folder. This is the folder where all our uploaded files will be stored.

With that in place, let’s write our main file.

Create the file main.go at the root of your project and add the following code:

package main

import (
    "html/template"
    "log"
    "net/http"
    "io"
    "os"
    "path/filepath"
    "github.com/google/uuid"
    "github.com/gorilla/mux"
)

var tmpl *template.Template

func init(){
    tmpl, _ = template.ParseGlob("templates/*.html")
}

func main() {


    router := mux.NewRouter()

    router.HandleFunc("/", homeHandler).Methods("GET")

    router.HandleFunc("/upload", UploadHandler).Methods("POST")

    log.Println("Server starting on :8080")
    log.Fatal(http.ListenAndServe(":8080", router))
}

func homeHandler(w http.ResponseWriter, r *http.Request) {

    tmpl.ExecuteTemplate(w, "upload", nil)

}

func UploadHandler(w http.ResponseWriter, r *http.Request) {


        // Initialize error messages slice
        var serverMessages []string

        // Parse the multipart form, 10 MB max upload size
        r.ParseMultipartForm(10 << 20)

        // Retrieve the file from form data
        file, handler, err := r.FormFile("avatar")
        if err != nil {
            if err == http.ErrMissingFile {
                serverMessages = append(serverMessages, "No file submitted")
            } else {
                serverMessages = append(serverMessages, "Error retrieving the file")
            }

            if len(serverMessages) > 0 {
                tmpl.ExecuteTemplate(w, "messages", serverMessages)
                return
            }

        }
        defer file.Close()

        // Generate a unique filename to prevent overwriting and conflicts
        uuid, err := uuid.NewRandom()
        if err != nil {
            serverMessages = append(serverMessages, "Error generating unique identifier")
            tmpl.ExecuteTemplate(w, "messages", serverMessages)

            return
        }
        filename := uuid.String() + filepath.Ext(handler.Filename) // Append the file extension

        // Create the full path for saving the file
        filePath := filepath.Join("uploads", filename)

        // Save the file to the server
        dst, err := os.Create(filePath)
        if err != nil {
            serverMessages = append(serverMessages, "Error saving the file")
            tmpl.ExecuteTemplate(w, "messages", serverMessages)

            return
        }
        defer dst.Close()
        if _, err = io.Copy(dst, file); err != nil {
            serverMessages = append(serverMessages, "Error saving the file")
            tmpl.ExecuteTemplate(w, "messages", serverMessages)
            return
        }


        serverMessages = append(serverMessages, "File Successfully Saved")
        tmpl.ExecuteTemplate(w, "messages", serverMessages)


}

Yope, that’s a bunch of code. Don’t worry, we’ll go through it all step by step to figure out what this is all doing.

First we define our package main and import a bunch of libraries we will be making use of. These imports include the Gorilla mux router and the Google UUID library that we installed earlier.

After that, I create a global tmpl variable to hold all the HTML templates in the project and in the init() function, the templates are all loaded from the templates folder.

The main() Function

Now to the main() function. Here, we have initlialized the Gorilla Mux router and set up two routes.

The GET / base route which will be handled by a homeHandler function and displays our upload form, and the POST /upload route that will be handled by UploadHandler and handles the upload itself.

Finally, we print out a message to indicate that our server is running, and run the server on port 8080.

The Handler Functions

First we have homeHandler . This is the function that handles our base route, and it simply calls ExecuteTemplate on the tmpl variable with the name we gave to our template

tmpl.ExecuteTemplate(w, "upload", nil)

This call is enough to simply render our upload page to the screen when we visit the base route.

After that is the UploadHandler function. This is where the real magic happens, so let’s walk through the function.

First, we create a slice of strings called serverMessages to hold any message we want to send back to the client.

After that, we call ParseMultipartForm on the request pointer to limit the size of uploaded files to within 20MB.

r.ParseMultipartForm(10 << 20)

Next, we get a hold on our file by referencing the name of the file field with FormFile on the request pointer.

With our reference to the file, we check if there is actually a file, and if not, we return a message saying that no file was submitted or an error was encountered when trying to retrieve the file to account for other errors.

file, handler, err := r.FormFile("avatar")
        if err != nil {
            if err == http.ErrMissingFile {
                serverMessages = append(serverMessages, "No file submitted")
            } else {
                serverMessages = append(serverMessages, "Error retrieving the file")
            }

            if len(serverMessages) > 0 {
                tmpl.ExecuteTemplate(w, "messages", serverMessages)
                return
            }

        }

At this point, if our messages slice is not empty, we return the messages to the client and exit the function.

If a file is found, we keep the file open and move to generating a new name for it with the UUID library and also handle the errors in that process accordingly.

We build a new file name with the generated string and the file extension and set it’s path to the uploads folder.

    uuid, err := uuid.NewRandom()
        if err != nil {
            serverMessages = append(serverMessages, "Error generating unique identifier")
            tmpl.ExecuteTemplate(w, "messages", serverMessages)

            return
        }
        filename := uuid.String() + filepath.Ext(handler.Filename) 

        // Create the full path for saving the file
        filePath := filepath.Join("uploads", filename)

Once the new file path is constructed, we then use the os library to create the file path

After that, we use the io library to move the file from it’s temporary location to the new location and also handle errors accordingly.

    dst, err := os.Create(filePath)
        if err != nil {
            serverMessages = append(serverMessages, "Error saving the file")
            tmpl.ExecuteTemplate(w, "messages", serverMessages)

            return
        }
        defer dst.Close()
        if _, err = io.Copy(dst, file); err != nil {
            serverMessages = append(serverMessages, "Error saving the file")
            tmpl.ExecuteTemplate(w, "messages", serverMessages)
            return
        }

If we get no errors from the file saving process, we then return a successful message to the client using our messages template as we have done with previous messages.

serverMessages = append(serverMessages, "File Successfully Saved")
tmpl.ExecuteTemplate(w, "messages", serverMessages)

And that’s everything.

Now let’s take this code for a spin.

Testing the File Upload

Save the file and head over to the command line.

At the root of the project, use the command below to run our little file upload application:

go run main.go

Now go to your browser and head over to http://localhost:8080, you should see the upload screen displayed.

Try testing with no file to see the error message displayed. Then test with an actual file and also see that you get a successful message.

Check the uploads folder to confirm that the file is actually being saved there.

And Wholla! You can now upload files to your Go servers using HTMX.

Conclusion

If you have enjoyed this article, and will like to learn more about building projects with HTMX, I’ll like you to check out HTMX + Go: Build Fullstack Applications with Golang and HTMX, and The Complete HTMX Course: Zero to Pro with HTMX to further expand your knowledge on building hypermedia-driven applications with HTMX.

HTMX + Go : Build a CRUD App with Golang and HTMX

Fikayo Adepoju — Mon, 15 Jul 2024 19:49:54 +0000

One question I see going around alot about HTMX, especially amongst developers that have just tried the library is “But what can you really build with it though?”

Great question, and in this article, we will start with baby steps by building a database-backed CRUD application with HTMX and Go as our backend language.

Let’s begin.

What exactly are we building?

I’ll like to call it a Task Management Application but I know you already figured that that’s just a fancy name for another Todo application. Don’t worry, Todo apps are great for learning fundamental operations with languages, libraries and frameworks so we will be using that same tested and trusted strategy.

Our application will be able to do the following:

Display tasks
Add new tasks
Update an existing task and …
Delete a task

Database Setup

So first, we need a database, and for this demo project, I will be using MySQL. Feel free to use any database of your choice and make the necessary code changes to reference your database as you follow along with this article.

We will keep things simple, no complicated schema design. First we create a database with the name testdb and inside this database, we create a todos table (feel free to give your database and table any name you prefer but ensure you use the same names in your SQL statements)

Inside the todos table, implement the schema below:

id: PK, Auto incrementing
task : VARCHAR(200) - Contains the task item
done: INT(1), default = 0 (Boolean field)

You can choose to seed the database table with some tasks so that we can start seeing some tasks the first time we load the application.

Creating the Hypermedia API

To begin setting up our little application, create a folder for the project at any convenient location in your development computer.

mkdir task-management

Run the following command at the root of the project folder to initialize it as a Golang project:

go mod init task-management

Next, we need to install some dependencies. We already know we are using MySQL as our database, thus, we need to install the MySQL driver for Golang.

We also need to install the Gorilla Mux Router which will be the routing library for our project. Run the two commands below at the root of your project to get these libraries installed into your project

MySQL:

go get -u github.com/go-sql-driver/mysql

Gorilla Mux:

go get -u github.com/gorilla/mux

With these libraries in place, create your main.go file at the root of the project and add the code below:

package main

import (
    "database/sql"
    "fmt"
    "html/template"
    "log"
    "net/http"
    "strconv"
    "strings"

    _ "github.com/go-sql-driver/mysql"
    "github.com/gorilla/mux"
)

var tmpl *template.Template
var db *sql.DB

type Task struct {
    Id   int
    Task string
    Done bool
}

func init() {
    tmpl, _ = template.ParseGlob("templates/*.html")

}

func initDB() {
    var err error
    // Initialize the db variable
    db, err = sql.Open("mysql", "root:root@(127.0.0.1:3333)/testdb?parseTime=true")
    if err != nil {
        log.Fatal(err)
    }

    // Check the database connection
    if err = db.Ping(); err != nil {
        log.Fatal(err)
    }
}

func main() {

    gRouter := mux.NewRouter()

    //Setup MySQL
    initDB()
    defer db.Close()

    gRouter.HandleFunc("/", Homepage)

    //Get Tasks
    gRouter.HandleFunc("/tasks", fetchTasks).Methods("GET")

    //Fetch Add Task Form
    gRouter.HandleFunc("/newtaskform", getTaskForm)

    //Add Task
    gRouter.HandleFunc("/tasks", addTask).Methods("POST")

    //Fetch Update Form
    gRouter.HandleFunc("/gettaskupdateform/{id}", getTaskUpdateForm).Methods("GET")

    //Update Task
    gRouter.HandleFunc("/tasks/{id}", updateTask).Methods("PUT", "POST")

    //Delete Task
    gRouter.HandleFunc("/tasks/{id}", deleteTask).Methods("DELETE")

    http.ListenAndServe(":4000", gRouter)

}

func Homepage(w http.ResponseWriter, r *http.Request) {

    tmpl.ExecuteTemplate(w, "home.html", nil)

}

func fetchTasks(w http.ResponseWriter, r *http.Request) {
    todos, _ := getTasks(db)
    //fmt.Println(todos)

    //If you used "define" to define the template, use the name you gave it here, not the filename
    tmpl.ExecuteTemplate(w, "todoList", todos)
}

func getTaskForm(w http.ResponseWriter, r *http.Request) {

    tmpl.ExecuteTemplate(w, "addTaskForm", nil)
}

func addTask(w http.ResponseWriter, r *http.Request) {

    task := r.FormValue("task")

    fmt.Println(task)

    query := "INSERT INTO tasks (task, done) VALUES (?, ?)"

    stmt, err := db.Prepare(query)

    if err != nil {
        log.Fatal(err)
    }
    defer stmt.Close()

    _, executeErr := stmt.Exec(task, 0)

    if executeErr != nil {
        log.Fatal(executeErr)
    }

    // Return a new list of Todos
    todos, _ := getTasks(db)

    //You can also just send back the single task and append it
    //I like returning the whole list just to get everything fresh, but this might not be the best strategy
    tmpl.ExecuteTemplate(w, "todoList", todos)

}

func getTaskUpdateForm(w http.ResponseWriter, r *http.Request) {

    vars := mux.Vars(r)

    //Convert string id from URL to integer
    taskId, _ := strconv.Atoi(vars["id"])

    task, err := getTaskByID(db, taskId)

    if err != nil {
        http.Error(w, err.Error(), http.StatusInternalServerError)
    }

    tmpl.ExecuteTemplate(w, "updateTaskForm", task)

}

func updateTask(w http.ResponseWriter, r *http.Request) {

    vars := mux.Vars(r)

    taskItem := r.FormValue("task")
    //taskStatus, _ := strconv.ParseBool(r.FormValue("done"))
    var taskStatus bool

    fmt.Println(r.FormValue("done"))

    //Check the string value of the checkbox
    switch strings.ToLower(r.FormValue("done")) {
    case "yes", "on":
        taskStatus = true
    case "no", "off":
        taskStatus = false
    default:
        taskStatus = false
    }

    taskId, _ := strconv.Atoi(vars["id"])

    task := Task{
        taskId, taskItem, taskStatus,
    }

    updateErr := updateTaskById(db, task)

    if updateErr != nil {
        log.Fatal(updateErr)
    }

    //Refresh all Tasks
    todos, _ := getTasks(db)

    tmpl.ExecuteTemplate(w, "todoList", todos)
}

func deleteTask(w http.ResponseWriter, r *http.Request) {

    vars := mux.Vars(r)

    taskId, _ := strconv.Atoi(vars["id"])

    err := deleTaskWithID(db, taskId)

    if err != nil {
        http.Error(w, err.Error(), http.StatusInternalServerError)
    }

    //Return list
    todos, _ := getTasks(db)

    tmpl.ExecuteTemplate(w, "todoList", todos)
}

func getTasks(dbPointer *sql.DB) ([]Task, error) {

    query := "SELECT id, task, done FROM tasks"

    rows, err := dbPointer.Query(query)

    if err != nil {
        return nil, err
    }

    defer rows.Close()
    var tasks []Task

    for rows.Next() {
        var todo Task

        rowErr := rows.Scan(&todo.Id, &todo.Task, &todo.Done)

        if rowErr != nil {
            return nil, err
        }

        tasks = append(tasks, todo)
    }

    if err = rows.Err(); err != nil {
        return nil, err
    }

    return tasks, nil

}

func getTaskByID(dbPointer *sql.DB, id int) (*Task, error) {

    query := "SELECT id, task, done FROM tasks WHERE id = ?"

    var task Task

    row := dbPointer.QueryRow(query, id)
    err := row.Scan(&task.Id, &task.Task, &task.Done)

    if err != nil {
        if err == sql.ErrNoRows {
            return nil, fmt.Errorf("No task was found with task %d", id)
        }
        return nil, err
    }

    return &task, nil

}

func updateTaskById(dbPointer *sql.DB, task Task) error {

    query := "UPDATE tasks SET task = ?, done = ? WHERE id = ?"

    result, err := dbPointer.Exec(query, task.Task, task.Done, task.Id)

    if err != nil {
        return err
    }

    rowsAffected, err := result.RowsAffected()

    if err != nil {
        return err
    }

    if rowsAffected == 0 {
        fmt.Println("No rows updated")
    } else {
        fmt.Printf("%d row(s) updated\n", rowsAffected)
    }

    return nil

}

func deleTaskWithID(dbPointer *sql.DB, id int) error {

    query := "DELETE FROM tasks WHERE id = ?"

    stmt, err := dbPointer.Prepare(query)

    if err != nil {
        return err
    }
    defer stmt.Close()

    result, err := stmt.Exec(id)
    if err != nil {
        return err
    }

    rowsAffected, err := result.RowsAffected()
    if err != nil {
        return err
    }
    if rowsAffected == 0 {
        return fmt.Errorf("no task found with id %d", id)
    }

    fmt.Printf("Deleted %d task(s)\n", rowsAffected)
    return nil

}

Yeah, that was alot of code. Don’t worry, we will take it from the very top and walk down

So first we import all our necessary packages. The MySQL driver and Gorilla Mux router we installed, and a bunch of packages from the Go standard library that will be useful in our code operations.

import (
    "database/sql"
    "fmt"
    "html/template"
    "log"
    "net/http"
    "strconv"
    "strings"
    _ "github.com/go-sql-driver/mysql"
    "github.com/gorilla/mux"
)

Next, we create a tmpl variable that will be used to hold our loaded templates and a db variable that will be a pointer to our database connection for running database tasks. We then create a custom Task struct that defines a task type.

Inside the init() function, we load all our templates from a templates folder. All our templates are expected to have the .html extension as since HTMX expects us to return HTML, this makes a ton of sense.

Go ahead and create the templates folder at the root of the project so that we can begin loading all our templates from there.

We also have an initDB() function that takes care of setting up our connection to the database and returns a pointer reference to our database. Ensure to change the connection string to match that of your database (credentials, host, port, database name etc)

Inside the main function, we initialize our router and call our initDB() database function to initialize our database. This is then followed by all our routes and route handlers and finally, we listen on port 4000 which is where we will be serving the application.

Routes and Handlers

Now let’s begin breaking down our routes and their respective handlers.

The GET / Base Route: This is our base route and loads the home page of the application. The handler, Hompage returns the home.html file to the client.
The GET /tasks Route: This route uses the fetchTasks handler to get all our tasks from our database and return them in an HTML list to the client using a todoList template.
The GET /newtaskform Route: This route will load a new task form from the server each time a user wants to create a new task or clicks a Add New Task button. It uses a addTaskForm template to display a new HTML form for adding a new task
The POST /tasks Route: This route calls the addTask handler to add a new task to the database and return an updated list of all tasks.
The GET /gettaskupdateform/{id} Route: Uses the Id of a task to load the task into an update form with the updateTaskForm template and returns this form to the client when the user clicks the Edit button.
The PUT/POST /tasks/{id} Route: Takes the Id of a task to be updated and updates it using the updateTask handler. After the update operation, the most recent version of the list is returned as HTML.
The DELETE /tasks/{id} Route: Uses the deleteTask handler and a task Id to delete a specific task. Once the task is deleted, an updated list of tasks is returned back to the client.

And that’s all the routes and handlers used in this application.

You may have noticed some other functions asides the route handlers also defined in our main.go file. These are functions for performing database operations for fetching tasks (getTasks), getting a single task using its Id (getTaskByID), updating a task using its Id (updateTaskById), and deleting a task using the tasks’ Id (deleTaskWithID).

These helper functions are used within our route handlers to facilitate database operations and keep the handlers lean.

Creating Our Templates

Now that we are familiar with our Hypermedia API, let’s begin creating the HTML templates that will be retuned in the response to our API calls.

First, we create home.html file in the templates folder. This will load the home page of our task management application. Add the following code to the file after creating it.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-QWTKZyjpPEjISv5WaRU9OFeRpok6YctnYmDr5pNlyT2bRjXh0JMhjY6hW+ALEwIH" crossorigin="anonymous">
    <script src="https://unpkg.com/htmx.org@1.9.12"></script>
    <title>To Do App</title>
</head>
<body>

    <div class="row">

        <div class="col">
            <h2>Tasks</h2>

            <div>
                <a href="#" hx-get="/newtaskform" hx-target="#addTaskForm">Add New Item</a>
            </div>

            <div id="taskList" hx-get="/tasks" hx-trigger="load" hx-swap="innerHTML">

            </div>

        </div>
        <!-- <div class="col">

        </div> -->
        <div class="col">
            <h2>Add New Task</h2>

            <div id="addTaskForm">
                {{template "addTaskForm"}}
            </div>

        </div>

    </div>

</body>
</html>

This templates forms the shell and layout of the entire application. We have the boilerplate HTML structure and I have also added the Bootstrap CSS library for some basic styling. The HTMX library has also been included through a CDN link.

The application layout contains two sections. One section for displaying tasks and the other for showing the new task and task update forms.

The first section contains a button for requesting a new task form from the hypermedia API. Once the form is returned, we then use hx-target to load the form into the div with an id of addTaskForm in the forms section of the page.

<a href="#" hx-get="/newtaskform" hx-target="#addTaskForm">Add New Item</a>

The next component in the first section is the div where our tasks will be loaded into. This div uses hx-trigger to initiate a GET request to the /tasks route once the page loads, thus immediately loading the tasks into the page.

<div id="taskList" hx-get="/tasks" hx-trigger="load" hx-swap="innerHTML">

</div>

In the second section, as mentioned earlier, we have a div with an id of addTaskForm for loading both our new task and update forms. We have also preloaded the form for adding a new task into this div using Go template import syntax so as to have a default form in place.

Now let’s create the form for adding a new task next. Inside the templates folder, create the file addTaskForm.html and add the following code inside it:

{{define "addTaskForm"}}
<form>
    <div>
        <input type="text" class="form-control" name="task">
    </div>
    <div class="mt-2">
        <button class="btn btn-primary" hx-post="/tasks" hx-target="#taskList" hx-target="innerHTML">
            Save
        </button>
    </div>

</form>
{{end}}

This templates loads a fresh form in the UI for adding a new task. When the submit button is clicked, it uses HTMX to send a POST request to the /tasks route to add a new task. When the operation is done, it uses HTMX once again to load the response, an updated list of tasks, into the div with an id of taskList.

Next is our update form template. Inside the templates folder, create the file updateTaskForm.html and add the following code:

{{define "updateTaskForm"}}
<form>
    <div>
        <input type="text" class="form-control" name="task" value="{{.Task}}">
    </div>
    <div>
        <input type="checkbox" name="done" {{if .Done}} checked {{end}} id="">
    </div>
    <div class="mt-2">
        <button class="btn btn-primary" hx-put="/tasks/{{.Id}}" hx-target="#taskList" hx-target="innerHTML">
            Update Task
        </button>
    </div>

</form>
{{end}}

This template takes in a task to be updated and uses it to pre-populate the update form so that the user can see the previous state of the task to be updated.

When the Update Task button is clicked, it will send the updated values to the hypermedia API for the task to be updated. Once updated, it loads the updated list into the page.

Finally, we create the template the returns our list of task items. Inside the templates folder, create the file todoList.html and add the following code:

{{define "todoList"}}
<ul>
    {{range .}}
        <li>
            <span {{if .Done}} style="text-decoration:line-through" {{end}}>{{.Task}}</span>
            [<a href="#" hx-get="/gettaskupdateform/{{.Id}}" hx-target="#addTaskForm" hx-swap="innerHTML">Edit</a>] | 
            <a href="#" hx-delete="/tasks/{{.Id}}" 
                        hx-confirm="Are you sure you want to Delete this Task?"
                        hx-target="#taskList">[Delete]</a>
        </li>
    {{end}}
</ul>

{{end}}

Yeah, a lot is going on in this template, so let’s break it down.

First, the template takes in a Go slice of Task types and loops over it using the range function to create an HTML list of unordered items.

The task it displayed in each list item and the Done property is used to check if the task is completed. If so, we use CSS to strike the task as being completed.

Just after the task text, we have an Edit button. This button calls the /gettaskupdateform endpoint to load an update form using the id of the specific task that was clicked. The user can then update the task and get an updated list of task items.

After the Edit button, we have a Delete button that uses hx-delete to call the DELETE /tasks/{id} endpoint so that we can delete the task. But before we can send the delete request, we use hx-confirm to display a confirmation dialog to the user so that they can confirm if they really want to delete this task item. Once deleted, a new updated list is returned and the task will be gone.

And with that we wrap up our application, so let’s move on to the fun part, checking it out.

Running the Application

With all the code in place, now let’s test our application.

Ensure that all files are saved and run the following command at the root of your project:

go run main.go

Now go to your browser and load the application page at http://localhost:4000. If you have used a different port, ensure that you’re using that port to load the app.

Now you should see your application as displayed below. See below as we add a new task, update an existing task and delete a task from our task list

Conclusion

Happy Coding :)