Have you ever typed something into Claude Code and wondered how it actually works? It’s not too hard to find out, after all, Anthropic accidentally released the Claude Code codebase back in March (The Verge). But what exactly is going on under the hood? How does the architecture function? And how can you build your own bespoke version of such a system? And do you even want to?

What Is an Agent Harness?

Finding a clear-cut definition of an “agent harness” isn’t easy. This is largely because many AI companies are reluctant to give away the exact approach of how their agents work, often disguising the technical definition in marketing jargon that sounds cool or magical (definitions e.g.: Google, OpenAi, Anthropic).

The best difinition I could find was one I stumbled over reading a Github repo about “Best of Agent Harnesses and Harness Techniques” which quoted a Blog entry from Simon Willison’s Weblog: “An LLM agent runs tools in a loop to achieve a goal.” (6)

Technically speaking, an agent harness is the infrastructure and control layer built around a Large Language Model (LLM). A base model (like Claude 3.7 or GPT-4o) cannot natively search your local files, execute terminal commands, or iteratively fix code—it only generates text. The harness is what grants the LLM autonomy. It provides the model with tools, enforces permissions, manages state, and orchestrates the overarching loop of an agentic session. (1)

Inside Claude Code: Architecture Overview

When we examine the architecture of a sophisticated harness like Claude Code, it reveals a highly structured system that goes far beyond a simple chat interface.

At its core, the architecture relies on a continuous evaluation loop. The model isn’t just generating an answer; it’s navigating a Gather-Act-Verify cycle. (2)

graph TD
    A[User Input / Prompt] --> B(Agent Harness Control Loop)
    B --> C{LLM Decision Engine}
    
    C -- Needs Context --> D[Gather]
    D --> D1(Search Files, Read Memory)
    D1 --> B
    
    C -- Ready to Execute --> E[Act]
    E --> E1(Write Code, Run Terminal)
    E1 --> B
    
    C -- Needs Validation --> F[Verify]
    F --> F1(Run Tests, Check Linting)
    F1 -- Error Found --> B
    F1 -- Success --> G[Final Response to User]

Another crucial component of this architecture is Memory Management. Developer Simon Willison highlighted a fascinating architectural detail in a recent blog post comparing the memory implementations of Claude and ChatGPT. (2)

Claude’s harness philosophy prioritizes extreme transparency. Unlike OpenAI, which often injects user profiles or past context into the background automatically, Claude Code starts every conversation as a blank slate. Memory is implemented as explicit tools (specifically conversation_search and recent_chats).

sequenceDiagram
    participant User
    participant Harness
    participant LLM
    participant MemoryDB
    
    User->>Harness: "Continue where we left off yesterday"
    Harness->>LLM: Pass user prompt
    LLM->>Harness: Tool Call: conversation_search()
    Harness->>MemoryDB: Query past logs
    MemoryDB-->>Harness: Return relevant context
    Harness-->>LLM: Inject context into prompt
    LLM->>User: "Ah yes, we were fixing the routing bug..."

Because the model decides when to pull from memory via a visible tool call, you avoid the issue of old “bug loops” silently poisoning a fresh workspace.

Building Your Own Agent Harness and the benefits

But why should you build your own agent harness when they already exist and work fine? I think its just the same reason why open source software exists. Closed-source systems like Claude Code are incredibly powerful, but they are highly opinionated and tailored to specific workflows (like general software development). By building your own, you gain maximum flexibility.

You can customize the exact tools the agent has access to, perhaps integrating it directly with your company’s proprietary databases, Jira ticketing systems, or internal APIs. Or you can just adjust it for your needs for software developement or general purpose use. Fortunately, you don’t have to start from scratch. An excellent starting point is the GitHub repository RyanAlberts/best-of-Agent-Harnesses. (4) This curated, weekly-updated list ranks over 100 open-source agent harnesses. Notably, it even includes an MCP (Model Context Protocol) server, llms.txt, and JSON data, allowing agents themselves to read the repository and recommend the best harness framework for your specific needs.

For what would i use a “Harness” for?

To understand the practical value, let’s look at a real-world project I am doing at work: a system designed to fully automate the production of AI-generated videos.
To be honest, the architecture diagram below represents a highly structured pipeline rather than a full-blown autonomous harness, because I have to make it highly predictable. However, it perfectly illustrates the foundational steps. By giving the central “Orchestrator” more flexibility and decision-making power, this pipeline could easily evolve into a true agentic harness.

How would this be agentic then if we give it more freedom to be “creative”. If we apply the Gather-Act-Verify principles discussed earlier to this exact diagram, the system becomes truly autonomous:

• Gather (Data & Script Prep): Instead of just following a static script, the agent uses tools to autonomously query the AWS Database for the latest product stats and fetches the correct Presentation Assets (potentially using the Model Context Protocol, MCP, to search through company directories).
• Verify (Validation & Creation): This is where a harness shines. In a rigid pipeline, if the Small compliance/Legal check fails, the system just throws an error and stops. In an agent harness, the LLM catches this error, analyzes why the script failed compliance, and autonomously rewrites it until it passes the check.
• Act (Audio, Sync & Rendering): Once the agent verifies the script is perfect, it triggers the text-to-speech tools, gathers the exact audio timestamps, and hands everything over to the rendering engine before finally publishing it.

Challenges and Best Practices

If you decide to build a custom harness, keep these best practices in mind:

1. Cost and Latency Control: Because the agent runs in continuous loops (sending accumulating context back to the model), API costs can skyrocket. Implementing effective Prompt Caching is mandatory. (5)
2. Robust Error Handling: If a tool (e.g., a terminal command) fails, the harness must not crash. It needs to gracefully catch the error (like a stack trace) and feed it back to the LLM during the Verify phase so the agent can self-correct. (5)
3. Transparency: Follow Claude’s example. Don’t hide memory injections in the system prompt. Implement memory and context retrieval as visible tool calls so users can audit what the agent is doing. (6)
4. Sandboxing: Because the Act phase allows the execution of commands, your harness must enforce strict security boundaries (e.g., running actions inside Docker containers) to prevent an autonomous agent from accidentally deleting critical system files. (5)

Conclusion

An agent harness is much more than an API wrapper, it is the vital infrastructure that gives a language model the tools it needs. While leaks and teardowns of commercial tools like Claude Code give us a glimpse into high-end, proprietary architectures, the vast open-source community proves that custom, bespoke solutions are more accessible than ever. By mastering the Gather-Act-Verify loop and maintaining clean, transparent tool management, you can transform a simple text generator into an autonomous, specialized digital colleague.

Btw: There is also a very good video if you want to know more about harnesses from Langchain: https://www.youtube.com/watch?v=HI2q3ci3Iuc&t=409s

Sources

1. https://vrungta.substack.com/p/claude-code-architecture-reverse
2. https://michaellivs.com/blog/architecture-behind-claude-code
3. https://www.mindstudio.ai/blog/claude-code-source-leak-memory-architecture
4. https://github.com/RyanAlberts/best-of-Agent-Harnesses
5. https://resources.anthropic.com/building-effective-ai-agents
6. https://simonwillison.net/2025/Sep/18/agents/