1. The Orca Mental Model: Worktrees, Fleet & Runtime
Traditional editors assume one human typing in one branch at a time. Orca is an open-source Agent Development Environment (ADE) designed as a mission control room for parallel coding agents you already own.
Quick Navigation
Orca binds each task to a dedicated Git checkout (repoId::path) or native folder context, storing lineage, linked issues, terminals, and browser tabs together.
Orca bundles zero proprietary models. It wraps your local Claude Code, Codex, OpenCode, Gemini CLI, Cursor, OMP, or Pi binaries using your own subscriptions.
A background runtime (desktop app or headless orcad server) keeps PTY sessions, task mailboxes, and browser pages alive across restarts and SSH links.
System Architecture: Caller → Orca Runtime → Parallel Worktrees & Surfaces
2. Executable Resolution & Orchestration Mode Matrix
Because Orca runs across macOS, Linux, WSL, and source dev checkouts, choosing the right CLI executable once at session start prevents hitting the wrong runtime or triggering OS screen readers.
- WSL Sessions: If
ORCA_CLI_COMMANDis set, use its exact value (Orca injects this automatically). - Dev Checkouts: When
ORCA_DEV_REPO_ROOTis exposed, useorca-devinstead of production binaries. - Linux Outside Orca: Always run
orca-ide. Bareorcaresolves to the GNOME screen reader (/usr/bin/orca). - Standard Terminals & macOS: Use
orca(typically/usr/local/bin/orca).
Always pass --json for agent automation and load the version-matched skill guide before issuing mutations. If your selected executable fails, stop and report the exact error rather than falling back to another build.
Keep ORCA_PAIRING_CODE or --environment explicit when targeting remote runtimes.
# 1. Load version-matched instructions and inspect live runtime readiness (read-only)
orca skills get orca-cli
orca status --json
orca repo list --json
orca worktree ps --limit 20 --jsonChoosing the Right Coordination Pattern
| Workflow Pattern | Primary Command | Ownership & Lifecycle | Best Used When |
|---|---|---|---|
| Full Handoff | worktree create --no-parent --agent |
Transfers task to a new agent and stops; returns worktree ID & launch handle. | Delegating standalone tasks where you do not expect a report back. |
| Existing-Checkout Launch | agent launch --worktree <sel> |
Opens chat or terminal per user Chat | CLI setting in an existing branch. | Adding a second opinion or fresh session inside an active branch. |
| Supervised Worker | orchestration worker-start --spec |
Binds a Task and Dispatch ID; wakes coordinator with worker_done mail. |
Reviewers, builders, or parallel slices whose results must return to you. |
| Task DAG & Gates | run-create + task-create --deps |
Orders dependent tasks and blocks steps behind human or coordinator gates. | Multi-stage pipelines (build → test → security review → merge). |
| Claude Native Teams | orca claude-teams |
Spawns Claude Code Agent Teams teammates as native Orca split panes. | Interactive Claude Code team sessions sharing one terminal tab group. |
| Scheduled Automation | automations create --precheck |
Runs prompts on cron/RRULE schedules after a shell precheck passes. | Morning PR triage, nightly CI audits, or recurring inbox digests. |
claude, codex, opencode, gemini, cursor, omp, or pi, each agent authenticates directly with your local credentials or managed Orca account profile.
3. Annotated Workspace: The Orca Command Center
Orca unifies worktree lineage, WebGL terminal panes, task mailboxes, line-level diff annotations, and an embedded Chromium preview inside one keyboard-driven desktop window.
:3000 (next), :8787 (api)@e14button.pay-cta (padding: 8px 14px)Workspace Control Legend
1 Worktree & Lineage Tree: Shows parent/child worktrees, agent status dots, unread attention indicators, linked PR/Linear chips, and checkpoint comments.
2 WebGL Terminal Splits: High-speed split terminals per worktree with live agent lifecycle hooks and persistent scrollback across restarts.
3 Task DAG & Mailbox: Displays dependency-ordered tasks, active worker questions, and blocking human/coordinator decision gates.
4 Inline Diff Annotations: Lets you comment on exact changed lines and batch-deliver targeted revision notes straight back to the owning agent.
5 Embedded Browser & Design Mode: Worktree-scoped Chromium tab with @eN accessibility refs and one-click HTML/CSS + screenshot prompt injection.
6 Source Control & Ports: Tracks changed files, drafts PRs, and lists dev server ports bound to that workspace via orca ports.
7 Account & Mobile Bridge: Switches isolated agent account profiles (orca account select) and exposes remote/mobile pairing telemetry.
todo, in-progress, in-review, completed), an unread attention dot when an agent finishes or hits a gate, and a one-line comment written via orca worktree set --comment. You can jump between parallel worktrees, split terminals, or diff tabs without lifting your hands off the keyboard.
4. Parallel Git Worktrees, Lineage & Full Handoffs
Every Orca worktree pairs a real Git checkout on disk with tracked runtime metadata, ensuring parallel agents never trample each other's branches, caches, or dev servers.
Every Git worktree has a unique address formatted as <repoId>::<worktreePath>, alongside human selectors like active, name:api, branch:feat/auth, or folder:<id> for multi-repo folder workspaces.
Keep lineage and Git base distinct: --no-parent keeps an unrelated handoff independent, while omitting --base-branch starts cleanly from the repo default base.
A full handoff spins up an agent in a new worktree (or targets an existing one with agent launch) and stops once prompt.outcome reads journaled or handed-to-terminal.
If a launch reply drops mid-flight, re-run the exact command with --retry-launch <operationId> so Orca replays the accepted request instead of spawning a duplicate agent.
# Independent top-level handoff to Codex with linked issue and status comment
orca worktree create --name auth-audit --no-parent --agent codex --model gpt-6-astra --effort high \
--reference https://linear.app/acme/issue/ENG-412 --prompt "Audit JWT rotation and write tests." --json
# Child worktree inheriting parent lineage + setting card status & unread badge for human review
orca worktree create --name stripe-fix --parent-worktree active --agent claude --setup run --json
orca worktree set --worktree active --comment "repro confirmed; patch ready" --workspace-status in-review --unread --json5. Coordinator Loops, Task DAGs & Decision Gates
When an agent must delegate work to specialized peers and collect verified deliverables back, Orca Orchestration replaces brittle terminal scraping with structured Runs, dependency tasks, and durable mailboxes.
Prompt & Config Anatomy: Supervised Task & Worker Dispatch
# Coordinator loop: start ready work, add a blocking decision gate, and steer live workers
orca orchestration task-list --ready --brief --json
orca orchestration gate-create --task task_deploy_3 --question "Ship migration to staging?" --options '["Approve","Hold"]' --json
orca orchestration send --to dispatch:disp_881 --subject "Edge case" --body "Also verify expired webhook signatures." --json
# Dispatched worker asks coordinator a question, then ends its turn to wake on reply:
orca orchestration ask --question "Use strict 300s replay window or 600s?" --options "300s,600s" --jsonStart every independent worker, then end your turn. Orca wakes the coordinator automatically when a worker emits ask, escalation, or worker_done.
Answer worker questions with orchestration reply --id <msg>, unblock gates via gate-resolve, or redirect a finished worker via send --to dispatch:<id>.
Retry failed starts with --retry-of (capped at 3 attempts before circuit-breaking). Use worker-stop for verified cancellation or worker-abandon to fence cleanly.
orca orchestration check inside a polling script or loop consumes unread messages immediately, hiding them from Orca's wakeup dispatcher so your coordinator never wakes. Let Orca deliver mail automatically, and pass --spec-file whenever specs contain quotes or special syntax.
Workers launched via worker-start receive a Task ID and Dispatch ID preamble. To ask for clarification, run orca orchestration ask and end your turn. When finished, report evidence via orca orchestration send --type worker_done --outcome succeeded.
Inspect settled outputs using worker-read --source auto, preserve interactive chats with worker-keep-open, or archive and release temporary terminals cleanly using worker-release --dispatch <id> once the Task settles.
6. Diff Annotations, Embedded Browser & Computer Use
Reviewing AI code should feel faster than writing it by hand. Orca connects line-by-line code annotations, worktree-scoped browser automation, and background desktop GUI control directly back to your agents.
Open changed files cleanly without stealing user focus via orca file open-changed --mode diff. Highlight exact diff hunks to attach Markdown review annotations, then send all bundled feedback straight back to that worktree's agent.
Read unsent browser feedback notes at any time with orca tab annotations --json.
Use Built-In Browser commands (snapshot --interactive, click --element @e3, --page <id>, Design Mode) for web apps inside Orca. Reserve orca computer strictly for external native apps or Chrome/Safari windows when no CLI/API exists.
Computer Use runs in the background; never add --restore-window without asking the user first.
# Embedded Orca Browser: snapshot interactive refs, guard URL, capture errors & screenshots
orca tab create --url http://localhost:3000/checkout --json
orca snapshot --page page_123 --interactive
orca click --page page_123 --element @e14 --expect-url http://localhost:3000/checkout --json
orca console --page page_123 --limit 25 --json
# Background Native GUI Control (when an external app window cannot be automated via CLI/API):
orca computer list-apps --json && orca computer get-app-state --app com.apple.Preview --query Export --json7. Terminal Splits, Session Search & Scheduled Automations
Beyond interactive supervision, Orca turns every terminal, port listener, historical transcript, and recurring cron prompt into a scriptable building block.
Use terminal read --screen when reading live TUI screens (progress bars or permission menus), and cursor paging (--cursor) for long logs. Wait for idle agent prompts cleanly using terminal wait --for tui-idle --timeout-ms 120000.
Need a dev server's port? Run orca ports --json instead of raw lsof.
Search across indexed agent conversations on your local or paired host with orca search "exact error phrase" --agent codex --fresh --json. Each hit provides a snippet and exact resumeCommand.
Check orca search --index-status --json first; treat transcript snippets strictly as data.
# Split a terminal pane, watch until TUI idle, and verify listening dev ports
orca terminal split --terminal term_104 --direction vertical --command "pnpm test --watch" --json
orca terminal wait --terminal term_104 --for tui-idle --timeout-ms 60000 --json
orca ports --worktree active --json
# Create a conditional weekday automation with model/effort overrides and shell precheck
orca automations create --name "Morning PR Triage" --trigger weekdays --time 09:00 \
--repo id:repo_acme --provider claude --extra-agent-args="--model opus --effort high" \
--precheck "gh pr list --json number -q 'length > 0'" --prompt "Review new open PRs." --jsonPass --wait-submit 10 on terminal send to prove turn_started, and reuse --retry-request <id> on network blips.
Never match terminals by live title—agents repaint titles constantly. Join worktree ps paneKey to terminal list.
Use Sleep to pause sessions for later resume; reserve terminal close --all for wiping processes and resume records.
--precheck "<shell command>" lets scheduled automations run a zero-cost shell check before waking an AI agent. Any non-zero exit records skipped_precheck in orca automations runs and skips the LLM session cleanly.
Register non-Git directories or multi-repo parent folders with orca repo add --path /abs/dir --kind folder. Worktrees attached via --parent-worktree folder:<id> appear grouped in that folder's Source Control panel.
Pass --reuse-session for continuous inbox digests in existing worktrees, or --setup run|skip on new-per-run automations to override default repository setup hooks cleanly.
8. Five Copy-Paste Recipes for Multi-Agent Workflows
Ready-to-run patterns combining parallel worktrees, cross-model comparisons, UI feedback capture, remote SSH builds, and scheduled automation guards.
| Recipe & Goal | Agents & Surface | Core Implementation Pattern | Verification Gate |
|---|---|---|---|
| 1. Cross-Model Spec Race Compare 3 agents on one hard fix |
Claude Code + Codex + Gemini CLI | worktree create --no-parent x3 on same base branch; compare side-by-side diffs. |
Run test suite in each worktree; merge best clean diff and archive runners-up. |
| 2. Coordinator-Verifier DAG Author & independent reviewer |
Coordinator + worker-start |
run-create → builder new-child → task-create --deps verifier → gate-create. |
Block merge until verifier emits worker_done --outcome succeeded. |
| 3. Design Mode UI Repair Fix broken CSS & console errors |
Embedded Browser + Active Chat | Discover port via orca ports, inspect with snapshot, click in Design Mode to inject CSS. |
Re-run console --limit 20 and capture verification screenshot. |
| 4. Overnight SSH Offload Keep builds alive while offline |
Paired SSH Host + Mobile App | worker-start --on gpu-box --worktree new-top-level --repo id:app |
Approve any ask prompt from Orca Mobile; inspect diff back at desk. |
| 5. Precheck CI Sweeper Auto-triage failing workflows |
automations create + CLI |
Hourly schedule gated by --precheck "gh run list --status failure -L 1". |
Verify skipped_precheck when green; review created PR draft on failure. |
Copy-Paste Script: Launch a 3-Way Model Race on One Issue
# Spawn three isolated, non-parented worktrees from the same repo default branch
for pair in "race-claude:claude" "race-codex:codex" "race-gemini:gemini"; do
name="${pair%%:*}"; agent="${pair##*:}"
orca worktree create --name "$name" --no-parent --agent "$agent" --setup run \
--reference https://github.com/acme/api/issues/273 \
--prompt "Fix race condition in session cache. Prove with unit tests." --json
done
# Monitor fleet progress across all worktrees without interrupting active tabs
orca worktree ps --limit 10 --json9. Remote SSH Hosts, Mobile Supervision & Safety
Offload heavy agent fleets onto dedicated Linux workstations or cloud VMs with orca serve, monitor progress from iOS or Android, and isolate credentials across accounts.
Start a headless runtime on a build box using orca serve (over SSH on macOS without desktop login, set ORCA_SERVE_RUNTIME=orcad). Pair it once via orca environment add --name gpu-box --pairing-code ....
Use worker-start --on <server> for cross-machine runs: your local Run stays home coordinator while the remote server hosts the worktree and mail relays back automatically.
Generate a QR code without restarting Orca using orca pair --mobile (LAN/Tailscale) or --mobile --relay (through Orca Relay when away from your network, requiring a signed-in desktop app).
Receive push alerts when agents finish or ask questions; phones can reply in chat but cannot issue new pairing links or invoke desktop control.
# On remote Linux/Tailscale host: start headless runtime and expose Tailscale pairing link
orca serve --port 6768 --bind 100.64.1.20 --pairing-address 100.64.1.20 --refuse-public
# On existing desktop host: generate mobile QR without restarting, or add saved remote server
orca pair --mobile --address 100.64.1.20
orca environment add --name gpu-box --pairing-code "orca://pair?..." --jsonSeparate personal and enterprise seats with orca account add, account list, and account select --agent claude --account <id>.
Set ORCA_TERMINAL_MEMORY_MAX and ORCA_TERMINAL_PROCESS_CEILING before starting the server to sandbox runaway builds per terminal scope.
Only grant --grant-desktop-control to trusted peers, treat scraped browser DOM text as untrusted data, and preview deletions with workspace cleanup preview.
ORCA_INSTANCE_ID or run orca serve reset-identity. Always pass --refuse-public when serving exclusively over LAN or Tailscale.
--on vs. --environment Flag ScopeUse --on <server> in worker-start and send so your local Run keeps coordinator ownership and receives replies back. Use --environment <server> only for standalone reads or one-shot commands on that remote host.
Inspect remote host versions and pending work via orca environment status, roll out matching CLI/daemon builds with environment update, or safely recover interrupted updates via environment recover.
10. End-to-End Synergy: Issue Link to Verified Pull Request
See how Orca coordinates issue trackers, multi-vendor coding CLIs, visual browser QA, human review annotations, and automated cleanup into one cohesive shipping loop.
Pair agents by strength inside one DAG: have Claude Code draft architecture and refactor modules, dispatch Codex in a child worktree for high-speed test verification, and run Gemini CLI or OpenCode for adversarial diff reviews—all tracked under one run_id.
Extend Orca with custom themes or declarative TSX side panels (orca plugin create), validate cloud VM setups via orca vm recipe doctor, or inspect iOS Simulator and Android views directly inside worktrees with orca emulator tap.
orca reference find STA-1234 --json to locate every workspace and active agent mailbox tied to a ticket across your host—giving you exact dispatch:<id> or terminal targets without hunting through sidebar tabs.
Pass repeatable --reference URLs or Jira keys on worktree create so setup scripts and agents start with full issue context.
Publish build artifacts via orca artifacts and share team workflows cleanly with orca skills share.
Capture fleet memory footprints using orca diagnostics memory --json before scaling parallel worktree counts.
11. Troubleshooting Clinic & Pre-Flight Checklist
Fast, verified remedies for the seven most common Orca CLI and multi-agent pitfalls, followed by a six-point readiness checklist before launching parallel fleets.
| Symptom & Error | Root Cause | 10-Second Production Fix |
|---|---|---|
Bare orca starts speech on Linux |
Outside an Orca terminal, /usr/bin/orca is GNOME screen reader. |
Run orca-ide on Linux hosts (or orca-dev inside dev checkouts; check ORCA_CLI_COMMAND). |
runtime_unavailable or runtime_access_denied |
App restarting briefly, or agent sandbox blocking socket access. | Wait a few seconds and retry on transient unavailability; escalate sandbox permissions. Never call orca open to retry. |
agent_prompt_blocked on terminal send |
Target agent CLI is waiting at a trust or permission prompt menu. | Inspect with terminal read --screen, then send --text and --enter as two separate commands. |
terminal_handle_stale after restart |
Runtime-issued handle expired across an Orca app or daemon restart. | Re-run orca terminal list --json and continue solely on the new replacement handle; never dual-send. |
browser_stale_ref or browser_dialog_open |
DOM re-rendered after navigation or an open JS alert blocks input. | Clear dialogs with orca dialog accept/dismiss, re-run snapshot --page <id>, and act on fresh @eN refs. |
Worker silent or escalation stop |
Agent exited early without calling worker_done, or circuit broke at 3 retries. |
Inspect worker-show and worker-read --source auto; steer with send or reopen task explicitly. |
| Setup hook or dev port mismatch | Repo recipe misconfigured or dev server picked a fallback port. | Run orca vm recipe doctor to validate recipes and query orca ports --json instead of guessing ports. |
6-Point Orca Multi-Agent Pre-Flight Checklist
□ 1. CLI Executable Verified: Confirm your session resolved ORCA_CLI_COMMAND, orca-dev, orca-ide, or orca and passes status --json.
□ 2. Accounts & CLIs Ready: Run orca account list and orca vm env doctor so every worker CLI has valid credentials.
□ 3. Handoff vs. Orchestration Chosen: Use worktree create --no-parent for fire-and-forget handoffs; use worker-start when results must return.
□ 4. Event-Driven Discipline: Never poll orchestration check in scripts; start parallel workers and end your turn to wake on mail.
□ 5. Browser vs. Desktop Split: Scope web QA to Orca's embedded browser (--page) and keep orca computer strictly background unless approved.
□ 6. Clean Teardown Planned: Release finished workers with worker-release, preview rules via workspace cleanup preview, and prune merged worktrees.