Orca Documentation

Pages

1. OverviewWhat Orca exposes (desktop app, runtime RPC, bundled CLI), primary entry points, BYOC agent model, and the shortest path from install to a running worktree with an agent terminal.
2. InstallationPlatform packages (onOrca.dev, Homebrew, AUR), Node 24/pnpm prerequisites for source builds, CLI registration, and mobile companion app install links.
3. QuickstartFirst successful session: open Orca, add a repo, create a worktree, launch a CLI agent terminal, and verify with `orca status` and `orca worktree current`.
4. Worktrees and reposOrca-managed git worktrees, repo registration, lineage/parent links, sparse checkout, workspace statuses, and CLI/RPC create/list/remove semantics.
5. Terminals and agentsPTY lifecycle, `TuiAgent` catalog and detection order, pane keys, agent status hooks, terminal env injection (`ORCA_*`), and when to use terminal CLI vs orchestration messaging.
6. Runtime environmentsHeadless `orca serve`, runtime metadata/RPC transport, pairing codes, saved environments, and targeting a remote runtime from the CLI with `--environment` or `--pairing-code`.
7. Repository hooks`orca.yaml` setup/archive scripts, issue-command defaults, hook command-source policies, trust prompts, and CLI `--run-hooks` behavior on create/remove.
8. CLI scripting workflowEnd-to-end agent automation with `orca open`, `orca status`, repo/worktree discovery, terminal read/send/wait, file open helpers, and worktree comment updates at checkpoints.
9. Agent orchestrationMulti-agent coordination: messaging (`send`/`check`/`reply`), task DAGs, dispatch/inject, coordinator `run`, decision gates, and group addresses—requires experimental feature and running runtime.
10. SSH remote worktreesSSH targets, relay grace periods, remote repo registration, remote PTY leases, agent-hook forwarding over SSH, and CLI selector constraints on paired runtimes.
11. Scheduled automationsCreate and run cron/RRULE automations via CLI: triggers, provider agents, workspace modes, session reuse, run history, and SSH execution targets.
12. Browser automationAutomate Orca's embedded browser: accessibility snapshots, interaction commands, tabs/profiles, capture/intercept/storage, and `orca exec` passthrough to agent-browser.
13. Source control integrationsBuilt-in review flows for GitHub, GitLab, and Linear: PR/MR/issue linking on worktrees, hosted review creation, diff annotation, and provider-specific IPC surfaces.
14. CLI core referenceFlags and signatures for `open`, `serve`, `status`, `repo`, `worktree`, `terminal`, `file`, `environment`, and `agent hooks` command groups.
15. CLI browser and computer referenceBrowser automation commands (navigation, interaction, cookies, storage, capture) and `computer` desktop accessibility commands with capability flags.
16. Selectors and JSON outputGlobal CLI flags (`--json`, `--help`, `--pairing-code`, `--environment`), worktree/repo selector grammar (`id:`, `path:`, `branch:`, `active`), JSON error shapes, and remote-runtime resolution rules.
17. Settings reference`GlobalSettings` fields that control workspaces, terminals, agents, themes, notifications, and integration toggles—persisted by the main-process store.
18. Develop and buildLocal dev (`pnpm dev`), typecheck targets, native runtime rebuilds, electron-vite build graph, relay/computer native artifacts, and platform release builds.
19. TestingUnit tests (Vitest), Playwright Electron E2E, computer-use smoke scripts, and SSH-localhost E2E env flags documented in test helpers.
20. ContributingContribution workflow, cross-platform/SSH/agent constraints from AGENTS.md, PR expectations, and maintainer release cutting via GitHub Actions.
21. TroubleshootingCommon failure modes: runtime not reachable, selector ambiguity on remote CLI, worktree delete preflight, terminal/orchestration timeouts, and platform-specific native dependency issues.
22. Telemetry and privacyConsent gating, event schemas in `telemetry-events.ts`, dashboard-ready boundaries in repo docs, and what usage data Orca collects.