/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/orscripts/, 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.