QoderAI/better-harness

Better Harness – a coach for AI coding agents

What it does

• When you use an AI‑powered coding assistant (Claude Code, Codex, Cursor, GitHub Copilot, Qoder, etc.), Better Harness watches the whole work loop: the task description, the commands the agent runs, the files it changes, the tests or linters that run, and the final review steps.
• It gathers whatever evidence the host can provide (project files, session transcripts, CI logs, etc.) and evaluates the workflow against five dimensions:
  1. Task Understanding – does the agent know the goal and the definition of “done”?
  2. Controlled Execution – are the steps repeatable and bounded by defined tools?
  3. Change Validation – is there concrete proof (tests, lint, diagnostics) that the change works?
  4. Reliable Delivery – are quality‑gate checks like review or CI still applied?
  5. Learning Capture – does the next task benefit from what was learned?
• Missing evidence is shown explicitly instead of being guessed. Where gaps exist, Better Harness creates prioritized findings that include:
  • the impact of the gap,
  • an expected outcome,
  • a scoped repair plan (a short‑hand “AI fix”), and
  • acceptance checks the team can run.
• The output is a self‑contained HTML report (with paired Markdown and JSON) that visualises the findings, the evidence sources, and a timeline of prompts, tool calls, and commits.

How you use it

• Install the plugin for the coding agent you already use (Claude Code, Codex Desktop/CLI, Qoder Desktop/CLI, Cursor, GitHub Copilot CLI, etc.). The README provides host‑specific install commands; there is no single universal entry point.
• In a new session on the repository you want to analyse, run the slash‑command:

  /better-harness analyze this project's AI coding workflow and generate an evidence‑backed report
  

• The host creates a report.html (plus report.md and findings.json) in a host‑specific folder. You can open the HTML to explore the findings or view the Markdown for a quick summary.
• A separate CLI (better-harness plugin status …, better-harness doctor …) lets you inspect the plugin’s installation state across all supported hosts without touching the host UI.

Why it matters

• AI coding agents can produce code fast, but teams often lose track of how the code was produced. Goals may be vague, steps improvised, validation incomplete, and lessons forgotten. Better Harness makes those hidden parts visible, turning vague friction into concrete, actionable improvement items.
• By keeping evidence explicit, the tool avoids over‑optimistic scores and gives teams a clear path to tighten their development process while still benefiting from AI speed.

Who it’s for

• Teams that already use an AI coding assistant and want to audit and improve the surrounding workflow.
• Engineering managers looking for a systematic way to capture the quality and repeatability of AI‑generated changes.
• Developers who want a visual, evidence‑backed report of what their AI agent actually did during a task.

Project health

• Published as an npm package (@qoder-ai/better-harness) and licensed MIT.
• Supports a growing list of hosts (Claude Code, Codex, Qoder, Cursor, GitHub Copilot, plus Qwen Code, Pi, Kimi Code, WorkBuddy, Grok).
• Development requires Node 22+ and includes tests, packaging scripts, and a preview server.
• Contribution guide encourages adding new host adapters, evaluation models, or workflow guidance.

Bottom line Better Harness is an open‑source “coach” that watches AI coding agents, records what they actually do, and turns gaps in evidence into concrete, prioritized improvement steps. It helps teams keep the speed of AI while regaining control, repeatability, and learning from each task.