OpenCoven
Start with OpenCoven

Quickstart

Choose your way into OpenCoven.

Start with the surface that matches how you already work — a terminal runtime, an interactive coding TUI, a visual desktop Cave, a Linux workspace, or GitHub automation. Every path ends the same way: concrete, checkable proof that it worked.

Four local surfaces, one foundation. Coven CLI, Coven Code, Cave, and CastCodes share the runtime and session history you already set up. GitHub automation has its own hosted or self-hosted access path.

Choose a product Read every guide

Mission trace

The sequence that actually runs.

  1. Step 1 of 4:

    Choose

    Choose a product

    Match the chooser below to how you already work today: terminal, an interactive TUI, a desktop app, a Linux workspace, or GitHub.

  2. Step 2 of 4:

    Prepare

    Prepare prerequisites

    Complete the prerequisites named by your guide — provider, account, runtime, or repository access — before you run anything.

  3. Step 3 of 4:

    Run

    Run the first loop

    Follow the guide's exact steps for one small, bounded task — the same loop you can repeat after this.

  4. Step 4 of 4:

    Verify

    Verify the result

    Confirm the stated arrival state. That checkable proof, not a tutorial's last screen, is what success means here.

    Arrival state — the proof it worked

Pick one to start

Five products. One successful first loop.

These are alternatives, not a sequence — install only the product you choose. Each card jumps straight to its own install, connect, and first-run guide below.

Shared foundation

Prepare once. Add surfaces when you need them.

  • Bring a project

    Local product paths start inside a Git-tracked project you already control. Hosted or self-hosted GitHub automation begins with repository and access setup.

  • Authenticate your provider

    For local provider-backed paths, connect Anthropic or OpenAI directly; those credentials remain provider-owned. Self-hosted GitHub workers require their own provider setup, while hosted beta users follow the access path they receive.

  • Keep the runtime local-first

    Coven CLI, Coven Code, Cave, and CastCodes share a local runtime and session history, so switching among those surfaces does not restart what you already built.

  • Install one surface at a time

    Add local surfaces one at a time without repeating their shared setup. GitHub automation has separate hosted-access or self-hosted operator setup.

The five guides

From install to proof.

Each guide below is self-contained: install, connect, run one bounded task, and the exact signal that means you succeeded.

Terminal runtime

Coven CLI

Install the shared OpenCoven runtime, check your project, and start a provider-backed session.

Best for
Terminal-first control, scripts, and a shared runtime for the OpenCoven ecosystem.
Availability
Recommended foundation
Platforms
macOS Apple Silicon · glibc Linux x64 · Windows x64
  1. Step 1 of 4:

    Install

    Install Coven globally

    Install the recommended shared runtime from npm.

    npm install -g @opencoven/cli
    coven --help
    Read the first-run guide (opens in new tab)

    Expect: The Coven help screen opens and lists the available top-level commands.

  2. Step 2 of 4:

    Check

    Check your project

    Open a terminal in the intended Git project so Coven can inspect that workspace.

    coven doctor

    Expect: Coven detects the project and reports actionable guidance for any missing setup.

  3. Step 3 of 4:

    Connect

    Prepare a provider harness

    Choose either provider. Your credentials remain owned and managed by that provider.

    npm install -g @openai/codex
    codex login
    npm install -g @anthropic-ai/claude-code
    claude

    Expect: The selected provider completes authentication and its harness is ready for use.

  4. Step 4 of 4:

    Run

    Start and inspect a session

    Run the command that matches your authenticated provider, then inspect the plain-text session history.

    coven run codex "explain this repo in 5 bullets"
    coven run claude "explain this repo in 5 bullets"
    coven sessions --plain

    Expect: The history row shows the session id, harness, title, and status.

Your first success

Your provider-backed session completes and remains available in local Coven history.
Blocked? Check these first
  • If the executable is missing from PATH, open a new terminal and check the npm global binary directory.
  • If the doctor reports a missing harness, complete the provider-specific setup it recommends.
  • If Coven rejects the project root, move to the intended Git project and check it again.

Interactive agent TUI

Coven Code

Use the unified Coven CLI to enter an interactive, provider-backed coding workspace.

Best for
An interactive coding-agent TUI inside an existing project.
Availability
Beta
Platforms
macOS · Linux · Windows
  1. Step 1 of 4:

    Install

    Install the unified CLI

    The unified CLI is the recommended path. The engine repository and direct package are advanced options.

    npm install -g @opencoven/cli
    Read the Coven Code guide (opens in new tab)

    Expect: The Coven executable is available from a new terminal session.

  2. Step 2 of 4:

    Launch

    Open Coven Code in your project

    Launch from the project you want to work on. The first run automatically installs the compatible engine.

    coven

    Expect: The TUI opens for the current project and offers first-run engine setup when needed.

  3. Step 3 of 4:

    Connect

    Choose your provider

    In the first-run picker, choose 1 for Claude or 2 for Codex. Press Enter for the full picker, and use /connect later to switch or repair a connection.

    Expect: The TUI confirms the selected provider and is ready to accept a task.

  4. Step 4 of 4:

    Work

    Complete one bounded task

    Start with a small request that is easy to verify.

    explain this repo in 5 bullets

    Expect: The provider returns a five-bullet repository explanation and the task completes.

Your first success

You complete a provider-backed task and can resume it from Coven history.
Blocked? Check these first
  • If no provider is connected, open /connect and choose an available provider again.
  • If a stale PATH copy launches, open a new terminal and verify the npm global binary directory comes first.
  • If startup still fails, use Coven Doctor and resolve each reported prerequisite.

Visual desktop home

Coven Cave

Connect the desktop app to its local Coven runtime, with an optional iOS companion handoff.

Best for
A visual desktop home for familiars, projects, and sessions, with an optional iOS companion.
Availability
Native app
Platforms
macOS · Windows · Linux · iOS
  1. Step 1 of 4:

    Prepare

    Prepare the desktop host

    Start on macOS, Windows, or Linux. Install the shared runtime, check its prerequisites, and start the daemon on this desktop host. The local daemon and socket do not run on iOS.

    npm install -g @opencoven/cli
    coven doctor
    coven daemon start

    Expect: The doctor completes without a blocking issue and the daemon starts on the desktop host.

  2. Step 2 of 4:

    Install

    Install Coven Cave on desktop

    Use Homebrew on macOS, or open the release page for the current Windows, Linux, or macOS build.

    brew install --cask opencoven/tap/coven-cave
    Download a desktop release (opens in new tab)

    Expect: Desktop Coven Cave is installed from the channel that matches the host platform.

  3. Step 3 of 4:

    Verify

    Open desktop Cave and verify the runtime

    Desktop Cave uses the desktop host’s local Coven socket as the authority for runtime-backed features; it does not imply a cloud runtime.

    coven daemon status

    Expect: The desktop daemon reports a running state and desktop Cave shows daemon-connected activity.

  4. Step 4 of 4:

    Explore

    Start on desktop, then optionally hand off

    On desktop, choose a familiar, select your first project, and run a small conversation you can inspect. For the companion path, install the TestFlight client and use Tailscale to pair or hand off through the desktop Cave host.

    Expect: Desktop Cave shows inspectable familiar and session activity; when used, the iOS companion is paired or handed off from the desktop host through Tailscale.

Your first success

Desktop Cave shows daemon-connected activity; optionally, the iOS companion is paired or handed off through that desktop host with Tailscale.
Blocked? Check these first
  • If Cave shows the daemon as disconnected, start the local runtime and verify its status before reopening Cave.
  • If the package manager install is unavailable, use the matching asset from the latest release page.
  • If the iOS companion cannot connect, confirm the desktop Cave host is running and reachable through Tailscale; TestFlight does not replace the desktop-first setup.

Linux code workspace

CastCodes

Open a Linux-native code and terminal workspace backed by your local Coven runtime.

Best for
A full code-and-terminal workspace on Linux.
Availability
Linux preview
Platforms
Linux x86_64
  1. Step 1 of 4:

    Prepare

    Prepare Coven

    Install the shared runtime, resolve its checks, and start the local daemon.

    npm install -g @opencoven/cli
    coven doctor && coven daemon start

    Expect: Coven reports a ready harness and a running local daemon.

  2. Step 2 of 4:

    Download

    Download the matching release

    Open the release page and download both the Linux x86_64 package and its matching .sha256 file.

    Open CastCodes releases (opens in new tab)

    Expect: The release package and its same-version checksum file are available locally.

  3. Step 3 of 4:

    Launch

    Run the portable AppImage

    Verify the downloaded AppImage against its matching checksum before marking it executable and launching it.

    expected="$(awk '{print $1}' CastCodes-x86_64.AppImage.sha256)" && actual="$(sha256sum CastCodes-x86_64.AppImage | awk '{print $1}')" && test "$actual" = "$expected" && echo "CastCodes-x86_64.AppImage: OK"
    chmod +x CastCodes-x86_64.AppImage
    ./CastCodes-x86_64.AppImage

    Expect: Verification prints “CastCodes-x86_64.AppImage: OK”, then CastCodes opens its code-and-terminal workspace on Linux.

  4. Step 4 of 4:

    Work

    Start a supported harness lane

    Open a Git project, choose a supported harness lane, and inspect its output and diffs. Cast Code grammar is not yet a stable interface.

    Expect: The first Coven-backed session appears with output and diffs available for review.

Your first success

Your first Coven-backed session is visible in CastCodes for review.
Blocked? Check these first
  • If verification fails, confirm the package and checksum file come from the same release and architecture.
  • If the AppImage does not open, install the runtime dependencies required by your Linux distribution.
  • If no harness lane starts, resolve Coven Doctor findings and confirm the local daemon is running.

Issue-to-PR automation

OpenCoven for GitHub

Connect a familiar to one test repository, assign a bounded issue, and review its GitHub status.

Best for
Issue-to-PR familiar workflows in a GitHub organization or repository.
Availability
Hosted beta · self-hostable
Platforms
GitHub · server
  1. Step 1 of 4:

    Choose

    Choose hosted or self-hosted

    Joining the hosted beta completes only the waitlist path and does not grant immediate GitHub App installation. Steps 2–4 require active hosted access or a completed, running self-host setup through the advanced guide.

    Join the hosted beta

    Expect: Hosted beta: waitlist submitted and onboarding pauses until access is granted. Self-hosted: self-host guide chosen; complete its setup before continuing.

  2. Step 2 of 4:

    Install

    Connect one test repository

    Continue only with active hosted access or a completed self-host setup. Install the GitHub App on one test repository, configure a signed webhook, and validate it. Self-hosters run the diagnostic from the cloned and built coven-github checkout after creating or editing config/local.toml.

    ./target/release/coven-github doctor --config config/local.toml

    Expect: The test repository installation is active and a signed webhook is accepted.

  3. Step 3 of 4:

    Assign

    Send one bounded issue

    Assign a small, well-scoped issue to the familiar or apply the configured trigger label.

    Expect: The issue receives a visible status update showing that the familiar accepted the task.

  4. Step 4 of 4:

    Review

    Review the familiar output

    Review the status, Check Run, and Cave link. Review a draft pull request only when the task produced commits.

    Expect: GitHub shows a final status and Check Run, plus a draft pull request only when commits were produced.

Your first success

With active hosted access or a running self-host, the issue shows a status and Check Run, with a draft pull request only when the familiar produced commits.
Blocked? Check these first
  • If hosted access is unavailable, remain on the waitlist or use the advanced self-hosting path.
  • If the self-hosted adapter is unhealthy, run the copied diagnostic against the local configuration and resolve its findings.
  • If an unsigned webhook returns 401, use the repository signed smoke script and confirm the signed request succeeds.

Keep going

Local surfaces reuse the foundation.

Coven CLI, Coven Code, Cave, and CastCodes reuse the local runtime, provider connection, and session history. GitHub automation connects separately through the hosted beta or a self-hosted deployment.