Better Harness: turning coding-agent sessions into evidence-bounded findings

The workflow around the diff is the problem Better Harness targets

Coding agents change code quickly, and reviewing only the final diff hides the system-level problems the README lists: goals that were fuzzy from the start, steps nobody can reproduce, "it works" asserted without proof, delivery checks bypassed for speed, and lessons that do not carry to the next task. Better Harness is aimed at the workflow around the diff rather than the diff itself. It gathers project evidence, and session evidence where the host supports it, then evaluates five connected dimensions and turns concrete gaps into prioritized findings. Each finding is tied to its evidence, an expected outcome, a repair boundary and a validation route, so a team can work through one issue at a time instead of receiving a score with no next step.

The audience is narrow on purpose. This is for teams that have already delegated real work to a coding agent and want to improve the loop around it. It is not a linter, not a test runner, and not a code review tool. Its unit of analysis is the Agent Work Loop.

Feedforward guides, feedback sensors, and the five Agent Work Loop dimensions

The mechanism is a feedforward-and-feedback loop. Feedforward guides are the artifacts available before work starts: AGENTS.md, specs, Skills and acceptance criteria. Feedback sensors are the signals available after the agent acts: linters, tests, Hooks and evaluation agents that let the agent self-correct. Better Harness evaluates five dimensions across that loop.

Task Understanding asks whether the agent knows the goal and what "done" means, backed by rules, AGENTS.md, specs and DESIGN.md. Controlled Execution asks whether work happens on supported, repeatable paths, backed by Skills, commands, MCP tools and sandbox boundaries. Change Validation asks whether there is evidence the change works, backed by tests, lint, Hooks and observable diagnostics. Reliable Delivery asks whether AI speed bypasses quality checks or acceptance, backed by human review, approvals, CI/CD and recovery paths. Learning Capture asks whether the next task benefits from this one, backed by Loop Discovery, reusable SDLC Skills and Memory.

The design decision worth naming is the evidence boundary. The README states that Better Harness scopes behavior claims to relevant Task Episodes and the surrounding project mechanisms, and that missing or partial evidence remains explicit. That is a deliberate refusal to fill gaps with inference, and it shapes what a report can say. If your repository has no tests or no hooks, the report should say so rather than guess at validation quality.

Installing Better Harness for Codex, Claude Code or Cursor

The README is explicit that Better Harness does not use one universal entrypoint across every host. You choose the host you already use, and that host's section gives its exact installation, verification, invocation and report-output steps. The package is published as @qoder-ai/better-harness on npm, and the repository ships host plugin directories including .claude-plugin/, .codex-plugin/, .cursor-plugin/, .qoder-plugin/, .kimi-plugin/ and qwen-extension.json. Because the README shows inline setup only for the most common hosts and defers the rest to the installation guide and the Host Adapter Matrix, treat the host's own section as the source of truth rather than adapting another host's commands.

After installation, the invocation is the same shape across hosts. Running the slash command establishes a task-bounded baseline and produces a visual report, a Markdown report, or both, depending on the host.

/better-harness

What you should see is a report rather than a score. Findings carry an impact, an expected output, a scoped repair and acceptance checks. The README links a complete self-contained English HTML report as a sample, and notes that Qoder and Cursor produce host-native Canvas reports while Claude Code, Codex, Qwen Code, GitHub Copilot and Kimi Code produce self-contained HTML with paired Markdown. If your host is not in the inline sections, check the Host Adapter Matrix before assuming parity.

Reading the report and the Inspector without overclaiming

Two artifacts are worth separating. The report is the per-task output: prioritized findings, each bounded by the evidence that supports it. The Harness Inspector is a separate, read-only workspace that follows product intent through agent activity, sessions, files and commits, keeping evidence strength and limitations visible. The README states the published Inspector sample uses fictional English data and never reads your workspace, which is a useful property for evaluation but also a reminder that the sample demonstrates the interface, not your codebase.

The history view is where the README is most careful. Once you have comparable reports over time, it shows how the five dimensions move. The README describes the static final frame as summarizing historical Harness reports and states plainly that it shows recorded trends, not causal proof of improvement. That distinction matters when the report is used in a planning meeting. A rising Change Validation dimension means the recorded evidence changed, not that the underlying engineering improved. The same caution applies to the Inspector: evidence strength is displayed alongside the link, so a weak link stays visibly weak.

Where Better Harness is the wrong tool

The clearest limitation is host dependence. The README states there is no universal entrypoint, and output format differs by host: Canvas for Qoder and Cursor, self-contained HTML with paired Markdown for Claude Code, Codex, Qwen Code, GitHub Copilot and Kimi Code. A team standardizing on one report format across a mixed fleet will not get it without work. Additional hosts, including Qwen Code, Pi, Kimi Code, WorkBuddy and Grok, keep their steps and boundaries in the installation guide and the adapter matrix rather than the README, and the README notes that placement in the README is a display choice, not a support-level claim. So a host appearing in the README is not a stronger guarantee than one appearing only in the matrix.

Second, the tool is bounded by evidence. If your project has no specs, no tests, no hooks and no review records, the report has little to evaluate and will say so. That is honest, but it means Better Harness cannot substitute for building those mechanisms. Third, it is the wrong tool for a single small change. The five dimensions describe a work loop, and a one-line fix does not have one. Fourth, the version history is worth noting: the latest release listed is v0.7.0-alpha2 from 2026-09-12, an alpha, and the previous release was v0.4.1 on 2026-08-04. Version numbering that skips from 0.4 to 0.7.0-alpha2 suggests the surface is still moving, so pin a version rather than tracking the default. The last push to the repository was on 2026-09-17.

How Better Harness differs from LangChain and from agent-native review

The related searches include comparisons with LangChain, which is a different category of tool. LangChain is a framework for building applications on top of models: you write chains, tools and agents, and the framework provides the orchestration. Better Harness does not build an agent. It runs through an agent you already use, as a plugin under .claude-plugin/, .codex-plugin/, .cursor-plugin/ and similar directories, and its output is a report about the work loop rather than a runtime. If you need to construct an agent, Better Harness is not that. If you already have an agent and cannot tell whether the loop around it is working, the framework question is beside the point.

The closer comparison is with the agent's own review or summary features. Those typically summarize what the session did. Better Harness evaluates five named dimensions against project mechanisms and keeps missing evidence explicit instead of narrating. The difference is the artifact: a finding with an impact, an expected output, a scoped repair and acceptance checks, versus a session summary. Whether that extra structure is worth the host-specific setup is the real adoption question.

Licence, maintenance and the cost of upgrading

Better Harness is MIT licensed, per both the README badge and the license field in package.json. MIT is permissive, so the practical constraint is not redistribution but attribution and the absence of warranty, which is typical for this licence and worth confirming with your own counsel rather than treating as settled here. The package is published under the @qoder-ai scope and authored by Qoder, with the homepage pointing at the GitHub repository.

The upgrade cost is real because the project is a workspace, not a single script: package.json declares workspaces for packages/harness, packages/harness-studio, packages/harness-ui and packages/better-harness-desktop, and the published files list includes host plugin directories, hooks, models, prompts, references and scripts while excluding the Docusaurus site directories. A version bump can therefore change plugin manifests, hooks and prompts together. The repository carries a CHANGELOG.md, which is the file to read before moving versions. Given that the current release is an alpha and the previous one was a minor release three steps behind, pinning an exact version and reading the changelog between the two is cheaper than tracking main.

Editorial conclusion

Adopt Better Harness if your team already delegates multi-step work to Claude Code, Codex, Cursor or Qoder and cannot say why the same friction keeps returning; the five-dimension report is the artifact to inspect. Skip it if you want a single universal entrypoint: the README states there is none, and behavior claims are scoped to relevant Task Episodes. Verify first that your host appears in the Host Adapter Matrix and that you can accept the report format it produces, since Qoder and Cursor emit host-native Canvas while Claude Code, Codex, Qwen Code, GitHub Copilot and Kimi Code emit self-contained HTML with paired Markdown.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. QoderAI/better-harness on GitHub
4. README
5. Releases