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
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.
- 💬 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.
Install from the OpenCoven tap:
brew install --cask opencoven/tap/coven-caveThe cask ships the same signed + notarized per-architecture DMG as the release pipeline and stays current automatically.
Grab the latest desktop build from the releases page:
→ https://github.com/OpenCoven/coven-cave/releases/latest
Release assets include macOS, Windows, and Linux builds plus update metadata and checksums.
The iOS client ships through TestFlight. See
apps/ios/CovenCave/README.md for the native
client and widget notes.
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 │ TestFlight
▼ ▼
┌──────────────────┐ ┌──────────────────┐
│ Browser mobile │ │ Native iOS │
│ dogfooding │ │ (apps/ios) │
└──────────────────┘ └──────────────────┘
| 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 |
| 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 |
apps/ |
Additional companion apps (markdown, terminal helpers) |
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 |
For deeper design context, start with docs/golden-paths.md,
docs/coven-design-language.md, and
docs/multi-session-coordination.md.
- Node.js 22+
- pnpm 10+
- Rust and Cargo
- Tauri desktop prerequisites for your platform
- Xcode + XcodeGen for iOS work
pnpm installpnpm devStarts the custom Next.js development server.
bash scripts/dev-app.sh # or: pnpm dev:appRun 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 picks the first free loopback port in 3000..3010 (if 3000 is
taken, e.g. by Docker, it uses 3001), reuses or starts the dev server, writes
a temporary Tauri config pointing devUrl at the real port, and runs
tauri dev. Force a port with PORT=3007 bash scripts/dev-app.sh.
Expected early output:
[dev:app] port 3001 is free
[dev:app] starting dev server on 3001
Running BeforeDevCommand (`PORT=3001 pnpm dev`)
> Ready on http://127.0.0.1:3001
Running DevCommand (`cargo run --no-default-features --color always --`)
Startup looks stuck? Diagnose it here
- First launch is slow by design. Cargo downloads and compiles Rust crates
before the window appears.
Compiling ...lines are progress, not a hang. - No
port ... is freeline + an error → every port in3000..3010is occupied. Free one or pass an explicitPORT=. - Stuck before
> Ready on ...→ the Next dev server. Check the wrapper's terminal for Next/Node errors. - Stuck after
Running DevCommandwith no Cargo output → the Rust toolchain. Verifycargo --versionand the Tauri prerequisites.
pnpm buildpnpm build also runs the generated icon/PWA/sandbox setup before the Next.js
and server builds.
pnpm mobile:tailscale # browser-based mobile dogfooding over Tailscale
pnpm mobile:tailscale:native # native iOS developmentThe native SwiftUI app has its own notes in
apps/ios/CovenCave/README.md.
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 registeredmain is protected — every change goes through a short-lived branch and a
pull request. Use a worktree:
git worktree add -b <branch> .worktrees/<branch> origin/main
cd .worktrees/<branch>Make the branch PR-shaped before opening: a scoped diff, relevant local verification, and a clear summary of what changed. After merge, delete the remote branch and remove the local worktree.
- Releases, TestFlight uploads, and updater validation start from clean
main. - See
AGENTS.mdandCLAUDE.mdfor the workflow notes coding agents follow, anddocs/workflows/branching.mdfor branch/release hygiene.
How is Coven Cave different from OpenCoven?
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.
Do I need to build from source to use it?
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.
Why is it a native app instead of a website?
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.
What is the "sidecar"?
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.
How does mobile handoff work?
Two paths. For quick dogfooding, pnpm mobile:tailscale exposes the web app to
your phone over Tailscale. For a first-class experience, the native SwiftUI
iOS client (shipped via TestFlight) has its own chat, code, tasks, and feed
tabs.
Which platforms are supported?
Desktop: macOS, Windows, and Linux. Mobile: iOS (native client) and any phone browser via Tailscale.
The desktop app seems stuck on first launch — is it broken?
Almost always no. The first dev:app or first install compiles Rust crates,
which can take several minutes. Compiling ... output is progress. See the
startup diagnostics above.
Can I run several familiars at once?
Yes. Coven Cave supports multiple concurrent agent sessions with coordination
across them — see docs/multi-session-coordination.md.
Coven Cave is licensed under MIT OR AGPL-3.0-only. See LICENSE,
LICENSE-MIT, and LICENSE-AGPL.
Part of OpenCoven · Knowledge is Freedom