Client Integration Guide

Coven is a runtime substrate. Clients should present, route, and observe work without taking over the authority boundary.

Integration Rule

Talk to Coven through the local socket API. Do not duplicate Coven's path, harness, live-session, or deletion policy in a way that can drift from the daemon.

Recommended handshake:

Call GET /api/v1/health.
Confirm apiVersion === "coven.daemon.v1" and the needed capabilities fields are available.
Call GET /api/v1/capabilities if using control-plane actions.
Use versioned /api/v1/... routes only.

Rendering diagram…

Clients should treat the handshake as mandatory before any other request. Skipping it means depending on undefined response shapes from a future daemon version.

Client Responsibilities

Client-owned UX surfaces and daemon-owned enforcement surfaces
Surface	Owner	Group	Implementation posture
Navigation	Client-owned	Shell	Clients can decide information architecture, routing, and page transitions.
Panes	Client-owned	Workspace UI	Clients can arrange session panes, inspectors, and review surfaces.
Chat or intake UI	Client-owned	Input	Clients can collect user intent before sending an explicit daemon request.
Task forms	Client-owned	Input	Clients can shape structured prompts, project choices, and launch options.
Diff and review surfaces	Client-owned	Review	Clients can make outputs inspectable before merge, PR, archive, or cleanup actions.
Notification rendering	Client-owned	Status	Clients can translate daemon events into local notifications and badges.
Session selection	Client-owned	Workspace UI	Clients can choose which daemon sessions to list, pin, open, or hide.
Optimistic local UI state	Client-owned	Status	Clients can show pending states, but must reconcile against daemon events.
User approval UX	Client-owned	Approvals	Clients can present approvals clearly; the daemon still owns sensitive enforcement.
Project-root boundaries	Daemon-enforced	Filesystem policy	The Rust daemon must canonicalize and reject widened project roots.
cwd restrictions	Daemon-enforced	Filesystem policy	The daemon must prove cwd resolves inside the approved project root.
Harness allowlists	Daemon-enforced	Harness policy	Unsupported harness ids fail closed even if a client presents them.
Live-session checks	Daemon-enforced	Session policy	Input and kill requests require daemon-verified live session state.
Destructive deletion rules	Daemon-enforced	Session policy	Running sessions cannot be permanently deleted by client-side confidence alone.
Socket trust	Daemon-enforced	Transport policy	Clients validate the local socket anchor; daemon-side home ownership remains authoritative.
External action approvals	Daemon-enforced	Approvals	Actions that leave the machine need explicit policy and approval handling.

CastCodes and Cast Agent

CastCodes is the first-party workspace layer. Cast Agent is the Coven-native substrate manager and agent backend inside that workspace.

CastCodes and Cast Agent responsibilities
Capability	Group	Data source	Client behavior
List Coven sessions	Session discovery	Daemon or CLI JSON	Show active work without becoming the source of truth.
Launch sessions from visible project/worktree context	Launch	Daemon API	Pass explicit project root, cwd, harness id, and prompt to the daemon.
Open sessions in panes	Workspace UI	Client state	Render live or replayed work inside visible panes.
Attach or rejoin live work	Session control	Daemon API	Offer attachment only after daemon liveness checks.
Collect substrate	Context	Cast Agent	Collect active file, panes, cwd, git branch, and diagnostics without turning context into authority.
Stream gateway responses	Agent runtime	Coven Gateway	Render streaming responses while keeping daemon-backed session operations separate.
Show logs and artifacts	Review	Event log	Make completed work inspectable after process exit or daemon restart.
Review diffs	Review	Repository state	Keep file changes visible before merge or cleanup actions.
Merge, PR, archive, or clean up explicitly	Completion flow	Client commands plus daemon state	Require explicit user action for state-changing workflow steps.

CastCodes should remain useful when Coven is not installed. If Coven is missing, present clear installation and fallback states instead of assuming the daemon exists.

Cast Codes are portable intent syntax that CastCodes and Cast Agent can parse. They are not permission grants; daemon validation still decides whether a launch, input, kill, action, archive, summon, or sacrifice request is allowed.

OpenClaw Plugin

OpenClaw integration belongs in the external @opencoven/coven package, not OpenClaw core. Treat this as the supported bridge direction, not permission to move Coven code into OpenClaw or to bypass the local daemon.

The package installs an opt-in OpenClaw plugin with plugin id opencoven-coven and ACP backend id coven. The intended install path is through ClawHub:

openclaw plugins install clawhub:@opencoven/coven

For local development from the Coven repo:

openclaw plugins install ./packages/openclaw-coven --force

The bridge is a client of Coven. Its first runtime step should be the same as every other client: connect to the configured local socket, call GET /api/v1/health, verify apiVersion === "coven.daemon.v1", then depend only on documented /api/v1 behavior.

Rendering diagram…

OpenClaw plugin contract
Expectation	Posture	Boundary	Reason
Register an optional Coven backend	Do	Integration	OpenClaw can opt into Coven without making Coven a core dependency.
Require explicit plugin/backend selection	Do	Configuration	The bridge should be intentional, visible, and reversible.
Validate config for UX	Do	Client experience	Fast feedback belongs in the plugin, but it is not enforcement.
Connect to the local socket	Do	Transport	The socket API is the supported compatibility layer.
Handshake with GET /api/v1/health before launch	Do	API compatibility	apiVersion and capabilities decide whether the plugin can safely operate.
Launch sessions through POST /api/v1/sessions	Do	Launch authority	The daemon must own project, cwd, harness, and liveness validation.
Map Coven events into OpenClaw runtime events	Do	Runtime bridge	OpenClaw should observe and present Coven work without hiding provenance.
Preserve fallback behavior only when explicitly configured	Do	Operational fallback	Fallbacks should be deliberate, visible, and testable.
Treat the Rust daemon as launch authority	Do	Policy	Client integration cannot replace daemon-side checks.
Bypass the daemon for launches	Do not	Launch authority	Direct harness launches recreate the policy drift Coven exists to prevent.
Depend on OpenClaw core internals	Do not	Package design	The bridge should remain external and replaceable.
Store provider credentials	Do not	Credentials	Provider authentication stays in each harness provider flow.
Assume unversioned routes are stable	Do not	API compatibility	Clients should target the versioned local contract.
Widen project-root permissions	Do not	Filesystem policy	Only daemon validation can decide the actual launch boundary.

Compatibility is the stability gate. The plugin source lives with the Coven daemon so fixture-backed tests can change in the same work slice as API-affecting daemon changes. When /api/v1/health, /api/v1/sessions, /api/v1/events, input, or kill behavior changes, update the bridge fixtures and compatibility tests before claiming broad plugin stability.

The current bridge scope is Codex and Claude Code. Future harness ids must be explicitly configured only after the Rust daemon supports and validates them. The plugin should not expose OpenClaw tools to Coven-managed harnesses, store provider credentials, or tunnel the raw Coven socket through TCP, browser, mobile, or remote transports.

Intake Surfaces

Intake clients are best treated as presentation layers.

Intake surface responsibilities
Responsibility	Group	Boundary
Capture user intent	Input	Collect the task, then hand off to Coven instead of becoming the runtime.
Show local status	Status	Reflect daemon and client state clearly.
Present approvals	Approvals	Make consent explicit before sensitive local or external actions.
Display notifications	Status	Surface session changes without inventing state.
Hand work into Coven	Launch	Use daemon APIs for project-scoped execution.
Show session updates from Coven	Observation	Render daemon events and session records as the source of truth.

Avoid making intake clients the automation engine. Reusable automation should live behind Coven capabilities and actions so the policy boundary stays centralized.

Desktop Clients and Control Rooms

A native control room can make Coven easier to operate by showing the operational surface in one place.

Control room surfaces
Surface	Group	Source	Purpose
Active sessions	Sessions	Daemon or CLI JSON	Show live and recent work that can be opened or inspected.
Archived sessions	Sessions	Daemon or CLI JSON	Recover preserved work without crowding the active list.
Daemon health	Runtime	Health endpoint	Expose availability, API version, and capability readiness.
Project roots	Runtime	Daemon records	Make launch boundaries visible before work starts.
Harness availability	Harnesses	Doctor or capabilities	Show which CLIs are installed, authenticated, and launchable.
Client integrations	Clients	Config and capability records	Make connected tools and bridges inspectable.
Capability catalog	Control plane	Capabilities endpoint	Show supported actions without hardcoding client assumptions.
Action approval queue	Approvals	Control plane	Keep sensitive pending actions reviewable.
Logs and traces	Observability	Event log	Preserve what happened across process exits and daemon restarts.
Docs and troubleshooting links	Support	Docs site	Route users from a broken state to the next useful action.

Use coven sessions --json for active sessions and coven sessions --json --all when the client needs archived records too. The CLI returns a top-level object with a sessions array, and each record uses the same SessionRecord field names exposed by the daemon API, including project_root, status, created_at, updated_at, and nullable archived_at.

The control room should still use the same socket API and capability handshake as other clients.

Desktop Automation Adapters

Desktop automation is useful when an app has no clean API. It is also powerful enough to need clear policy.

Recommended pattern:

user request
  -> client captures intent
  -> Coven exposes capability and policy hints
  -> client asks for approval when required
  -> Coven routes a known action id
  -> adapter performs the local UI action
  -> event/result returns to the client

Do not let UI clients bind directly to OS automation libraries and then call that "Coven integration." The reusable boundary should be Coven's control plane.

Compatibility Expectations

Client compatibility expectations
Rule	Risk area	Client behavior
Use /api/v1	API versioning	Route all supported calls through the versioned local contract.
Call health first	Handshake	Confirm daemon availability and compatible apiVersion before other requests.
Ignore unknown additive fields when safe	Forward compatibility	Avoid breaking when the daemon adds optional response data.
Fail closed on unknown required behavior	Safety	Do not guess when a new daemon response changes required semantics.
Test against representative daemon responses	Compatibility tests	Keep bridge behavior pinned to real response shapes.
Update docs/API-CONTRACT.md when response shapes change	Contract drift	Document API-affecting daemon changes in the same work slice.

Error Handling

A good client should translate daemon errors into action-oriented UI.

Daemon error handling matrix
Condition	Category	Client response
Daemon unavailable	Runtime	Show start or restart instructions.
Unsupported API version	Compatibility	Ask the user to update Coven or the client.
Missing harness	Harnesses	Show coven doctor guidance and install/auth hints.
outside-root cwd	Filesystem policy	Explain the project boundary and offer a valid cwd choice.
Session not live	Session policy	Offer log viewing instead of live input.
Destructive action blocked	Session policy	Explain that the session is running or lacks confirmation.

Client Integration

On this page