README.md

Host Adapter Matrix

This is the single entry point for Claude Code, Codex, Qoder, Cursor, Qwen, GitHub Copilot, Pi, Kimi Code, WorkBuddy, and Grok host boundaries. Do not create docs/adapters/claude-code.md, docs/adapters/codex.md, docs/adapters/qoder.md, docs/adapters/cursor.md, docs/adapters/qwen.md, docs/adapters/copilot.md, docs/adapters/pi.md, docs/adapters/kimi-code.md, docs/adapters/workbuddy.md, or docs/adapters/grok.md by default.

Adding another host? Follow Contributing a New Coding Agent Host before editing the matrix. The guide separates shell, configured-asset, session, output, and packaging claims and links reviewed Qwen Code and GitHub Copilot pull requests as worked examples.

Host differences enter only this matrix, capability-local configured-asset providers, real session-evidence adapters, and output modes. Canonical product judgment stays in skills/, models/, references/, templates/, and scripts/<capability>/.

The @qoder-ai/better-harness npm package includes seven filesystem metadata roots for Qoder, Claude Code, Codex, Cursor, Qwen, Copilot, and Kimi Code, plus Pi install metadata in the existing package.json. The generated Qoder runtime bundle includes only the Qoder shell, .qoder-plugin/; non-Qoder generated host artifacts remain source-local. Claude Code installs its shell through the repository's native marketplace manifest. Pi installs the repository as a pi package through the pi manifest in package.json. Kimi Code installs the repository as a plugin through the .kimi-plugin/plugin.json manifest with /plugins install <source> (or a manual skills/better-harness copy/symlink into ~/.kimi-code/skills/ or a project .kimi-code/skills/), then runs /skill:better-harness.

Host	Positioning	Shell	Configured Assets	Session Evidence	Default Output	Rules / Prompts	Smoke
Claude Code	Analysis-capable source-local host	.claude-plugin/	scripts/agent-customize/providers/claude.mjs	scripts/session-analysis/platforms/claude.mjs	self-contained HTML + Markdown	.claude + CLAUDE.md + Plugin assets	claude plugin validate --strict . -> isolated install/discovery -> configured-asset baseline -> validated html render
Codex	Analysis-capable source-local host	.codex-plugin/	scripts/agent-customize/providers/codex.mjs	scripts/session-analysis/platforms/codex.mjs	self-contained HTML + Markdown	.codex + .agents + AGENTS.md	harness prepare --platform codex -> finalize with html-report validation
Qoder	First-class product host	.qoder-plugin/	scripts/agent-customize/providers/qoder.mjs	scripts/session-analysis/platforms/qoder.mjs	better-harness	.qoder/rules + AGENTS.md + output templates	better-harness harness render --mode qoder-canvas --validate
Cursor	Canvas-capable source-local host	.cursor-plugin/	scripts/agent-customize/providers/cursor.mjs	scripts/session-analysis/platforms/cursor.mjs	cursor-canvas	.cursor + .codex compatibility + AGENTS.md	native cursor-agent --help contract check -> unavailable install plan -> Cursor evidence bundle -> validated cursor-canvas render
Qwen Code	Analysis-capable source-local host	qwen-extension.json	scripts/agent-customize/providers/qwen.mjs	scripts/session-analysis/platforms/qwen.mjs	self-contained HTML + Markdown	.qwen + QWEN.md + AGENTS.md	harness prepare --platform qwen -> finalize with html-report validation
GitHub Copilot	Analysis-capable source-local host	.github/plugin/	scripts/agent-customize/providers/copilot.mjs	scripts/session-analysis/platforms/copilot.mjs	self-contained HTML + Markdown	.github + AGENTS.md + ~/.copilot	copilot plugin marketplace add . -> copilot plugin install better-harness@better-harness -> configured-asset baseline -> validated html render
Pi	Analysis-capable source-local host	pi manifest in package.json	scripts/agent-customize/providers/pi.mjs	scripts/session-analysis/platforms/pi.mjs	self-contained HTML + Markdown	.pi + .agents + AGENTS.md	pi install <source> or pi -e <source> -> /better-harness prompt template -> validated html render
Kimi Code	Analysis-capable source-local host	.kimi-plugin/plugin.json	scripts/agent-customize/providers/kimi.mjs	scripts/session-analysis/platforms/kimi.mjs	self-contained HTML + Markdown	AGENTS.md + ~/.kimi-code/skills + project .kimi-code/skills/.kimi/skills + ~/.kimi-code/mcp.json	harness evidence-bundle --platform kimi -> validated html render
WorkBuddy	Analysis-capable source-local host	none (skills install into ~/.workbuddy/skills)	scripts/agent-customize/providers/workbuddy.mjs	scripts/session-analysis/platforms/workbuddy.mjs	self-contained HTML + Markdown	~/.workbuddy AGENTS.md + identity files + .agents + AGENTS.md	session-analysis --platform workbuddy sources -> validated html render
Grok	Analysis-capable source-local host	none (skills install into ~/.grok/skills)	scripts/agent-customize/providers/grok.mjs	scripts/session-analysis/platforms/grok.mjs	self-contained HTML + Markdown	~/.grok + .grok + .agents + AGENTS.md	session-analysis --platform grok sources -> skill symlink -> validated html render

Read-only Plugin Lifecycle

better-harness plugin status, plan, and verify expose a Better Harness-only view over these adapters. The shadow declarations in scripts/host-support/ record lifecycle evidence without replacing this matrix while ADR-0002 is proposed. Each host declaration lives in scripts/host-support/profiles/<host>.mjs and uses the shared typed constructors rather than copying registry logic. Each module is locally validated and deeply frozen before registry composition; aggregate validation adds only cross-host id and alias uniqueness. The same profile declares its provider home option and each surface's observation kind, so status collection does not carry a second host lookup table or host-specific branches. Lifecycle status and plan also share one private target resolver for aliases, explicit host requirements, surfaces, and scopes, keeping usage diagnostics consistent as profiles grow. Plugin leaf metadata is declared once and projected into the root command registry; runtime definitions bind the same entries to executors and human renderers without leaf-name branches. Every observed or inventory-failure status instance passes through one validated row factory, so host additions cannot invent a second status shape. Every lifecycle plan likewise passes through one transition and validation model: mutation steps declare external host-plugin-state effects, while follow-up verification steps declare read-only host-observation effects. The thin plan core does not copy lifecycle state policy when a host profile is added. Plans never execute and always preserve native surface differences:

Host surface	Lifecycle disposition
Claude Code CLI	Native install, update, remove, and details verification steps
Codex CLI / Desktop	Native CLI argv; manual Desktop UI steps
Qoder Desktop / CLI	Bundled Desktop; manual CLI install, verified list/remove, unavailable update
Cursor Agent	Session-only evidence; install remains unavailable while the local help contract is stale
Qwen Code	Native extension install/list argv; update and remove remain unavailable until safe scope-targeted mutation semantics are evidenced
GitHub Copilot CLI	Native marketplace install, list, update, and uninstall argv
Pi CLI / CLI session	Persistent user/project install guidance and inventory; separate pi -e session-only activation whose update/remove operations are not applicable
WorkBuddy	PLUGIN_LIFECYCLE_UNSUPPORTED; adapter evidence remains available

Kimi Code and Grok are absent from this table on purpose: neither host has a validated native lifecycle contract yet, so lifecycle targets reject them with UNKNOWN_HOST instead of borrowing another host's install route. Their adapter, configured-asset, and session evidence remain available through the matrix above.

The lifecycle commands do not read raw session transcripts, contact a registry, edit host settings, or register an apply path.

Discovery And Evidence

• Claude Code discovers the canonical root skills/ directory through .claude-plugin/plugin.json; .claude-plugin/marketplace.json makes the repository installable with Claude's native plugin commands. Its capability-owned session adapter reads workspace-matching local Claude transcripts when present; the shell does not own that evidence. Configured user/project/Plugin assets are inventoried through scripts/agent-customize/providers/claude.mjs; installed Plugin records are kept separate from marketplace catalogs and runtime-use claims.

• Qoder configured assets are inventoried from Qoder plugin, rules, commands, skills, hooks, and MCP-facing paths through scripts/agent-customize/providers/qoder.mjs. Session evidence comes from scripts/session-analysis/platforms/qoder.mjs.

• Codex configured assets are inventoried through scripts/agent-customize/providers/codex.mjs. Session evidence comes from scripts/session-analysis/platforms/codex.mjs. The .codex-plugin/ shell is install/discovery metadata included in the public npm package; it does not own Codex evidence collection.

• Cursor configured assets are inventoried through scripts/agent-customize/providers/cursor.mjs and the active .cursor-plugin/ shell, which is included in the public npm package. Session evidence comes from scripts/session-analysis/platforms/cursor.mjs, which keeps transcript, metadata, and audit coverage explicit when local identities do not join.

• Qwen Code configured assets are inventoried through scripts/agent-customize/providers/qwen.mjs. Session evidence comes from scripts/session-analysis/platforms/qwen.mjs, which reads workspace-matching JSONL transcripts under ~/.qwen/projects/<slug>/chats/. The qwen-extension.json manifest is native Qwen install/discovery metadata included in the public npm package; it does not own Qwen evidence collection.

• GitHub Copilot configured assets are inventoried through scripts/agent-customize/providers/copilot.mjs, covering AGENTS.md, .github/copilot-instructions.md, .github/instructions/, .github/skills/, .agents/skills/, .github/agents/, .github/prompts/, .github/hooks/, .mcp.json, .github/mcp.json, and the user-scope ~/.copilot equivalents. Installed-Plugin records come from the installedPlugins array in ~/.copilot/config.json and stay separate from marketplace catalogs and runtime-use claims. Session evidence comes from scripts/session-analysis/platforms/copilot.mjs, which reads workspace-matching ~/.copilot/session-state/<id>/events.jsonl bound through each session's workspace.yaml. Copilot transcripts record no per-response model token usage, and a matched session directory without events.jsonl stays an explicit partial coverage boundary. ~/.copilot/session-store.db is documented as automatically managed and is not an evidence source. The .github/plugin/ shell is native Copilot install/discovery metadata included in the public npm package; it does not own Copilot evidence collection.

• Pi configured assets are inventoried through scripts/agent-customize/providers/pi.mjs, covering ~/.pi/agent (settings-declared pi packages, skills, prompt templates, extensions, the global AGENTS.md context file), the shared .agents/skills directories, and project .pi assets. Session evidence comes from scripts/session-analysis/platforms/pi.mjs, which reads workspace-matching JSONL transcripts under ~/.pi/agent/sessions/--<cwd-slug>--/ and honors the PI_CODING_AGENT_DIR and PI_CODING_AGENT_SESSION_DIR overrides. Pi discovers the canonical root skills/ directory and the prompts/ templates through the pi manifest in package.json; that manifest is install/discovery metadata and does not own Pi evidence collection.

• Kimi Code configured assets are inventoried through scripts/agent-customize/providers/kimi.mjs: user-level ~/.kimi-code/skills/**/SKILL.md and ~/.kimi-code/mcp.json, plus project-level AGENTS.md/CLAUDE.md and the probed skill roots .kimi-code/skills/**/SKILL.md and .kimi/skills/**/SKILL.md. The repository's .kimi-plugin/plugin.json manifest makes Better Harness installable through Kimi Code's /plugins manager. Kimi Code also supports hooks, custom agents, plugin-declared slash commands, and plugin-bundled skills (installed per user under ~/.kimi-code/plugins/managed/); the provider inventories those surfaces for plugins recorded in ~/.kimi-code/plugins/installed.json (assets only for enabled: true records), while memory has no Kimi Code equivalent. Session evidence comes from scripts/session-analysis/platforms/kimi.mjs, which reads ~/.kimi-code/sessions/<wd_*>/ses{sion}_*/agents/*/wire.jsonl and resolves the workspace-to-wd_* mapping through workspaces.json and session_index.jsonl (falling back to wd_<name>_* directory prefixes).

• WorkBuddy configured assets are inventoried through scripts/agent-customize/providers/workbuddy.mjs, covering ~/.workbuddy user skills, marketplace plugins under plugins/marketplaces/ with enabled state from settings.json, mcp.json/.mcp.json user and plugin MCP servers, the global AGENTS.md and identity context files, the shared .agents/skills directories, and project .workbuddy assets. Session evidence comes from scripts/session-analysis/platforms/workbuddy.mjs, which reads workspace-matching JSONL transcripts under ~/.workbuddy/projects/<cwd-slug>/. Embedded cwd values are authoritative; cwd-less 5.x transcripts qualify only from an exact workspace slug. The adapter honors the WORKBUDDY_DIR override. WorkBuddy has no install shell in this repository; skills install manually into ~/.workbuddy/skills or through WorkBuddy's own marketplace surfaces.

• Grok configured assets are inventoried through scripts/agent-customize/providers/grok.mjs, covering ~/.grok user skills (including bundled skills), hooks, MCP servers declared in config.toml, installed plugins under installed-plugins/, shared .agents/skills, and project .grok assets. Session evidence comes from scripts/session-analysis/platforms/grok.mjs, which reads workspace-matching session directories under ~/.grok/sessions/<url-encoded-cwd>/<session-id>/ (summary.json, updates.jsonl, optional chat_history.jsonl and signals.json). The adapter honors GROK_HOME. Grok has no install shell in this repository; skills install manually into ~/.grok/skills (symlink is enough for /better-harness).

Output Modes

Canonical templates live under templates/reporting/.

• qoder-canvas.md: Qoder Canvas output contract, covering renderer-owned findings.json, Canvas-only canvas.json, and report.canvas.tsx.
• cursor-canvas.md: Cursor Canvas output contract, covering the complete report, native Context Usage projection, and public IDE actions.
• html-visual.md: portable Claude Code/Codex/Qwen/Copilot/Pi/Kimi Code/WorkBuddy/Grok visual output contract, covering findings.json, report.md, and report.html.
• Markdown-only output has no visual companion.

Split Triggers

Split a host into docs/adapters/<host>.md only when at least one condition is true:

• That host's discovery, smoke, or packaging guidance exceeds one screen.
• That host has an independent release or install lifecycle.
• That host's evidence collection is referenced by two or more capabilities.
• That host's prompt contract changes generated artifacts or validation.
• This README matrix is no longer easy to scan.

A split file must link back to this matrix and keep canonical judgment in the owning capability, template, skill, model, or reference path.