Doctor

coven doctor is the first command to run after install and the first command to run when something feels broken.

coven doctor

It checks which Coven executable is answering, the local state directory, project detection, daemon/socket status, and supported harness CLIs.

What it checks

Area	What to look for
Installed binary	In the CLI release that includes OpenCoven/coven#1124, the `Install` / `Installs` output lists every `coven` executable visible on `PATH` in resolution order, with how each was installed (npm and its prefix, `cargo install`, source build, legacy coven-code installer) and which entry is the running process. Until then, Doctor prints the older path-only list. When more than one exists, each shadowed copy gets its exact removal command, and when one of them is an npm install Doctor reports where `npm install -g` currently writes. In that release, JSON reports `install:conflicts` with the copy count and each copy's origin kind (for example `active: npm; shadowed: npm, cargo install`), but no paths, npm prefixes, or removal commands. This check appears first because every later diagnostic must describe the binary you intended to run.
Store	The path Coven will use for local state. Defaults to `~/.coven` unless `COVEN_HOME` is set.
Project	Whether the current directory resolves to a git/project root.
Daemon	Whether the daemon is running, stale, or stopped, and which local IPC endpoint it owns.
Harnesses	Whether Codex, Claude Code, GitHub Copilot CLI, or the managed Coven Code engine is available.
Engine	Which `coven-code` Coven will run and whether it meets the minimum version. In the CLI release that includes OpenCoven/coven#1124, an advisory `[--]` line names a `coven-code` that is first on `PATH` but is not the engine Coven runs; JSON reports the same condition as the path-free `engine:path` warning.
Next steps	A provider-specific install, `coven setup <provider>`, or `coven run <harness> "..."` command.

doctor does not inspect provider credential stores and does not silently run a network verification turn. Provider verification can consume network access or paid usage, so it remains a separately consented coven setup action.

Shadowed installs

When Doctor prints an Installs: block, more than one coven is on PATH and the first entry answers every command. Until the CLI release that includes OpenCoven/coven#1124, Doctor still prints the older path-only list; treat the block below as the forthcoming format. Do not reinstall repeatedly; read the block, which already names each copy's origin and the command that removes it:

Installs:
  [OK] ~/.local/bin/coven (active, this process) — npm, prefix ~/.local
  [!!] ~/.nvm/versions/node/v24.18.1/bin/coven (shadowed) — npm, prefix ~/.nvm/versions/node/v24.18.1
       remove: npm uninstall -g --prefix ~/.nvm/versions/node/v24.18.1 @opencoven/cli
  [!!] ~/.cargo/bin/coven (shadowed) — cargo install
       remove: cargo uninstall coven-cli

The first entry wins. Keep one install per machine: remove the shadowed copies with the commands above, then re-check with coven --version.

Run each remove: command, then confirm one copy remains and it is the version you expect:

which -a coven
coven --version
coven doctor

Get-Command -All coven
coven --version
coven doctor

In the CLI release that includes OpenCoven/coven#1124, when copies conflict and at least one is an npm install, Doctor also asks npm where npm install -g writes and prints the answer as the last line of the Installs: block. A [!!] line means that prefix holds a shadowed copy or no coven on PATH at all, so the documented upgrade command never touches the binary your shell runs; the line ends with the upgrade command for the active copy. If npm is missing or does not answer within five seconds, Doctor leaves the line out. For an npm active copy, use this prefix-explicit upgrade until the extra copies are gone:

npm install -g --prefix <active-prefix> @opencoven/cli@latest

Then restart the daemon so its binary matches the foreground CLI:

coven daemon restart
coven doctor

Doctor recognizes these origins:

Origin	Removal
`npm, prefix <dir>`	`npm uninstall -g --prefix <dir> @opencoven/cli`
`cargo install`	`cargo uninstall coven-cli`
`source build`	Delete the link or binary; it points into a checkout's `target/` directory.
`legacy coven-code installer`	Delete the `coven` file in `~/.coven-code/bin`.
`unknown origin`	Identify the install method before deleting anything.

The JSON report (coven doctor --json) keeps install:conflicts path-free by design; use the prose form for the paths. See Install Debugging for the platform-specific causes.

Common next steps

If the daemon is stopped:

coven daemon start

If the daemon is stale:

coven daemon restart

If a provider CLI is missing, install it with the provider's official package. If the executable exists but login is incomplete, hand the terminal to the provider-owned flow explicitly:

coven setup codex
coven setup claude
coven setup copilot

Use coven setup <provider> --verify only when you also want a separate bounded provider turn after login. See Provider setup.

Support evidence

Before sharing output, follow Support to redact private data and choose the right reporting route. Include:

Redacted coven doctor output, including install:conflicts.
The command you expected to work.
The current working directory, if it is not private.
Whether you use custom COVEN_HOME.
A redacted coven setup <provider> --verify-only --report-json <new-path> report when stronger provider evidence is necessary and you explicitly accept possible provider usage or cost.

For daemon-specific failures, continue with Daemon commands and Daemon observability.

What it checks

Shadowed installs

Common next steps

Support evidence

On this page