Custom Adapters

Coven ships built-in adapters for Codex, Claude Code, Coven Code, and Copilot CLI — and it loads external adapters from JSON manifests at startup. You can run another coding-agent CLI through Coven today without patching Coven, as long as the adapter meets the same bar as the built-ins.

Three ways to register an adapter

Mechanism	How it works
Trusted recipe	`coven adapter install <id>` writes a Coven-maintained manifest to `COVEN_HOME/adapters/<id>.json`. Loaded only while the file byte-for-byte matches the shipped recipe.
`COVEN_HARNESS_ADAPTER_MANIFEST`	Environment variable pointing at one manifest JSON file.
`COVEN_HARNESS_ADAPTER_DIRS`	Environment variable with a path-separated list of directories; every `*.json` file in each directory is loaded (sorted order).

Set the environment variables before starting Coven (both the CLI and the daemon read them at startup). Across all sources, the first manifest to claim an id wins; later duplicates are skipped with a warning. An adapter whose id matches a built-in harness is skipped — built-ins cannot be overridden.

Trusted recipes: grok and hermes

The examples below use the grok and hermes installable recipes. The current recipe registry also includes opencode.

Recipe	Label	Executable	Auth
`grok`	Grok Build	`grok`	`grok login`, or set `XAI_API_KEY` for headless auth
`hermes`	Hermes Agent	`hermes`	Complete Hermes' own local setup

coven adapter install grok
coven adapter doctor grok
coven run grok --permission full "what is in this project?"

Grok's headless runner never blocks on approvals: with --permission omitted it silently auto-cancels every tool call that would prompt (that is, every mutating call). Always pass --permission full or --permission read-only explicitly when running grok.

Adapter commands

coven adapter list            # configured adapters, source, availability (--json available)
coven adapter doctor [id]     # diagnose all adapters or one id; exits 1 if unavailable
coven adapter install <id>    # install a trusted recipe (grok, hermes, or opencode)

coven run with an unregistered harness id fails closed and names the known recipes plus the manifest mechanism.

Manifest format

A manifest is a JSON file with an adapters array. Required fields per adapter:

Field	Meaning
`id`	Stable harness id clients pass to `coven run` and the socket API.
`label`	Human-readable display name.
`executable`	Binary name resolved on `PATH`; not an arbitrary client-supplied path.
`interactive_prompt_prefix_args`	Fixed argv prefix for terminal sessions.
`non_interactive_prompt_prefix_args`	Fixed argv prefix for scripts and output capture.
`install_hint`	Actionable setup text for `coven doctor` and `coven adapter doctor`.

Optional fields: system_prompt_flag, prompt_flag, interactive_prompt_flag, model_flag or model_arg_template, capabilities (stream, preassigned_session_id, think, speed — all default off), sandbox (single-flag or argv-list permission mapping), add_dir_flag, stream_args, and continuity_args. Omitted mechanisms make the matching coven run flag a warned no-op rather than an error.

The prompt is the final argument after the fixed prefix args unless the adapter declares a prompt_flag.

Prompt safety

In the CLI release that includes OpenCoven/coven#1089, the manifest loader refuses adapters that could run the prompt as code. Coven appends the prompt as a trailing argument, so:

executable may not name a shell or language interpreter, such as sh, bash, zsh, python3, node, env, or powershell. Names are compared case-insensitively, ignoring surrounding whitespace and a .exe suffix.
Neither interactive_prompt_prefix_args nor non_interactive_prompt_prefix_args may contain -c, -e, --eval, --command, -command, or /c as a whole argument, compared case-insensitively.

Other fields are not checked for these flags, so model_arg_template: "-c model={model}" stays valid for a harness that is not an interpreter.

A rejected adapter fails the whole manifest load. Until you fix it, coven run (for every harness, built-ins included), coven doctor, coven adapter list, and coven adapter doctor exit with an error that names the manifest path, the adapter id, and the rejected executable or field.

To fix it, point executable at the real harness CLI on the daemon's PATH and let it take the prompt as data. Do not work around the check with sh -c, an interpreter wrapper script, or by moving the flag to another field. Coven re-reads manifest files on every launch; if you changed COVEN_HARNESS_ADAPTER_MANIFEST or COVEN_HARNESS_ADAPTER_DIRS, run coven daemon restart so the daemon sees the new value. Then run coven adapter doctor <id>.

These checks block known interpreter names; they are not a sandbox. Review the manifest and the binary its executable resolves to, because external adapters run with your user's authority.

Review checklist

Before registering a new adapter, verify:

The CLI can run inside a normal PTY.
It has a stable command-line prompt shape.
It can run from an explicit working directory.
Provider credentials stay with the harness.
It has a clear install/auth story.
It does not require clients to pass secrets through Coven.
It can fail closed when the executable is missing.

External adapters run with your user's authority, exactly like built-ins. Only load manifests you wrote or reviewed. The daemon still validates harness id, project root, and working directory for every launch — see Daemon security posture.

For the built-in adapters, use Codex, Claude Code, Copilot CLI, Coven Code, and the CLI run reference.