🕯️ Coven Cave
The desktop control room for your OpenCoven familiars.
Chat with familiars, orchestrate local agent sessions, triage GitHub, track
tasks, browse memory and libraries, and hand the whole thing off to your phone —
all from one native app.
Install · Features · Architecture · Development · FAQ
What is Coven Cave?
Coven Cave is the desktop and mobile home for OpenCoven. Where OpenCoven
gives you a coven of AI familiars — specialized agents for code, research,
social, memory, and strategy — Coven Cave is the room you sit in to talk to
them, watch them work, and steer the work when it matters.
It runs as a native app (not a browser tab): a Next.js + React interface
packaged with Tauri for macOS, Windows, and Linux, plus a native SwiftUI
iOS client. Because it's native, it can do things a web page can't — spawn
local terminal and browser panes, drive local agent sessions through a sidecar,
persist state offline, and hand a live session off to your phone over Tailscale.
In one line: OpenCoven is the coven; Coven Cave is where you meet it.
What it does
- 💬 Chat with familiars — Talk to any OpenCoven familiar and route work
through local agent sessions, with multi-session coordination when several
familiars are working at once.
- 🗂️ Track work — Manage tasks on the Board and Gantt surfaces, with bulk
edits and undo. Browse reminders, calendars, and daily/retro reports.
- 🧠 Memory & libraries — Browse project sessions, local libraries, the
knowledge vault, and marketplace packages in one place.
- 🐙 GitHub triage — Review GitHub activity, PRs, and issues inline and feed
them straight into familiar work.
- 🖥️ Local surfaces — Launch desktop-local terminal and browser
panes through the Cave sidecar, right inside the app window.
- 📱 Mobile handoff — Hand the app off to a phone over Tailscale, or run
the dedicated native iOS client with its own chat, code, tasks, and feed tabs.
- ⚙️ Workflows & automations — Run and inspect OpenCoven workflows,
automations, and marketplace-seeded catalog data.
Flow executions and Chat
Automated Flow transcripts stay in Flow runs, not the ordinary Chat list.
Research iterations stay grouped under their mission. In Chat's Sessions list,
choose Session view options > Flow runs to inspect execution history and
read transcripts without creating a chat.
Use Discuss in Chat when you want a separate conversation with the familiar:
it links back to the execution and starts with a bounded snapshot of its output,
without resuming the automation or inheriting its runtime permissions.
Execution ownership is retained independently of the capped, clearable run
history. Older sessions are classified only from exact run/session links, never
from a title such as "Flow:". Clearing history does not delete transcripts or
make execution sessions reappear in Chat.
Routine success stays quiet. Failures, approval requests, and checkpoints that
need human input produce one actionable notification per run or Research
mission, linking to that exact owner. Its guidance updates as blockers change;
resolved work clears the notification without generating another completion.
Install
Use a prebuilt package to run Coven Cave. Desktop installs do not need
Node.js, pnpm, Rust, or a local source checkout.
macOS (Homebrew — recommended)
Install from the OpenCoven tap:
brew install --cask opencoven/tap/coven-cave
The cask ships the same signed + notarized per-architecture DMG as the
release pipeline and stays current automatically.
macOS / Windows / Linux (direct download)
Grab the latest desktop build from the releases page:
→ https://github.com/OpenCoven/coven-cave/releases/latest
Choose the asset that matches your platform:
| Platform | Published architectures | Package |
|---|
| macOS | Apple Silicon (aarch64) and Intel (x86_64) | .dmg |
| Windows | x64 only | .msi when present on that release |
| Linux | amd64/x86_64 only | .AppImage |
Check the selected release's asset list before downloading: partial releases may
not include every platform or SHA256SUMS. If the release marked latest has no
MSI, use the newest earlier release that lists one, and verify the download
against that release's SHA256SUMS.
Windows on ARM and Linux on ARM do not currently have published desktop
artifacts.
iOS
The native iOS client is under active development. Maintainer builds use
TestFlight, but no public TestFlight or App Store enrollment link is currently
published, so there is no end-user iOS install path yet. Contributors can
build the client from source by following
apps/ios/CovenCave/README.md.
Architecture
Coven Cave is a web UI in a native shell. The React/Next.js frontend renders
every surface; the Tauri (Rust) shell gives it native powers — windows, a
sidecar for local agent sessions, and OS-level terminal/browser/speech
integration.
┌──────────────────────────────────────────────────────────────┐
│ Coven Cave │
│ │
│ ┌────────────────────────┐ ┌───────────────────────┐ │
│ │ Frontend (src/) │ │ Native shell │ │
│ │ Next.js 16 · React 19│◀────▶│ (src-tauri/, Rust) │ │
│ │ Tailwind 4 · TS │ IPC │ · window & updater │ │
│ │ │ │ · pty terminal │ │
│ │ Surfaces: │ │ · browser pane │ │
│ │ chat · board · gantt │ │ · speech │ │
│ │ familiars · settings │ │ · sidecar archive │ │
│ │ github · libraries │ └───────────┬───────────┘ │
│ │ reminders · workflows │ │ │
│ └───────────┬────────────┘ │ │
│ │ ▼ │
│ │ ┌───────────────────────┐ │
│ └───────────────────▶│ Cave sidecar │ │
│ local API routes │ local agent sessions │ │
│ └───────────────────────┘ │
└──────────────────────────────────────────────────────────────┘
▲ ▲
│ Tailscale handoff │ private TestFlight
▼ ▼
┌──────────────────┐ ┌──────────────────┐
│ Browser mobile │ │ Native iOS │
│ dogfooding │ │ (apps/ios) │
└──────────────────┘ └──────────────────┘
Tech stack
| Layer | Technology |
|---|
| UI framework | Next.js 16, React 19, TypeScript |
| Styling | Tailwind CSS 4 + the Coven design language |
| Native shell | Tauri 2 (Rust) — desktop app + sidecar |
| Native mobile | SwiftUI iOS client (apps/ios/CovenCave) |
| Mobile handoff | Tailscale for LAN/remote device access |
| Tooling | pnpm, custom Next dev server, Vitest-style tests |
Repository layout
| Path | What lives there |
|---|
src/ | Next.js app, API routes, React components, shared libraries, sandbox |
src-tauri/ | Tauri desktop shell + sidecar (Rust: pty, browser, speech, archive) |
apps/ios/ | Native SwiftUI iOS client and widget targets |
docs/ | Design notes, audits, mobile checklists, workflows, and feature specs |
scripts/ | Build, mobile, test, packaging, and maintenance helpers |
marketplace/ | Seeded OpenCoven marketplace catalog data |
workflows/ | OpenCoven workflow definitions |
docs/README.md indexes every document there and marks each
one living, program, historical, or tombstone — read that before trusting a doc
to describe current behavior. For deeper design context, start with
docs/golden-paths.md,
docs/coven-design-language.md, and
docs/multi-session-coordination.md.
For interface direction explored outside this repository,
OpenCoven UI is a self-contained,
dependency-free component library and specimen lab for exploring agent-surface
direction — composer, messages, context, actions, and run rails. Its
OpenCoven/ui repository is a reference
workspace, not an installable package, production application, or canonical
source for Cave components; shipped code in src/components/ui/,
src/styles/globals/primitives.css, and docs/coven-design-language.md remains
authoritative.
Local client access
Native OpenCoven clients can discover the owner-local Cave listener and request
scoped access through the Client v1 pairing API. Pairing always requires a human
decision in Settings → Client access, where pending requests can be approved
or denied and issued credentials can be revoked. Cave stores bearer hashes only;
the paired native client owns secure bearer storage.
See docs/api/client-v1.md for the discovery and API
contract, docs/client-v1-release.md for the
compatibility metadata each release advertises and the gates that protect it,
and docs/client-v1-settings.md for the
operator workflow and security boundary.
Development
Contributor quickstart
Clone the repository and bootstrap the exact package-manager version declared
in package.json:
git clone https://github.com/OpenCoven/coven-cave.git
cd coven-cave
corepack enable
corepack install
pnpm --version # 10.34.0
pnpm install --frozen-lockfile
The repository requires Node.js 24.18.0 or newer within Node 24. Corepack
then selects the pinned pnpm 10.34.0 release; a generic “pnpm 10+” install is
not sufficient for a reproducible setup.
Platform prerequisites
Install Rust through rustup, then
follow Tauri's authoritative prerequisite section for your development OS:
- macOS prerequisites —
install Xcode Command Line Tools with
xcode-select --install for desktop
work, or full Xcode for iOS work.
- Windows prerequisites —
install Microsoft C++ Build Tools with Desktop development with C++ and
the WebView2 Evergreen Runtime.
- Linux prerequisites —
install the WebKitGTK, app-indicator, compiler, and system packages listed for
your distribution.
For native iOS work, also install Xcode 16+ and
XcodeGen (brew install xcodegen).
Run the web app
pnpm dev
Starts the custom Next.js development server.
Run the native desktop shell
bash scripts/dev-app.sh # or: pnpm dev:app
Run the wrapper in the foreground and leave the terminal attached; stop it
with Ctrl-C. Detached runs can exit without leaving useful Tauri logs, so
foreground startup is the reliable way to confirm the app launched.
The wrapper resolves one dedicated loopback port: COVEN_CAVE_PORT takes
precedence, then PORT, then the fixed dev default 3000. It does not scan for
an arbitrary free port. If that port answers as CovenCave, the wrapper attaches
to it; if it answers as another or gated service, the wrapper refuses instead
of relocating. A silent holder is treated as free so the wrapper's own bind
reports the concrete listen error. It writes a temporary Tauri config pointing
devUrl at the resolved port and runs tauri dev. Choose another free port
with COVEN_CAVE_PORT=3007 bash scripts/dev-app.sh (PORT=3007 remains the
fallback when COVEN_CAVE_PORT is unset).
Expected early output:
[dev:app] dedicated dev port 3000
[dev:app] starting dev server on 3000
Running BeforeDevCommand (`PORT=3000 pnpm dev`)
> Ready on http://127.0.0.1:3000
Running DevCommand (`cargo run --no-default-features --color always --`)
- First launch is slow by design. Cargo downloads and compiles Rust crates
before the window appears.
Compiling ... lines are progress, not a hang.
attaching to the CovenCave dev server already on ... → a healthy Cave
already owns the resolved port, so no second dev server is started.port ... is held by something that is not CovenCave → free that port or
choose another one with an explicit COVEN_CAVE_PORT=.... is serving with an access token configured → the holder refused the
identity probe; stop it or choose another explicit COVEN_CAVE_PORT=.- Stuck before
> Ready on ... → the Next dev server. Check the wrapper's
terminal for Next/Node errors.
- Stuck after
Running DevCommand with no Cargo output → the Rust
toolchain. Verify cargo --version and the Tauri prerequisites.
Build
pnpm build
pnpm build also runs the generated icon/PWA/sandbox setup before the Next.js
and server builds.
Mobile & iOS
pnpm mobile:tailscale # browser-based mobile dogfooding over Tailscale
pnpm mobile:tailscale:app # pair the native iOS app to a daemon over Tailscale
pnpm mobile:ios:sim # build & run the native iOS app in the simulator
The native SwiftUI app has its own notes in
apps/ios/CovenCave/README.md.
Verification
Run the checks that match what you changed:
pnpm typecheck # TypeScript
pnpm test:app # app/component tests
pnpm test:api # API route tests
pnpm test:mobile # mobile/iOS logic tests
pnpm test:e2e # end-to-end
pnpm check:tests-wired # ensure new tests are registered
Contributing
main is protected — every change goes through a short-lived branch and a
pull request. Use GitHub Issues for durable development work and the
Cave Project for planning.
Start with GitHub work tracking.
Reuse matching work and record its owner, scope, branch, and worktree before
editing. Follow that guide's ownership and budget review before creating an
issue-owned worktree from current origin/main with --no-track.
Make the branch PR-shaped before opening: a scoped diff, relevant local
verification, and a clear summary of what changed. Follow
Branch To Merge for the authorized
protected merge. Worktree retirement is a separate decision requiring current
authority and preservation evidence; never delete branches or worktrees ad hoc.
- Releases, TestFlight uploads, and updater validation start from a successful
signed release candidate on clean
main, followed by a signed final tag on
that exact commit.
- See
AGENTS.md and CLAUDE.md for the workflow
notes coding agents follow, and
docs/workflows/branching.md for branch/release
hygiene.
FAQ
OpenCoven is the platform and the coven of familiars. Coven Cave is the native
client you use to interact with them — the control room. You can think of
OpenCoven as the engine and Coven Cave as the cockpit.
No. Install the signed desktop build via Homebrew (brew install --cask opencoven/tap/coven-cave) or download it from the
releases page.
Building from source is only needed for development.
Native capabilities: local terminal and browser panes, a sidecar that drives
local agent sessions, offline-capable state, OS-level speech, auto-updates, and
device handoff. A browser tab can't spawn a local shell or hold a persistent
agent session the way the Tauri shell can.
The Cave sidecar is the local companion process the Tauri shell manages. It
backs the desktop-local surfaces (terminal, browser) and hosts local agent
sessions so familiar work can run on your machine.
Two paths. For quick dogfooding, pnpm mobile:tailscale exposes the web app to
your phone over Tailscale. The native SwiftUI iOS client has its own chat,
code, tasks, and feed tabs, but no public TestFlight or App Store enrollment
link is currently available.
Desktop: macOS on Apple Silicon and Intel, Windows on x64, and Linux
on amd64/x86_64. Mobile: the native iOS client can be built from source but
is not publicly distributed yet; phone browsers can use the Tailscale path.
Almost always no. A source launch through dev:app compiles Rust crates and
can take several minutes. Prebuilt Homebrew, DMG, MSI, and AppImage installs do
not compile Rust locally. Compiling ... output is progress when running from
source; see the startup diagnostics above.
Yes. Coven Cave supports multiple concurrent agent sessions with coordination
across them — see docs/multi-session-coordination.md.
License
Coven Cave is licensed under MIT OR AGPL-3.0-only. See LICENSE,
LICENSE-MIT, and LICENSE-AGPL.
Part of OpenCoven · Knowledge is Freedom
