CovenDocs
CLI ReferenceWorkRun

Run

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

3 min read

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"

These examples use codex and claude; see Harnesses for the supported adapters in your build.

Syntax

coven run <harness> <prompt> [--cwd <path>] [--title <title>] [--detach]
PartMeaning
<harness>A supported, configured harness id for your build.
<prompt>Required task text for the harness.
--cwd <path>Working directory inside the detected project root.
--title <title>Readable session title for coven sessions.
--detachCreate the session record without launching the harness.

Project boundary

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.

Title

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"

Detached records

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.

Claude scoped writes

Newer source builds accept --write-scope <file> for Claude streamed launches. This is a separate owner-authorized write set; it cannot be combined with --permission or --add-dir, used with another harness, or used for a detached launch. Check your installed build's help and the daemon's owner-local sessionClaudeWriteScope capability before using it. Capability discovery advertises parsing, not a qualified local executable or a grant.

coven run claude --cwd /path/to/project --stream-json --write-scope /path/to/scope.json -- "Review the project"

The scope document is bounded to 65,536 bytes and uses version 2 with primaryRoot, writableRoots, readOnlyRoots, and protectedRoots. Roots must be existing absolute directories; the primary root must equal launch cwd and be explicitly writable. Optional mcpConfigFile and mcpServerNames must be supplied together. The file can contain credentials, so keep it private; only the listed MCP servers start.

The current execution profile requires macOS and Claude Code 2.1.318 or later. Shell and file-tool writes are confined by Claude's OS sandbox, and launch fails when that sandbox is unavailable. The scope does not confine shell reads, network access, listed MCP servers, the per-user temporary directory, or concurrent external filesystem actors. Protected and nested read-only trees are audited for aliases, while writable project trees are not exhaustively walked; a pre-existing writable hardlink to an ungranted object remains writable. Unsupported layouts and native permission/settings environment overrides fail closed, with no fallback to unrestricted Full. User/project settings and MCP configuration cannot broaden the requested set. See the owning source contract for overlap rules and verification limits. Scope admission, actual artifacts, provider-backed behavior, and release readiness are separate evidence.

Chat workspace integration

Source builds expose --chat-workspace-policy-v1 <file> for Chat's host-owned workspace policy and optional --chat-input-directory <directory> for staged read-only inputs. This integration requires streamed execution through the built-in Coven Code adapter on macOS. It refuses detached execution and separate permission, add-dir, Claude write-scope or context-admission options. It is not a daemon CreateSession field or an alternative Full permission mode.

The version-1 policy binds one run id, workspace-write access, the canonical launch root, and explicit sorted writable/read-only roots. The policy file, enforcing executable and staged input directory must remain outside writable grants. The engine must return an exact enforced-policy receipt before the turn is admitted; missing enforcement fails visibly. Staged inputs never grant writes. The host owns policy creation and effective-access presentation; inspect the installed build's help rather than constructing a broader grant to bypass a refusal. Native engine enforcement, installed Chat behavior and release acceptance remain separate evidence.

Was this page helpful?No

Last updated on

On this page