Coding harness compatibility

Detection on PATH means only that RepoOS found a binary. It does not promise that the adapter can safely drive that release. RepoOS keeps a small, versioned contract for each drivable harness and checks the installed version against its supported line and any recorded certification.

Statuses

• Verified — the release family is covered by a real RepoOS adapter contract suite and a recorded evidence source.
• Upgrade recommended — the installed release is older than the supported line. RepoOS still permits work when local capability checks pass.
• Newer than verified — the release is newer than RepoOS's last tracked certification. It is not blocked; run a compatibility probe before important work — see Probes, privacy, and upgrades.
• Unsupported — a known incompatible family or a required local capability is missing.
• Not yet probed — RepoOS could not parse a version or has not yet validated that harness with an in-repo contract suite.

Compatibility is narrower than model quality, cost, or task success. A green model-selection check is not certification of the complete adapter contract.

Supported coding harness versions

Harness	CLI id	Binary	Supported range	Newest certified	Notes
OpenCode	opencode	opencode	>=2.0.0 <3.0.0	2.0.11 (2026-09-22)	Full 8-seam certification. Use --standalone for isolated probes.
Claude Code	claude code	claude	>=2.0.0 <3.0.0	2.1.285 (2026-10-04)	Full 8-seam certification. Requires --verbose with stream-json.
Codex	codex	codex	>=0.100.0 <1.0.0	0.160.0 (2026-10-04)	codex exec --json --approve-for-me; --approve-for-me precedes resume subcommand.
Cursor Agent	cursor	cursor-agent	>=2026.0.0 <2027.0.0	2026.10.1 (2026-10-02)	Stream-json mode; -f/--force bypasses approval prompts.
Kiro	kiro	kiro-cli	>=2.0.0 <3.0.0	2.27.1 (2026-10-04)	Plain-text output; session-continuation and structured-events skipped (captured post-run).
Antigravity	antigravity	agy	>=1.0.0 <2.0.0	1.2.16 (2026-10-04)	Gemini-backed; --dangerously-skip-permissions for unattended work.
GitHub Copilot	github copilot	copilot	>=1.0.0 <2.0.0	1.0.91 (2026-10-04)	--output-format json JSONL; --no-ask-user --yolo for headless.
Qwen Code	qwen code	qwen	>=0.1.0 <1.0.0	Pending	Claude-compatible interface; --yolo for headless. Requires --auth-type configured.
Crush	crush	crush	>=0.97.0 <0.98.0	Pending	Plain-text headless runs; session-continuation and structured-events skipped (session id and usage captured post-run via crush session list / session show --json). Pre-1.0, so the range is narrow.
pi	pi	pi	>=1.0.0 <2.0.0	1.0.0 (2026-10-04)	Strict JSONL event stream (--mode json) with a session header and usage, documented --session resume, and no approval prompts in a non-interactive run.
Muse Code	muse	muse	>=1.0.0 <2.0.0	1.4.14 (2026-11-05)	Full 8-seam certification. muse exec --json MSP-envelope stream; UUID-only --session-id resume; --trust-workspace + --approval-mode never every turn; --disable-write --disable-shell for advisory turns; tokens reported, cost not.

This table is derived from src/core/agent-compatibility.json. Update that manifest and add contract evidence together when certifying a release. Do not silently widen a range because a newer binary happens to start.

Probes, privacy, and upgrades

The default detector and repoos doctor are offline and token-free. They read the local binary version and static contract metadata; they do not send version telemetry or collect prompts and project code.

Running a live probe

A live compatibility probe is available on request and is opt-in:

repoos doctor --probe opencode --yes

This runs the harness's adapter-contract suite inside an isolated temporary directory, exercising eight seams: version detection, help/flag shape, model discovery, a headless one-shot, structured event parsing, permission/auto mode, session continuation, and cancellation. The one-shot, resume, and cancellation seams each start a real harness run, so the probe may consume provider tokens. The command warns clearly about this, asks for confirmation when you are at a terminal (pass --yes to skip the prompt), and cleans up the fixture when it finishes.

Run a probe when:

• the Agents page marks your installed harness newer than verified and you want to start important work with it, or
• you are a maintainer certifying a release — see below.

--binary override

Both repoos doctor --probe and repoos certify accept --binary <path> to probe a specific binary instead of resolving from PATH:

repoos doctor --probe opencode --binary ~/.opencode/bin/opencode --yes
repoos certify opencode --binary ~/.opencode/bin/opencode --yes

This is useful when you have multiple versions installed or the binary is not on PATH under the expected name.

--model override

Both commands also accept an optional --model <id> that pins the model used for the probe's one-shot and resume runs. Use it when a harness picks its default model from your environment and that default is not usable — for example pi prefers a provider whose API key is set in your shell over its stored login, so a stray OPENAI_API_KEY can make the one-shot fail with a 401. Currently only pi honours it; other harnesses ignore it.

repoos doctor --probe pi --model openrouter/deepseek/deepseek-v4.1-flash --yes
repoos certify pi --model openrouter/deepseek/deepseek-v4.1-flash --yes

Shared machine-wide detect cache

The detected binary and version information is currently per-project (stored in the RepoOS server's in-memory state and refreshed on page load). There is no cross-project shared cache for detection results, but compatibility contract data (src/core/agent-compatibility.json) ships with RepoOS itself — every project using the same RepoOS version sees the same certification status without re-running probes.

Certifying a release (maintainers)

repoos certify runs the probe and, when every seam passes, writes the certification evidence back into src/core/agent-compatibility.json automatically. This is the maintainer path from "probe passed" to "all users see verified."

# Full probe + manifest write in one step:
repoos certify opencode --yes

# Probe a specific binary path:
repoos certify "claude code" --binary /usr/local/bin/claude --yes

# JSON output (for CI / scripting):
repoos certify opencode --yes --json

# Re-probe a version that is already certified (skipped by default):
repoos certify opencode --yes --force

By default certify reads --version first and skips the live probe (no tokens spent) when the installed version is already covered by the manifest's newestCertifiedVersion. Pass --force to run it anyway.

When certify passes all seams it:

1. Updates newestCertifiedVersion, verifiedAt, and verificationSource in the manifest.
2. Prints the path of the updated file and suggests the commit command.
3. Exits 0.

When any seam fails the manifest is not updated and the command exits 1.

Weekly CI certification

A GitHub Actions workflow (.github/workflows/certify-harnesses.yml) runs repoos certify weekly for headlessly-installable harnesses (opencode, claude-code, codex). It requires the corresponding API key secrets (ANTHROPIC_API_KEY, OPENAI_API_KEY) to be configured in the repository. When all seams pass it opens a pull request with the updated manifest. This keeps the shipped compatibility data current automatically.

What each seam checks

Seam	What passes
version	--version exits 0 and prints a parseable semver triple
help	--help exits 0 and prints usage text containing run, usage, options, or command
model-discovery	models subcommand exits 0 (no output is fine for server-backed CLIs)
headless-one-shot	A one-shot run completes, exits 0, and the output contains a recognizable answer
structured-events	The output contains at least one recognized event/line in the CLI's structured format
auto-permissions	The run used a permission-bypass flag (--auto, --dangerously-skip-permissions, --yolo, -f, etc.) and completed
session-continuation	A session ID was captured from the first run and a --resume follow-up completed
cancellation	A run starts and exits cleanly after SIGTERM

Adding a new harness

To add contract templates for a new harness:

1. Add the harness to KNOWN_AGENTS in src/core/detect.ts (cli, binary, etc.).
2. Add a ContractCommandTemplates entry in src/core/agent-contract.ts:
   • version(), help(), models() (return null when no listing command exists)
   • run(dir, prompt), resume(dir, sessionId, prompt) — use the exact flags the driver uses
   • parseRun(stdout) — extract sessionId, hasAnswer, recognized event count
3. Register it in CONTRACT_TEMPLATES.
4. Add a stub entry in src/core/agent-compatibility.json with newestCertifiedVersion: null.
5. Run repoos certify <cli> --yes and commit the updated manifest.

RepoOS never installs, upgrades, or changes a harness automatically. Upgrade or roll back a harness using its official installer and then refresh the Detected Coding Agents tab. Keep the previous release available if a rollback is needed.