# Overview

> 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.

- Repository: stablyai/orca
- GitHub: https://github.com/stablyai/orca
- Human docs: https://grok-wiki.com/public/docs/stablyai-orca-2036d532bf1c
- Complete Markdown: https://grok-wiki.com/public/docs/stablyai-orca-2036d532bf1c/llms-full.txt

## Source Files

- `README.md`
- `package.json`
- `src/main/index.ts`
- `src/preload/index.ts`
- `src/renderer/src/main.tsx`
- `src/cli/index.ts`
- `AGENTS.md`

---

---
title: "Overview"
description: "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."
---

Orca ships as an Electron desktop application (`package.json` → `main: ./out/main/index.js`), a long-lived **runtime** (`OrcaRuntimeService`) exposed over **runtime RPC** (`OrcaRuntimeRpcServer`), and a bundled **`orca` CLI** (`bin.orca` → `./out/cli/index.js`). The renderer talks to main through a preload `contextBridge` (`window.electron`, `window.api`); automation and scripting talk to the same runtime state through RPC using bootstrap metadata in `orca-runtime.json` under the app user-data directory.

## Three surfaces

| Surface | Role | Primary entry |
| --- | --- | --- |
| **Desktop app** | UI for repos, worktrees, terminals, review, browser, settings | `src/main/index.ts` → `createMainWindow()` / `src/renderer/src/main.tsx` |
| **Runtime + RPC** | Authoritative graph of worktrees, tabs, PTYs, git, orchestration DB | `OrcaRuntimeService` + `OrcaRuntimeRpcServer` started from `src/main/index.ts` |
| **CLI** | Scripting, headless serve, remote pairing | `src/cli/index.ts` → `RuntimeClient` + `COMMAND_SPECS` |

Desktop and headless modes share one runtime implementation. `orca serve` starts RPC without opening a window; the packaged app starts RPC in parallel with the first `BrowserWindow`.

```mermaid
flowchart TB
  subgraph desktop["Desktop (Electron)"]
    R["renderer — React App"]
    P["preload — contextBridge api"]
    M["main — IPC + services"]
    R --> P --> M
  end
  subgraph runtime["Runtime layer"]
    ORS["OrcaRuntimeService"]
    RPC["OrcaRuntimeRpcServer"]
    M --> ORS
    RPC --> ORS
  end
  subgraph clients["Clients"]
    CLI["orca CLI — RuntimeClient"]
    MOB["mobile / web pairing"]
  end
  CLI --> RPC
  MOB --> RPC
  MD["orca-runtime.json metadata"] --> CLI
```

## Build and process layout

`electron-vite` compiles three targets from `electron.vite.config.ts`:

- **main** — `src/main/index.ts` plus sidecars (`daemon-entry`, `computer-sidecar`, `stt-worker`, agent-hook controls)
- **preload** — `src/preload/index.ts` (IPC bridge)
- **renderer** — `src/renderer/src/main.tsx` (React 19 + Vite)

The CLI is built separately (`pnpm build:cli` → `out/cli/`). Release artifacts bundle the desktop app and register the `orca` binary; local development can use `orca-dev` (`package.json` → `bin.orca-dev`).

<Note>
Engine requirement for source builds: **Node 24** (`package.json` → `engines.node`). Package manager: **pnpm 10**.
</Note>

## Runtime RPC and discovery

When the runtime starts, `OrcaRuntimeRpcServer` writes **`orca-runtime.json`** (see `getRuntimeMetadataPath` in `src/shared/runtime-bootstrap.ts`) containing:

- `runtimeId`, `pid`, `authToken`
- `transports[]` — typically Unix socket or Windows named pipe **and** WebSocket (default port **6768**, overridable in dev/E2E/serve)

The CLI `RuntimeClient` reads that file, authenticates, and dispatches RPC methods implemented under `src/main/runtime/rpc/`. Global CLI flags (`src/cli/args.ts`): `--json`, `--help`, `--pairing-code`, `--environment`.

| CLI area | Examples | Notes |
| --- | --- | --- |
| Lifecycle | `open`, `serve`, `status` | `serve` runs foreground headless runtime; `open` launches app and waits for reachability |
| Repos / worktrees | `repo add`, `worktree create`, `worktree current` | Worktree selectors: `id:`, `path:`, `branch:`, `active` |
| Terminals | `terminal list`, `read`, `send`, `wait`, `create` | Targets live PTYs in the runtime graph |
| Remote | `--environment`, `--pairing-code` | Resolved before RPC except for `environment`, `serve`, `agent` command trees |

`orca status --json` reports `app.running`, `runtime.reachable`, and `graph.state` (`CliStatusResult` in `src/shared/runtime-types.ts`).

## BYOC agent model

Orca does **not** require an Orca account or hosted model API. The README positions the product as **bring your own** CLI agent subscription (Claude Code, Codex, Grok, etc.). Implementation details:

1. **Catalog** — `TuiAgent` union in `src/shared/types.ts` (claude, codex, grok, cursor, …). Each id has launch/detect metadata in `TUI_AGENT_CONFIG` (`src/shared/tui-agent-config.ts`).
2. **Detection** — `detectInstalledAgents()` probes `TUI_AGENT_CONFIG[*].detectCmd` on PATH (`src/main/ipc/preflight.ts`). Auto-pick order when no default is set: `TUI_AGENT_AUTO_PICK_ORDER` in `src/shared/tui-agent-selection.ts`.
3. **Overrides** — `GlobalSettings.agentCmdOverrides` replaces the launch command per agent id; workspace creation can use `agentId: 'custom'` with a user command template.
4. **Terminal context** — Spawned PTYs receive `ORCA_PANE_KEY`, `ORCA_TAB_ID`, and `ORCA_WORKTREE_ID` so agent hooks and scripts can attribute activity to a pane/worktree without inferring from cwd alone.

Any CLI agent on PATH can be used; the catalog is for detection, trust presets, prompt injection, and UI—not an allowlist.

## Shortest path: install → worktree → agent terminal

<Steps>
<Step title="Install Orca">

Download from [onOrca.dev](https://onOrca.dev) or install via Homebrew (`brew install --cask stablyai/orca/orca`) / AUR packages listed in the README. Ensure your chosen agent CLI is installed and authenticated with its vendor (e.g. `claude`, `codex`, `grok`).

</Step>
<Step title="Open Orca and register a repo">

Launch the desktop app. Add a repository (folder with a git root). Orca persists repos and worktree metadata in its store (`Store` in main process).

</Step>
<Step title="Create a worktree workspace">

Create a new worktree from the UI (or `orca worktree create --repo <selector> --name <name> --json`). Orca creates an isolated git worktree and wires it into the workspace graph. Optional `orca.yaml` setup hooks may run in a first terminal depending on repo policy.

</Step>
<Step title="Start an agent terminal">

Open a terminal tab in that worktree and pick an agent (or accept auto-detected default). Orca spawns the agent TUI via `buildAgentStartupPlan` / PTY spawn with agent-specific env and trust presets.

</Step>
<Step title="Verify from the shell">

From the worktree directory:

```bash
orca status --json
orca worktree current --json
```

Expect `runtime.reachable: true` and `worktree current` resolving to a `path:` selector for the enclosing worktree.

</Step>
</Steps>

<Tip>
For automation without the UI, use `orca worktree create` then `orca terminal create --command "<agent-cmd>"` in the new worktree, or drive an existing pane with `terminal read` / `send` / `wait`. Agent-to-agent messaging uses a separate orchestration surface (experimental)—see `/agent-orchestration`.
</Tip>

## Desktop IPC vs CLI RPC

| Concern | Desktop path | CLI / headless path |
| --- | --- | --- |
| UI state, settings, file picks | `window.api` IPC (`src/preload/index.ts`) | N/A (use RPC + JSON flags) |
| Worktrees, terminals, git | IPC handlers → `OrcaRuntimeService` | `RuntimeClient` RPC |
| PTY I/O | Renderer xterm + main/daemon PTY provider | `terminal read` / `send` / streaming RPC |
| Headless server | — | `orca serve` registers headless PTY runtime, publishes empty graph, prints pairing endpoint |

In desktop mode, a **daemon PTY provider** (`initDaemonPtyProvider`) can route spawns after first window startup; `orca serve` skips the desktop daemon and uses `registerHeadlessPtyRuntime` instead.

## What else lives in the repo

High-level capabilities referenced elsewhere in this wiki (not separate product binaries):

- **SSH remote worktrees** — relay/SSH PTY path with remote agent detection
- **Source control** — GitHub, GitLab, Linear review flows via main-process clients and preload APIs
- **Browser automation** — embedded browser + `agent-browser` bridge; CLI browser command groups
- **Scheduled automations** — `AutomationService` + CLI `automation` specs
- **Computer use** — macOS sidecar (`computer-sidecar` entry) for accessibility automation

Cross-cutting constraints for contributors: `AGENTS.md` (cross-platform shortcuts, SSH-aware changes, Git provider neutrality, worktree-safe editing).

## Related pages

<CardGroup>
<Card title="Installation" href="/installation">
Platform packages, Node/pnpm prerequisites, CLI registration, mobile companion links.
</Card>
<Card title="Quickstart" href="/quickstart">
First session walkthrough with UI and verification commands.
</Card>
<Card title="Worktrees and repos" href="/worktrees-and-repos">
Registration, lineage, selectors, and CLI create/list/remove semantics.
</Card>
<Card title="Terminals and agents" href="/terminals-and-agents">
PTY lifecycle, TuiAgent catalog, ORCA_* env, pane keys, agent hooks.
</Card>
<Card title="Runtime environments" href="/runtime-environments">
Headless serve, pairing codes, remote `--environment` targeting.
</Card>
<Card title="CLI scripting workflow" href="/cli-scripting-workflow">
End-to-end automation with open, status, terminal I/O, and checkpoints.
</Card>
</CardGroup>