Better Hands-On Guide: How to Review AI Coding Agent Workflows with Evidence

Reviewing Diffs is Not Enough: How to Evaluate AI Coding Agent Workflows

AI coding agents write code quickly, but the workflows surrounding them are often fragile. If you only review the final code diff, you miss systemic issues. Better Harness is an open-source tool that analyzes the workflow behind the changes, gathers project and session evidence, and translates specific gaps into prioritized improvements.

It focuses the analysis on a closed loop of feedforward guidance and feedback sensors. Feedforward guidance includes AGENTS.md, specs, and acceptance criteria. Feedback sensors include linters, tests, and evaluation agents. Within this loop, it evaluates performance across five dimensions.

  • Task Understanding checks if the agent knows the goal and the definition of done, supported by rules and specs.
  • Controlled Execution verifies if work follows a supported and repeatable path, supported by Skills and sandbox boundaries.
  • Change Validation confirms there is evidence that the changes work, supported by tests and linters.
  • Reliable Delivery checks if AI speed bypassed quality gates or acceptance, supported by human review and CI/CD.
  • Learning Capture determines if the next task can benefit from the current one, supported by reusable Skills.

Install Better Harness in Your Coding Agent (Host-Specific Steps and Pitfalls)

Different coding agents require different installation methods. You must install Better Harness separately for each host, except for Qoder CLI which uses the built-in Qoder Desktop version. Always start a new session after installing or updating a plugin so the host reloads its manifest.

Claude Code

Register the repository as a Marketplace and install the plugin directly.

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

Verify the discovery status in your shell.

claude plugin details better-harness@better-harness

The details must show Skills (1) better-harness. Start a new session in your target repository and run the report prompt /better-harness 分析此项目的 AI 编码工作流并生成基于证据的报告.

Reports generate in the .claude/better-harness directory by default, containing report.html, report.md, and findings.json. You can request inline output if you prefer not to generate files.

Codex (Desktop and CLI)

The Desktop version requires you to open Settings > Plugins and add from Marketplace. Use the Git repository URL https://github.com/QoderAI/better-harness.git and set the ref to main.

Codex add plugin Marketplace dialog with repository, Git ref, and optional sparse paths

The CLI version has a specific trap. You must pass the repository URL when adding the source, not the raw marketplace.json URL.

codex plugin marketplace add \
  'https://github.com/QoderAI/better-harness.git' \
  --ref main

Install the plugin using plugin add and --marketplace. Do not use plugin install or --source as those belong to a different CLI interface.

codex plugin list --marketplace better-harness
codex plugin add better-harness@better-harness

Cursor

There is a major pitfall here. The Cursor plugin is not published to a Marketplace, and the local Cursor help does not validate the historical --plugin-dir contract. Even if you clone the source, Better Harness marks the installation plan as unavailable and outputs no execution command.

Currently, you can only clone the source and attempt to generate a plan to check the status.

git clone https://github.com/QoderAI/better-harness.git
better-harness plugin plan install --host cursor --surface agent --scope session

Session evidence comes from workspace-matched session records and audit logs. Run better-harness plugin verify --host cursor --surface agent to validate. Incomplete or unavailable coverage is explicitly marked.

Qoder and GitHub Copilot

Qoder Desktop has Better Harness built in. Type /better-harness directly in your session. Qoder CLI works right away if you have Desktop installed. If not, you need to manually add a Marketplace source or clone from Git.

GitHub Copilot prefers Marketplace installation because the Copilot CLI deprecated direct installation from repositories or URLs.

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

Copilot session evidence comes from ~/.copilot/session-state/ records. Copilot does not log per-response token usage, and VS Code Copilot Chat lacks persistent session records. These are explicitly marked as evidence gaps.

What is Inside the Report After Running /better-harness?

Running the report command establishes a task-bounded baseline. The report does not score arbitrarily. It insists on truthful presentation. Unobserved behaviors are explicitly marked rather than turned into unsupported claims. A current passing check only proves an improvement was executed. Only subsequent comparable results prove the loop actually improved.

Each finding includes the impact, expected output, a scoped fix, and acceptance checks. You can click to view a self-contained HTML report example.

Better Harness HTML report showing an evidence-backed finding with impact, expected output, scoped AI fix, and acceptance checks

Open the full self-contained English HTML report
(source file).

If you need to track the delivery chain, the interactive Harness Inspector links product intent, agent activity, sessions, and commits in a read-only workspace while keeping evidence strength and limitations visible.

Harness Inspector session view: synchronized timeline of prompts, tool calls, and commits with an evidence drawer explaining each link

Open the interactive Harness Inspector example (uses fictional English data and does not read your workspace).

After accumulating multiple reports, the history view shows changes across the five dimensions. This image displays recorded trends and does not prove causation between improvements.

Static final frame of Better Harness report history showing changes in five dimensions of the agent work loop over time

Local Dev Environment to Modify Source or Build Locally

The development environment requires Node.js >=22.20.0 <25.0.0 and npm >=10.9.3 <12.0.0. It supports Windows, macOS, and Linux.

npm ci
npm test
npm run pack:verify

Build the Codex local plugin artifact using node scripts/packaging/build-host-plugin.mjs. Validated artifacts output to dist/plugins/better-harness.

If you want to check repository evidence without reading sessions, use node scripts/better-harness.mjs report --no-sessions. Running npm run preview -- --open in the source checkout directory provides a built-in test fixture. Canvas preview requires an installed Qoder runtime, or explicit --sdk-media or --sdk-root paths. The service listens on 127.0.0.1 by default. It is a local inspection tool, not a shared authenticated service.

Quick Action Checklist

  1. Check plugin status: better-harness plugin status --host all
  2. Generate install plan: better-harness plugin plan install --host <host> --surface <surface> --scope <scope>
  3. Install for Claude Code: /plugin marketplace add QoderAI/better-harness then /plugin install better-harness@better-harness
  4. Install for Codex CLI: codex plugin marketplace add 'https://github.com/QoderAI/better-harness.git' --ref main then codex plugin add better-harness@better-harness
  5. Generate report: Start a new session in your target repo and run /better-harness 分析此项目的 AI 编码工作流并生成基于证据的报告
  6. Verify local source: npm ci && npm test && npm run pack:verify

FAQ

Q: Does the Better Harness report give a score?
Unobserved behaviors are explicitly marked and are not converted into unsupported scores or claims. Only task-linked evidence proves a mechanism was used or improved an outcome.

Q: Why can’t I install the Cursor plugin directly?
The Cursor plugin is not published to a Marketplace, and the local Cursor help does not validate the historical --plugin-dir contract. Better Harness marks the installation plan as unavailable and outputs no execution command.

Q: What if I use plugin install for Codex CLI?
The current Codex version uses plugin add and --marketplace. Using plugin install or --source targets a different CLI interface.

Q: Where do the reports generate?
Claude Code generates report.html, report.md, and findings.json in the .claude/better-harness directory by default. Other hosts like Qoder and Cursor generate native Canvas reports.

Q: Can GitHub Copilot CLI install directly from a repository URL?
Avoid this method. The Copilot CLI deprecated direct installation from repositories, URLs, or local paths. Use Marketplace installation.

Q: Do I need to understand the entire runtime to contribute?
No. You can start with the smallest scope matching your improvement goal, such as adding workflow guidance in skills/ or a report mode in templates/reporting/.

Q: What is required to preview Canvas reports locally?
Canvas preview requires an installed Qoder runtime, or explicit --sdk-media or --sdk-root paths.