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.

🌐 Ecosystem	💬 Community	🛠️ Development
Website	Discord	GitHub Issues
Documentation	X (@OpenCvn)	Public Roadmap
Submit Feedback		Contributing

⚠️ 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.

🔒 PRs Closed Until July 2026 — We are currently only accepting Issues and Bug Reports. Pull Requests will be closed without review until July 2026. If you have a fix or feature in mind, open an issue to track it.

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?

Without Coven	With Coven
Run `codex` directly; no persistent session history	Every run creates a session record with metadata and events
No project boundary enforcement	Agent is locked to an explicit project root; cannot escape
Lose track of agent work when the terminal closes	Sessions persist across daemon restarts via SQLite
Manually juggle multiple harness CLIs	One unified `coven run` entry point for all harnesses
No API for clients to consume agent sessions	Versioned `coven.daemon.v1` socket API for all clients
No standard way to observe or replay past work	`coven sessions` browser with Rejoin, View Log, and Archive

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, OpenMeow, 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.

Install

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

npm (recommended for users)

Verify your setup instantly with npx — no install required:

npx @opencoven/cli doctor
# or with pnpm:
pnpm dlx @opencoven/cli doctor

To use coven as a persistent command, install globally:

npm install -g @opencoven/cli
coven doctor

Available npm packages:

Package	Platform
`@opencoven/cli`	Universal wrapper — auto-selects your platform
`@opencoven/cli-macos`	macOS (arm64 + x64)
`@opencoven/cli-linux-x64`	Linux x64
`@opencoven/cli-windows`	Windows x64 (staging for next release)

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.

Requirements

Requirement	Notes
Rust stable toolchain	Required only when building from source
Git	Required
macOS or Linux	Daemon socket and PTY behavior; Windows x64 support staged for next release
Node.js 18+	Required only for npm wrapper or package/plugin development
At least one harness CLI	Codex and/or Claude Code (see below)

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.

Commands Reference

Core commands

Command	Action
`coven`	Open the beginner-friendly interactive menu
`coven tui`	Explicitly open the slash-command TUI
`coven doctor`	Detect supported harness CLIs and print install hints

Daemon lifecycle

Command	Action
`coven daemon start`	Start the local Coven daemon
`coven daemon status`	Show daemon health, PID, and socket path
`coven daemon restart`	Restart the local daemon and rebind the socket
`coven daemon stop`	Stop the local daemon

Session management

Command	Action
`coven run <harness> <prompt>`	Launch a project-scoped harness session
`coven run <harness> <prompt> --cwd <path>`	Launch from a cwd inside the project root
`coven run <harness> <prompt> --title <title>`	Set a readable session title
`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 <session-id>`	Replay/follow session output and forward input
`coven summon <session-id>`	Restore an archived session, then replay/follow it
`coven archive <session-id>`	Hide a non-running session while preserving its events
`coven sacrifice <session-id> --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.

Ritual	Reversible?	Works on	Description
Archive	✅ Yes	Non-running sessions	Hides from active list; all events preserved
Summon	N/A	Archived sessions	Restores to active list
Sacrifice	❌ No	Non-running sessions	Permanently deletes session and all events; requires `--yes`
Rejoin	N/A	Live sessions	Reattaches to running session

System diagnostics (`coven pc`, macOS-first)

Command	Action
`coven pc`	Full system report: CPU, memory, disk, top processes
`coven pc status`	One-line health summary with 🟢/🟡/🔴 indicators
`coven pc status --json`	Machine-readable health summary
`coven pc top --n 10`	Top-N processes by CPU usage
`coven pc disk`	Disk usage breakdown
`coven pc kill <pid> --confirm`	SIGTERM with PID identity re-check (requires `--confirm`)
`coven pc cache clear --confirm`	Clear `~/Library/Caches` and `/Library/Caches` (requires `--confirm`)

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

Other

Command	Action
`coven patch openclaw`	Open the OpenClaw repair rescue loop
`coven logs prune`	Manually prune session logs and raw encrypted artifacts

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

Endpoint	Method	Purpose
`/api/v1/health`	`GET`	Daemon health, API version, and capability catalog
`/api/v1/api-version`	`GET`	Active and supported API versions
`/api/v1/capabilities`	`GET`	Machine-readable capability catalog for clients
`/api/v1/sessions`	`GET`	List sessions
`/api/v1/sessions`	`POST`	Launch a session
`/api/v1/sessions/:id`	`GET`	Fetch one session
`/api/v1/events`	`GET`	Read session events (supports `afterSeq` cursor pagination)
`/api/v1/sessions/:id/events`	`GET`	Session-scoped events alias
`/api/v1/sessions/:id/log`	`GET`	Redacted log preview for a session
`/api/v1/sessions/:id/input`	`POST`	Forward input to a live session
`/api/v1/sessions/:id/kill`	`POST`	Kill a live session
`/api/v1/actions`	`POST`	Route a control-plane action (advanced clients)

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,
    "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:

Call GET /api/v1/health
Verify apiVersion === "coven.daemon.v1" and capabilities.structuredErrors === true
Check capabilities.eventCursor === "sequence" before using afterSeq pagination
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) ───────┤
  └── OpenMeow ──────────────────────────────────┘
                                                │
                                ┌───────────────▼──────────────────┐
                                │         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:

projectRoot must be explicit — no fallback
cwd must canonicalize inside the declared project root
Harness ID must be allowlisted (codex, claude)
Session IDs must exist and be in the expected state
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

Variable	Default	Description
`COVEN_HOME`	`~/.coven`	Root directory for all daemon state: SQLite database, Unix socket, logs, encryption keys
`COVEN_PERSIST_RAW_ARTIFACTS`	`0`	Set to `1` to enable local encrypted storage of raw session artifact payloads (advanced)

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:

Key	Default	Description
`persist_raw_artifacts`	`false`	Enable local encrypted storage of raw session artifacts

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

Data type	Default retention	Manual control
Redacted session event logs	30 days	`coven logs prune`
Raw encrypted artifacts (if enabled)	7 days	`coven logs prune`

OpenCoven Integrations

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

Integration	Role	How it connects
CastCodes	Primary public workspace; the local-first AI coding product built on Coven	HTTP over Unix socket
comux	Legacy terminal cockpit (useful reference; not the future public story)	HTTP over Unix socket
OpenClaw	External coding agent; integrates via opt-in plugin only	`@opencoven/coven` plugin → socket
OpenMeow	Desktop companion surface for advanced intake	Capability discovery + `/api/v1/actions`

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

Document	What it covers
Getting started	Full install → first session walkthrough
Concepts	Definitions: harness, session, project, ritual, daemon, store, client
Glossary	Term definitions for the full OpenCoven ecosystem
Architecture	Runtime topology, session lifecycle, authority boundary diagrams
API contract	Full `coven.daemon.v1` contract: shapes, cursors, error codes
Session lifecycle	Detailed state machine for sessions
Safety model	Trust boundary, local access model, data rules
Operational model	Day-to-day operation and daemon management
Client integration guide	How to build a client against the socket API
Harness adapter guide	How to implement a new harness adapter
Troubleshooting	Diagnose and resolve common issues
Public roadmap	Shipped, now, next, and later milestones
Product spec	Product requirements and design decisions
MVP plan	Current MVP scope and checklist
Future harnesses	Research notes for upcoming adapter work
Brand assets	Logo, colors, and usage guidance
Design system	Full brand reference: palette, typography, iconography
Brand adherence checklist	Checklist for brand-compliant contributions
Documentation maintenance	How docs are organized and kept up to date
Security policy	Vulnerability reporting and data handling

FAQ

Q: What is Coven, exactly?

Coven is a local Rust daemon and CLI that supervises coding-agent CLI sessions (like Codex or Claude Code) inside explicit project boundaries, records everything to SQLite, and exposes it all through a versioned local HTTP API over a Unix socket.

Q: Does Coven replace Codex or Claude Code?

No. Coven wraps them. You still use the harness CLI for its AI capabilities — Coven adds project-scoped boundaries, session persistence, and a unified API on top.

Q: Does Coven require an internet connection or an account?

No. Coven itself is fully local. Your harness CLIs (Codex, Claude Code) require their own provider authentication, but Coven stores no credentials and makes no outbound network calls.

Q: Is Windows supported?

The @opencoven/cli-windows package is staged for the next release. The daemon socket and PTY behavior currently target macOS and Linux. Adventurous Windows users may build from source.

Q: What is coven pc?

A macOS-first system diagnostics and relief tool built into the CLI. It shows CPU, memory, disk, and process health without launching a harness — useful when sessions feel slow or the daemon is sluggish to start. All read operations are side-effect-free. Write operations (kill, cache clear) require an explicit --confirm flag and cannot be bypassed.

Q: What does "Sacrifice" mean?

Sacrifice is Coven's intentionally explicit verb for permanently deleting a session and all its event history. It requires --yes on the command line so beginners don't accidentally delete work. Archive + Summon are the reversible alternatives for non-destructive session management.

Q: What is COVEN_HOME?

The directory where Coven stores all local state: SQLite database, Unix socket, logs, and encryption keys. Defaults to ~/.coven. To isolate environments (e.g., in CI), set COVEN_HOME to a separate path for each environment.

Q: Is CastCodes the same as Coven?

No. CastCodes is a separate product — the local-first AI coding workspace and primary public-facing product that runs on top of Coven. Coven is the runtime substrate. CastCodes is the workspace you open.

Q: What is the relationship with OpenClaw?

OpenClaw is an external coding agent that can optionally integrate with Coven through the @opencoven/coven plugin package. OpenClaw core contains no Coven code. The integration is strictly opt-in and requires installing the plugin separately.

Q: Can I build my own client on top of Coven?

Yes. The daemon exposes a stable coven.daemon.v1 HTTP API over a local Unix socket. All clients are untrusted for enforcement, but the API surface is stable and versioned. See docs/API-CONTRACT.md and docs/CLIENT-INTEGRATION.md.

Q: What if I want to add a new harness (like Aider or Gemini)?

See docs/HARNESS-ADAPTERS.md for the adapter contract. The v0 focus is Codex and Claude Code — new harnesses are planned for later milestones after adapter contracts are stable.

Troubleshooting

The fastest first step for any broken setup:

coven doctor

coven doctor checks store readiness, project detection, daemon status, and harness availability — and prints specific next steps for every failure branch.

Quick reference

Symptom	First step
`coven: command not found`	Use `npx @opencoven/cli` or build from source; verify binary is on `PATH`
`doctor` reports missing harness	Install and authenticate the harness CLI (see Requirements)
Daemon won't start	Run `coven daemon restart`; check `$COVEN_HOME` ownership and permissions
Session browser shows a table, not a UI	Terminal isn't interactive; use `coven sessions --manage` to force the browser
`cwd` rejected at launch	The working directory resolves outside the project root; use a path inside it
Stale "running" sessions after daemon crash	Run `coven sessions --all`; archive or sacrifice orphaned records
Sessions feel slow / daemon sluggish	Run `coven pc status` to check system pressure; `coven pc top --n 10` for CPU culprits
`coven attach` won't accept input	The session is not live; attach replays logs for completed or archived sessions
Secret scan fails	Remove the secret from your working tree; rotate it if it entered git history
API version mismatch	Update Coven to match the client's expected contract, or update the client

For the full diagnostic flowchart and detailed resolution steps, see docs/TROUBLESHOOTING.md.

Contributing

⚠️ Contribution Status — Updated May 2026

We are currently only accepting Issues and Bug Reports. Pull Requests will not be reviewed or merged until July 2026. Please do not open PRs at this time — they will be closed without review. If you have a fix or feature in mind, open an issue to track it and we will pick it up when the window reopens.

First 10 minutes (source checkout)

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

A healthy first pass: the workspace builds, doctor prints setup status, and the smoke test passes. The smoke test uses an isolated temporary COVEN_HOME and injects a fake codex binary into PATH — it does not require real harness credentials or a network connection.

Local development loop

# Build
cargo build --workspace

# Rust checks (required before any PR)
cargo fmt --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace --locked

# Secret scanner (required before any PR)
python scripts/check-secrets.py

# Smoke test (required for daemon/session/attach/ritual changes)
cargo test -p coven-cli --test smoke -- --nocapture

# Manual smoke run — use a throwaway project, not a real repository
cargo run -p coven-cli -- daemon start
cargo run -p coven-cli -- run codex "say hello from coven"
cargo run -p coven-cli -- sessions
cargo run -p coven-cli -- daemon stop

Architecture rules for contributors

Rust is the authority layer. Process launch, cwd/project-root validation, PTY lifecycle, session persistence, and socket request enforcement are all Rust's responsibility. TypeScript clients improve UX but are never the trust boundary.
All clients are untrusted for enforcement — this includes comux and the OpenClaw plugin.
Keep harness support focused. v0 targets Codex and Claude Code only until adapter contracts are stable.
OpenClaw separation. Do not place Coven code in OpenClaw core. The integration belongs in packages/openclaw-coven as @opencoven/coven.
No future orchestration commands as user-facing until they exist in the CLI and socket API.

Documentation rules

Use OpenCoven for the ecosystem and organization. Use Coven for the CLI and daemon product.
The user-facing command is always coven — never opencoven or @opencoven in user-facing documentation.
Use canonical community references: discord.gg/opencoven and @OpenCvn.
Use placeholders in all examples: /path/to/project, /Users/example, session-1, intent-1.
Run python scripts/check-secrets.py before submitting any PR, including docs-only changes.
Update docs whenever command behavior, API behavior, or trust boundaries change.

Maintainer release checklist

cargo fmt --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace --locked
python scripts/check-secrets.py
# For package releases: verify package contents with dry run, attach checksums for native binaries

See CONTRIBUTING.md for the full development loop, release checklist, and documentation standards.

Code of Conduct

OpenCoven is committed to building a welcoming, respectful community where people of all backgrounds and experience levels can contribute and learn.

We expect all contributors and community members to:

Be respectful and kind in all interactions — issues, PRs, Discord, and X
Focus criticism on ideas and code, not people
Welcome newcomers and answer questions with patience
Assume good faith before assuming bad

We do not tolerate:

Harassment, discrimination, or abuse in any form
Personal attacks or derogatory language
Sustained or repeated disruptive behavior

To report unacceptable behavior, contact the maintainers privately through GitHub or Discord. Reports will be handled with discretion.

Roadmap

Last updated: May 2026. See docs/ROADMAP.md for detailed milestone checklists with individual items.

Status	Milestone	Summary
✅ Shipped	A: Local runtime foundation	`coven` CLI, Rust daemon, PTY sessions, SQLite ledger, versioned `coven.daemon.v1` API, Codex + Claude adapters, npm packages
🔄 Now	B: CastCodes workspace	CastCodes as primary public workspace; Cast Agent + Coven integration direction
🔄 Now	C: Community transparency	Public roadmap, Discord update cadence, public issue board
📋 Next	D: Harness expansion	Generic command adapter from real usage, third harness proof, compatibility docs
🔬 Next/Lab	E: Visible lane → verify → review	CastCodes-native agent lanes, live session display, verification gates, explicit PR/merge workflow
🔭 Later	F: Multi-harness orchestration	Handoff protocol, capability routing, multi-instance coordination, audit dashboard (Phases 1–4)

The roadmap is written as a community-facing progress ledger, not an internal promise sheet. Items move when they are designed, implemented, tested, and released. Dates are avoided unless a release is already scheduled.

Security

Coven is pre-1.0 software. Treat it accordingly:

Do not run untrusted harnesses or prompts in sensitive repositories. Session logs capture harness output; if the harness dumps secrets, Coven logs them.
Do not commit runtime state. .coven/, *.sqlite, *.sock, .env* files, and encryption keys should never enter source control.
Do not paste secrets into prompts. Event payloads are redacted before API display, but defense in depth starts with not having secrets in prompts.

Reporting vulnerabilities: Please use GitHub Security Advisories for this repository. If advisories are unavailable, contact the maintainer privately. Do not post exploit details in public issues.

See SECURITY.md for the full security policy and docs/SAFETY-MODEL.md for the trust boundary and local access model.

License

Community & Support

Channel	Link
🌐 Website	opencoven.ai
📝 Feedback	feedback.opencoven.ai
💬 Discord	discord.gg/opencoven
🐦 X / Twitter	@OpenCvn
🐛 Issues & Bug Reports	GitHub Issues
📖 Documentation	`docs/` directory
🗺️ Public Roadmap	docs/ROADMAP.md

OpenCoven — One project. Any harness. Visible work.

Name		Name	Last commit message	Last commit date
Latest commit History 365 Commits
.github		.github
assets/opencoven		assets/opencoven
brand		brand
crates		crates
docs		docs
npm		npm
packages		packages
scripts		scripts
skills		skills
specs		specs
web		web
.gitignore		.gitignore
CHAT-QUICKSTART.md		CHAT-QUICKSTART.md
CONTRIBUTING.md		CONTRIBUTING.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
DESIGN.md		DESIGN.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
deny.toml		deny.toml

Folders and files

Latest commit

History

Repository files navigation

Coven

Table of Contents

What is Coven?

Why Coven?

Features

Install

npm (recommended for users)

Build from source (recommended for contributors)

Quick Start

Option A — Interactive menu (recommended for new users)

Option B — Direct commands

Option C — OpenClaw rescue loop

Requirements

Installing harness CLIs

Commands Reference

Core commands

Daemon lifecycle

Session management

System diagnostics (coven pc, macOS-first)

Other

Local API

Endpoint reference

Recommended client handshake

Architecture

Runtime topology

Authority boundary

Session lifecycle

Repository Structure

Configuration

Environment variables

Configuration file

What should never enter your repository

Data retention defaults

OpenCoven Integrations

CastCodes

comux (legacy reference)

Documentation

FAQ

Troubleshooting

Quick reference

Contributing

First 10 minutes (source checkout)

Local development loop

Architecture rules for contributors

Documentation rules

Maintainer release checklist

Code of Conduct

Roadmap

Security

License

Community & Support

About

Topics

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 5

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

System diagnostics (`coven pc`, macOS-first)

Packages