/better-harness Goes Open Source

Last week, we built Better Harness into Qoder Desktop. After launch, many users asked the same question: Will this be open source?

In its first three days, 100,000 people tried Better Harness.

The answer is yes.

Today, Better Harness is officially open source. You can find the project at github.com/QoderAI/better-harness.

Better Harness is an open-source analysis and continuous-improvement tool for coding-agent workflows. It connects the engineering practices, evaluation model, and runtime capabilities of Harness Engineering and Loop Engineering. The initial open-source release supported Claude Code, Codex, Qoder, and Cursor with one shared judgment model, although session analysis, evidence coverage, and output capabilities were not yet identical across the four hosts. Qoder, which had already been exercised repeatedly in real development workflows, was the most complete reference implementation at launch.

Launch host	Installation or loading path	Default output
Claude Code	Add the repository marketplace, then install the plugin	HTML + Markdown
Codex	Install through a Git marketplace	HTML + Markdown
Qoder Desktop	Built in; no separate installation	Canvas
Cursor Agent	Load from source	HTML / Markdown

Editor's note: This table records the launch state. Better Harness now publishes additional host integrations, and entrypoints differ by host. See the current Installation guide before installing or running a review.

At launch, the shared workflow was commonly invoked as:

/better-harness

You could start the analysis, inspect the report as it ran, and continue reading this article. When a category of evidence was unavailable, Better Harness preserved that boundary in the result instead of substituting config counts or data from another host.

Better Harness cares about what the agent did in the task

Imagine that an agent modifies a module, runs one test command, and declares the task complete. The real question is not whether the repository has tests. It is whether that test was relevant to the change, covered the main risks, and produced enough evidence to support delivery.

Better Harness therefore does not treat the presence of AGENTS.md, Rules, Skills, MCP servers, Hooks, memories, tests, or CI as proof that they influenced the task. Every improvement item—a Finding—must include traceable evidence, a specific user impact, the smallest repair boundary, and a way to verify the result after the repair.

In one self-analysis snapshot produced from Codex, Better Harness did not turn the absence of an executed Codex host test into the stronger claim that “Codex has failed.” It kept the unexecuted host test as an explicit evidence boundary. Scores can help locate a problem, but the conclusion, impact, repair scope, and verification method are what matter.

That is the difference between Better Harness and a configuration checklist. A checklist tells you what the project possesses. Better Harness asks whether those capabilities actually helped the agent complete a trustworthy task.

And if the judgments in a report are meant to be inspected, changed, and reverified, open source cannot stop at publishing an executable entrypoint.

The three-layer open-source system behind Better Harness

Publishing the /better-harness prompt on GitHub would technically qualify as open source. But for a coding agent, no single prompt determines the result. What matters is the full working method behind it: what is worth checking, what counts as evidence, how judgments are formed, and how they can keep running and changing in real projects.

That is why Better Harness opens three connected layers.

Layer 1: Harness Engineering best practices

This layer answers a practical question: when we examine sessions, CLIs, observability, Rules, Skills, MCP servers, memories, Hooks, and automation, what should we check—and which conclusions cannot be drawn merely from the presence of configuration?

The knowledge is organized by problem domain under references/:

Domain	Question it answers	Main evidence
Session Evidence	How did the agent actually complete the task?	Sessions, task episodes, tool calls, retries, usage, and outcome evidence
Project Harness	Does the project provide reliable execution, verification, and delivery paths?	CLI, observability, design contracts, tests, Git Hooks, sensitive code, and recovery mechanisms
Agent Customize	Are agent assets discoverable, applicable, and actually useful?	Rules, Skills, MCP, memories, Hooks, Custom Agents, and host configuration
Loop Engineering	Which mechanism should own a confirmed repeated workflow?	Skills, Hooks, scripts, automation, Rules, Custom Agents, MCP, and related mechanisms

Better Harness does not load one endlessly expanding master prompt on every run. It reads the judgment criteria for the problem at hand. A diagnostic issue routes to observability practices. A Skill issue routes to Skill Review. A repeated workflow first triggers a decision about whether a Skill, Hook, script, or automation should own it over time.

Layer 2: the Agent Work Loop evaluation model

This layer turns engineering practices into questions that can be checked one by one, while constraining the relationship between evidence, scores, and conclusions. The current model and evidence states are public in the Agent Work Loop model.

Because the standard is still emerging, we did not want one model to define a “good harness” subjectively. The first internal evaluation selected 30 real GitHub projects. Four model families independently evaluated them using OpenAI's Harness Engineering article as a starting point, producing 120 standardized reports. Cross-model comparison and human calibration then clarified evidence requirements, judgment boundaries, and differences between project types before every project was evaluated again under the updated criteria.

This loop—automated evaluation, automated aggregation, human calibration, and automated reruns—produced the first reproducible Harness Engineering evaluation model that we could continue to adjust.

The first version still resembled a conventional software-engineering maturity scan. It focused on whether a project had documentation, tests, CI, and safety mechanisms. We soon learned that static assets cannot prove that an agent actually completed a task.

Better Harness itself is developed through a spec-driven process so that changes in the model and product capabilities remain traceable. As more than 200 specs accumulated, the model shifted from asking “What exists in the repository?” to asking “What actually happened in the task?”

The evaluation target narrowed from a repository or a session to a concrete task. A session stopped being the thing being evaluated and became a container for evidence. The model then stabilized around five dimensions: task understanding, controlled execution, change verification, reliable delivery, and experience capture. File existence, config counts, temporal proximity, and even a successful command can no longer be treated as direct proof that a capability was effective.

The Agent Work Loop is therefore not a static scorecard. It is a judgment system centered on real tasks, designed to be reproduced and continuously calibrated.

Layer 3: a runnable engineering implementation

The third layer makes the practices and model repeatable in real projects. Better Harness starts an analysis through a plugin or CLI—the JavaScript code under the project's scripts/ directory—freezes the task scope, and collects three evidence lanes independently:

• Session Evidence reconstructs the agent's behavior in real tasks.
• Project Harness checks whether the project can be started, diagnosed, verified, and recovered.
• Agent Customize checks the configuration, routing, and usage evidence for Rules, Skills, MCP servers, memories, and Hooks.

The lanes remain separate during collection and analysis. Only then does the Lead reconcile them using the criteria in references/ and the Agent Work Loop model. “The project has this capability” and “the agent used this capability in the task” remain two different facts.

The output is not just a score. It is a set of Findings with evidence boundaries, user impact, repair scope, and verification methods. Once rendered and validated, the report can enter a repair flow. If the analysis finds stable repeated work, Loop Engineering determines whether a Skill, Hook, script, automation, or another mechanism should own it over time.

Completing a repair still does not prove that the workflow improved. The loop is closed only when a later task of the same kind produces a better observed result.

Start with the first verifiable problem

For Qoder users

At the time of the announcement, Qoder Desktop included Better Harness in the Quest view as Better Harness (Beta) and exposed /better-harness directly. Qoder CLI and the JetBrains plugin could use the same capability on a machine where Qoder Desktop had already been installed. Refer to the current Installation guide for today's supported Qoder entrypoints.

From the open-source repository

Visit the Better Harness GitHub repository and follow the current README or Installation guide. For example, Claude Code users can run:

/plugin marketplace add QoderAI/better-harness
/plugin install better-harness@better-harness

Then start a review with:

/better-harness Analyze my project's harness and generate an HTML report

Your first Better Harness run does not need to build a complete agent engineering system, and it does not need to chase a perfect score. A more practical starting point is one problem with clear evidence, a concrete impact, and a fast verification path.

It might be a check command the agent cannot find, an error log with no useful next diagnostic step, or a Skill that exists but has never entered the task routing path.

Fix one problem, run the review again, and observe whether a later task of the same kind changes. Harness Engineering is not a one-time configuration project. It is the continuous work of making a project easier for an agent to understand, execute, and verify.

We know it is not complete

Better Harness has been run and calibrated repeatedly in Qoder's real development workflows, but the current model still reflects the project types and task scenarios we know best.

Different technology stacks, project sizes, team constraints, and coding agents may reveal blind spots. Better Harness needs more real evidence to keep correcting them.

If you would like to contribute, there are several useful starting points:

• Add an engineering practice. Add a judgment guide for a language, framework, or common workflow under references/. No code is required.
• Add an evaluation perspective. Add an evidence-backed dimension or detector under models/ or scripts/, together with fixtures and tests.
• Add host support. Complete evidence collection and verification for another coding agent. The repository Roadmap lists candidate work.
• Add a real case study. Contribute a redacted team example under case-studies/.

If you disagree with a Finding, please open an issue. A counterexample from a real project is more useful to us than a star—although we will happily accept the star too. 😁

---

Born in Qoder, returned to the community. Give every coding agent a foundation of verified engineering practice.