Getting started

What you get

Coven supervises a coding-agent CLI in a project boundary, then keeps its session record and event log locally. Your harness keeps its own provider login; Coven keeps the lifecycle, replay, and local API consistent.

One pass through this page is the whole first-session journey: install and verify Coven, connect a harness, run one recorded session, inspect its record, and recover from the first failure. Advanced next steps stay one link away until that journey is done.

Interactive default

Run coven when you want Coven's guided interactive front door. The default interactive path is the managed coven-code engine: on first run Coven can install the pinned engine for you, and later interactive launches reuse that managed binary. COVEN_LEGACY_TUI=1 is only a deprecated compatibility escape hatch for the older in-process shell.

1. Install and verify

Install Coven with the published npm wrapper:

npm install -g @opencoven/cli

Verify the install before connecting anything:

coven --version
coven doctor

doctor reports the next setup action when the local store, project detection, daemon, or a harness is not ready.

Use the package without installing coven on PATH only for a one-off readiness check:

npx @opencoven/cli doctor

That is only a preflight. The daemon and recorded-session steps below expect coven on PATH, so finish a normal install before continuing. Source checkouts install with cargo install --path crates/coven-cli; cargo build --workspace is only an active-development build and does not install coven on PATH. Both routes are detailed in Install Coven, with per-OS notes in Platforms.

2. Connect a harness

Install the provider CLI you want Coven to launch:

npm install -g @openai/codex
npm install -g @anthropic-ai/claude-code
npm install -g @github/copilot

Then choose the provider you actually intend to use and hand the terminal to its provider-owned login flow:

coven setup codex
# or: coven setup claude
# or: coven setup copilot

Coven shows the exact login command and asks for explicit consent before launching it. Credentials remain in the provider CLI's own store.

A stronger setup check is optional:

coven setup codex --verify

Verification asks for separate consent, requires network access, and may incur provider usage or cost. It is not required for the normal first-session loop.

See Provider setup for verification and report semantics, Install harness CLIs for the setup matrix, and Harnesses for adapter behavior and credential boundaries.

3. Run a first session

From the repository you want to work in, use this exact first-session loop as the checked Codex example. It assumes you installed and verified Coven above and already authenticated Codex. If you chose Claude Code or Copilot CLI instead, keep the same loop and substitute claude or copilot in the coven run command.

coven doctor
coven daemon start
coven run codex "explain this repo in 5 bullets"
coven sessions

This keeps the readiness check, daemon startup, first recorded run, and session browser in one concrete flow. The daemon rejects a missing project root or a working directory outside that root. This is the core distinction: a harness runs the task; Coven enforces and records the session around it.

4. Inspect the result

Use the interactive coven sessions browser to open the recorded run directly, or list plain session IDs when you need one for a later command:

coven sessions --plain

Then attach or inspect the recorded session without attaching:

coven attach <session-id>

Inspect a record without attaching:

coven sessions show <session-id>
coven sessions events <session-id> --limit 100
coven sessions log <session-id>

Unique session-id prefixes are accepted when they identify exactly one session. Use coven sessions search "query" for full-text search over recorded event payloads.

Archive a completed record when it is no longer active; sacrifice it only when you intend to delete its events permanently.

coven archive <session-id>
coven sacrifice <session-id> --yes

For a cross-surface summary of the daemon, open sessions, familiars, skills, research, and hub state:

coven status

5. Recover when a step fails

Every stage above has the same recovery entry point:

coven doctor

Keep recovery narrow:

• Fix the first failing branch doctor reports, then rerun coven doctor before changing anything else.
• Inspect before you mutate. coven sessions show, coven sessions events, coven sessions log, and coven status are read-only; coven sacrifice permanently deletes a non-running session and its events.
• Route the failure to the stage it appeared in — harness, daemon, project boundary, or session state — and follow the first fix that matches.

The ordered decision path for every failure mode, including a broken install, lives in Troubleshooting.

6. Advanced next steps

Once the first recorded session is inspectable, choose a task in Next steps. For a specific area, use its canonical reference below:

Browse every public command grouped by task with:

coven help --all

For the model behind the runtime, read Core concepts and Architecture.