Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.opencoven.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Coven 🜨

OpenCoven

“Bring any familiar into the circle.”

OpenCoven is an open ecosystem for persistent AI familiars. Coven is the local runtime substrate that supervises every harness — Codex, Claude Code, and future Hermes, Aider, and Gemini CLIs — inside explicit project boundaries.
Launch a session, watch the PTY, attach later, archive when done. One daemon, one socket, every familiar on equal footing.

Get started

Install Coven, run coven doctor, and launch your first harness session in about five minutes.

Concepts

Familiars, harnesses, sessions, rituals, daemon, and the local socket authority boundary.

Open the CLI

Every command, every flag, every ritual — coven, coven run, coven sessions, and friends.

​
What is Coven?

Coven is a local-first runtime substrate: a single Rust daemon that owns harness PTYs, session state, and an append-only event ledger on your own machine. Clients like the coven CLI/TUI, the comux cockpit, OpenMeow, and the external OpenClaw plugin all coordinate through one versioned HTTP-over-Unix-socket contract. Who is it for? Developers and operators who want their AI familiars to keep running locally, remember what they did, and stay inside project boundaries you can audit. What makes it different?
  • Local-first — the daemon, the store, and the socket all live under $COVEN_HOME. No cloud relay, no daemon OAuth.
  • Harness-neutral — Codex and Claude Code today; Hermes, Aider, Gemini, and custom adapters next. Same lifecycle, same rituals.
  • Project-rooted — every launch carries an explicit project root and canonicalized working directory. The Rust daemon revalidates each request.
  • Inspectable — sessions and events are SQLite rows you can browse with coven sessions, replay with coven attach, or sacrifice when you no longer need them.
  • MIT licensed — packaged for early adopters under @opencoven/*, command always coven.
What do you need? A Rust stable toolchain (or the published @opencoven/cli wrapper), at least one supported harness CLI on PATH, and a project to run inside.

​
How it works

The daemon is the single source of truth for sessions, PTY lifecycle, and capability routing.

​
Key capabilities

Harness-neutral runtime

Codex, Claude Code, and future Hermes/Aider/Gemini adapters launched through one supervised PTY layer.

Persistent familiars

Named agents with memory, tools, identity, roles, and continuity across sessions.

Project-scoped sessions

Every session pins a canonical project root and refuses to wander.

Append-only event log

Replay output, recover from daemon restarts, audit what a familiar actually did.

Rituals

Archive, summon, and sacrifice — explicit, beginner-safe verbs around destructive operations.

Local socket API

GET /api/v1/health first; then sessions, events, capabilities, and actions over Unix socket.

​
Quick start

1

Install Coven

npm install -g @opencoven/cli
Building from source? See Install from source.
2

Check your environment

coven doctor
doctor reports whether codex and claude are on PATH, whether the daemon socket can bind, and what to install next.
3

Start the daemon

coven daemon start
coven daemon status
4

Launch your first session

cd /path/to/your/project
coven run codex "describe this repo"
Or open the human session browser:
coven sessions
Need the full install and developer setup? See Getting started.

​
Session browser

coven sessions opens a human-friendly browser of every live and archived session. Pick one, then choose a ritual:
  • Rejoin — attach to a live PTY and follow its output.
  • View log — open the append-only event log.
  • Summon — restore an archived session into the active list.
  • Archive — hide a finished session without deleting events.
  • Sacrifice — permanently delete a non-running session (requires --yes).
Pipe-friendly variants exist too: coven sessions --plain for tables, coven sessions --json for clients.

​
Configuration (optional)

Coven state lives under $COVEN_HOME (defaulting to ~/.coven on macOS/Linux). The daemon binds a Unix socket at <covenHome>/coven.sock and refuses TCP by default.
  • If you do nothing, Coven uses your existing local harness logins.
  • If you want to lock it down, scope $COVEN_HOME per project root or per familiar.
Example coven.toml: 
[daemon]
home = "~/.coven"
socket = "~/.coven/coven.sock"

[harnesses.codex]
enabled = true

[harnesses.claude]
enabled = true

​
Start here

Concepts

Runtime topology, authority boundary, session lifecycle, and the control plane.

Harnesses

Per-harness setup, provider auth boundary, and adapter expectations.

Local API

Versioned socket API for comux, OpenMeow, OpenClaw plugin, and your own clients.

Rituals

Archive, summon, and sacrifice — the beginner-safe verbs around session state.

Help

Common setup issues, environment variables, and how to file a diagnostics bundle.

​
Learn more

Full feature list

Authority boundary, store guarantees, supported harnesses, and roadmap signals.

Orchestration

Multi-harness handoff, capability routing, and parallel specialist lanes (Phase 1-4).

Safety model

Trust boundary, secret handling, socket posture, and automation approvals.

Troubleshooting

Daemon diagnostics, harness install hints, orphan recovery, and verification.

Brand and credits

Project origins, palette, typography, and the OpenCoven mark.