Harness Adapters
Connecting different AI providers as harnesses.
Harness Adapter Guide
Coven v0 supports Codex and Claude Code. This guide describes the current adapter shape and the bar for adding more harnesses.
Current Adapter Shape
A built-in harness adapter defines a compact launch contract.
| Field | Purpose | Consumer |
|---|---|---|
| Stable Coven harness id | Names the adapter in CLI and API requests. | CLI/API |
| User-facing label | Gives clients a readable display name. | Client UI |
| Executable name | Lets coven doctor detect the CLI on PATH. | Doctor |
| Interactive prompt args | Defines the fixed argv prefix for live PTY sessions. | Launcher |
| Non-interactive prompt args | Defines the fixed argv prefix for one-shot output capture. | Launcher |
| Install/authentication hint | Explains the next setup step when detection fails. | Doctor |
The current implementation expects the prompt to be the final command argument after any fixed prefix args.
Built-in Harnesses
| Harness | Harness id | Executable | Interactive prefix args | Non-interactive prefix args | Setup hint |
|---|---|---|---|---|---|
| Codex | codex | codex | None | exec --skip-git-repo-check --color never | npm install -g @openai/codex; codex login |
| Claude Code | claude | claude | None | --print | npm install -g @anthropic-ai/claude-code; claude doctor |
Compatibility Matrix
| Surface | Codex (`codex`) | Claude Code (`claude`) | Requirement for another harness |
|---|---|---|---|
| Provider auth | codex login; Coven does not read tokens. | claude doctor; Coven does not read tokens. | Auth remains provider-owned. No API key, OAuth token, account id, or org id is added to Coven requests. |
| Command construction | Program codex; prompt is an argv element after fixed prefix args. | Program claude; prompt is an argv element after fixed prefix args. | Build with argv APIs only. No prompt execution through sh -c or equivalent shell interpolation. |
| Project root and cwd | Daemon validates projectRoot and cwd before launch. | Daemon validates projectRoot and cwd before launch. | Launch must fail closed when cwd resolves outside the project root. |
| PTY lifecycle | Daemon spawns and owns the PTY, input writer, and killer handle. | Daemon spawns and owns the PTY, input writer, and killer handle. | Adapter must work under daemon-owned PTY supervision and return clear spawn failures. |
| Event replay | Output and exit data are appended to the SQLite event log. | Output and exit data are appended to the SQLite event log. | Output must be replayable through GET /api/v1/events and coven attach after process exit. |
| Live input | POST /api/v1/sessions/:id/input writes { data } to the live PTY. | POST /api/v1/sessions/:id/input writes { data } to the live PTY. | Live input must either work through the daemon PTY writer or be explicitly documented as unsupported before public support. |
| Live kill | POST /api/v1/sessions/:id/kill uses the daemon killer handle and records killed. | POST /api/v1/sessions/:id/kill uses the daemon killer handle and records killed. | Kill must terminate only a daemon-verified running session and return 409 session_not_live otherwise. |
| Client compatibility | Covered by API/session docs and local smoke coverage. | Covered by API/session docs and local smoke coverage. | Update docs, daemon tests, smoke coverage, and client/plugin compatibility fixtures before advertising support. |
Current, Future, and Unsupported Adapters
| Name | Status | Reason |
|---|---|---|
codex | Current | Built-in adapter and harness id in the daemon. |
claude | Current | Built-in adapter and harness id in the daemon. |
| Hermes | Future / planned | Documented as a candidate, not a current daemon adapter. |
| Aider | Future / planned | Documented as a candidate, not a current daemon adapter. |
| Gemini CLI | Future / planned | Documented as a candidate, not a current daemon adapter. |
| OpenCode | Future / planned | Documented as a candidate, not a current daemon adapter. |
| Custom local harness | Future / design | Requires a policy and compatibility story before broad support. |
| OpenClaw | Not a Coven harness | OpenClaw integration is an external client/plugin path through @opencoven/coven, not a daemon harness id. |
| Generic command adapter | Not supported in v0 | Arbitrary commands need explicit policy, approval, and audit behavior before they can be safe. |
Adapter Requirements
Before adding a new harness, confirm the readiness checks below.
| Requirement | Risk area | Acceptance signal |
|---|---|---|
CLI detection on PATH | Setup | coven doctor can find the executable safely. |
| Prompt passed without shell interpolation | Command safety | Launcher builds argv directly and keeps the prompt as data. |
| Validated project cwd | Filesystem policy | The process starts only after project-root and cwd checks pass. |
| PTY/session event capture | Observability | Output and exit data become replayable session events. |
| Provider-owned authentication | Credentials | Login remains in the harness provider flow. |
coven doctor failure clarity | Setup | Missing auth or executable states include actionable hints. |
| Command and missing-executable tests | Regression coverage | Tests prove safe argv construction and understandable failures. |
What Not to Add Yet
Avoid generic arbitrary command adapters until Coven has explicit policy and approval behavior for them.
Arbitrary commands are more dangerous than named harness adapters because they can blur the difference between "run a coding agent in this project" and "execute whatever string a client sent." Keep v0 narrow.
Future Harness Evaluation Checklist
For a candidate harness, document the evaluation packet.
| Field | Group | Why it matters |
|---|---|---|
| Install command | Setup | Users need a repeatable path to get the CLI. |
| Executable name | Setup | Doctor detection needs the exact binary name. |
| Local auth flow | Credentials | Provider credentials must stay outside Coven. |
| One-shot prompt command | Launch shape | Non-interactive runs need predictable output capture. |
| Interactive command | Launch shape | Live PTY sessions need a stable argv shape. |
| Resume/session command | Session continuity | Native upstream session ids may become useful metadata. |
| Non-interactive output mode | Output | Clients need clean logs without terminal control noise. |
| stdin prompt injection requirement | Launch shape | stdin prompts have different safety and replay behavior. |
| Color/control sequence controls | Output | Replay and docs output should stay readable. |
| Shell quoting hazards | Command safety | Adapters must avoid sh -c style prompt execution. |
| Known exit codes | Error handling | Clients can translate failures into useful next steps. |
| Minimum safe smoke test | Regression coverage | Public support needs proof beyond a maintainer machine. |
Session Identity Mapping
Some harnesses have their own upstream session ids. Coven's session id remains the local runtime id.
If upstream ids become useful, store them as metadata rather than replacing Coven's own id. Clients should be able to rely on a stable Coven id for attach, events, archive, summon, and sacrifice.
Suggested Adapter Maturity Stages
| Stage | Name | Proof required |
|---|---|---|
| 1 | Research note | Document CLI shape and risks. |
| 2 | Command construction tests | Prove argv construction is safe. |
| 3 | Doctor detection | Add install and authentication hints. |
| 4 | Launch smoke | Prove a session can run in a temporary project. |
| 5 | Attach/replay smoke | Prove events can be replayed. |
| 6 | Client compatibility | Update docs and integration tests. |
Do not skip from research directly to public support.
Rendering diagram…
A harness skipping any stage is not ready for public support, even if it appears to work on a maintainer's machine.
Harness Adapter Model
Rendering diagram…
Last updated on