better-harness

See it in action

Ask /better-harness to review the current task and its surrounding project Harness, then generate a durable report:

/better-harness review this project's AI coding workflow and generate a report

The report keeps missing evidence explicit and turns supported gaps into prioritized findings with an impact, expected output, scoped repair, and acceptance checks.

After you have comparable reports over time, the history view shows how the five Agent Work Loop dimensions move:

The animation replays historical Harness reports. It shows recorded trends, not causal proof of improvement. See how the demo was recorded.

Why Better Harness?

AI coding agents change code fast, but the workflow around them is often the weak point:

• 🎯 Fuzzy goals — the agent confidently solves the wrong problem.
• 🧭 Improvised steps — work happens on paths nobody can reproduce.
• ✅ "It works" without proof — validation is incomplete or missing.
• 🚢 Speed over safeguards — review and delivery checks get bypassed.
• 🧠 Lessons lost — the same friction comes back on the next task.

Reviewing only the final diff misses these system-level problems. Better Harness reviews the workflow itself: it gathers project evidence (and session evidence where supported), evaluates five connected dimensions, and turns concrete gaps into prioritized findings — each tied to its evidence, expected outcome, repair boundary, and validation route, so a team can improve one issue at a time.

How Better Harness works

Better Harness uses a feedforward-and-feedback loop that combines guidance available before work starts with signals available after the agent acts:

• Feedforward guides — AGENTS.md, specs, Skills, and acceptance criteria steer the agent before it acts.
• Feedback sensors — linters, tests, Hooks, and review agents observe results and help the agent self-correct.

Across that loop, it evaluates five parts of delivery — the Agent Work Loop:

Running /better-harness establishes a task-bounded baseline and, depending on the host, produces a visual report, a Markdown report, or both. The report combines the five-part overview, prioritized findings, detected agent assets, and an evidence brief. Each finding includes a repair action that drafts a scoped fix plan for review.

Better Harness is deliberately honest: unobserved behavior stays explicit instead of becoming an unsupported score or claim. Passing a current check proves that the intervention was exercised; only a comparable later result can prove that the loop improved.

What is open

Better Harness opens three connected layers, not only a slash-command prompt:

• Engineering practices — evidence and judgment guidance across Session Evidence, Project Harness, Agent Customize, and Loop Engineering.
• Evaluation model — the task-centered Agent Work Loop, including evidence states, findings, scoring boundaries, and longitudinal validation.
• Runnable implementation — the canonical /better-harness workflow, evidence collectors, analyzers, renderers, and thin host adapters.

The three layers share the same boundary: configured assets can establish that a mechanism exists, but only linked task evidence can establish that it was used or improved an outcome.

Architecture

The architecture keeps the three evidence domains independent until unified analysis by the lead agent. Every result retains a visible evidence source, owner, and validation route.

Quick start

Pick your coding agent — you can be looking at your first report in minutes:

Once installed, ask Better Harness to generate the host's durable report:

/better-harness review this project's AI coding workflow and generate a report

Better Harness scopes behavior claims to relevant Task Episodes and the surrounding project mechanisms. Qoder produces a Canvas report; Claude Code, Codex, and Cursor produce self-contained HTML with paired Markdown. Missing or partial evidence remains explicit. See the Host Adapter Matrix for current coverage and output differences.

Installation

Installation differs by coding agent. Install Better Harness separately for each host, except that Qoder CLI can use the version bundled with Qoder Desktop. After installing or updating a plugin, start a new session or task so the host reloads its plugin inventory.

Claude Code

Register this repository as a Claude Code marketplace:

/plugin marketplace add QoderAI/better-harness

Then install Better Harness:

/plugin install better-harness@better-harness

Verify discovery from the shell:

claude plugin details better-harness@better-harness

The details should include Skills (1) better-harness. Then start a new Claude session in the repository you want to review and run the report prompt:

/better-harness review this project's AI coding workflow and generate a report

Claude Code defaults to a self-contained report.html with paired report.md and findings.json under the repository's .claude/better-harness report root. Ask for inline or no-files output to keep the result in chat only. Workspace- matching local Claude sessions are included when available; missing evidence stays explicit rather than being inferred.

Codex

Codex Desktop

1. Open Settings > Plugins.
2. Select + Add > From Marketplace.
3. Enter the Git repository URL, set its Git ref, and leave Sparse paths empty for this single-plugin repository.
4. Select Add marketplace, then install Better Harness from the new marketplace.
5. Start a new task in the repository you want to review and use the report prompt from Quick start.

Use https://github.com/QoderAI/better-harness.git with Git ref main.

Codex CLI

Add the repository source:

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

Then inspect and install Better Harness:

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