{"id":50288814,"url":"https://github.com/opencoven/coven","last_synced_at":"2026-07-05T03:00:28.995Z","repository":{"id":354212937,"uuid":"1222160568","full_name":"OpenCoven/coven","owner":"OpenCoven","description":"Local harness substrate for project-scoped agent sessions.","archived":false,"fork":false,"pushed_at":"2026-06-30T05:07:09.000Z","size":76584,"stargazers_count":29,"open_issues_count":7,"forks_count":15,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-30T06:08:01.699Z","etag":null,"topics":["ai-agents","anthropic","claude-code","codex","harness","harness-agnostic","harness-engineering","harness-framework","meta-harness","model-agnostic","openai","openclaw","opencoven","substrate","substrate-runtime"],"latest_commit_sha":null,"homepage":"https://opencoven.ai","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OpenCoven.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"docs/ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-27T05:18:06.000Z","updated_at":"2026-06-30T05:07:06.000Z","dependencies_parsed_at":null,"dependency_job_id":"ab630939-a872-476f-aa0d-1b877f4e0e93","html_url":"https://github.com/OpenCoven/coven","commit_stats":null,"previous_names":["opencoven/coven"],"tags_count":38,"template":false,"template_full_name":null,"purl":"pkg:github/OpenCoven/coven","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenCoven%2Fcoven","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenCoven%2Fcoven/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenCoven%2Fcoven/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenCoven%2Fcoven/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OpenCoven","download_url":"https://codeload.github.com/OpenCoven/coven/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenCoven%2Fcoven/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35141966,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-05T02:00:06.290Z","response_time":100,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","anthropic","claude-code","codex","harness","harness-agnostic","harness-engineering","harness-framework","meta-harness","model-agnostic","openai","openclaw","opencoven","substrate","substrate-runtime"],"created_at":"2026-05-28T04:04:23.612Z","updated_at":"2026-07-05T03:00:28.984Z","avatar_url":"https://github.com/OpenCoven.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/opencoven/opencoven.svg\" alt=\"OpenCoven logo\" width=\"128\" height=\"128\"\u003e\n\u003c/p\u003e\n\n# Coven\n\n**Local harness substrate for project-scoped agent sessions**\n\nRun Codex, Claude Code, and future coding harnesses inside explicit local project boundaries.\nLaunch, observe, attach, and coordinate agent work through one neutral runtime substrate.\n\n[![MIT License](https://img.shields.io/badge/license-MIT-9A8ECD?style=flat-square)](LICENSE)\n[![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux-9A8ECD?style=flat-square)](#requirements)\n[![npm](https://img.shields.io/badge/npm-%40opencoven%2Fcli-9A8ECD?style=flat-square)](https://www.npmjs.com/package/@opencoven/cli)\n[![Built with Rust](https://img.shields.io/badge/built%20with-Rust-9A8ECD?style=flat-square)](https://www.rust-lang.org/)\n\n| 🌐 **Ecosystem**                                      | 💬 **Community**                            | 🛠️ **Development**                                             |\n| :---------------------------------------------------- | :------------------------------------------ | :------------------------------------------------------------- |\n| [**Website**](https://opencoven.ai/)                  | [**Discord**](https://discord.gg/opencoven) | [**GitHub Issues**](https://github.com/OpenCoven/coven/issues) |\n| [**Documentation**](https://docs.opencoven.ai/)       | [**X (\\@OpenCvn)**](https://x.com/OpenCvn)  | [**Public Roadmap**](docs/ROADMAP.md)                          |\n| [**Submit Feedback**](https://feedback.opencoven.ai/) |                                             | [**Contributing**](CONTRIBUTING.md)                            |\n\n---\n\n\u003e **⚠️ 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.\n\u003e\n\u003e **External PRs are open** — Start from an issue for larger changes, keep PRs scoped, and include the readiness packet requested by the PR template.\n\n---\n\n## Table of Contents\n\n- [What is Coven?](#what-is-coven)\n- [Why Coven?](#why-coven)\n- [Features](#features)\n- [Requirements](#requirements)\n- [Install](#install)\n- [Quick Start](#quick-start)\n- [Commands Reference](#commands-reference)\n- [Local API](#local-api)\n- [Architecture](#architecture)\n- [Repository Structure](#repository-structure)\n- [Configuration](#configuration)\n- [OpenCoven Integrations](#opencoven-integrations)\n- [Documentation](#documentation)\n- [FAQ](#faq)\n- [Troubleshooting](#troubleshooting)\n- [Contributing](#contributing)\n- [Code of Conduct](#code-of-conduct)\n- [Roadmap](#roadmap)\n- [Security](#security)\n- [License](#license)\n- [Community \u0026 Support](#community--support)\n\n---\n\n## What is Coven?\n\nCoven is the local harness substrate for the [OpenCoven](https://github.com/OpenCoven) ecosystem. It gives coding-agent CLIs like [Codex](https://github.com/openai/codex) and [Claude Code](https://docs.anthropic.com/en/docs/claude-code) a shared room where project work can happen visibly and safely.\n\n\u003e **One project. Any harness. Visible work.**\n\nCoven doesn't replace your coding agent, your UI, or other clients. It acts as a neutral runtime layer:\n\n- **You choose the harness** — Codex, Claude Code, or future adapters.\n- **Coven owns the session** — project-scoped boundaries, PTY execution, event logging, SQLite persistence.\n- **Clients present the work** — CastCodes, the CLI/TUI, comux, or your own integration over the local socket API.\n\nThe 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.\n\n---\n\n## Why Coven?\n\n| Without Coven                                       | With Coven                                                  |\n| --------------------------------------------------- | ----------------------------------------------------------- |\n| Run `codex` directly; no persistent session history | Every run creates a session record with metadata and events |\n| No project boundary enforcement                     | Agent is locked to an explicit project root; cannot escape  |\n| Lose track of agent work when the terminal closes   | Sessions persist across daemon restarts via SQLite          |\n| Manually juggle multiple harness CLIs               | One unified `coven run` entry point for all harnesses       |\n| No API for clients to consume agent sessions        | Versioned `coven.daemon.v1` socket API for all clients      |\n| No standard way to observe or replay past work      | `coven sessions` browser with Rejoin, View Log, and Archive |\n\n---\n\n## Features\n\n- **🏠 Project-root boundaries** — Every launch is tied to an explicit repository or project root. The daemon rejects working directories that escape the declared boundary.\n- **🔌 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).\n- **🖥️ Interactive session browser** — Live and completed work can be selected, rejoined, viewed, archived, restored, or sacrificed without memorizing IDs.\n- **📡 Attachable PTY sessions** — Live sessions can be replayed or followed from explicit CLI verbs.\n- **🔌 Local daemon API** — CastCodes, comux, and the OpenClaw plugin coordinate through one versioned socket contract (`coven.daemon.v1`).\n- **🗄️ SQLite-backed history** — Session metadata and event logs survive daemon restarts.\n- **🦀 Rust authority layer** — Launch, cwd, input, kill, and path-sensitive requests are revalidated in Rust. Clients are never the trust boundary.\n- **🔒 External OpenClaw bridge** — `@opencoven/coven` is an opt-in plugin; OpenClaw core does not include Coven code.\n- **📦 @opencoven namespace** — CLI wrapper packages live under `@opencoven/*`; the user-facing command is always `coven`.\n- **🩺 System diagnostics** — `coven pc` (macOS-first) surfaces CPU, memory, disk, and process health without launching a harness.\n\n---\n\n## Requirements\n\n| Requirement                  | Notes                                                                       |\n| ---------------------------- | --------------------------------------------------------------------------- |\n| **Rust stable toolchain**    | Required only when building from source                                     |\n| **Git**                      | Required                                                                    |\n| **macOS, Linux, or Windows x64** | Native npm packages are published for all three platforms                  |\n| **Node.js 18+**              | Required only for npm wrapper or package/plugin development                 |\n| **At least one harness CLI** | Codex and/or Claude Code (see below)                                        |\n\n### Installing harness CLIs\n\nRun `coven doctor` first — it prints specific install hints for any missing harness.\n\n**Codex (OpenAI):**\n\n```bash\nnpm install -g @openai/codex\n# or: brew install --cask codex\ncodex login\n```\n\n**Claude Code (Anthropic):**\n\n```bash\nnpm install -g @anthropic-ai/claude-code\nclaude doctor\n```\n\nAfter 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`.\n\n---\n\n## Install\n\nCoven is available as an npm wrapper for the fastest install, or you can build from source.\n\n### npm (recommended)\n\nInstall globally:\n\n```bash\nnpm install -g @opencoven/cli\ncoven doctor\n```\n\n**Available npm packages:**\n\n| Package                    | Platform                                       |\n| -------------------------- | ---------------------------------------------- |\n| `@opencoven/cli`           | Universal wrapper — auto-selects your platform |\n| `@opencoven/cli-macos`     | macOS Apple Silicon                            |\n| `@opencoven/cli-linux-x64` | Linux x64                                      |\n| `@opencoven/cli-windows`   | Windows x64                                    |\n\n### Build from source (recommended for contributors)\n\n```bash\ngit clone https://github.com/OpenCoven/coven.git\ncd coven\ncargo build --workspace\ncargo run -p coven-cli -- doctor\n```\n\n\u003e **Note:** Building from source requires Rust stable. See [Requirements](#requirements).\n\n---\n\n## Quick Start\n\n### Option A — Interactive menu (recommended for new users)\n\n```bash\ncd /path/to/your/project\ncoven\n# or explicitly:\ncoven tui\n```\n\nThe 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.\n\n### Option B — Direct commands\n\n```bash\ncd /path/to/your/project\n\n# 1. Verify setup\ncoven doctor\n\n# 2. Start the daemon\ncoven daemon start\n\n# 3. Launch a session\ncoven run codex \"fix the failing tests\"\n# or with Claude Code:\ncoven run claude \"polish this UI\"\n\n# 4. Browse and manage sessions\ncoven sessions\n\n# 5. Stop the daemon when done\ncoven daemon stop\n```\n\n### Option C — OpenClaw rescue loop\n\nIf OpenClaw breaks, Coven provides a predictable repair room:\n\n```bash\ncoven patch openclaw\n```\n\nChoose a repo, choose a harness, get a verified patch.\n\n---\n\n## Commands Reference\n\n### Core commands\n\n| Command        | Action                                                |\n| -------------- | ----------------------------------------------------- |\n| `coven`        | Open the beginner-friendly interactive menu           |\n| `coven tui`    | Explicitly open the slash-command TUI                 |\n| `coven doctor` | Detect supported harness CLIs and print install hints |\n\n### Daemon lifecycle\n\n| Command                | Action                                         |\n| ---------------------- | ---------------------------------------------- |\n| `coven daemon start`   | Start the local Coven daemon                   |\n| `coven daemon status`  | Show daemon health, PID, and socket path       |\n| `coven daemon restart` | Restart the local daemon and rebind the socket |\n| `coven daemon stop`    | Stop the local daemon                          |\n\n### Session management\n\n| Command                                        | Action                                                           |\n| ---------------------------------------------- | ---------------------------------------------------------------- |\n| `coven run \u003charness\u003e \u003cprompt\u003e`                 | Launch a project-scoped harness session                          |\n| `coven run \u003charness\u003e \u003cprompt\u003e --cwd \u003cpath\u003e`    | Launch from a cwd inside the project root                        |\n| `coven run \u003charness\u003e \u003cprompt\u003e --title \u003ctitle\u003e` | Set a readable session title                                     |\n| `coven run \u003charness\u003e \u003cprompt\u003e --model \u003cid\u003e`    | Forward a model override to the harness                          |\n| `coven run \u003charness\u003e \u003cprompt\u003e --think`         | Request deeper reasoning when the harness supports it            |\n| `coven run \u003charness\u003e \u003cprompt\u003e --speed \u003clevel\u003e` | Set a latency/reasoning hint: `fast`, `balanced`, or `thorough`  |\n| `coven run \u003charness\u003e --continue`               | Resume the latest active session for this project                |\n| `coven run \u003charness\u003e --continue \u003cid\u003e`          | Resume a specific session by id                                  |\n| `coven run \u003charness\u003e \u003cprompt\u003e --detach`        | Create the session record without launching the harness          |\n| `coven run \u003charness\u003e \u003cprompt\u003e --labels \u003cl\u003e`    | Attach comma-separated labels to the session                     |\n| `coven run \u003charness\u003e \u003cprompt\u003e --visibility \u003cv\u003e`| Set visibility: `private` (default), `workspace`, or `shared`   |\n| `coven run \u003charness\u003e \u003cprompt\u003e --archive`       | Auto-archive the session when the run completes                  |\n| `coven run \u003charness\u003e \u003cprompt\u003e --familiar \u003cid\u003e` | Inject a familiar identity preamble (e.g. `--familiar charm`)    |\n| `coven run \u003charness\u003e \u003cprompt\u003e --stream-json`   | Emit JSONL events on stdout (for tooling/piping)                 |\n| `coven run claude \u003cp\u003e --stream-json --stream-json-input` | Also read JSONL user messages from stdin             |\n| `coven sessions`                               | Open the session browser in a terminal; print a table when piped |\n| `coven sessions --all`                         | Browse active and archived sessions; print all when piped        |\n| `coven sessions --manage`                      | Force the interactive session browser                            |\n| `coven sessions --plain`                       | Force plain table output for scripts or copying                  |\n| `coven sessions --json`                        | Output sessions as JSON                                          |\n| `coven sessions --json --all`                  | Output all sessions (including archived) as JSON                 |\n| `coven attach \u003csession-id\u003e`                    | Replay/follow session output and forward input                   |\n| `coven summon \u003csession-id\u003e`                    | Restore an archived session, then replay/follow it               |\n| `coven archive \u003csession-id\u003e`                   | Hide a non-running session while preserving its events           |\n| `coven sacrifice \u003csession-id\u003e --yes`           | Permanently delete a non-running session and its events          |\n\n\u003e **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.\n\n| Ritual        | Reversible? | Works on             | Description                                                  |\n| ------------- | ----------- | -------------------- | ------------------------------------------------------------ |\n| **Archive**   | ✅ Yes      | Non-running sessions | Hides from active list; all events preserved                 |\n| **Summon**    | N/A         | Archived sessions    | Restores to active list                                      |\n| **Sacrifice** | ❌ No       | Non-running sessions | Permanently deletes session and all events; requires `--yes` |\n| **Rejoin**    | N/A         | Live sessions        | Reattaches to running session                                |\n\n### System diagnostics (`coven pc`, macOS-first)\n\n| Command                          | Action                                                                |\n| -------------------------------- | --------------------------------------------------------------------- |\n| `coven pc`                       | Full system report: CPU, memory, disk, top processes                  |\n| `coven pc status`                | One-line health summary with 🟢/🟡/🔴 indicators                      |\n| `coven pc status --json`         | Machine-readable health summary                                       |\n| `coven pc top --n 10`            | Top-N processes by CPU usage                                          |\n| `coven pc disk`                  | Disk usage breakdown                                                  |\n| `coven pc kill \u003cpid\u003e --confirm`  | SIGTERM with PID identity re-check (requires `--confirm`)             |\n| `coven pc cache clear --confirm` | Clear `~/Library/Caches` and `/Library/Caches` (requires `--confirm`) |\n\n\u003e All read operations are side-effect-free. Write operations (kill, cache clear) require `--confirm` and cannot be bypassed. Termination is SIGTERM only — no SIGKILL.\n\n### Other\n\n| Command                | Action                                                  |\n| ---------------------- | ------------------------------------------------------- |\n| `coven patch openclaw` | Open the OpenClaw repair rescue loop                    |\n| `coven logs prune`     | Manually prune session logs and raw encrypted artifacts |\n\n---\n\n## Local API\n\nThe daemon exposes a versioned HTTP API over a Unix socket. The current public contract is `coven.daemon.v1` (prefix: `/api/v1`).\n\n### Endpoint reference\n\n| Endpoint                                 | Method | Purpose                                                     |\n| ---------------------------------------- | ------ | ----------------------------------------------------------- |\n| `/api/v1/health`                         | `GET`  | Daemon health, API version, and capability catalog          |\n| `/api/v1/api-version`                    | `GET`  | Active and supported API versions                           |\n| `/api/v1/capabilities`                   | `GET`  | Machine-readable capability catalog for clients             |\n| `/api/v1/sessions`                       | `GET`  | List sessions                                               |\n| `/api/v1/sessions`                       | `POST` | Launch a session                                            |\n| `/api/v1/sessions/:id`                   | `GET`  | Fetch one session                                           |\n| `/api/v1/events`                         | `GET`  | Read session events (supports `afterSeq` cursor pagination) |\n| `/api/v1/sessions/:id/events`            | `GET`  | Session-scoped events alias                                 |\n| `/api/v1/sessions/:id/log`               | `GET`  | Redacted log preview for a session                          |\n| `/api/v1/sessions/:id/input`             | `POST` | Forward input to a live session                             |\n| `/api/v1/sessions/:id/kill`              | `POST` | Kill a live session                                         |\n| `/api/v1/actions`                        | `POST` | Route a control-plane action (advanced clients)             |\n| `/api/v1/travel/profiles`                | `POST` | Generate a read-only travel profile for offline laptop work |\n| `/api/v1/travel/deltas`                  | `POST` | Upload offline travel results for hub reconciliation        |\n| `/api/v1/travel/state`                   | `GET`  | Read hub/travel handoff state for a client                  |\n| `/api/v1/scheduler/decisions`            | `POST` | Choose a node for a multi-host job                          |\n| `/api/v1/scheduler/decisions/:id`        | `GET`  | Fetch a persisted scheduler decision                        |\n| `/api/v1/scheduler/redispatch`           | `POST` | Redispatch or pause a loop after executor failure           |\n| `/api/v1/scheduler/loops/:loopId`        | `GET`  | Recover persisted scheduler loop state                      |\n\n### Recommended client handshake\n\nAll API clients should start with a health negotiation:\n\n```bash\n# Example: health check via Unix socket\ncurl --unix-socket ~/.coven/coven.sock http://localhost/api/v1/health\n```\n\nExample response:\n\n```json\n{\n  \"ok\": true,\n  \"apiVersion\": \"coven.daemon.v1\",\n  \"covenVersion\": \"0.0.10\",\n  \"capabilities\": {\n    \"sessions\": true,\n    \"events\": true,\n    \"travel\": true,\n    \"scheduler\": true,\n    \"eventCursor\": \"sequence\",\n    \"structuredErrors\": true\n  },\n  \"daemon\": {\n    \"pid\": 12345,\n    \"startedAt\": \"2026-05-09T06:43:00Z\",\n    \"socket\": \"/Users/alice/.coven/coven.sock\"\n  }\n}\n```\n\n**Before depending on any other endpoint:**\n\n1. Call `GET /api/v1/health`\n2. Verify `apiVersion === \"coven.daemon.v1\"` and `capabilities.structuredErrors === true`\n3. Check `capabilities.eventCursor === \"sequence\"` before using `afterSeq` pagination\n4. Only then depend on the documented `v1` sessions/events shapes\n\nAll API errors use a structured envelope. Branch on `error.code`, never on `error.message`:\n\n```json\n{\n  \"error\": {\n    \"code\": \"session_not_found\",\n    \"message\": \"Session was not found.\",\n    \"details\": { \"sessionId\": \"abc-123\" }\n  }\n}\n```\n\nTreat 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`](docs/API-CONTRACT.md) for the full versioned contract including error codes, cursor pagination, session shapes, and compatibility rules.\n\n---\n\n## Architecture\n\n### Runtime topology\n\nCoven is a local-first harness substrate. The Rust daemon is the authority boundary. All clients — including the CLI/TUI — are untrusted for enforcement purposes.\n\n```\nDeveloper\n  │\n  ├── CastCodes workspace ─────────────────────┐\n  ├── coven CLI / TUI ─────────────────────────┤ HTTP over Unix socket\n  ├── comux (legacy/reference) ────────────────┤ ~/.coven/coven.sock\n  └── @opencoven/coven (OpenClaw plugin) ───────┘\n                                                │\n                                ┌───────────────▼──────────────────┐\n                                │         Coven Rust Daemon         │\n                                │                                   │\n                                │  ┌───────────────────────────┐   │\n                                │  │    Authority boundary      │   │\n                                │  │  • Canonicalize project root│  │\n                                │  │  • Validate cwd in root   │   │\n                                │  │  • Allowlist harness id   │   │\n                                │  │  • Validate session state │   │\n                                │  │  • Route action via policy │  │\n                                │  └────────────┬──────────────┘   │\n                                │               │                   │\n                                │  ┌────────────▼─────────────┐    │\n                                │  │   Harness adapter router  │    │\n                                │  └───────┬──────────────┬───┘    │\n                                │          │              │          │\n                                │      ┌───▼──┐      ┌───▼───┐     │\n                                │      │Codex │      │Claude │     │\n                                │      │ PTY  │      │  PTY  │     │\n                                │      └───┬──┘      └───┬───┘     │\n                                │          │              │          │\n                                │  ┌───────▼──────────────▼──────┐  │\n                                │  │  SQLite session ledger +     │  │\n                                │  │  append-only event log       │  │\n                                │  └──────────────────────────────┘  │\n                                └───────────────────────────────────┘\n```\n\n### Authority boundary\n\nThe Rust daemon validates every request before acting:\n\n1. `projectRoot` must be explicit — no fallback\n2. `cwd` must canonicalize inside the declared project root\n3. Harness ID must be allowlisted (`codex`, `claude`)\n4. Session IDs must exist and be in the expected state\n5. All harness commands are built with argv APIs — never `sh -c`\n\nClients 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.\n\n### Session lifecycle\n\n```\ncoven run codex \"fix tests\"\n        │\n        ▼\nPOST /api/v1/sessions  { projectRoot, cwd, harness, prompt }\n        │\n        ▼\nDaemon: canonicalize → validate → spawn or reject\n        │\n        ▼\nSession record created in SQLite\n        │\n        ▼\nHarness spawned in PTY → output events streamed to SQLite\n        │\n        ▼\ncoven sessions → Rejoin / View Log / Archive / Sacrifice\n```\n\nFor full architecture diagrams (including Mermaid flow charts), see [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md).\n\n---\n\n## Repository Structure\n\n```\ncoven/\n├── .github/                    # GitHub Actions workflows, issue templates\n├── assets/opencoven/           # Project assets (logos, icons for npm packages)\n├── brand/                      # OpenCoven brand system\n│   ├── icons/                  # Brand icon set (trident, agent-node, etc.)\n│   ├── social/                 # Social media assets (X, GitHub)\n│   └── ui/                     # CSS color tokens and typography scale\n├── crates/\n│   ├── coven-cli/              # Main Rust binary — the `coven` command\n│   └── coven-relay/            # Internal relay crate\n├── docs/                       # Full documentation suite (see Documentation section)\n├── npm/                        # npm wrapper package source for @opencoven/cli\n├── packages/\n│   └── openclaw-coven/         # External OpenClaw bridge plugin (@opencoven/coven)\n├── scripts/\n│   └── check-secrets.py        # CI / pre-release secret scanner\n├── skills/opencoven-design/    # Design skill files\n├── web/                        # Web surface files\n├── Cargo.lock                  # Locked Rust dependency tree\n├── Cargo.toml                  # Rust workspace manifest\n├── CONTRIBUTING.md             # Contribution guidelines\n├── DESIGN.md                   # Full brand and design system reference\n├── LICENSE                     # MIT license\n├── README.md                   # This file\n└── SECURITY.md                 # Security policy\n```\n\n**Key directories:**\n\n- **`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.\n- **`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`.\n- **`scripts/check-secrets.py`** — Required pre-release and pre-PR scan. Run it before pushing to avoid leaking credentials into git history.\n- **`docs/`** — The canonical documentation suite. All product docs, architecture, API contract, safety model, and roadmap live here.\n\n---\n\n## Configuration\n\n### Environment variables\n\n| Variable                      | Default    | Description                                                                              |\n| ----------------------------- | ---------- | ---------------------------------------------------------------------------------------- |\n| `COVEN_HOME`                  | `~/.coven` | Root directory for all daemon state: SQLite database, Unix socket, logs, encryption keys |\n| `COVEN_PERSIST_RAW_ARTIFACTS` | `0`        | Set to `1` to enable local encrypted storage of raw session artifact payloads (advanced) |\n\n\u003e **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.\n\n### Configuration file\n\nLocal privacy and storage settings live in `\u003cCOVEN_HOME\u003e/privacy.toml`:\n\n| Key                     | Default | Description                                             |\n| ----------------------- | ------- | ------------------------------------------------------- |\n| `persist_raw_artifacts` | `false` | Enable local encrypted storage of raw session artifacts |\n\nWhen enabled, raw artifacts are encrypted using a local key at `\u003cCOVEN_HOME\u003e/keys/session-artifacts.key`. This file is generated automatically with private permissions and is never stored in the repository or SQLite database.\n\n### What should never enter your repository\n\n```\n.coven/          # Daemon state directory — local only\n*.sqlite         # SQLite database files\n*.sqlite3\n*.db\n*.sock           # Unix socket files\n.env*            # Environment variable files\n*.key            # Encryption key files\n```\n\nThese patterns are covered by `.gitignore`. Before submitting any PR or publishing documentation, run the secret scanner:\n\n```bash\npython scripts/check-secrets.py\n```\n\nIf the scan fails, remove the secret from your working tree. If a secret entered git history, rotate the credential before rewriting history or publishing.\n\n### Data retention defaults\n\n| Data type                            | Default retention | Manual control     |\n| ------------------------------------ | ----------------- | ------------------ |\n| Redacted session event logs          | 30 days           | `coven logs prune` |\n| Raw encrypted artifacts (if enabled) | 7 days            | `coven logs prune` |\n\n---\n\n## OpenCoven Integrations\n\nCoven is the runtime layer. Other surfaces in the OpenCoven ecosystem sit above it and connect through the local socket API.\n\n| Integration                                              | Role                                                                       | How it connects                          |\n| -------------------------------------------------------- | -------------------------------------------------------------------------- | ---------------------------------------- |\n| **[CastCodes](https://github.com/OpenCoven/cast-codes)** | Primary public workspace; the local-first AI coding product built on Coven | HTTP over Unix socket                    |\n| **comux**                                                | Legacy terminal cockpit (useful reference; not the future public story)    | HTTP over Unix socket                    |\n| **OpenClaw**                                             | External coding agent; integrates via opt-in plugin only                   | `@opencoven/coven` plugin → socket       |\n\n\u003e **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.\n\n### CastCodes\n\nCastCodes 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.\n\nThe intended flow is:\n\n```\nUser → CastCodes → coven run → Coven daemon → Harness PTY\nHarness output → Coven event log → CastCodes session view\n```\n\n### comux (legacy reference)\n\ncomux 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.\n\n---\n\n## Documentation\n\n| Document                                                | What it covers                                                        |\n| ------------------------------------------------------- | --------------------------------------------------------------------- |\n| [Getting started](docs/GETTING-STARTED.md)              | Full install → first session walkthrough                              |\n| [Concepts](docs/CONCEPTS.md)                            | Definitions: harness, session, project, ritual, daemon, store, client |\n| [Glossary](docs/GLOSSARY.md)                            | Term definitions for the full OpenCoven ecosystem                     |\n| [Architecture](docs/ARCHITECTURE.md)                    | Runtime topology, session lifecycle, authority boundary diagrams      |\n| [API contract](docs/API-CONTRACT.md)                    | Full `coven.daemon.v1` contract: shapes, cursors, error codes         |\n| [Session lifecycle](docs/SESSION-LIFECYCLE.md)          | Detailed state machine for sessions                                   |\n| [Safety model](docs/SAFETY-MODEL.md)                    | Trust boundary, local access model, data rules                        |\n| [Operational model](docs/OPERATIONAL-MODEL.md)          | Day-to-day operation and daemon management                            |\n| [Client integration guide](docs/CLIENT-INTEGRATION.md)  | How to build a client against the socket API                          |\n| [Harness adapter guide](docs/HARNESS-ADAPTERS.md)       | How to implement a new harness adapter                                |\n| [Troubleshooting](docs/TROUBLESHOOTING.md)              | Diagnose and resolve common issues                                    |\n| [Public roadmap](docs/ROADMAP.md)                       | Shipped, now, next, and later milestones                              |\n| [Product spec](docs/PRODUCT-SPEC.md)                    | Product requirements and design decisions                             |\n| [MVP plan](docs/MVP-PLAN.md)                            | Current MVP scope and checklist                                       |\n| [Future harnesses](docs/FUTURE-HARNESSES.md)            | Research notes for upcoming adapter work                              |\n| [Brand assets](docs/BRAND.md)                           | Logo, colors, and usage guidance                                      |\n| [Design system](DESIGN.md)                              | Full brand reference: palette, typography, iconography                |\n| [Brand adherence checklist](docs/BRANDING-ADHERENCE.md) | Checklist for brand-compliant contributions                           |\n| [Documentation maintenance](docs/DOCS-MAINTENANCE.md)   | How docs are organized and kept up to date                            |\n| [Security policy](SECURITY.md)                          | Vulnerability reporting and data handling                             |\n\n---\n\n## FAQ\n\n**Q: What is Coven, exactly?**\n\nCoven 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.\n\n**Q: Does Coven replace Codex or Claude Code?**\n\nNo. 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.\n\n**Q: Does Coven require an internet connection or an account?**\n\nNo. 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.\n\n**Q: Is Windows supported?**\n\nYes. `@opencoven/cli-windows` ships a native Windows x64 binary, and the universal `@opencoven/cli` wrapper selects it automatically. Run `coven doctor` from the same PowerShell, Windows Terminal, or WSL2 environment where your harness CLI is installed.\n\n**Q: What is `coven pc`?**\n\nA 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.\n\n**Q: What does \"Sacrifice\" mean?**\n\nSacrifice 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.\n\n**Q: What is `COVEN_HOME`?**\n\nThe 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.\n\n**Q: Is CastCodes the same as Coven?**\n\nNo. 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.\n\n**Q: What is the relationship with OpenClaw?**\n\nOpenClaw 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.\n\n**Q: Can I build my own client on top of Coven?**\n\nYes. 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`](docs/API-CONTRACT.md) and [`docs/CLIENT-INTEGRATION.md`](docs/CLIENT-INTEGRATION.md).\n\n**Q: What if I want to add a new harness (like Aider or Gemini)?**\n\nSee [`docs/HARNESS-ADAPTERS.md`](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.\n\n---\n\n## Troubleshooting\n\nThe fastest first step for any broken setup:\n\n```bash\ncoven doctor\n```\n\n`coven doctor` checks store readiness, project detection, daemon status, and harness availability — and prints specific next steps for every failure branch.\n\n### Quick reference\n\n| Symptom                                     | First step                                                                             |\n| ------------------------------------------- | -------------------------------------------------------------------------------------- |\n| `coven: command not found`                  | Run `npm install -g @opencoven/cli`; verify binary is on `PATH`                        |\n| `doctor` reports missing harness            | Install and authenticate the harness CLI (see [Requirements](#requirements))           |\n| Daemon won't start                          | Run `coven daemon restart`; check `$COVEN_HOME` ownership and permissions              |\n| Session browser shows a table, not a UI     | Terminal isn't interactive; use `coven sessions --manage` to force the browser         |\n| `cwd` rejected at launch                    | The working directory resolves outside the project root; use a path inside it          |\n| Stale \"running\" sessions after daemon crash | Run `coven sessions --all`; archive or sacrifice orphaned records                      |\n| Sessions feel slow / daemon sluggish        | Run `coven pc status` to check system pressure; `coven pc top --n 10` for CPU culprits |\n| `coven attach` won't accept input           | The session is not live; attach replays logs for completed or archived sessions        |\n| Secret scan fails                           | Remove the secret from your working tree; rotate it if it entered git history          |\n| API version mismatch                        | Update Coven to match the client's expected contract, or update the client             |\n\nFor the full diagnostic flowchart and detailed resolution steps, see [`docs/TROUBLESHOOTING.md`](docs/TROUBLESHOOTING.md).\n\n---\n\n## Contributing\n\n\u003e **Contribution Status — Updated July 2026**\n\u003e\n\u003e External Pull Requests are open. Please start from an issue for larger changes\n\u003e and include the readiness packet requested by the PR template.\n\n### First 10 minutes (source checkout)\n\n```bash\ngit clone https://github.com/OpenCoven/coven.git\ncd coven\ncargo build --workspace\ncargo run -p coven-cli -- doctor\ncargo test -p coven-cli --test smoke -- --nocapture\n```\n\nA 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.\n\n### Local development loop\n\n```bash\n# Build\ncargo build --workspace\n\n# Rust checks (required before any PR)\ncargo fmt --check\ncargo clippy --workspace --all-targets -- -D warnings\ncargo test --workspace --locked\n\n# Secret scanner (required before any PR)\npython scripts/check-secrets.py\n\n# Smoke test (required for daemon/session/attach/ritual changes)\ncargo test -p coven-cli --test smoke -- --nocapture\n\n# Manual smoke run — use a throwaway project, not a real repository\ncargo run -p coven-cli -- daemon start\ncargo run -p coven-cli -- run codex \"say hello from coven\"\ncargo run -p coven-cli -- sessions\ncargo run -p coven-cli -- daemon stop\n```\n\n### Architecture rules for contributors\n\n- **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.\n- **All clients are untrusted for enforcement** — this includes comux and the OpenClaw plugin.\n- **Keep harness support focused.** v0 targets Codex and Claude Code only until adapter contracts are stable.\n- **OpenClaw separation.** Do not place Coven code in OpenClaw core. The integration belongs in `packages/openclaw-coven` as `@opencoven/coven`.\n- **No future orchestration commands as user-facing** until they exist in the CLI and socket API.\n\n### Documentation rules\n\n- Use **OpenCoven** for the ecosystem and organization. Use **Coven** for the CLI and daemon product.\n- The user-facing command is always `coven` — never `opencoven` or `@opencoven` in user-facing documentation.\n- Use canonical community references: `discord.gg/opencoven` and `@OpenCvn`.\n- Use placeholders in all examples: `/path/to/project`, `/Users/example`, `session-1`, `intent-1`.\n- Run `python scripts/check-secrets.py` before submitting any PR, including docs-only changes.\n- Update docs whenever command behavior, API behavior, or trust boundaries change.\n\n### Maintainer release checklist\n\n```bash\ncargo fmt --check\ncargo clippy --workspace --all-targets -- -D warnings\ncargo test --workspace --locked\npython scripts/check-secrets.py\n# For package releases: verify package contents with dry run, attach checksums for native binaries\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for the full development loop, release checklist, and documentation standards.\n\n---\n\n## Code of Conduct\n\nOpenCoven is committed to building a welcoming, respectful community where people of all backgrounds and experience levels can contribute and learn.\n\n**We expect all contributors and community members to:**\n\n- Be respectful and kind in all interactions — issues, PRs, Discord, and X\n- Focus criticism on ideas and code, not people\n- Welcome newcomers and answer questions with patience\n- Assume good faith before assuming bad\n\n**We do not tolerate:**\n\n- Harassment, discrimination, or abuse in any form\n- Personal attacks or derogatory language\n- Sustained or repeated disruptive behavior\n\nTo report unacceptable behavior, contact the maintainers privately through GitHub or Discord. Reports will be handled with discretion.\n\n---\n\n## Roadmap\n\n\u003e **Last updated: May 2026.** See [`docs/ROADMAP.md`](docs/ROADMAP.md) for detailed milestone checklists with individual items.\n\n| Status          | Milestone                         | Summary                                                                                                                       |\n| --------------- | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |\n| ✅ **Shipped**  | A: Local runtime foundation       | `coven` CLI, Rust daemon, PTY sessions, SQLite ledger, versioned `coven.daemon.v1` API, Codex + Claude adapters, npm packages |\n| 🔄 **Now**      | B: CastCodes workspace            | CastCodes as primary public workspace; Cast Agent + Coven integration direction                                               |\n| 🔄 **Now**      | C: Community transparency         | Public roadmap, Discord update cadence, public issue board                                                                    |\n| 📋 **Next**     | D: Harness expansion              | Generic command adapter from real usage, third harness proof, compatibility docs                                              |\n| 🔬 **Next/Lab** | E: Visible lane → verify → review | CastCodes-native agent lanes, live session display, verification gates, explicit PR/merge workflow                            |\n| 🔭 **Later**    | F: Multi-harness orchestration    | Handoff protocol, capability routing, multi-instance coordination, audit dashboard (Phases 1–4)                               |\n\nThe 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.\n\n---\n\n## Security\n\nCoven is pre-1.0 software. Treat it accordingly:\n\n- **Do not run untrusted harnesses or prompts in sensitive repositories.** Session logs capture harness output; if the harness dumps secrets, Coven logs them.\n- **Do not commit runtime state.** `.coven/`, `*.sqlite`, `*.sock`, `.env*` files, and encryption keys should never enter source control.\n- **Do not paste secrets into prompts.** Event payloads are redacted before API display, but defense in depth starts with not having secrets in prompts.\n\n**Reporting vulnerabilities:** Please use [GitHub Security Advisories](https://github.com/OpenCoven/coven/security/advisories) for this repository. If advisories are unavailable, contact the maintainer privately. Do not post exploit details in public issues.\n\nSee [SECURITY.md](SECURITY.md) for the full security policy and [`docs/SAFETY-MODEL.md`](docs/SAFETY-MODEL.md) for the trust boundary and local access model.\n\n---\n\n## License\n\nMIT © Valentina Alexander and the OpenCoven contributors — see [LICENSE](LICENSE) for full terms.\n\n---\n\n## Community \u0026 Support\n\n| Channel                 | Link                                                       |\n| ----------------------- | ---------------------------------------------------------- |\n| 🌐 Website              | [opencoven.ai](https://opencoven.ai/)                      |\n| 📝 Feedback             | [feedback.opencoven.ai](https://feedback.opencoven.ai/)    |\n| 💬 Discord              | [discord.gg/opencoven](https://discord.gg/opencoven)       |\n| 🐦 X / Twitter          | [@OpenCvn](https://x.com/OpenCvn)                          |\n| 🐛 Issues \u0026 Bug Reports | [GitHub Issues](https://github.com/OpenCoven/coven/issues) |\n| 📖 Documentation        | [`docs/` directory](docs/)                                 |\n| 🗺️ Public Roadmap       | [docs/ROADMAP.md](docs/ROADMAP.md)                         |\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**[OpenCoven](https://github.com/OpenCoven)** — One project. Any harness. Visible work.\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopencoven%2Fcoven","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopencoven%2Fcoven","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopencoven%2Fcoven/lists"}