Concepts
Core ideas behind Coven and how it works.
Coven Concepts
This page defines the nouns used across CovenCLI, the daemon, API, docs, and client integrations.
Every term below is one node in the graph above.
OpenCoven
OpenCoven is the ecosystem and organization around the runtime, cockpit, and integrations.
Use OpenCoven when talking about the broader project family.
Coven
Coven is the local runtime substrate. It owns project-scoped harness sessions, PTYs, logs, local daemon state, and the socket API.
Use Coven for the CLI, daemon, Rust crate, npm wrapper, and local session runtime.
CovenCLI
CovenCLI is the user-facing command surface for the coven binary.
Do not tell users to run opencoven or @opencoven. The package names live under @opencoven/*, the docs name is CovenCLI, and the shell command remains coven.
CastCodes
CastCodes is the first-party OpenCoven workspace and cockpit app. It gives Coven sessions a visible place to live alongside panes, files, diffs, diagnostics, and review flow.
Use CastCodes when talking about the product surface.
Cast Agent
Cast Agent is the Coven-native substrate manager and AI agent backend inside CastCodes. It collects workspace context, talks to Coven Gateway when available, lists local Coven sessions, and keeps daemon-backed session operations visible in the app.
Cast Agent is still a client-side backend. It does not replace daemon validation.
Cast Codes
Cast Codes are the portable intent grammar for switching familiars, delegating work, broadcasting constraints, checking status, resuming lanes, and requesting handoff context.
Use Cast Codes for parseable intent. Do not treat a Cast Code as authorization; the daemon still validates sensitive requests.
Harness
A harness is an external coding-agent CLI that Coven can launch and supervise.
Current v0 harnesses:
| Harness | Harness id | Auth owner |
|---|---|---|
| Codex | codex | Codex CLI local authentication flow |
| Claude Code | claude | Claude Code CLI local authentication flow |
Coven does not store provider credentials. Each harness keeps using its own local authentication flow.
Project Root
The project root is the explicit boundary for a session. Coven validates and canonicalizes the project root before launching work.
The root matters because it defines where the harness is allowed to start. A client cannot widen this boundary by sending a different cwd or a looser config value.
Working Directory
The working directory is the launch directory for a harness session. It must be inside the project root after canonicalization.
Examples:
coven run codex "fix tests"
coven run codex "inspect the CLI package" --cwd packages/cliThe second command is valid only when packages/cli resolves inside the selected project root.
Session
A session is a Coven-owned record of one harness run.
It includes the record fields clients need to list, inspect, and replay work.
| Field | Group | Purpose |
|---|---|---|
| Stable session id | Identity | Lets clients attach, replay, archive, summon, or sacrifice a specific run. |
| Project root | Boundary | Preserves the launch boundary. |
| Harness id | Execution | Records which adapter ran the work. |
| Readable title | Display | Makes session lists scannable. |
| Status | Lifecycle | Shows whether the run is live, finished, failed, or orphaned. |
| Optional exit code | Lifecycle | Captures process completion detail when available. |
| Archive state | Lifecycle | Separates hidden archived records from active sessions. |
| Created/updated timestamps | Timeline | Supports sorting and recency views. |
Session records are stored in SQLite.
Event
An event is an append-only record associated with a session.
Events include output, exit, and metadata records. They let clients replay or inspect what happened after the process exits or the daemon restarts.
Daemon
The daemon is the local Rust process that owns live session state and exposes the HTTP-over-Unix-socket API.
The daemon is the authority boundary.
| Check | Risk area | Failure posture |
|---|---|---|
| Launch requests | Session creation | Reject malformed or unsupported requests before spawning. |
| Project roots | Filesystem policy | Require an explicit valid root. |
| Working directories | Filesystem policy | Reject cwd values outside the project root. |
| Harness ids | Harness policy | Fail closed on unsupported harnesses. |
| Live input | Session control | Only forward input to a verified live process. |
| Kill requests | Session control | Only terminate a verified live process. |
| Session ids | Session control | Return not found or conflict instead of guessing. |
Store
The store is Coven's local SQLite database. It contains session metadata and append-only event history.
Runtime state belongs outside source control. Do not commit .coven/, databases, sockets, logs, or environment files.
Client
A client is anything that talks to Coven rather than launching harnesses directly.
Known client shapes:
| Client | Status | Role |
|---|---|---|
CovenCLI (coven) | Current | First-party command and terminal UI. |
| CastCodes | Current | First-party workspace for panes, sessions, agent substrate, and review. |
| Cast Agent | Current backend | CastCodes substrate manager and Coven-native agent backend. |
@opencoven/coven OpenClaw plugin | External bridge | Optional OpenClaw integration package. |
| Future desktop intake surfaces | Future | Local UI entrypoints that hand work into Coven. |
Clients are convenience layers, not trust roots.
Control Plane
The control plane is the capability and action-routing layer in front of future adapters.
It lets clients discover what Coven can do through GET /api/v1/capabilities and send known actions through POST /api/v1/actions. Unknown action ids fail closed.
Capability
A capability describes a daemon-owned or adapter-owned feature that a client may present.
Capability records include the fields clients need to render and route actions:
id— Stable machine name for discovery and routing.label— Readable UI label.owning adapter— Identifies the runtime or adapter responsible for the capability.status— Shows whether the capability is available, planned, disabled, or missing setup.policy hint— Tells clients how cautious the UI should be.action ids— Lists daemon-recognized actions clients may request.
Rituals
Rituals are Coven's human-friendly session-management verbs.
| Ritual | Reversible | Effect |
|---|---|---|
| Archive | Yes | Hides a completed session from the active list while preserving events. |
| Summon | Yes | Restores an archived session. |
| Sacrifice | No | Permanently deletes a non-running session and its events. |
Ritual names are product language. The safety behavior underneath them should stay precise and conservative.
Socket API
The socket API is the public compatibility boundary for local clients.
Current stable prefix:
/api/v1Clients should handshake with:
GET /api/v1/healthbefore depending on other response shapes.
The Coven Stack
Last updated on