Getting Started with Coven

This guide takes a new user from a fresh checkout or npm install to a visible project-scoped agent session.

What Coven Is

Coven is a local-first runtime for coding-agent harnesses. It runs supported CLIs such as Codex and Claude Code inside explicit project boundaries, records session metadata and events, and exposes the work through a CLI, TUI, and local socket API.

The short promise:

One project. Any harness. Visible work.

Install Paths

For the full platform matrix, source build path, WSL2 guidance, and unsupported container/Nix status, see Install Coven.

Use the npm wrapper when you want the fastest public install:

npx @opencoven/cli doctor
pnpm dlx @opencoven/cli doctor

Build from source when you are contributing to Coven:

git clone https://github.com/OpenCoven/coven.git
cd coven
cargo build --workspace
cargo run -p coven-cli -- doctor

Prerequisites

Coven needs the local prerequisites below.

Supported v0 harnesses are codex and claude.

Install and authenticate a harness before expecting coven run to work:

npm install -g @openai/codex
codex login

npm install -g @anthropic-ai/claude-code
claude doctor

First Run

From a project directory:

coven

The default command opens the prompt-first TUI.

If you prefer to run the explicit setup checks:

coven doctor

coven doctor checks setup readiness before you launch work.

Run a Session

Start the daemon, then launch a harness session from a repository or project directory:

coven daemon start
coven run codex "fix the failing tests"

or:

coven run claude "polish the CLI help text"

For a more readable session list, pass a title:

coven run codex "update the docs" --title "Docs refresh"

Use a specific working directory only when it is inside the detected project root:

coven run codex "inspect this package" --cwd packages/cli

Coven rejects outside-root working directories. Clients may validate for nicer UX, but the Rust daemon is the authority.

Browse Sessions

In an interactive terminal:

coven sessions

This opens the session browser. You can select a session and choose contextual actions.

For scripts or copy/paste workflows:

coven sessions --plain
coven sessions --all --plain
coven sessions --json
coven sessions --json --all

Attach, Archive, Summon, and Sacrifice

Lower-level session verbs remain available:

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

Archive is reversible. Summon restores an archived session to the active list. Sacrifice is destructive and refuses live sessions.

Stop the Daemon

coven daemon stop

Use restart when the socket or daemon state looks stale:

coven daemon restart

Diagnostics and Relief

coven pc is a macOS-first system diagnostics and relief tool surfaced through the Coven CLI. All read operations are side-effect free.

Inspect:

coven pc                  # full report: CPU, memory, disk, top processes
coven pc status           # one-line health summary with 🟢/🟡/🔴 indicators
coven pc status --json    # machine-readable health summary
coven pc top --n 10       # top-N processes by CPU usage
coven pc disk             # disk usage breakdown

Relief operations mutate system state and require an explicit --confirm gate:

coven pc kill <pid> --confirm     # SIGTERM with PID identity re-check
coven pc cache clear --confirm    # clear ~/Library/Caches + /Library/Caches

Safety constraints in v1:

End-to-end Flow

The "install → doctor → daemon → run → sessions" loop is the entire happy path for a first session. Everything else in this guide is fallback or troubleshooting.

Contributor Verification Loop

Before opening a PR:

cargo fmt --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace --locked
python scripts/check-secrets.py

For daemon/session changes, also run the smoke test:

cargo test -p coven-cli --test smoke -- --nocapture

The smoke test uses a temporary COVEN_HOME and a fake harness executable. It does not require private harness credentials.