Skip to main content

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.

Prerequisites​

To use Better Harness from a host, install one of the supported coding agents below and make sure it can open the repository you want to analyze. The host's own system requirements and runtime still apply; follow its tab without running the repository's development setup unless the tab explicitly uses a source checkout.

Node.js and npm are required only when you use the standalone CLI, run Better Harness from a source checkout, or contribute to this repository. Those paths support Windows, macOS, and Linux and require:

  • Node.js >=22.20.0 <25.0.0
  • npm >=10.9.3 <12.0.0

Check the active runtime before using the standalone or source CLI:

node --version
npm --version

Inspect and plan lifecycle changes​

The standalone CLI exposes a read-only view of Better Harness installation evidence. It does not contact a registry, modify host configuration, or execute the steps in a lifecycle plan:

better-harness plugin status --host all
better-harness doctor --platform all
better-harness plugin plan install --host qwen --surface cli --scope user
better-harness plugin verify --host qwen --surface cli

Plans preserve host differences instead of inventing a common mutation path. Qoder Desktop is bundled, Codex Desktop returns manual UI steps, Cursor remains session-only while its native command contract is reconciled, Pi operations without current native evidence are manual or unavailable, and WorkBuddy has no managed plugin lifecycle surface. There is no plugin apply command.

Git can clone the Cursor manifest for inspection, but manifest presence alone does not establish a supported installation route.

Don't see your Coding Agent?

The six tabs below are the verified Quickstart paths, while the project tracks ten host adapters in total. Compare all adapter support boundaries, then follow the new-host contribution workflow and worked pull requests if you want to add or complete an integration. You can also browse current repository pull requests before starting overlapping work.

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 installation​

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 analyze and run the report prompt:

/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.

Next step​

Generate your first report. If installation or discovery fails, use the bounded checks in Troubleshooting.