Coven Documentation

Reference for coven run, supported harness ids, cwd/title flags, detach mode, and project-root safety.

coven run launches a project-scoped harness session and records it in the Coven session ledger.

coven run codex "fix the failing tests"
coven run claude "polish this UI"

The current built-in harness ids are codex and claude.

Syntax

coven run <harness> <prompt> [--cwd <path>] [--title <title>] [--detach]

Part	Meaning
`<harness>`	Supported harness id. Currently `codex` or `claude`.
`<prompt>`	Required task text for the harness.
`--cwd <path>`	Working directory inside the detected project root.
`--title <title>`	Readable session title for `coven sessions`.
`--detach`	Create the session record without launching the harness.

Coven resolves the current project root before launch. If you pass --cwd, the path must stay inside that project root.

cd /path/to/project
coven run codex "add focused tests for the auth helper" --cwd packages/api

The daemon and CLI validate project and cwd boundaries so a client cannot quietly widen a session beyond the intended project.

Use --title when the prompt is long or when the session will be selected later from the browser:

coven run claude "review the settings page for mobile layout issues" --title "Settings mobile review"

Use --detach when you want a record in the ledger but do not want to spawn a harness yet:

coven run codex "prepare release notes" --detach

Detached mode is intentionally narrow. Most users should launch a live harness and then manage it through Sessions.