Better Harness: Open-Source Five-Dimension Evaluation for Agent Loops

---

Why teams hit loop friction first

When coding-agent quality stalls, teams often reach for a newer model first. In practice, the same failures often come from the loop:

📑Table of Contents

1. Why teams hit loop friction first
2. What Better Harness Actually Reviews
3. Five Dimensions and How to Read Findings
4. Install Paths and Report Outputs by Host
5. Human-Approved Fixes, Not Auto-Repair
6. Should You Adopt? Decision Checklist
7. FAQ
8. Summary: What to Do Next

• Fuzzy goals
• Non-reproducible paths
• Weak validation
• Review bypass under speed pressure
• No durable lessons

What Better Harness contributes

Better Harness is an MIT open-source tool that reviews that loop—not only the final diff. It scores an Agent Work Loop across five dimensions, ties findings to evidence about the project harness, and starts human-approved fix plans instead of auto-applying repo edits. Host paths cover Claude Code, Codex, Qoder, and source-local Cursor.

---

What this article covers

This article covers the following in practical order:

• What the tool scores
• How to install it per host
• How to read findings
• A practical adopt/hold checklist

---

What Better Harness Actually Reviews

Bottom line

Better Harness is a diagnostic for agent harness and Work Loop gaps, not a model leaderboard. It maps how agents understand tasks, execute under control, validate changes, deliver reliably, and capture learning—with evidence, not config presence alone.

---

Why the loop matters

“Can do many things” is not the same as “safe enough to ship.” Qoder’s docs frame Loop/Harness Engineering as making understand → act → check → adjust trustworthy, including goals, forbidden boundaries, correctness checks, and failure handling (Qoder Docs).

---

Three open layers

1. Engineering practices — session evidence, project harness, agent customization, loop guidance
2. Evaluation model — Agent Work Loop, evidence states, findings, cross-cutting checks
3. Runnable implementation — /better-harness skill, collectors, analyzers, host adapters

Evidence is collected in three independent classes—agent customization, real task sessions, and project engineering foundations—then merged to reduce cross-contamination.

---

Snapshot table

Item	Detail
Class	Harness / Work Loop review + improvement kickoff
License	MIT
Runtime note	Node.js >= 22.20.0 for dev/pack paths
Dimensions	Task Understanding, Controlled Execution, Change Validation, Reliable Delivery, Learning Capture
Evidence rule	Config files alone do not prove capability; link to task evidence
Fix policy	No auto-apply; Plan a fix → human-approved Quest/plan
Hosts	Claude Code, Codex Desktop/CLI, Qoder, Cursor (source-local)
External report note	Independent press cites internal evaluation on ~30 real GitHub projects

---

Public sources and independent coverage

Sources: GitHub QoderAI/better-harness, Qoder Docs, IT Home coverage (as of July 2026).

Source

---

Takeaway

Read it as a loop quality diagnostic and fix launcher, not as a substitute for model evaluation articles.

---

Five Dimensions and How to Read Findings

Bottom line

Scores are gap reports tied to questions and supporting assets—not vibe ratings. Findings carry priority, cause, expected output, and scoped fix instructions a human can edit.

---

Dimension table

Dimension	Core question	Typical supporting assets
Task Understanding	Are goal and done defined?	Rules, AGENTS.md, specs, DESIGN.md
Controlled Execution	Is the path reproducible and permission-bound?	Skills, commands, MCP, sandbox
Change Validation	Is there proof the change works?	tests, lint, Hooks, diagnostics
Reliable Delivery	Does speed bypass review/acceptance?	human review, approvals, CI/CD, recovery
Learning Capture	Do lessons survive into the next task?	reusable Skills, Memory, Loop Discovery

---

Dimension sources

Sources: GitHub README, Qoder Docs (July 2026).

---

Finding payload

Typical card fields include:

• Priority: High / Medium / Low
• Cause
• Expected Output
• Editable Fix Instructions
• Plan a fix

---

Honesty rules from the README

• Unobserved items stay explicit—no invented scores
• Passing a static check is not proof an intervention ran
• Causal claims about loop improvement need comparable follow-up results

A common surprise: low scores despite “we have Rules/Skills files.” Presence is not the same as used-on-task evidence.

---

Install Paths and Report Outputs by Host

Bottom line

Marketplace vs plugin-dir steps differ by host. After install, start a fresh session so inventory reloads before you generate a report.

---

Shared prompt example

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

---

Claude Code

1. /plugin marketplace add QoderAI/better-harness
2. /plugin install better-harness@better-harness
3. Confirm skills via claude plugin details better-harness@better-harness
4. Generate the report in a new session

Default outputs land under .claude/better-harness as report.html, report.md, and findings.json.

---

Codex Desktop

Settings > Plugins > + Add > From Marketplace → https://github.com/QoderAI/better-harness.git (ref main) → invoke with @better-harness ....

---

Codex CLI

codex plugin marketplace add 'https://github.com/QoderAI/better-harness.git' --ref main
codex plugin add better-harness@better-harness
# e.g. $better-harness:better-harness review this project's AI coding workflow and generate a report

---

Qoder

Desktop ships built-in UI / /better-harness. CLI can add/install from marketplace. Reports center on Canvas.

---

Cursor

No marketplace listing in the 2026-07-29 README. Source-local only:

git clone https://github.com/QoderAI/better-harness.git
cursor-agent --plugin-dir /path/to/better-harness

---

Limits

• Cursor remains source-local
• Session evidence coverage varies by host; missing coverage should be explicit
• Qoder UI routes fixes through Quest—no silent repo rewrites

Sources: GitHub README, Qoder Docs.

---

Human-Approved Fixes, Not Auto-Repair

Bottom line

The product value is launching the smallest reviewable fix, not bulk auto-heal.

---

Qoder flow (docs)

1. Scan (first run includes project-structure understanding)
2. Five-dimension bars + finding cards
3. Plan a fix (cause / expected output / instructions)
4. Quest review → apply or roll back
5. Regenerate when needed

---

README improvement loop

Map → breakpoints → minimal vehicle (Rule / Skill / Hook / script / human gate) → fix & verify → re-run.

---

Practical next actions on one repo

1. Generate one report; read High findings only
2. Split “missing config” from “present but unused/unverified”
3. Ship one scoped repair through a human gate
4. Re-run on a similar task and check Validation / Learning Capture

Docs suggest regenerate after merged improvements, major structure changes, or a few weeks of drift.

---

Should You Adopt? Decision Checklist

Bottom line

Not mandatory for every team. It pays off when agents already touch near-production changes and the same loop frictions keep repeating.

---

Good fit

• Multi-host setups (Claude Code / Codex / Cursor) with scattered harness assets
• Thick Rules/Skills without evidence-linked validation, approval, or learning
• “We swapped models but quality is still unstable” debates that need harness isolation

---

Poor fit / hold

• Early trial use with thin session/project evidence
• Expectation of automatic mass fixes
• Cursor-only teams that refuse source-local plugins

---

Adjacent tools

Workspace multiplexers (for example wmux) optimize the execution workbench. Better Harness optimizes loop diagnosis and improvement tasking. Different layers—not substitutes.

---

Checklist

• ✓ Plugin or source-local install is allowed on the target host
• ✓ You picked one first repository
• ✓ High findings are labeled missing-config vs unused/unverified
• ✓ Team agrees to try exactly one human-gated fix
• ✓ You scheduled a re-scan after the fix or a structural change

Independent coverage (IT Home, Sina Tech, Sohu, and similar) corroborates multi-host support and evidence-first findings. Adoption still hinges on your findings, not discovery buzz.

---

FAQ

Q1. Is Better Harness a model benchmark?

No. It reviews coding-agent Work Loop / harness quality with evidence (README / Docs).

---

Q2. Will it rewrite the repo automatically?

Official docs say no auto-apply. Fixes go through Plan a fix and human-approved Quest/plans.

---

Q3. Claude Code only—or Codex and Cursor too?

README documents Claude Code, Codex Desktop/CLI, Qoder, and source-local Cursor, with host-specific report shapes.

---

Q4. Why low scores when config files exist?

Presence ≠ used-on-task evidence. Unused or unverified assets remain gaps.

---

Q5. How often should we rescan?

Docs recommend regenerate after merged improvements, major structure changes, or a few weeks—treat as operational guidance.

---

Q6. License and reuse?

MIT per README. Easy to fold into internal harness work; scrub secrets and internal paths before publishing findings.

---

Summary: What to Do Next

Better Harness is a diagnostic and fix launcher for reproducible agent loops, not a smarter-model switch.

1. Pick the install path for your host from the official README
2. Generate one repo report and keep High findings to three or fewer
3. Apply one human-approved fix; rescan Validation / Learning Capture
4. Promote what worked into Rules/Skills so Learning Capture is intentional

Start with GitHub: QoderAI/better-harness and Qoder Docs, then prove value on a single High finding under a human gate.

Related articles:

• 13626
• 13580
• 13621