# Orca Documentation

> Reference for the Orca Electron IDE and `orca` CLI: worktree orchestration, multi-agent terminals, runtime RPC, browser/computer automation, SSH remotes, and git-provider integrations. For builders automating Orca or contributing to stablyai/orca.

This is a Grok-Wiki source-grounded repository documentation set. Use the complete Markdown link when an agent needs the full repo context.

## Context Links

- [Complete Markdown docs](https://grok-wiki.com/public/docs/stablyai-orca-2036d532bf1c/llms-full.txt)
- [Complete Markdown alias](https://grok-wiki.com/public/docs/stablyai-orca-2036d532bf1c.md)
- [Human interactive docs](https://grok-wiki.com/public/docs/stablyai-orca-2036d532bf1c)
- [GitHub repository](https://github.com/stablyai/orca)

## Repository

- Repository: stablyai/orca

- Generated: 2026-06-01T20:12:52.786Z
- Updated: 2026-06-01T20:13:17.164Z
- Runtime: Grok CLI
- Format: Documentation
- Pages: 22

## Pages

- [Overview](https://grok-wiki.com/public/docs/stablyai-orca-2036d532bf1c/pages/01-overview.md): What 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.
- [Installation](https://grok-wiki.com/public/docs/stablyai-orca-2036d532bf1c/pages/02-installation.md): Platform packages (onOrca.dev, Homebrew, AUR), Node 24/pnpm prerequisites for source builds, CLI registration, and mobile companion app install links.
- [Quickstart](https://grok-wiki.com/public/docs/stablyai-orca-2036d532bf1c/pages/03-quickstart.md): First successful session: open Orca, add a repo, create a worktree, launch a CLI agent terminal, and verify with `orca status` and `orca worktree current`.
- [Worktrees and repos](https://grok-wiki.com/public/docs/stablyai-orca-2036d532bf1c/pages/04-worktrees-and-repos.md): Orca-managed git worktrees, repo registration, lineage/parent links, sparse checkout, workspace statuses, and CLI/RPC create/list/remove semantics.
- [Terminals and agents](https://grok-wiki.com/public/docs/stablyai-orca-2036d532bf1c/pages/05-terminals-and-agents.md): PTY lifecycle, `TuiAgent` catalog and detection order, pane keys, agent status hooks, terminal env injection (`ORCA_*`), and when to use terminal CLI vs orchestration messaging.
- [Runtime environments](https://grok-wiki.com/public/docs/stablyai-orca-2036d532bf1c/pages/06-runtime-environments.md): Headless `orca serve`, runtime metadata/RPC transport, pairing codes, saved environments, and targeting a remote runtime from the CLI with `--environment` or `--pairing-code`.
- [Repository hooks](https://grok-wiki.com/public/docs/stablyai-orca-2036d532bf1c/pages/07-repository-hooks.md): `orca.yaml` setup/archive scripts, issue-command defaults, hook command-source policies, trust prompts, and CLI `--run-hooks` behavior on create/remove.
- [CLI scripting workflow](https://grok-wiki.com/public/docs/stablyai-orca-2036d532bf1c/pages/08-cli-scripting-workflow.md): End-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.
- [Agent orchestration](https://grok-wiki.com/public/docs/stablyai-orca-2036d532bf1c/pages/09-agent-orchestration.md): Multi-agent coordination: messaging (`send`/`check`/`reply`), task DAGs, dispatch/inject, coordinator `run`, decision gates, and group addresses—requires experimental feature and running runtime.
- [SSH remote worktrees](https://grok-wiki.com/public/docs/stablyai-orca-2036d532bf1c/pages/10-ssh-remote-worktrees.md): SSH targets, relay grace periods, remote repo registration, remote PTY leases, agent-hook forwarding over SSH, and CLI selector constraints on paired runtimes.
- [Scheduled automations](https://grok-wiki.com/public/docs/stablyai-orca-2036d532bf1c/pages/11-scheduled-automations.md): Create and run cron/RRULE automations via CLI: triggers, provider agents, workspace modes, session reuse, run history, and SSH execution targets.
- [Browser automation](https://grok-wiki.com/public/docs/stablyai-orca-2036d532bf1c/pages/12-browser-automation.md): Automate Orca's embedded browser: accessibility snapshots, interaction commands, tabs/profiles, capture/intercept/storage, and `orca exec` passthrough to agent-browser.
- [Source control integrations](https://grok-wiki.com/public/docs/stablyai-orca-2036d532bf1c/pages/13-source-control-integrations.md): Built-in review flows for GitHub, GitLab, and Linear: PR/MR/issue linking on worktrees, hosted review creation, diff annotation, and provider-specific IPC surfaces.
- [CLI core reference](https://grok-wiki.com/public/docs/stablyai-orca-2036d532bf1c/pages/14-cli-core-reference.md): Flags and signatures for `open`, `serve`, `status`, `repo`, `worktree`, `terminal`, `file`, `environment`, and `agent hooks` command groups.
- [CLI browser and computer reference](https://grok-wiki.com/public/docs/stablyai-orca-2036d532bf1c/pages/15-cli-browser-and-computer-reference.md): Browser automation commands (navigation, interaction, cookies, storage, capture) and `computer` desktop accessibility commands with capability flags.
- [Selectors and JSON output](https://grok-wiki.com/public/docs/stablyai-orca-2036d532bf1c/pages/16-selectors-and-json-output.md): Global CLI flags (`--json`, `--help`, `--pairing-code`, `--environment`), worktree/repo selector grammar (`id:`, `path:`, `branch:`, `active`), JSON error shapes, and remote-runtime resolution rules.
- [Settings reference](https://grok-wiki.com/public/docs/stablyai-orca-2036d532bf1c/pages/17-settings-reference.md): `GlobalSettings` fields that control workspaces, terminals, agents, themes, notifications, and integration toggles—persisted by the main-process store.
- [Develop and build](https://grok-wiki.com/public/docs/stablyai-orca-2036d532bf1c/pages/18-develop-and-build.md): Local dev (`pnpm dev`), typecheck targets, native runtime rebuilds, electron-vite build graph, relay/computer native artifacts, and platform release builds.
- [Testing](https://grok-wiki.com/public/docs/stablyai-orca-2036d532bf1c/pages/19-testing.md): Unit tests (Vitest), Playwright Electron E2E, computer-use smoke scripts, and SSH-localhost E2E env flags documented in test helpers.
- [Contributing](https://grok-wiki.com/public/docs/stablyai-orca-2036d532bf1c/pages/20-contributing.md): Contribution workflow, cross-platform/SSH/agent constraints from AGENTS.md, PR expectations, and maintainer release cutting via GitHub Actions.
- [Troubleshooting](https://grok-wiki.com/public/docs/stablyai-orca-2036d532bf1c/pages/21-troubleshooting.md): Common failure modes: runtime not reachable, selector ambiguity on remote CLI, worktree delete preflight, terminal/orchestration timeouts, and platform-specific native dependency issues.
- [Telemetry and privacy](https://grok-wiki.com/public/docs/stablyai-orca-2036d532bf1c/pages/22-telemetry-and-privacy.md): Consent gating, event schemas in `telemetry-events.ts`, dashboard-ready boundaries in repo docs, and what usage data Orca collects.

## Source Files

- `.env.e2e`
- `.github/CONTRIBUTING.md`
- `.github/workflows/release-cut.yml`
- `AGENTS.md`
- `components.json`
- `config/electron-builder.config.cjs`
- `config/scripts/computer-use-smoke.mjs`
- `config/scripts/ensure-native-runtime.mjs`
- `config/scripts/install-dev-cli.mjs`
- `config/scripts/orca-dev`
- `config/scripts/run-electron-vite-build.mjs`
- `config/scripts/run-electron-vite-dev.mjs`
- `config/vitest.config.ts`
- `docs/automations-navigation-stack.md`
- `docs/reference/telemetry-availability.md`
- `docs/STYLEGUIDE.md`
- `docs/worktree-delete-preflight.md`
- `orca.yaml`
- `package.json`
- `README.md`
- `skills/computer-use/SKILL.md`
- `skills/orca-cli/SKILL.md`
- `skills/orchestration/SKILL.md`
- `src/cli/args.ts`
- `src/cli/dispatch.ts`
- `src/cli/format.ts`
- `src/cli/handlers/automations.ts`
- `src/cli/handlers/browser-capture.ts`
- `src/cli/handlers/browser-interact.ts`
- `src/cli/handlers/browser-tab.ts`
- `src/cli/handlers/computer.ts`
- `src/cli/handlers/core.ts`
- `src/cli/handlers/orchestration.ts`
- `src/cli/handlers/worktree.ts`
- `src/cli/help.ts`
- `src/cli/index.test.ts`
- `src/cli/index.ts`
- `src/cli/runtime-client.ts`
- `src/cli/selectors.ts`
- `src/cli/specs/agent-hooks.ts`
- `src/cli/specs/automations.ts`
- `src/cli/specs/browser-advanced.ts`
- `src/cli/specs/browser-basic.ts`
- `src/cli/specs/computer.ts`
- `src/cli/specs/core.ts`
- `src/cli/specs/environment.ts`
- `src/cli/specs/file.ts`
- `src/cli/specs/orchestration.ts`
- `src/main/agent-hooks/server.ts`
- `src/main/automations/service.ts`
- `src/main/browser/agent-browser-bridge.ts`
- `src/main/browser/browser-manager.ts`
- `src/main/git/worktree.ts`
- `src/main/index.ts`
- `src/main/ipc/pty.ts`
- `src/main/ipc/runtime-environments.ts`
- `src/main/persistence/index.ts`
- `src/main/runtime/orca-runtime.ts`
- `src/main/runtime/orchestration/db.ts`
- `src/main/runtime/orchestration/formatter.ts`
- `src/main/runtime/runtime-metadata.ts`
- `src/main/runtime/runtime-rpc.ts`
- `src/main/runtime/worktree-teardown.ts`
- `src/main/telemetry/client.ts`
- `src/main/telemetry/consent.ts`
- `src/main/text-generation/pull-request-context.ts`
- `src/preload/api-types.ts`
- `src/preload/gitlab.ts`
- `src/preload/index.ts`
- `src/preload/runtime-environment-subscriptions.ts`
- `src/renderer/src/assets/main.css`
- `src/renderer/src/components/settings/RepositoryHooksSection.tsx`
- `src/renderer/src/lib/ensure-hooks-confirmed.ts`
- `src/renderer/src/main.tsx`
- `src/shared/agent-detection.ts`
- `src/shared/automations-types.ts`
- `src/shared/hosted-review.ts`
- `src/shared/runtime-bootstrap.ts`
- `src/shared/runtime-rpc-envelope.ts`
- `src/shared/setup-runner-command.ts`
- `src/shared/ssh-types.ts`
- `src/shared/telemetry-events.ts`
- `src/shared/tui-agent-config.ts`
- `src/shared/tui-agent-selection.ts`
- `src/shared/tui-agent-startup.ts`
- `src/shared/types.ts`
- `src/shared/work-items.ts`
- `tests/e2e/helpers/orca-app.ts`
- `tests/e2e/ssh-localhost.spec.ts`
- `tests/playwright.config.ts`
- `vite.web.config.ts`