Overview

Orca documentation

Orca (orcasynth) is a self-hosted daemon that orchestrates autonomous coding agents — Claude Code, OpenCode, Codex — in isolated tmux sessions, exposing a REST API, a CLI, and a real-time Next.js web UI. No SaaS, no lock-in: your machine, your agents, your code.

This section mirrors the essentials from the in-repo docs/ directory. Use the sidebar to navigate the five core areas:

Install & Quickstart

Get the daemon and web UI running in under a minute — npm i -g orcasynth, orca up, sign in at :4500.

Concepts

Tasks, missions, autonomy levels (L0–L3), the overseer decision gate, the deriver, and the PR-native workflow.

CLI reference

Every orca command: ls, ready, sessions, close, plan submit, overseer poll/decide, api, and the lifecycle verbs.

Architecture

Modules, timer loops, request/spawn flow, the event bus, and how the daemon and the web UI talk over HTTP+SSE.

What it does, in a sentence

Hand Orca a goal — it plans the work, spawns the right agent for each step in its own tmux session, streams every keystroke to your browser, and gates dangerous actions behind a human when you want it to. Turn autonomy up when you trust it, down when you don't.

Highlights

Autopilot planning — the Pilot decomposes a goal into ordered, dependency-chained phases, optionally picking the best model per phase (autoModel).
PR-native autopilot — a mission works in an isolated git worktree, commits each approved phase, runs your verify command, then pushes and opens a GitHub PR. Review feedback folds back as bounded fix phases.
Agent-agnostic — Claude Code, OpenCode, Codex in isolated tmux sessions; route tasks with exec:<spec> labels.
Live web UI with real-PTY terminals — xterm over WebSocket, not a read-only mirror; you type straight into the agent.
Autonomy levels L0–L3 — from "plan only, nothing runs without you" to full auto, with the overseer clearing prompts when confidence is high.
Phone push — VAPID web-push with inline Approve / Reject / Open action buttons; routes to the mission owner + admins.
Self-healing — stuck-session detector, janitor, overseer watchdog; destructive ops (rm -rf, DROP TABLE, force-push, touching .env) always escalate.
Self-hosted & lightweight — one SQLite-backed Hono daemon (:4400) plus a Next.js UI (:4500). Nothing else required beyond your LLM provider.

Architecture, at a glance

┌───────────┐ │ Client │ │ (CLI/Web) │ └─────┬─────┘ │ HTTP/SSE ▼ ┌──────────────────┐ │ Hono Server │ │ port 4400 │ └──────┬───────────┘ │ ┌───────┼───────────────────────┐ ▼ ▼ ▼ ┌──────────────┐ ┌──────────────────┐ ┌──────────────┐ │ TaskStore │ │ MissionEngine │ │ EventBus │ │ (CRUD) │ │ (90s tick) │ │ (SSE push) │ └──────┬───────┘ └──────┬───────────┘ └──────────────┘ │ │ │ ┌────────▼────────┐ │ │ Routing + │ │ │ Decision │ │ └────────┬────────┘ │ │ │ ┌────────▼────────┐ │ │ SpawnService │ │ │ (tmux launch) │ │ └────────┬────────┘ │ │ │ ┌────────▼────────┐ │ │ Deriver │ │ │ (5s poll loop) │ │ └────────┬────────┘ │ │ ▼ ▼ ┌──────────────────────────────────────┐ │ SQLite (WAL) │ │ tasks / missions / agents / users │ └──────────────────────────────────────┘

For the deep dive, see Architecture.