Building a High-Performance Coding Agent in Under 1000 Lines of Python

In the current landscape of Large Language Model (LLM) development, the prevailing trend is towards complexity. Developers often reach for massive frameworks with orchestration graphs, sophisticated memory systems, and complex UI dashboards. However, the 'nano-harness' project proves that efficiency often lies in simplicity. By building a coding agent in approximately 970 non-blank lines of Python, we can achieve a score of 59.6% on the Terminal-Bench 2.0 suite—a result that rivals much larger, more complex systems.

This article explores the architecture of nano-harness, the philosophy of 'Score-per-Line-of-Code,' and how you can leverage high-speed LLM APIs from n1n.ai to build your own high-performance agents.

The Philosophy: Score-per-Line-of-Code

The core thesis of nano-harness is to create the smallest readable harness that still puts up a real number on a real benchmark. Inspired by minimalist projects like Andrej Karpathy's nanoGPT, this harness is designed to be read end-to-end in one sitting.

When building agents, the 'harness' is the part you can actually engineer. While the model provides the intelligence, the harness provides the environment, the constraints, and the reliability. For developers using n1n.ai, having a lightweight harness allows for faster iteration and lower latency when switching between models like Claude 3.5 Sonnet or GPT-4o.

Core Architecture: Five Files, Three Tools

The nano-harness consists of only five core Python files: agent.py, tools.py, providers.py, prompts.py, and cli.py. This minimalist structure relies on just three primary tools:

1. Bash: A persistent shell where the current working directory (CWD), environment variables, and state survive between calls.
2. Read File: A tool for line-numbered reads with slicing capabilities to manage context windows.
3. Edit File: A tool for exact unique-match string replacement, ensuring precision in code modifications.

By using a persistent Bash shell, the harness avoids the need for specific tools like ls, grep, or install. The model simply executes standard shell commands, making the system highly flexible.

Implementation: The Reliability Loop

A coding agent is only as good as its ability to stay 'alive' and 'honest.' In nano-harness, 'alive' means handling transient API failures and context window limits.

Here is a simplified look at the tool execution logic:

def execute_tool(tool_call, shell_state):
    try:
        if tool_call['name'] == "bash":
            # Execute in a persistent subprocess
            result = shell_state.run(tool_call['arguments']['command'])
            return {"status": "success", "output": result.stdout, "exit_code": result.returncode}
        # ... other tools
    except Exception as e:
        return {"status": "error", "message": str(e)}

'Honesty' is maintained through a Verify Gate. When the model signals it is 'done,' the harness challenges it: 'Re-read the task, run the relevant checks, and prove it.' A completion is only accepted if tool evidence (like passing tests) has appeared since the challenge. This prevents the model from hallucinating success.

Benchmarking Results on Terminal-Bench 2.0

Performance was measured using the Harbor framework across 89 tasks. Each task runs in its own Docker container to ensure isolation.

To achieve these results reliably, high-throughput API access is critical. Platforms like n1n.ai provide the necessary stability for long-running benchmarks, which can take upwards of 16 hours for a full suite.

The Importance of Adversarial Review

One of the most pivotal moments in the development of nano-harness was an adversarial code review by an independent frontier model. The review initially gave the code a 4/10, identifying a critical flaw: the Bash tool captured output but not the exit status. This meant the 'Verify Gate' could be satisfied by a failing test if the output looked 'clean.'

Key Fixes Applied After Review:

• Exit Status Mapping: Non-zero shell status now raises a tool error.
• Permission Preservation: The edit_file tool now preserves Linux file permissions (e.g., the executable bit).
• Context Truncation: Fixed a bug where tool arguments were silently re-inflated during serialization.

Pro Tips for Agent Developers

1. Failure is Information: Ensure your harness communicates failures clearly to the model. If a command fails, the model needs to see the error code, not just an empty output.
2. Stateless vs. Stateful: While stateless tools are easier to implement, stateful tools (like a persistent shell) allow models to perform complex, multi-step operations more naturally.
3. Cost Management: Benchmarking is expensive. A full 89-task run can consume over 3 million tokens. Using an aggregator like n1n.ai allows you to compare pricing across providers and find the most cost-effective route for your testing phase.
4. Escape MDX Syntax: When writing documentation or prompts for agents, remember to escape special characters. For example, use < for the less-than sign and wrap curly braces in code ticks: \{variable\}.

Why Minimalist Harnesses Matter

Large frameworks often hide the 'magic' behind layers of abstraction. By building from scratch, you understand exactly how the context window is managed, how tools are dispatched, and where the bottlenecks lie. Nano-harness proves that you don't need 10,000 lines of code to build a system that can solve real-world engineering tasks.

The harness's job is not to be smart—the model is smart. The harness's job is to keep the run alive and refuse to let anyone lie, including the model and the developer.

Ready to build your own agent? Start with a solid foundation and a high-performance API.

Get a free API key at n1n.ai