| summary |
Launch a harness session inside a project root. |
| read_when |
|
| title |
coven run |
| description |
Reference for coven run: one-shot harness execution that spawns a session, streams events, and records the result in the Coven ledger. |
coven run <harness> <prompt> [flags]
<harness> is a configured harness id such as codex, claude, or copilot.
| Flag |
Behavior |
--cwd <path> |
Launch from a directory inside the resolved project root. |
--add-dir <path> |
Grant the harness access to an additional directory beyond its cwd; repeat the flag for multiple directories. Maps to each harness's native trust flag (--add-dir for codex, claude, copilot, and coven-code). Harnesses with no add-dir mechanism warn and continue. |
--title <text> |
Store a readable session title. |
--model <id> |
Forward a model override to harnesses that declare model support. Namespaced ids such as anthropic/claude-sonnet-4 are forwarded to the harness as the bare model id. |
--think |
Request deeper reasoning. Claude maps this to --effort high; unsupported harnesses warn and continue. |
--speed <level> |
Set a latency/reasoning hint: fast, balanced, or thorough. Claude maps these to --effort low, medium, or high; unsupported harnesses warn and continue. |
--detach |
Create the session record without launching the harness. |
--continue [id] |
Resume a specific session, or the latest active session for this project when id is omitted. |
--labels <a,b> |
Attach comma-separated labels to a new session. |
--visibility <private|workspace|shared> |
Set session visibility metadata. |
--archive |
Archive the session after the run completes. |
--familiar <id> |
Inject familiar identity context. |
--stream-json |
Emit Coven JSONL events on stdout. Codex runs as codex exec --json over ordinary pipes and is normalized into assistant / result events; on Windows its npm .cmd shim receives the prompt on stdin rather than through ConPTY. Other external non-stream adapters have raw PTY output wrapped in output events. See docs/STREAM-JSON.md. |
--stream-json-input |
With --stream-json, read JSONL user messages from stdin for Claude stream mode. |
Examples:
coven run claude "audit this branch" --think
coven run claude "make the smallest fix" --speed fast
coven run codex "fix the failing tests" --speed thorough