Coven

Local harness substrate for project-scoped agent sessions

Run Codex, Claude Code, and future coding harnesses inside explicit local project boundaries. Launch, observe, attach, and coordinate agent work through one neutral runtime substrate.

⚠️ Early MVP — Coven is a local-first runtime in active development. It is usable by adventurous developers on macOS and Linux. The npm package is live. Expect rough edges.

External PRs are open — Start from an issue for larger changes, keep PRs scoped, and include the readiness packet requested by the PR template.

Table of Contents

• What is Coven?
• Why Coven?
• Features
• Requirements
• Install
• Quick Start
• Commands Reference
• Local API
• Architecture
• Repository Structure
• Configuration
• OpenCoven Integrations
• Documentation
• FAQ
• Troubleshooting
• Contributing
• Code of Conduct
• Roadmap
• Security
• License
• Community & Support

What is Coven?

Coven is the local harness substrate for the OpenCoven ecosystem. It gives coding-agent CLIs like Codex and Claude Code a shared room where project work can happen visibly and safely.

One project. Any harness. Visible work.

Coven doesn't replace your coding agent, your UI, or other clients. It acts as a neutral runtime layer:

• You choose the harness — Codex, Claude Code, or future adapters.
• Coven owns the session — project-scoped boundaries, PTY execution, event logging, SQLite persistence.
• Clients present the work — CastCodes, the CLI/TUI, comux, or your own integration over the local socket API.

The Rust daemon is the authority boundary. All clients — including the CLI itself — are convenience layers. Security decisions flow inward to the daemon, never outward to clients.

Why Coven?

Features

• 🏠 Project-root boundaries — Every launch is tied to an explicit repository or project root. The daemon rejects working directories that escape the declared boundary.
• 🔌 Harness-neutral runtime — supported harnesses are Codex, Claude Code, and GitHub Copilot CLI, with a clean adapter path for future harnesses (Hermes, Aider, Gemini, and user-defined CLIs).
• 🖥️ Interactive session browser — Live and completed work can be selected, rejoined, viewed, archived, restored, or sacrificed without memorizing IDs.
• 📡 Attachable PTY sessions — Live sessions can be replayed or followed from explicit CLI verbs.
• 🔌 Local daemon API — CastCodes, comux, and the OpenClaw plugin coordinate through one versioned socket contract (coven.daemon.v1).
• 🗄️ SQLite-backed history — Session metadata and event logs survive daemon restarts.
• 🦀 Rust authority layer — Launch, cwd, input, kill, and path-sensitive requests are revalidated in Rust. Clients are never the trust boundary.
• 🔒 External OpenClaw bridge — @opencoven/coven is an opt-in plugin; OpenClaw core does not include Coven code.
• 📦 @opencoven namespace — CLI wrapper packages live under @opencoven/*; the user-facing command is always coven.
• 🩺 System diagnostics — coven pc (macOS-first) surfaces CPU, memory, disk, and process health without launching a harness.

Requirements

Installing harness CLIs

Run coven doctor first — it prints specific install hints for any missing harness.

Codex (OpenAI):

npm install -g @openai/codex
# or: brew install --cask codex
codex login

Claude Code (Anthropic):

npm install -g @anthropic-ai/claude-code
claude doctor

After installing and authenticating, run coven doctor again to confirm the harness is detected. If doctor still reports missing, ensure the harness binary is on your PATH.

Install

Coven is available as an npm wrapper for the fastest install, or you can build from source.

npm (recommended)

Install globally:

npm install -g @opencoven/cli
coven doctor

Available npm packages:

Build from source (recommended for contributors)

git clone https://github.com/OpenCoven/coven.git
cd coven
cargo build --workspace
cargo run -p coven-cli -- doctor

Note: Building from source requires Rust stable. See Requirements.

Quick Start

Option A — Interactive UI (recommended for new users)

cd /path/to/your/project
coven
# or explicitly:
coven chat

Bare coven opens the interactive Coven UI, powered by the Coven engine. The first time you run it, coven offers to download and install the engine automatically (or install it anytime with coven engine install); it's a version-pinned, checksum-verified binary that coven manages for you — there's no separate package to install. You can also pass a task directly — coven "fix the failing tests" — and Coven will show a plan card and run it in a recorded session.

Option B — Direct commands

cd /path/to/your/project

# 1. Verify setup
coven doctor

# 2. Start the daemon
coven daemon start

# 3. Launch a session
coven run codex "fix the failing tests"
# or with Claude Code:
coven run claude "polish this UI"

# 4. Browse and manage sessions
coven sessions

# 5. Stop the daemon when done
coven daemon stop

Option C — OpenClaw rescue loop

If OpenClaw breaks, Coven provides a predictable repair room:

coven patch openclaw

Choose a repo, choose a harness, get a verified patch.

Commands Reference

Core commands

Harness adapters

Experimental opt-in recipe: coven adapter install grok adds the Grok Build adapter without promoting it into Coven's bundled default harness set.

Daemon lifecycle

Session management

attach, summon, archive, sacrifice, kill, and the sessions show/events/log subcommands accept a unique prefix of the session id (e.g. coven attach 9099), so you don't have to paste full UUIDs.

Session rituals are intentionally explicit. Archive is reversible and keeps the full event ledger. Summon brings an archived session back. Sacrifice is destructive, refuses live sessions, and requires --yes so beginners don't delete work by accident.

System diagnostics (coven pc, macOS-first)

All read operations are side-effect-free. Write operations (kill, cache clear) require --confirm and cannot be bypassed. Termination is SIGTERM only — no SIGKILL.

Coven observability (Cave parity from the terminal)

Everything the CovenCave dashboard reads is also visible from the CLI. All of these are read-only, work without a running daemon, and take --json for machine-readable output that carries the same body as the daemon API route.

Parallel work protocol (worktrees, claims, hooks)

Other

Local API

The daemon exposes a versioned HTTP API over a Unix socket. The current public contract is coven.daemon.v1 (prefix: /api/v1).

Endpoint reference

Recommended client handshake

All API clients should start with a health negotiation:

# Example: health check via Unix socket
curl --unix-socket ~/.coven/coven.sock http://localhost/api/v1/health

Example response:

{
  "ok": true,
  "apiVersion": "coven.daemon.v1",
  "covenVersion": "0.0.10",
  "capabilities": {
    "sessions": true,
    "events": true,
    "travel": true,
    "scheduler": true,
    "eventCursor": "sequence",
    "structuredErrors": true
  },
  "daemon": {
    "pid": 12345,
    "startedAt": "2026-05-09T06:43:00Z",
    "socket": "/Users/alice/.coven/coven.sock"
  }
}

Before depending on any other endpoint:

1. Call GET /api/v1/health
2. Verify apiVersion === "coven.daemon.v1" and capabilities.structuredErrors === true
3. Check capabilities.eventCursor === "sequence" before using afterSeq pagination
4. Only then depend on the documented v1 sessions/events shapes

All API errors use a structured envelope. Branch on error.code, never on error.message:

{
  "error": {
    "code": "session_not_found",
    "message": "Session was not found.",
    "details": { "sessionId": "abc-123" }
  }
}

Treat the socket API as the product contract. Clients may validate for better UX, but the Rust daemon remains the authority boundary. See docs/API-CONTRACT.md for the full versioned contract including error codes, cursor pagination, session shapes, and compatibility rules.

Architecture

Runtime topology

Coven is a local-first harness substrate. The Rust daemon is the authority boundary. All clients — including the CLI/TUI — are untrusted for enforcement purposes.

Developer
  │
  ├── CastCodes workspace ─────────────────────┐
  ├── coven CLI / TUI ─────────────────────────┤ HTTP over Unix socket
  ├── comux (legacy/reference) ────────────────┤ ~/.coven/coven.sock
  └── @opencoven/coven (OpenClaw plugin) ───────┘
                                                │
                                ┌───────────────▼──────────────────┐
                                │         Coven Rust Daemon         │
                                │                                   │
                                │  ┌───────────────────────────┐   │
                                │  │    Authority boundary      │   │
                                │  │  • Canonicalize project root│  │
                                │  │  • Validate cwd in root   │   │
                                │  │  • Allowlist harness id   │   │
                                │  │  • Validate session state │   │
                                │  │  • Route action via policy │  │
                                │  └────────────┬──────────────┘   │
                                │               │                   │
                                │  ┌────────────▼─────────────┐    │
                                │  │   Harness adapter router  │    │
                                │  └───────┬──────────────┬───┘    │
                                │          │              │          │
                                │      ┌───▼──┐      ┌───▼───┐     │
                                │      │Codex │      │Claude │     │
                                │      │ PTY  │      │  PTY  │     │
                                │      └───┬──┘      └───┬───┘     │
                                │          │              │          │
                                │  ┌───────▼──────────────▼──────┐  │
                                │  │  SQLite session ledger +     │  │
                                │  │  append-only event log       │  │
                                │  └──────────────────────────────┘  │
                                └───────────────────────────────────┘

Authority boundary

The Rust daemon validates every request before acting:

1. projectRoot must be explicit — no fallback
2. cwd must canonicalize inside the declared project root
3. Harness ID must be allowlisted (codex, claude)
4. Session IDs must exist and be in the expected state
5. All harness commands are built with argv APIs — never sh -c

Clients may improve UX by validating early, but they are never the enforcement boundary. A client cannot widen the project boundary, bypass the harness allowlist, or escape session state validation.

Session lifecycle

coven run codex "fix tests"
        │
        ▼
POST /api/v1/sessions  { projectRoot, cwd, harness, prompt }
        │
        ▼
Daemon: canonicalize → validate → spawn or reject
        │
        ▼
Session record created in SQLite
        │
        ▼
Harness spawned in PTY → output events streamed to SQLite
        │
        ▼
coven sessions → Rejoin / View Log / Archive / Sacrifice

For full architecture diagrams (including Mermaid flow charts), see docs/ARCHITECTURE.md.

Repository Structure

coven/
├── .github/                    # GitHub Actions workflows, issue templates
├── assets/opencoven/           # Project assets (logos, icons for npm packages)
├── brand/                      # OpenCoven brand system
│   ├── icons/                  # Brand icon set (trident, agent-node, etc.)
│   ├── social/                 # Social media assets (X, GitHub)
│   └── ui/                     # CSS color tokens and typography scale
├── crates/
│   ├── coven-cli/              # Main Rust binary — the `coven` command
│   └── coven-relay/            # Internal relay crate
├── docs/                       # Full documentation suite (see Documentation section)
├── npm/                        # npm wrapper package source for @opencoven/cli
├── packages/
│   └── openclaw-coven/         # External OpenClaw bridge plugin (@opencoven/coven)
├── scripts/
│   └── check-secrets.py        # CI / pre-release secret scanner
├── skills/opencoven-design/    # Design skill files
├── web/                        # Web surface files
├── Cargo.lock                  # Locked Rust dependency tree
├── Cargo.toml                  # Rust workspace manifest
├── CONTRIBUTING.md             # Contribution guidelines
├── DESIGN.md                   # Full brand and design system reference
├── LICENSE                     # MIT license
├── README.md                   # This file
└── SECURITY.md                 # Security policy

Key directories:

• crates/coven-cli — Everything that becomes the coven binary. This is where daemon, PTY adapter, session store, socket API, and CLI surface live in Rust.
• packages/openclaw-coven — The opt-in bridge between OpenClaw and Coven. Lives here (not in OpenClaw core) to keep the trust boundary clean. Published as @opencoven/coven.
• scripts/check-secrets.py — Required pre-release and pre-PR scan. Run it before pushing to avoid leaking credentials into git history.
• docs/ — The canonical documentation suite. All product docs, architecture, API contract, safety model, and roadmap live here.

Configuration

Environment variables

Tip: If you run Coven in CI or need isolated environments, set COVEN_HOME to a unique path per environment. Coven will create the directory if it doesn't exist.

Configuration file

Local privacy and storage settings live in <COVEN_HOME>/privacy.toml:

When enabled, raw artifacts are encrypted using a local key at <COVEN_HOME>/keys/session-artifacts.key. This file is generated automatically with private permissions and is never stored in the repository or SQLite database.

What should never enter your repository

.coven/          # Daemon state directory — local only
*.sqlite         # SQLite database files
*.sqlite3
*.db
*.sock           # Unix socket files
.env*            # Environment variable files
*.key            # Encryption key files

These patterns are covered by .gitignore. Before submitting any PR or publishing documentation, run the secret scanner:

python scripts/check-secrets.py

If the scan fails, remove the secret from your working tree. If a secret entered git history, rotate the credential before rewriting history or publishing.

Data retention defaults

OpenCoven Integrations

Coven is the runtime layer. Other surfaces in the OpenCoven ecosystem sit above it and connect through the local socket API.

Important: OpenClaw core does not contain Coven code. The integration lives exclusively in packages/openclaw-coven and publishes as @opencoven/coven. This separation keeps the trust boundary clean — the plugin is treated as an untrusted socket client, and the Rust daemon revalidates every request it makes.

CastCodes

CastCodes is the primary product users open: terminal/code workspace, visible agent lanes, review flows, and approval UX. It is the first-contact public story for Coven.

The intended flow is:

User → CastCodes → coven run → Coven daemon → Harness PTY
Harness output → Coven event log → CastCodes session view

comux (legacy reference)

comux is a standalone terminal cockpit that proved the tmux-cockpit model for parallel agent work. Its useful primitives (worktree isolation, pane menus, agent launcher registry) are being folded into CastCodes-native concepts. comux is no longer the future-facing public surface.

Documentation