better-harness

Better Harness

English · 简体中文

Delegate coding to agents. Improve the loop around them.

Better Harness provides open-source insights for the Agent Work Loop. It runs through your Coding Agent and turns project and session evidence into prioritized improvements and verifiable next steps. Missing evidence stays explicit.

Website · Choose your host · Sample report · Docs

## Quick start Analyze and improve your coding workflow with: [Claude Code](#claude-code), [Codex Desktop](#codex-desktop), [Codex CLI](#codex-cli), [Qoder Desktop/CLI](#qoder), [Cursor](#cursor), or [GitHub Copilot CLI](#github-copilot). Choose the host you already use to get its exact installation, verification, invocation, and report-output steps. Better Harness does not use one universal entrypoint across every host. This README shows inline setup for the most common hosts. Additional supported hosts (Qwen Code, Pi, Kimi Code, WorkBuddy, and Grok) keep their steps and boundaries in the [installation guide](docs/docs/installation.mdx) and the [public Host Adapter Matrix](docs/docs/hosts/adapter-matrix.md); see [More adapters](#more-adapters). README placement is a display choice, not a support-level claim. Better Harness scopes behavior claims to relevant Task Episodes and the surrounding project mechanisms. Qoder and Cursor produce host-native Canvas reports; Claude Code, Codex, Qwen Code, GitHub Copilot, and Kimi Code produce self-contained HTML with paired Markdown. Missing or partial evidence remains explicit. See the [Host Adapter Matrix](docs/adapters/README.md) for current coverage and output differences. ## See it in action The report keeps missing evidence explicit and turns supported gaps into prioritized findings with an impact, expected output, scoped repair, and acceptance checks.

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

For delivery tracing, the interactive [Harness Inspector](https://qoderai.github.io/better-harness/inspector) follows product intent through agent activity, sessions, files, and commits in a read-only workspace, keeping evidence strength and limitations visible:

Open the interactive Harness Inspector sample (fictional English data; it never reads your workspace).

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

The static final frame summarizes historical Harness reports. It shows recorded trends, not causal proof of improvement. [See how the demo was recorded](dev/terminal-demo/README.md). ## 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 analyzes the workflow around the diff: 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](https://martinfowler.com/articles/harness-engineering.html#FeedforwardandFeedback) 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 evaluation agents observe results and help the agent self-correct. Across that loop, it evaluates five parts of delivery — the **Agent Work Loop**: | Dimension | The question it answers | Backed by | | --- | --- | --- | | **Task Understanding** | Does the agent know the goal and what "done" means? | Rules, `AGENTS.md`, specs, `DESIGN.md` | | **Controlled Execution** | Is the work on supported, repeatable paths? | Skills, commands, MCP tools, sandbox boundaries | | **Change Validation** | Is there evidence the change actually works? | Tests, lint, Hooks, observable diagnostics | | **Reliable Delivery** | Does AI speed bypass quality checks or acceptance? | Human review, approvals, CI/CD, recovery paths | | **Learning Capture** | Does the next task benefit from this one? | Loop Discovery, reusable SDLC Skills, Memory | 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](references/README.md). - **Evaluation model** — the task-centered [Agent Work Loop](models/agent-work-loop.md), including evidence states, findings, scoring boundaries, and longitudinal validation. - **Runnable implementation** — the canonical [`/better-harness` workflow](skills/better-harness/SKILL.md), evidence collectors, analyzers, renderers, and thin [host adapters](docs/adapters/README.md). 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. ## 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: ```text /plugin marketplace add QoderAI/better-harness ``` Then install Better Harness: ```text /plugin install better-harness@better-harness ``` Verify discovery from the shell: ```bash 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 analyze and run the report prompt: ```text /better-harness analyze this project's AI coding workflow and generate an evidence-backed 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 analyze and run the report prompt: ```text @better-harness analyze this project's AI coding workflow and generate an evidence-backed report ``` Use `https://github.com/QoderAI/better-harness.git` with Git ref `main`. #### Codex CLI Add the repository source: ```bash codex plugin marketplace add \ 'https://github.com/QoderAI/better-harness.git' \ --ref main ``` Then inspect and install Better Harness: ```bash codex plugin list --marketplace better-harness codex plugin add better-harness@better-harness ``` Start a new Codex task in the repository you want to analyze and run the report prompt: ```text $better-harness:better-harness analyze this project's AI coding workflow and generate an evidence-backed report ``` Use the repository URL with `marketplace add`, not a raw `marketplace.json` URL. Current Codex builds use `plugin add` and `--marketplace`; examples that use `plugin install` or `--source` target a different CLI contract. ### Qoder Better Harness is built into the [Qoder](https://qoder.com/) desktop app, so no Marketplace or local plugin installation is required there. Choose either entry point: 1. **From a session:** Open the repository you want to analyze, start a new session, and run the report prompt: ```text /better-harness analyze this project's AI coding workflow and generate an evidence-backed report ``` 2. **From Quest (Qoder 1.18.0+):** Open Quest, then select **Better Harness (Beta)** from the left sidebar. #### Qoder CLI If Qoder Desktop is installed, Better Harness is already available in Qoder CLI. No marketplace or plugin installation is required. Start a new Qoder CLI session in the repository you want to analyze and run the report prompt: ```text /better-harness analyze this project's AI coding workflow and generate an evidence-backed report ``` Only when using Qoder CLI without Qoder Desktop, inspect the current manual installation disposition before following: ##### From marketplace ```bash # Add the plugin marketplace source qodercli plugin marketplace add 'https://github.com/QoderAI/better-harness.git' # Install the plugin qodercli plugin install better-harness@better-harness # Check installation qodercli plugin list ``` ##### From git ```bash # Make sure directory exist mkdir -p $HOME/.qoder/plugins/marketplaces/ git clone https://github.com/QoderAI/better-harness.git \ $HOME/.qoder/plugins/marketplaces/better-harness --depth 1 qodercli plugin install $HOME/.qoder/plugins/marketplaces/better-harness ``` Replace `.qoder` to `.qoder-cn` in urls for Qoder CN series. Then start a new Qoder CLI session before using `/better-harness`. ### Cursor The Cursor plugin is not published to the marketplace. The repository carries the source-local manifest, but the current local Cursor help does not verify the historical `--plugin-dir` contract. Better Harness