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 — v0 focuses on Codex and Claude Code 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 menu (recommended for new users)

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

The menu opens with a Start here guide, checks your local setup, and shows the safest first command to try. Type a task directly (e.g., fix the failing tests) or use slash commands like /run codex fix the failing tests. Press h or type /help for examples.

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

Daemon lifecycle

Session management

--stream-json --stream-json-input| Also read JSONL user messages from stdin | |coven sessions| Open the session browser in a terminal; print a table when piped | |coven sessions --all| Browse active and archived sessions; print all when piped | |coven sessions --manage| Force the interactive session browser | |coven sessions --plain| Force plain table output for scripts or copying | |coven sessions --json| Output sessions as JSON | |coven sessions --json --all| Output all sessions (including archived) as JSON | |coven attach | Replay/follow session output and forward input | |coven summon | Restore an archived session, then replay/follow it | |coven archive | Hide a non-running session while preserving its events | |coven sacrifice --yes` | Permanently delete a non-running session and its events |

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.