Local harness substrate for project-scoped agent sessions
Run Codex, Claude Code, GitHub Copilot CLI, 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, Linux, and Windows x64. 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.
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.
- You choose the harness — Codex, Claude Code, GitHub Copilot CLI, 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 same-user local IPC 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. OpenClaw integrates only through the opt-in @opencoven/coven plugin in packages/openclaw-coven; OpenClaw core contains no Coven code.
npm install -g @opencoven/cli
coven doctor| Package | Platform |
|---|---|
@opencoven/cli |
Universal wrapper — auto-selects your platform |
@opencoven/cli-macos |
macOS Apple Silicon |
@opencoven/cli-macos-x64 |
macOS Intel x64 |
@opencoven/cli-linux-x64 |
glibc-based Linux x64 (Alpine unsupported) |
@opencoven/cli-windows |
Windows x64 |
The memory dashboard is an opt-in companion installed separately with
npm install -g @opencoven/coven-memory-dashboard (Node.js 24+); see
docs/reference/cli-observe.md.
Install routes (npm, cargo, source), platform behavior, service managers, and containers are documented at https://docs.opencoven.ai/docs/guide/install.
cd /path/to/your/project
# 1. Complete provider-owned login
coven setup codex
# 2. Check local readiness
coven doctor
# 3. Start the daemon
coven daemon start
# 4. Launch a session
coven run codex "fix the failing tests"
# 5. Browse and manage sessions
coven sessions
# 6. Stop the daemon when done
coven daemon stopBare coven opens the interactive Coven UI instead — see
Interactive UI. The command
reference lives at docs.opencoven.ai/docs/cli.
Public installation, CLI, daemon, harness, API, memory, and troubleshooting documentation is canonical at docs.opencoven.ai. Start with:
- Getting started
- CLI reference
- Daemon
- Harnesses
- Local API
- Memory
- Troubleshooting — or run
coven doctorfirst
This repository keeps only documentation that must evolve with the source:
| Local document | Why it remains here |
|---|---|
| API contract | Normative coven.daemon.v1 request, response, error, and compatibility contract |
| Architecture | Source-adjacent crate ownership, authority boundaries, and dependency direction |
| Session lifecycle | Normative state-machine and persistence behavior |
| Harness adapter contract | Maintainer and adapter-author implementation contract |
| CLI core functionality | Maintainer source map and verification loop |
| Documentation maintenance | Ownership rules for public docs versus repository contracts |
| Security policy | Vulnerability reporting and repository security policy |
See CONTRIBUTING.md for the first-10-minutes checkout path, the full local development loop, and the PR readiness packet. The short rules:
- Rust is the authority layer. Launch, cwd validation, PTY lifecycle, session persistence, and IPC enforcement are Rust's responsibility; clients are never the trust boundary.
- Keep harness support focused on Codex, Claude Code, and GitHub Copilot CLI until adapter contracts are stable.
- Run
python scripts/check-secrets.pybefore every PR, including docs-only changes, and never commit runtime state (.coven/,*.sqlite*,*.sock,.env*,*.key).
Performance baselines collect trend data without gating merges:
cargo build -p coven-cli --locked
node scripts/benchmark-cli.mjs --binary target/debug/coven --iterations 3 --output /tmp/coven-perf.json
node scripts/benchmark-chaos.mjs --binary target/debug/coven --output /tmp/coven-chaos.jsonBoth use disposable COVEN_HOME directories and a fixture-only fake harness; scripts/benchmark-chaos.test.mjs gates deterministically in CI.
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 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. See SECURITY.md for the policy and Safety for the public trust boundary.
The milestone ledger lives in docs/ROADMAP.md; items move when they are designed, implemented, tested, and released.
MIT © Valentina Alexander and the OpenCoven contributors — see LICENSE for full terms.
OpenCoven — One project. Any harness. Visible work.