Architecture
How Coven is structured under the hood.
System Overview
Coven Architecture
Coven is a local-first harness substrate. The Rust CLI/daemon is the authority layer; clients such as the CLI/TUI, CastCodes, Cast Agent, and the optional OpenClaw plugin are presentation/integration layers.
The versioned local socket API contract lives in Coven Local API. Clients should use GET /api/v1/health and negotiate against apiVersion: "coven.daemon.v1" and the capabilities object before depending on session or event response shapes. All error responses use the structured { error: { code, message, details } } envelope documented there.
Runtime Topology
Session Lifecycle
Authority Boundary
Cast Codes are parsed intent. Every sensitive request they produce is still revalidated by the Rust daemon.
Cast Agent Request Flow
Automation Boundary
Coven is the canonical shared local runtime for reusable automation because it centralizes the authority surfaces below.
| Surface | Group | Reason |
|---|---|---|
| Daemon/process ownership | Runtime | One process owns launch, liveness, input, and kill decisions. |
| Policy and permission decisions | Policy | Sensitive choices fail closed at the daemon boundary. |
| Config/profile storage | State | Clients read state instead of inventing drift-prone local copies. |
| Capability discovery | Control plane | Clients can show only supported actions. |
| Action routing and event emission | Control plane | Adapter actions stay inspectable and replayable. |
| Adapter ownership | Adapters | Accessibility, AppleScript, keyboard/mouse, window, filesystem, clipboard, and app-specific bridges stay behind Coven. |
The intended flow is:
user -> client -> Coven -> adapters -> desktop/apps
desktop/apps -> Coven -> client UI updatesGET /api/v1/capabilities lets clients discover what Coven can route. POST /api/v1/actions gives clients a stable intent envelope without coupling them directly to brittle OS automation APIs.
Future Adapter Boundary
Coven's current public runtime is single-harness per session. The daemon already keeps the right lower-level boundary for future coordination work: clients can discover capabilities, launch known harnesses, read events, and preserve project-root enforcement in Rust.
Do not document future orchestration commands as user-facing until they exist in the CLI and socket API. Future coordination layers should build above the current session/event contract without bypassing daemon validation.
Current User-facing Surface
| Surface | Category | Behavior |
|---|---|---|
CovenCLI (coven and coven tui) | Entry point | Open the beginner-friendly slash-command palette. |
coven doctor | Diagnostics | Checks store/project/harness readiness and prints next steps. |
coven daemon start/status/restart/stop | Daemon | Manages the local daemon. |
coven run codex|claude <prompt> | Launch | Launches a project-scoped PTY session. |
coven sessions | Sessions | Opens the human session browser; --plain keeps scriptable output. |
| Session browser actions | Sessions | Surfaces Rejoin, View Log, Summon, Archive, and Sacrifice. |
coven attach|summon|archive|sacrifice <session-id> | Sessions | Keeps explicit lower-level verbs available for scripts and copy/paste workflows. |
Distribution Snapshot
The npm wrapper packages are published for early adopters.
| Package | Target | Role |
|---|---|---|
@opencoven/cli | Universal wrapper | User-facing install entrypoint. |
@opencoven/cli-macos | macOS | Platform binary package. |
@opencoven/cli-linux-x64 | Linux x64 | Platform binary package. |
@opencoven/cli-windows | Windows x64 | Platform binary package. |
The source package versions stay template-like in the repo; release workflow dispatch supplies the published version and builds platform packages. Check the npm registry and GitHub releases before making version-specific release claims.
Last updated on