A developer's open-source blueprint for coding agents that fix their own mistakes

Why demo agents fall over

As dev.to reported, developer Wang Guo has published a tutorial and open-source code for what he calls a harness: the wrapper that runs a coding agent, checks what it did, and decides what happens next. His argument is that the AI model sets the ceiling on what is possible, while the harness sets the floor on how reliable the result is.

He describes three ways agents fail once they meet a large, older codebase, which he puts at 50,000+ lines. The first is what he calls the Optimistic Surrender. The agent edits a file, never compiles or tests it, and announces that the bug is fixed.

The second is context blow-up. After several rounds of error messages, the raw output can take up 40,000 tokens (the chunks of text a model reads), and the original task gets pushed out of the model's working memory. The third is unsafe tool use: an agent with shell access might run a destructive command or print a secret key into a log.

A loop built to converge

The guide argues that a serious coding agent cannot be a bare loop of 'ask the model, run the tool, repeat'. Instead it lays out a nine-step cycle, from taking the user's request to a human approving the final release. Five guarantees carry most of the weight.

• Isolation. The agent works in a separate Git worktree (a throwaway copy of the project folder) or a temporary container, never on the main branch.
• Pre-checks. Before a command runs, the harness inspects it with an AST validator (a tool that reads the structure of code rather than just its text). Commands like rm, dd and drop table are blocked, which the author says takes under 1ms.
• Forced verification. The agent cannot declare victory until the tests, run with pytest or Maven, return exit code 0.
• Filtered failures. A failed test does not dump everything into the prompt. The harness extracts the failed check, the line number and the diff, and feeds back only that.
• A retry cap. If the loop has not converged after 4 attempts, it stops and escalates instead of burning tokens.

After each step, a masking pass hides secrets, and a person signs off at the end.

Keeping the agent's memory small

The most concrete idea is a two-stage compression scheme the author calls /compact. In stage one, once the agent has read and acted on a test result or file, the bulky text is deleted and replaced by a one-line note, such as how many bytes were removed and which assertion failed.

In stage two, when the prompt reaches 75% of the model's capacity, the harness writes a short structured checkpoint. It records the goal, the decisions already made (such as which files were changed), the current blocker and the next step.

The author says this cuts token use by over 85% and lets agents run through 20+ iterations without degrading. Those are his own figures from his own project, and the post gives no independent benchmark, so treat them as a claim to test.

Where MCP fits in

MCP, the Model Context Protocol, is a standard way for AI assistants to plug into tools and data. The author says it spares developers from writing custom glue code for each model vendor, and he lists Anthropic, OpenAI, DeepSeek and local Ollama as the ones his project supports.

His implementation covers three basic calls over JSON-RPC 2.0, a common message format. One call sets up the connection, one lists available tools, and one runs a tool with strict time limits. The tool list is revealed in three tiers, starting with short descriptions and only later full details, so hundreds of internal services do not crowd the model's prompt.

What you get, and what to keep in mind

The repository offers two versions under the MIT license, a permissive open-source license. One is a Java 17 and Spring Boot 3.3 app with a visual web interface, approval gates for humans, and a simulation mode that needs no API key. The other is a Python 3.9+ library with no outside dependencies, which the author says shows 8 core harness patterns in a form you can read in five minutes.

This is a self-published post by one developer, and we have not run the code or checked the numbers. Our reasoning: anything that lets an agent run commands should first be tried on a throwaway project, with a hard limit on retries and a clear list of what the agent may touch. The design here is built around those same limits.