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.

DeepSeek Harness verified discovery (not Quickstart)​

DeepSeek Harness (DSH) has a bounded Verified install/discovery route for the qualified DSH 0.1.1-rc.2 contract. This is not a public Quickstart or a complete report loop.

Start from a complete Better Harness source checkout or npm package directory. Call its absolute directory <BETTER_HARNESS_ROOT> below. It must contain skills/better-harness/SKILL.md, scripts/better-harness.mjs, references/, models/, and templates/.

Headless/base​

In the active headless profile's cordis.patch.yml, configure the existing global Skill filesystem row and insert the Better Harness DSH policy:

- id: skill-filesystem
  config:
    customSkillDirs:
      - /absolute/path/to/better-harness/skills

- insert:
    - id: better-harness-explicit-only
      name: /absolute/path/to/better-harness/scripts/dsh-skill-discovery/index.mjs
      config:
        betterHarnessRoot: /absolute/path/to/better-harness

The profile file is normally $DSH_HOME/profiles/headless/cordis.patch.yml. Replace every example with the same real absolute root before starting a new session.

Web standard, code, or cordis​

The Web host owns Skill discovery inside the selected agent preset. In Web's Agent Presets settings, copy standard, code, or cordis to a user preset. Edit that copy's active skill-filesystem row in $DSH_HOME/.agent-presets/<your-preset>/agent.cordis.yml:

- id: skill-filesystem
  name: '@deepseek-ai/dsh-skill-filesystem'
  config:
    customSkillDirs:
      - /absolute/path/to/better-harness/skills

Then insert the same better-harness-explicit-only policy row shown above in $DSH_HOME/profiles/web/cordis.patch.yml, select the copied user preset, and start a new session. Editing only the global Web skill-filesystem row is not the qualified route. Web minimal does not mount the Skill loader and remains unsupported.

Verify the boundary​

Enter the gesture directly as the user:

/better-harness

DSH must inject the canonical Skill before model request derivation. The local policy checks DSH's winning source, path, directory resource base, complete-root invariant, and required root resources. It rejects a higher-precedence project-local same-name Skill and rejects model-facing skill({ name: "better-harness" }) calls.

Use an absolute path on macOS, Linux, and Windows, including when it contains spaces or Unicode. DSH resolves relative customSkillDirs from its process working directory and does not expand a literal ~. Do not install a standalone Skill copy or use a symlink/junction as the canonical route. If the complete Better Harness root moves, update both the customSkillDirs value and policy plugin path/configuration. Repository contributors can repeat the pinned, credential-free native proof with npm run test:dsh-native.

Inventory configured assets​

The independent developer-preview configured-assets provider reports native filesystem Skill winners and cwd-sensitive Instruction sources as configured-not-observed evidence:

better-harness agent-customize inventory --provider dsh --workspace <path> [--cwd <path>] [--dsh-home <path>] [--include-user-home[=true]]

The default excludes user-home DSH and Agents roots. Add --include-user-home only when those sources are intentionally in scope. Runtime/in-process Skills and active Cordis, Profile, and Preset composition remain unresolved, so the inventory does not prove that any asset was used. Repository contributors can repeat the pinned, credential-free native comparison with npm run test:dsh-configured-assets-native. The complete configured-assets boundary is documented in the adapter matrix.

Shared read-only analysis is available through harness evidence-bundle and harness analyze; pass --workspace <path> --cwd <effective-cwd> --platform dsh. The configured cwd must resolve inside the workspace. DSH still does not provide complete runtime configured-asset resolution, output routing, rendering, Checkup, lifecycle management, MCP/profile product support, Web minimal, a public Quickstart, or a full durable report workflow. The adapter matrix tracks the exact boundary.

Don't see your Coding Agent?

The six tabs below are the verified Quickstart paths, while the project tracks ten fuller host adapters plus bounded DSH capabilities. 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.