Orca

https://github.com/stablyai/orca
Admin
A next-gen IDE for parallel agentic development that enables running multiple AI agents (Claude...
Tokens:481,542
Snippets:3,470
Trust Score:8.1
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### Start Orca server with example IP

Source: https://github.com/stablyai/orca/blob/main/docs/site/content/docs/remote-servers.mdx

An example of starting the server with a specific Tailscale IP address.

```bash
orca serve --pairing-address 100.64.1.20
# Linux
orca-ide serve --pairing-address 100.64.1.20
```

--------------------------------

### Install and start desktop Orca from repository root

Source: https://github.com/stablyai/orca/blob/main/mobile/README.md

Run these commands from the repository root to install dependencies and start the desktop app. The mobile RPC server listens on port 6768.

```bash
pnpm install
pnpm dev
```

--------------------------------

### Load version-matched guide with ORCA skills get

Source: https://github.com/stablyai/orca/blob/main/skill-stubs/orca-per-workspace-env.md

Loads the version-matched guide for the current Orca session before running commands.

```text
ORCA skills get orca-per-workspace-env
```

--------------------------------

### Install dependencies and run locally

Source: https://github.com/stablyai/orca/blob/main/cloud/apps/relay-ops/README.md

Install dependencies and start the dashboard locally. Requires Node 24, pnpm 10, and authenticated gcloud and gh credentials. The server binds to loopback and refreshes data every minute.

```sh
pnpm install
pnpm ops:relay
```

--------------------------------

### Configure agent startup and setup hooks

Source: https://github.com/stablyai/orca/blob/main/docs/site/content/docs/cli/reference.mdx

Commands to initialize worktrees with specific agents and setup policies. The --setup flag accepts run, skip, or inherit.

```bash
orca worktree create --name review-api --agent claude --setup run --json
orca worktree create --name quick-check --agent codex --prompt "Summarize the diff" --setup skip --json
orca worktree create --name hidden-setup --setup inherit --json
```

--------------------------------

### Build and start production server

Source: https://github.com/stablyai/orca/blob/main/docs/site/README.md

Build and serve the production bundle. The start command serves the build on port 3004.

```bash
cd docs/site
pnpm --ignore-workspace install
pnpm --ignore-workspace build
pnpm --ignore-workspace start
```

--------------------------------

### Load version-matched guide with ORCA skills get linear-tickets

Source: https://github.com/stablyai/orca/blob/main/skills/linear-tickets/SKILL.md

Loads the version-matched guide for the linear-tickets skill. Prefer --json. If Orca is not running, start it with ORCA open --json and retry; if it fails with runtime_access_denied, re-run with escalated permissions and do not run ORCA open or restart Orca.

```text
ORCA skills get linear-tickets
```

--------------------------------

### orca.yaml configuration example

Source: https://github.com/stablyai/orca/blob/main/docs/site/content/docs/model/orca-yaml.mdx

An example configuration for a pnpm-based project that installs dependencies, defines an archive script, sets an agent startup policy, and configures default terminal tabs and shared directories.

```yaml
scripts:
  setup: |
    pnpm install
  archive: |
    echo Workspace archived
setupAgentStartupPolicy: wait-for-setup
defaultTabs:
  - title: Agent
  - title: Git status
    command: git status --short
worktree:
  sharedDirectories:
    - .cache
```

--------------------------------

### ORCA emulator command examples

Source: https://github.com/stablyai/orca/blob/main/skill-guides/orca-emulator-android.md

A set of example ORCA emulator commands covering device listing, attaching, tapping, typing, pressing buttons, installing, launching, granting permissions, inspecting the accessibility tree, reading logcat, and killing the emulator. All commands use the --json flag for structured output.

```text
ORCA emulator devices --json
ORCA emulator attach emulator-5554 --json
ORCA emulator tap 0.5 0.85 --json
ORCA emulator type "hello world" --json
ORCA emulator button recents --json
ORCA emulator install ./app-debug.apk --reinstall --json
ORCA emulator launch com.acme.app --json
ORCA emulator permissions grant com.acme.app android.permission.CAMERA --json
ORCA emulator ax --json
ORCA emulator logcat --lines 100 --json
ORCA emulator kill --json
```

--------------------------------

### Install orca-cli skill

Source: https://github.com/stablyai/orca/blob/main/docs/site/content/docs/cli/skills.mdx

Installs the orca-cli skill globally. After installation, load the version-matched command guide with 'orca skills get orca-cli'.

```bash
npx skills add https://github.com/stablyai/orca --skill orca-cli --global
```

--------------------------------

### Install the module

Source: https://github.com/stablyai/orca/blob/main/mobile/packages/expo-two-way-audio/README.md

Install the @orca/expo-two-way-audio package using npm.

```bash
npm i @orca/expo-two-way-audio
```

--------------------------------

### Start the mobile app with Expo

Source: https://github.com/stablyai/orca/blob/main/mobile/README.md

From the mobile/ directory, install dependencies and start the Expo development server. Scan the QR code with your phone's camera on iOS or Expo Go on Android.

```bash
cd mobile
pnpm install
pnpm start
```

--------------------------------

### Load version-matched computer-use guide

Source: https://github.com/stablyai/orca/blob/main/skill-stubs/computer-use.md

Loads the version-matched computer-use guide from the Orca executable used for the current session. Run this before executing Orca commands.

```text
ORCA skills get computer-use
```

--------------------------------

### Install computer-use skill with npx skills add

Source: https://github.com/stablyai/orca/blob/main/docs/site/content/docs/cli/computer-use.mdx

The shipped `computer-use` skill packages the same command surface with safety guidance. Install it into the agent's skill directory.

```bash
npx skills add https://github.com/stablyai/orca --skill computer-use
```

--------------------------------

### Load Orca emulator guide

Source: https://github.com/stablyai/orca/blob/main/skill-stubs/orca-emulator.md

Loads the version-matched Orca emulator guide before running Orca commands. Use this command to fetch the guide from the Orca executable used for the current session.

```text
ORCA skills get orca-emulator
```

--------------------------------

### Orca worktree create with agent and setup flags

Source: https://github.com/stablyai/orca/blob/main/skill-guides/orca-cli.md

Commands for creating worktrees with agent and setup flags. Use `--agent codex --prompt "hi"` to create a worktree with a codex agent and prompt. Use `--agent claude --setup run` to run setup with claude agent. Use `--setup skip` to skip setup. Use `--run-hooks` to run hooks.

```text
ORCA worktree create --name task --agent codex --prompt "hi" --json
ORCA worktree create --name task --agent claude --setup run --json
ORCA worktree create --name task --setup skip --json
ORCA worktree create --name task --run-hooks --json
```

--------------------------------

### Load version-matched orchestration guide

Source: https://github.com/stablyai/orca/blob/main/skill-stubs/orchestration.md

Run this command to print the compact, version-matched orchestration guide for the exact binary that will handle your next commands. It covers the normal local coordinator loop. For a conditional action gate, load only the reference that gate names with --reference; if that is rejected, use --full and read the named bundled reference.

```text
ORCA skills get orchestration
```

--------------------------------

### Start local development server

Source: https://github.com/stablyai/orca/blob/main/docs/site/README.md

Run the docs site locally. Requires pnpm and a checkout of the repository. Serves the app at http://localhost:3004/docs.

```bash
cd docs/site
pnpm --ignore-workspace install
pnpm --ignore-workspace dev
```

--------------------------------

### Create automation targeting a project host setup

Source: https://github.com/stablyai/orca/blob/main/docs/site/content/docs/cli/automations.mdx

Creates a new automation with a daily trigger, a prompt, and a Claude provider, targeting a specific project and host. Use --project-host-setup <id> when you already have a setup id. Optional --source-context '<json>' pins task/provider data to a host/account (pass null on edit to clear).

```bash
orca automations create \
  --name "Remote triage" \
  --trigger daily \
  --time 09:00 \
  --prompt "Triage open issues" \
  --provider claude \
  --project <projectId> \
  --host <hostId> \
  --disabled \
  --json
```

--------------------------------

### TypeScript example using shellScriptTest

Source: https://github.com/stablyai/orca/blob/main/src/main/providers/__tests__/shell-ready-framework/README.md

Shows how to use the `shellScriptTest` function to test ZDOTDIR discovery from a multi-file config. The script includes setup commands (creating config files) and a run command (zsh -c 'env | grep ...'). The output is checked with `toMatchInlineSnapshot`.

```typescript
import { shellScriptTest } from '../__tests__/shell-ready-framework/shell-script-test'

it('discovers ZDOTDIR from multi-file config', async () => {
  const { stdout } = await shellScriptTest(`
    # Setup multi-file config
    mkdir -p ~/.config/zsh
    cat > ~/.config/zsh/env <<'EOF'
export ZDOTDIR="$HOME/.config/zsh"
EOF

    cat > ~/.zshenv <<'EOF'
source "$HOME/.config/zsh/env"
EOF

    # Run: check discovered ZDOTDIR
    zsh -c 'env | grep -E "^(ORCA_|ZDOTDIR|HOME)=" | sort'
  `)

  expect(stdout).toMatchInlineSnapshot(`
    "HOME=<HOME>
    ZDOTDIR=<HOME>/.config/zsh
    "
  `)
})
```

--------------------------------

### Install, build, and test the relay

Source: https://github.com/stablyai/orca/blob/main/cloud/README.md

Run these commands from the cloud directory to install dependencies, build, and run the SQLite-backed test suite.

```sh
cd cloud
pnpm install
pnpm build
pnpm test
```

--------------------------------

### Start worker with launch preferences

Source: https://github.com/stablyai/orca/blob/main/skill-guides/orchestration/references/coordinator-loop.md

Start a worker with specific agent, model, and effort configurations. Omit model and effort when using defaults or unsupported hosts.

```text
ORCA orchestration worker-start --task <task_id> --worktree current --agent claude --model opus --effort high --json
ORCA orchestration worker-start --task <task_id> --worktree current --agent muse --model muse-spark-1.3 --json
```

--------------------------------

### Install computer-use skill

Source: https://github.com/stablyai/orca/blob/main/docs/site/content/docs/cli/skills.mdx

Installs the computer-use skill globally. Use when an agent needs to inspect and operate local desktop app windows.

```bash
npx skills add https://github.com/stablyai/orca --skill computer-use --global
```

--------------------------------

### Orca automations command examples

Source: https://github.com/stablyai/orca/blob/main/skill-guides/orca-cli/references/automations.md

Shows the full set of automations subcommands: list, show, create (with various options), edit, run, runs, and remove. Use --json for JSON output. Create examples demonstrate daily, cron, and hourly triggers, repo and workspace selectors, and the --disabled flag.

```text
ORCA automations list --json
ORCA automations show <automationId> --json
ORCA automations create --name "Daily review" --trigger daily --time 09:00 --prompt "Review open changes" --provider codex --repo id:<repoId> --json
ORCA automations create --name "Weekday triage" --trigger "0 9 * * 1-5" --prompt "Triage issues" --provider claude --repo path:/abs/repo --disabled --json
ORCA automations create --name "Inbox digest" --trigger hourly --prompt "Summarize unread mail" --provider codex --workspace active --reuse-session --json
ORCA automations edit <automationId> --trigger weekdays --time 09:30 --fresh-session --json
ORCA automations run <automationId> --json
ORCA automations runs --id <automationId> --json
ORCA automations remove <automationId> --json
```

--------------------------------

### Start headless Orca server on Linux with orca-ide serve

Source: https://github.com/stablyai/orca/blob/main/docs/site/content/docs/ways-to-run.mdx

Start a headless Orca server on Linux. The CLI is named orca-ide on Linux, so use this command instead of orca serve. Replace the placeholder with a reachable Tailscale IP or hostname.

```bash
orca-ide serve --pairing-address <reachable-tailscale-ip-or-hostname>
```

--------------------------------

### Start worker with placement choices

Source: https://github.com/stablyai/orca/blob/main/skill-guides/orchestration/references/placement-and-remote.md

Commands for starting a worker in the current workspace, a stacked child worktree, or an independent top-level worktree.

```text
# Current workspace; setup is not rerun.
ORCA orchestration worker-start --task <task_id> --worktree current --agent codex --json

# Stacked child worktree.
ORCA orchestration worker-start --task <task_id> --worktree new-child --name <name> --agent codex --setup run --json

# Independent top-level worktree.
ORCA orchestration worker-start --task <task_id> --worktree new-top-level --name <name> --agent codex --setup run --json
```

--------------------------------

### Copy Install Command for .deb package

Source: https://github.com/stablyai/orca/blob/main/docs/site/content/docs/install.mdx

Example of the install command Orca provides via the Copy Install Command button for .deb packages. It uses absolute paths and single-quotes the package path. The package manager shown depends on the system: apt, else dpkg -i for .deb; zypper, dnf, yum, then rpm -Uvh for .rpm.

```bash
/usr/bin/sudo /usr/bin/apt install -- '/home/you/.cache/orca-updater/pending/orca-ide_1.4.194_amd64.deb'
```

--------------------------------

### Start a federated worker and send a follow-up message

Source: https://github.com/stablyai/orca/blob/main/docs/site/content/docs/cli/orchestration.mdx

Starts a remote worker with the specified task, platform, worktree, repo, name, agent, and setup, then sends a follow-up message to a dispatch ID. Later commands route by Dispatch ID; do not repeat --on.

```bash
orca orchestration worker-start \
  --task <taskId> \
  --on windows \
  --worktree new-top-level \
  --repo <exact_remote_repo_selector> \
  --name remote-worker \
  --agent codex \
  --setup run \
  --json
orca orchestration send --to dispatch:<dispatchId> --subject "Follow-up" --body "…" --json
```

--------------------------------

### Get full orchestration skill documentation

Source: https://github.com/stablyai/orca/blob/main/docs/site/content/docs/cli/orchestration.mdx

Run this command after installing orca to retrieve the full, up-to-date orchestration skill documentation, since command flags evolve with the app.

```bash
orca skills get orchestration --full
```

--------------------------------

### Install orca-linear skill

Source: https://github.com/stablyai/orca/blob/main/docs/site/content/docs/cli/skills.mdx

Installs the orca-linear skill globally. Agents should load 'orca skills get orca-linear' before mutating tickets. Covers issue --full, save-issue, list-issues, relations, completion attach+comment flow, and untrusted-ticket rules.

```bash
npx skills add https://github.com/stablyai/orca --skill orca-linear --global
```

--------------------------------

### Create script (<provider>-create.sh)

Source: https://github.com/stablyai/orca/blob/main/skill-guides/orca-per-workspace-env.md

Creates a VM instance from an authenticated snapshot, publishes a port, ensures the repo is at the desired commit (rebuilding only if changed), and optionally starts orca serve in server mode. Fails clearly if snapshotId is missing. Prints one recipe-result JSON object to stdout.

```bash
#!/usr/bin/env bash
set -euo pipefail
# read authenticated snapshotId/scope/project/port/repo*/project_root (env→state→fallback)
# fail clearly if snapshotId is missing (point back to the snapshot phases)
# name = orca-${ORCA_RECIPE_ID}-${ORCA_VM_INSTANCE_ID} (sanitized, length-capped)
# 1. boot from snapshotId with a published port; capture the public URL → pairing address
#    (an externally reachable wss:// URL); trap: remove the environment on error
# 2. remote exec: ensure repo at desired commit; rebuild only if commit changed (cache marker)
# 3. Orca-server mode only: remote exec starting orca serve and reading the recipe JSON it writes
# 4. print one recipe-result JSON object to stdout
```

--------------------------------

### Install CodeBuddy CLI

Source: https://github.com/stablyai/orca/blob/main/docs/site/content/docs/agents/supported.mdx

Use this command to install the CodeBuddy CLI globally via npm.

```bash
npm install -g @tencent-ai/codebuddy-code
```

--------------------------------

### ORCA computer commands for browser automation

Source: https://github.com/stablyai/orca/blob/main/skill-guides/computer-use.md

Example commands for getting app state, setting a value, and pressing a key in a browser. These use the --json flag and target the Edge browser on macOS.

```text
ORCA computer get-app-state --app com.microsoft.edgemac --restore-window --json
ORCA computer set-value --app com.microsoft.edgemac --element-index <addressBarIndex> --value "test123" --json
ORCA computer press-key --app com.microsoft.edgemac --key Return --json
```

--------------------------------

### Load version-matched Orca guide

Source: https://github.com/stablyai/orca/blob/main/skill-stubs/orca-linear.md

Loads the version-matched guide for the Orca executable used in the current session. Run this before executing other Orca commands to ensure you have the correct documentation.

```text
ORCA skills get orca-linear
```

--------------------------------

### Load Orca CLI guide

Source: https://github.com/stablyai/orca/blob/main/skill-stubs/orca-cli.md

Loads the version-matched guide for the Orca CLI before running commands. This command is a prerequisite for using Orca CLI features.

```text
ORCA skills get orca-cli
```

--------------------------------

### Start mock server with pnpm

Source: https://github.com/stablyai/orca/blob/main/mobile/README.md

Starts the mock WebSocket server on port 6768. Connect from the app using endpoint ws://localhost:6768 and token mock-device-token.

```bash
pnpm mock-server           # starts mock WebSocket server on port 6768
```

--------------------------------

### Install Orca via Homebrew and AUR package managers

Source: https://github.com/stablyai/orca/blob/main/README.md

Install the Orca desktop app using Homebrew on macOS or yay on Arch Linux. The AUR package stably-orca-bin installs the prebuilt binary, while stably-orca-git builds from source.

```bash
# macOS (Homebrew)
brew install --cask stablyai/orca/orca

# Arch Linux (AUR) — or stably-orca-git to build from source
yay -S stably-orca-bin
```

--------------------------------

### Load Orca emulator Android guide

Source: https://github.com/stablyai/orca/blob/main/skill-stubs/orca-emulator-android.md

Loads the version-matched guide for the Orca emulator on Android before running Orca commands.

```text
ORCA skills get orca-emulator-android
```

--------------------------------

### Run reproduction script with ORCA_BACKGROUND_LAUNCH=1

Source: https://github.com/stablyai/orca/blob/main/docs/audits/stale-pty-inventory/README.md

Run the reproduction script from a checkout with dependencies installed. It executes the runtime inventory, registration, spawn, and exit methods with deferred provider responses, uses temporary Vitest configuration to reverse only fix.patch for the baseline, and removes its temporary files. It launches no app, enumerates no real processes, and installs nothing.

```sh
ORCA_BACKGROUND_LAUNCH=1 node docs/audits/stale-pty-inventory/reproduce.mjs
```

--------------------------------

### Run OMP relay-host immediate-close probe

Source: https://github.com/stablyai/orca/blob/main/tests/tools/omp-relay-close-lifecycle.md

Runs the opt-in OMP relay-host immediate-close probe with a real installed OMP binary and native PTYs. Requires ORCA_BACKGROUND_LAUNCH=1, an absolute path to the OMP binary, and a shell (defaults to zsh on macOS, bash on Linux; Windows is skipped). Existing native node-pty dependencies must be present; do not install or rebuild as part of the probe.

```sh
ORCA_BACKGROUND_LAUNCH=1 ORCA_OMP_PROBE_BINARY=/absolute/path/to/omp \
  ORCA_OMP_PROBE_SHELL=/bin/bash \
  node node_modules/vitest/vitest.mjs run --config config/vitest.config.ts \
  tests/tools/omp-relay-close-lifecycle.test.mjs
```

--------------------------------

### Create run, task, and start worker (with optional new worktree and model/effort overrides)

Source: https://github.com/stablyai/orca/blob/main/docs/site/content/docs/cli/orchestration.mdx

Commands to create an orchestration run and task, then start a worker. The worker can use the current worktree or a new child worktree. Optional per-worker model/effort overrides apply only to that launch and cannot be combined with --terminal. --agent accepts any Orca agent ID enabled on the worker server (e.g., claude, codex, cursor, antigravity, muse, opencode, opencode2). --model accepts opaque provider model IDs for Claude, Codex, Cursor, Antigravity, and Muse; OpenCode accepts a per-launch model only in an existing worktree. --effort requires --model and only applies when the agent/model supports the level. Overrides show under launch.requested / launch.effective in the start receipt.

```bash
orca orchestration run-create --objective "Split checkout QA and summarize blockers" --json
orca orchestration task-create --spec "Audit billing settings for mobile layout" --task-title "Billing audit" --json
orca orchestration worker-start --task <taskId> --worktree current --agent codex --json
# or new worktree:
orca orchestration worker-start --task <taskId> --worktree new-child --name billing-audit --agent codex --setup run --json
# optional per-worker model / effort (Claude, Codex, Cursor, Antigravity, Muse; not with --terminal):
orca orchestration worker-start --task <taskId> --worktree current --agent claude --model <opaque-model-id> --effort high --json
```

--------------------------------

### Install orca-per-workspace-env skill

Source: https://github.com/stablyai/orca/blob/main/docs/site/content/docs/cli/skills.mdx

Use this command to install the 'orca-per-workspace-env' skill globally. It is intended for setting up or debugging per-workspace environment recipes in 'orca.yaml'.

```bash
npx skills add https://github.com/stablyai/orca --skill orca-per-workspace-env --global
```

--------------------------------

### List and fetch skills with orca skills

Source: https://github.com/stablyai/orca/blob/main/docs/site/content/docs/cli/skills.mdx

Shows the CLI commands agents use to list skills and fetch guides. `--reference <name>` prints a single conditional reference, `--references` lists names, and `--full` prints the kernel plus every reference. Add `--json` for deterministic automation output.

```bash
orca skills list
orca skills get orca-cli
orca skills get orchestration --references
orca skills get orchestration --reference recovery-and-cleanup
orca skills get orchestration --full
orca skills get orca-linear --json
```

--------------------------------

### Core loop: list apps, get state, click element

Source: https://github.com/stablyai/orca/blob/main/skill-guides/computer-use.md

Use these commands in sequence to drive a GUI: list running apps, get the accessibility tree of a specific app, then click an element by its index. Always use the fresh state from each action for the next element index. Element indexes are short-lived and may go stale; never infer them from `elementCount`.

```text
ORCA computer list-apps --json
```

```text
ORCA computer get-app-state --app com.spotify.client --json
```

```text
ORCA computer click --app com.spotify.client --element-index 42 --json
```

--------------------------------

### Runtime commands: open, status, serve

Source: https://github.com/stablyai/orca/blob/main/docs/site/content/docs/cli/reference.mdx

Starts the runtime server in the foreground without opening the desktop window. Use it for Remote Orca Servers or headless environments, and stop it with Ctrl-C.

```bash
orca open --json
orca status --json
orca serve --port 6768 --pairing-address 100.64.1.20 --json
```

--------------------------------

### Base snapshot script (<provider>-base-snapshot.sh)

Source: https://github.com/stablyai/orca/blob/main/skill-guides/orca-per-workspace-env.md

Hand-run script that provisions an environment, installs dependencies, builds the CLI and headless Electron main, snapshots the stopped environment, and merges the snapshot id and repo metadata into state. Requires exported provider scope/project, repo URL/ref, and a git token before the first run; later runs read them from state. Prints only the final state JSON to stdout.

```bash
#!/usr/bin/env bash
set -euo pipefail
# resolve base_name/repo_url/repo_ref/project_root/port/scope/project/timeout (env→state→fallback)
# resolve gh token: GH_TOKEN | GITHUB_TOKEN | `gh auth token`
# 1. provision an environment (timeout/vcpus/published port/snapshot retention); trap: remove on error
# 2. remote exec (long timeout): install pkgs + gh + corepack/pnpm + agent CLI;
#    clone with GIT_ASKPASS(token); write headless main-only build config;
#    dev setup; pnpm install; build CLI; build headless electron main; smoke-check tools
# 3. snapshot stopped environment; parse snapshot id (fail if unparseable)
# 4. merge { baseName, snapshotId, projectRoot, repoUrl, repoRef, port, scope, project } into state
# print only the state JSON to stdout
```

--------------------------------

### Build and run native dev-client for Android and iOS

Source: https://github.com/stablyai/orca/blob/main/mobile/README.md

Use these commands to create a native development client build. Run from the mobile/ directory. The first two commands build the native app, and the third starts the dev server with the dev-client flag.

```bash
pnpm exec expo run:android
pnpm exec expo run:ios
pnpm start --dev-client
```

--------------------------------

### Manual replication shell commands

Source: https://github.com/stablyai/orca/blob/main/src/main/providers/__tests__/shell-ready-framework/README.md

Provides the shell commands from the test for manual replication. It includes setup commands (before the `# Run:` marker) and the run command (after the marker). Note that the test framework applies Orca's wrapper configuration, so manual output may differ.

```bash
# Setup commands (before # Run: marker):
mkdir -p ~/.config/zsh
cat > ~/.config/zsh/env <<'EOF'
export ZDOTDIR="$HOME/.config/zsh"
EOF

cat > ~/.zshenv <<'EOF'
source "$HOME/.config/zsh/env"
EOF

# Run command (after # Run: marker):
zsh -c 'env | grep -E "^(ORCA_|ZDOTDIR|HOME)=" | sort'
```

--------------------------------

### orca capture start

Source: https://github.com/stablyai/orca/blob/main/docs/site/content/docs/cli/reference.mdx

Starts capturing browser activity (console, network, etc.) for the selected worktree. Use --json for structured output.

```APIDOC
## orca capture start

### Description
Starts capturing browser activity (console, network, etc.) for the selected worktree. Use --json for structured output.

### Method
CLI

### Endpoint
orca capture start

### Parameters
#### Options
- **--worktree** (string) - Optional - Worktree to operate on. Use 'active' for the active worktree.
- **--json** (boolean) - Optional - Output in JSON format.

### Request Example
```bash
orca capture start --worktree active --json
```

### Response
#### Success Response
- **status** (string) - Status of the operation.
- **capture** (boolean) - Whether capture is active.

#### Response Example
```json
{
  "status": "success",
  "capture": true
}
```
```

--------------------------------

### Run the queued-terminal-graph-exit reproduction script

Source: https://github.com/stablyai/orca/blob/main/docs/audits/queued-terminal-graph-exit/README.md

Run the reproduction script from the checkout with installed dependencies. The script uses the real renderer graph publisher, main Store.persistPtyBinding, runtime, daemon server, adapter, and local sockets, and creates temporary data/socket paths. It does not launch an Electron window or install dependencies.

```sh
ORCA_BACKGROUND_LAUNCH=1 node docs/audits/queued-terminal-graph-exit/reproduce.mjs /tmp/queued-terminal-graph-exit.json
```

--------------------------------

### Start Pi with UI prompt extension

Source: https://github.com/stablyai/orca/blob/main/tests/tools/pi-ui-prompt-verification.md

Starts Pi in offline mode without a session, loading the Orca status extension and the additional UI prompt extension. Requires Pi 0.84.4 or newer to emit ui_prompt_start and ui_prompt_end events. If launching Pi directly through node or disabling extension discovery, explicitly load Orca's generated orca-agent-status.ts with another -e argument.

```sh
pi --offline --no-session -e /absolute/path/to/orca/tests/tools/pi-ui-prompt-extension.mjs
```

--------------------------------

### Install Orca with Homebrew

Source: https://github.com/stablyai/orca/blob/main/docs/site/content/docs/install.mdx

Installs the Orca desktop app on macOS via Homebrew. The cask tracks the stable channel and is auto-bumped on every stable release.

```bash
brew install --cask stablyai/orca/orca
```

--------------------------------

### List installed skills as JSON

Source: https://github.com/stablyai/orca/blob/main/docs/site/content/docs/cli/skills.mdx

Returns safe selectors for installed skills without exposing local paths. Use this to discover skill IDs for sharing.

```bash
orca skills installed --json
```

--------------------------------

### Install Orca CLI skill

Source: https://github.com/stablyai/orca/blob/main/docs/site/content/docs/cli/overview.mdx

Use these commands to install the Orca CLI skill for agents, either via npx or directly through the CLI for headless environments.

```bash
npx skills add https://github.com/stablyai/orca --skill orca-cli
# headless / no Settings UI:
orca skills install --skill orca-cli
```

--------------------------------

### Start worker on a connected server

Source: https://github.com/stablyai/orca/blob/main/skill-guides/orchestration/references/placement-and-remote.md

Starts a worker on a specific execution host using the --on flag. The flag appears only on worker-start and selects the worker's execution server.

```text
ORCA orchestration worker-start --task <task_id> --on <host> --worktree new-top-level --repo <exact_repo_selector> --name <name> --agent codex --setup run --json
```

--------------------------------

### Use selectors for Orca commands

Source: https://github.com/stablyai/orca/blob/main/docs/site/content/docs/cli/reference.mdx

Examples of using various selectors to target repositories and worktrees without needing long IDs.

```bash
orca repo show --repo id:<repoId> --json
orca worktree show --worktree active --json
orca worktree show --worktree path:/abs/path/to/worktree --json
orca worktree show --worktree branch:feature-name --json
orca worktree show --worktree issue:123 --json
```

--------------------------------

### Reproduce: start server, stream events, drive TUI

Source: https://github.com/stablyai/orca/blob/main/docs/bug-reproductions/opencode2-form-created-kinds/README.md

Commands to reproduce the issue: start opencode serve, stream events via curl, and drive the TUI in a PTY. Requires OPENCODE_SERVER_PASSWORD and a session ID.

```sh
opencode serve --hostname 127.0.0.1 --port 47391     # OPENCODE_SERVER_PASSWORD=<pw>
curl -s -u opencode:<pw> -N http://127.0.0.1:47391/api/event   # tee this
opencode --server http://127.0.0.1:47391 --session <sid>       # drive in a PTY
```

--------------------------------

### Prerequisite: List Orca environments, worktrees, and terminals

Source: https://github.com/stablyai/orca/blob/main/tests/tools/freeze-repro/README.md

Run these commands to verify the Orca desktop is running and to inspect the paired remote environment before starting a freeze repro.

```bash
orca environment list --json
orca worktree list --environment <name> --json | head
orca terminal list --environment <name> --json | head
```

--------------------------------

### Create and list ready tasks

Source: https://github.com/stablyai/orca/blob/main/skill-guides/orchestration/references/coordinator-loop.md

Create independent tasks with dependencies and list them using the ready view as external memory.

```text
ORCA orchestration task-create --spec "<dependent work>" --deps <json_array> --json
ORCA orchestration task-list --ready --brief --json
```

--------------------------------

### Reproduce the audit with ORCA_BACKGROUND_LAUNCH=1

Source: https://github.com/stablyai/orca/blob/main/docs/audits/tui-transcript-close/README.md

Run from the repository root with existing dependencies installed. Launches the reproduction script that uses the actual structured host, record store, journal, handoff coordinator, and transcript watcher against a temporary synthetic Codex transcript.

```sh
ORCA_BACKGROUND_LAUNCH=1 node docs/audits/tui-transcript-close/reproduce.mjs
```

--------------------------------

### Base snapshot script for Vercel sandbox

Source: https://github.com/stablyai/orca/blob/main/skill-guides/orca-per-workspace-env/references/provider-vercel.md

Provision a fresh build sandbox, install tools and clone, build headless, then snapshot. Use fresh sandbox names so cleanup cannot remove an existing environment. The snapshot is taken from a stopped sandbox and the id is parsed from CLI output, failing if unparseable.

```bash
# provision a fresh build sandbox (retain a couple of snapshots)
trap 'cleanup_snapshot "$base"' EXIT
vercel sandbox create --name "$base" --runtime node24 --timeout 30m --vcpus 4 --publish-port "$port" \
  --snapshot-expiration 30d --keep-last-snapshots 2 "${vercel_args[@]}" >&2
# remote build (long timeout): install pkgs+gh+pnpm+agent CLI, clone with GIT_ASKPASS (the helper's
# \$1/\$GH_TOKEN escaping is load-bearing — see the guide's Credentials section — then
# `rm -f /tmp/askpass.sh`), write the headless main-only build config (drop the renderer), dev setup,
# build CLI + headless main, smoke-check
vercel sandbox exec "$base" "${vercel_args[@]}" --timeout 25m --env "GH_TOKEN=$gh_token" … -- bash -lc '…build…' >&2
# snapshot the STOPPED sandbox and parse the id from CLI output (fail if unparseable)
out="$(vercel sandbox snapshot "$base" --stop --expiration 30d "${vercel_args[@]}" 2>&1)"; printf '%s\n' "$out" >&2
snapshot_id="$(printf '%s\n' "$out" | sed -nE 's/.*(snap_[A-Za-z0-9]+).*/\1/p' | tail -1)"
[ -n "$snapshot_id" ] || { echo "snapshot id missing" >&2; exit 1; }
# merge { baseName, snapshotId, scope, project, port, repoUrl, repoRef, projectRoot } into state; print state JSON

```

--------------------------------

### Get microphone samples

Source: https://github.com/stablyai/orca/blob/main/mobile/packages/expo-two-way-audio/README.md

Set up an event listener for microphone data and unmute the microphone to start receiving events.

```JSX
// Set up a function to deal with microphone sample events.
// In this case just print the data in the console.
useExpoTwoWayAudioEventListener(
    "onMicrophoneData",
    useCallback<MicrophoneDataCallback>((event) => {
        console.log(`MIC DATA: ${event.data}`);
    }, []),
);

// Unmute the microphone to get microphone data events
toggleRecording(true);
```

--------------------------------

### Run win-update-e2e via pnpm or node

Source: https://github.com/stablyai/orca/blob/main/tests/tools/win-update-e2e/README.md

Run the end-to-end Windows update test. The first block shows the pnpm wrapper with local setup files or GitHub release tags; the second shows the direct node invocation. The --expect flag is required and must be either cold-restore or survival.

```bash
pnpm win-update-e2e --from <setup.exe> --to <setup.exe> --expect <profile>
# or download release assets via gh (one call each):
pnpm win-update-e2e --from-release v1.4.124-rc.9 --to-release v1.4.125-rc.1 --expect cold-restore
```

```bash
node tests/tools/win-update-e2e/run.mjs --from ... --to ... --expect ...
```

--------------------------------

### Install and update skills with orca CLI wrappers

Source: https://github.com/stablyai/orca/blob/main/docs/site/content/docs/cli/skills.mdx

Local CLI wrappers for headless hosts (SSH, containers, CI, `orca serve`) that resolve the same `npx` commands and add non-interactive flags. Default scope is global; pass `--local` for the current project. `install` targets detected agents (or use `--agent`), `update` only refreshes already-installed skills, and `--dry-run` prints the resolved command.

```bash
orca skills install                                      # list installable names
orca skills install --skill orca-cli --skill orchestration
orca skills install --skill orca-cli --agent claude-code,codex
orca skills install --all --dry-run
orca skills update --all
orca skills update --skill orca-cli --dry-run
```

--------------------------------

### Interactive agent login command

Source: https://github.com/stablyai/orca/blob/main/skill-guides/orca-per-workspace-env/references/ssh-host.md

Example of the interactive command used to perform device-auth login on the persistent host.

```bash
ssh -t user@host '<agent> login --device-auth'
```

--------------------------------

### Run isolated update E2E with --install-dir

Source: https://github.com/stablyai/orca/blob/main/tests/tools/win-update-e2e/README.md

Runs the end-to-end update harness in isolated mode, installing into C:\OrcaE2E. Requires --install-dir to be absolute and spaces-free; the harness snapshots and restores registry keys and shortcuts, and always uninstalls the test install at teardown.

```bash
pnpm win-update-e2e \
  --from-release v1.4.124-rc.9 --to-release v1.4.125-rc.1 \
  --expect cold-restore --install-dir C:\OrcaE2E
```

--------------------------------

### Reproduce script command

Source: https://github.com/stablyai/orca/blob/main/docs/audits/browser-destroyed-guest-retention/README.md

Run this command from the repository root to reproduce the audit. It requires dependencies to be installed and launches the actual manager with EventEmitter WebContents fixtures.

```sh
ORCA_BACKGROUND_LAUNCH=1 node docs/audits/browser-destroyed-guest-retention/reproduce.mjs
```

--------------------------------

### Install orca-emulator-android skill

Source: https://github.com/stablyai/orca/blob/main/docs/site/content/docs/cli/skills.mdx

Installs the orca-emulator-android skill globally. Use for adb-connected Android AVDs/devices: list/boot, tap/swipe/type, hardware buttons, install/launch, permissions, accessibility tree, logcat. Load details with 'orca skills get orca-emulator-android'.

```bash
npx skills add https://github.com/stablyai/orca --skill orca-emulator-android --global
```

--------------------------------

### Reproduce terminal-close-observed-exit with shell commands

Source: https://github.com/stablyai/orca/blob/main/docs/audits/terminal-close-observed-exit/README.md

Run the reproduction script and the test suite from the checkout with dependencies installed. The script runs eight scenarios before and after the change, using the actual runtime close method and real daemon socket endpoints. It does not install dependencies, launch a UI, or alter the checkout; results.json preserves the recorded result, so use a separate output path when rerunning.

```shell
ORCA_BACKGROUND_LAUNCH=1 node docs/audits/terminal-close-observed-exit/reproduce.mjs /tmp/terminal-close-observed-exit.json
ORCA_BACKGROUND_LAUNCH=1 node node_modules/vitest/vitest.mjs run --config config/vitest.config.ts src/main/runtime/terminal-close-observed-exit.test.ts
```

--------------------------------

### Install orchestration skill

Source: https://github.com/stablyai/orca/blob/main/docs/site/content/docs/cli/skills.mdx

Installs the orchestration skill globally. Use when an agent should coordinate other agents through Runs, tasks, supervised workers, and decision gates. Always load 'orca skills get orchestration --full' before mutating orchestration state.

```bash
npx skills add https://github.com/stablyai/orca --skill orchestration --global
```

--------------------------------

### Reproduce the quota race with ORCA_BACKGROUND_LAUNCH

Source: https://github.com/stablyai/orca/blob/main/docs/audits/claude-history-window-budget/README.md

Runs the seven-case fixture against real temporary files, injecting an append after the size snapshot. Each child has a 45-second timeout and a 512 MiB old-space ceiling; no application window or provider process starts.

```sh
ORCA_BACKGROUND_LAUNCH=1 node docs/audits/claude-history-window-budget/reproduce.mjs
```

--------------------------------

### Start Orca server with pairing address

Source: https://github.com/stablyai/orca/blob/main/docs/site/content/docs/remote-servers.mdx

Use the --pairing-address flag to specify the server's Tailscale IP or hostname. On Linux, use the orca-ide command instead of orca.

```bash
orca serve --pairing-address <server-tailscale-ip-or-hostname>
# Linux
orca-ide serve --pairing-address <server-tailscale-ip-or-hostname>
```

--------------------------------

### orca computer list-apps

Source: https://github.com/stablyai/orca/blob/main/docs/site/content/docs/cli/reference.mdx

Lists the applications available for desktop computer use. Use the --json flag to get structured output.

```APIDOC
## orca computer list-apps

### Description
Lists the applications available for desktop computer use.

### Method
CLI command

### Command
`orca computer list-apps --json`

### Parameters
#### Flags
- **--json** (boolean) - Optional - Output in JSON format.

### Response
#### Success Response
- JSON array of application objects.

#### Response Example
```json
[
  {
    "name": "Safari",
    "bundleId": "com.apple.Safari"
  }
]```
```

--------------------------------

### Per-workspace Vercel sandbox create with orca serve

Source: https://github.com/stablyai/orca/blob/main/skill-guides/orca-per-workspace-env/references/provider-vercel.md

Creates a Vercel sandbox from an authenticated snapshot, publishes a port, and starts an orca serve process inside it. Requires snapshot_id, scope, project, port, repo_url, repo_ref, and project_root; fails if snapshot_id is missing or ORCA_VM_INSTANCE_ID is too long. The script derives a wss:// pairing address from the published URL, rebuilds only when the commit changes, and outputs enriched recipe JSON with userData.

```bash
#!/usr/bin/env bash
set -euo pipefail
# resolve from env→state→fallback: snapshot_id, scope, project, port, repo_url, repo_ref, project_root
vercel_args=(); [ -n "$scope" ] && vercel_args+=(--scope "$scope"); [ -n "$project" ] && vercel_args+=(--project "$project")
[ -n "$snapshot_id" ] || { echo "snapshotId missing — build the base and auth snapshots first" >&2; exit 1; }
gh_token="${GH_TOKEN:-${GITHUB_TOKEN:-$(command -v gh >/dev/null 2>&1 && gh auth token 2>/dev/null || true)}}"
recipe_id="${ORCA_RECIPE_ID:-vercel-sandbox}"
recipe_id="${recipe_id//./-}"  # Vercel names forbid dots.
instance_id="${ORCA_VM_INSTANCE_ID:-$(date +%s)}"
max_recipe_id_length=$((128 - ${#instance_id} - 6))  # Preserve the unique instance suffix.
[ "$max_recipe_id_length" -gt 0 ] || { echo "ORCA_VM_INSTANCE_ID is too long for a Vercel sandbox name" >&2; exit 1; }
name="orca-${recipe_id:0:max_recipe_id_length}-${instance_id}"

# Arm cleanup BEFORE create so a failing create can't leak a half-built paid sandbox.
cleanup_on_error() { [ "$?" -ne 0 ] && vercel sandbox remove "$name" "${vercel_args[@]}" >/dev/null 2>&1 || true; }
trap cleanup_on_error EXIT

# 1. boot from the authenticated snapshot, publish the serve port
create_output="$(vercel sandbox create --name "$name" --snapshot "$snapshot_id" \
  --timeout 30m --publish-port "$port" "${vercel_args[@]}" 2>&1)"; printf '%s\n' "$create_output" >&2
# Vercel prints the published https URL; derive the external wss:// pairing address from it
public_url="$(printf '%s\n' "$create_output" | sed -nE 's#.*(https://[^[:space:]]+\.vercel\.run).*#\1#p' | head -1)"
[ -n "$public_url" ] || { echo "no published URL in create output" >&2; exit 1; }
pairing_ws="${public_url/https:\/\//wss://}"

# 2. (remote) ensure the repo is at the right commit; rebuild only if the commit changed (cache marker)
vercel sandbox exec "$name" "${vercel_args[@]}" --timeout 20m \
  --env "GH_TOKEN=$gh_token" --env "ORCA_PROJECT_ROOT=$project_root" \
  --env "ORCA_REPO_URL=$repo_url" --env "ORCA_REPO_REF=$repo_ref" \
  -- bash -lc 'set -euo pipefail; cd "$ORCA_PROJECT_ROOT"; \
    export GIT_TERMINAL_PROMPT=0; \
    # Escaping is load-bearing here: re-test the fetch after any edit to the nested quoting.
    if [ -n "${GH_TOKEN:-}" ]; then \
      printf "%s\n" "#!/usr/bin/env bash" "case \"\$1\" in *Username*) echo x-access-token;; *Password*) echo \"\$GH_TOKEN\";; esac" > /tmp/askpass.sh; \
      chmod 700 /tmp/askpass.sh; export GIT_ASKPASS=/tmp/askpass.sh; fi; \
    git fetch origin "$ORCA_REPO_REF"; \
    git checkout -B "$ORCA_REPO_REF" FETCH_HEAD; \
    rm -f /tmp/askpass.sh; \
    c="$(git rev-parse HEAD)"; [ -f .orca-built ] && [ "$(cat .orca-built)" = "$c" ] || { \
      pnpm install --prefer-offline && pnpm run build:cli && \
      node config/scripts/run-electron-vite-build.mjs --config config/electron-vite.vm-serve.config.ts && \
      printf "%s" "$c" > .orca-built; }' >&2

# 3. (remote) start orca serve in the background, writing recipe JSON to a file; poll until it parses
recipe_json="$(vercel sandbox exec "$name" "${vercel_args[@]}" --timeout 60s \
  --env "ORCA_PORT=$port" --env "ORCA_PROJECT_ROOT=$project_root" --env "ORCA_PAIRING_ADDRESS=$pairing_ws" \
  -- bash -lc 'set -euo pipefail; cd "$ORCA_PROJECT_ROOT"; rm -f /tmp/orca-recipe.json /tmp/orca-serve.log; \
    nohup pnpm exec orca-dev serve --port "$ORCA_PORT" --project-root "$ORCA_PROJECT_ROOT" \
      --pairing-address "$ORCA_PAIRING_ADDRESS" --recipe-json >/tmp/orca-recipe.json 2>/tmp/orca-serve.log </dev/null & \
    pid=$!; for _ in $(seq 1 80); do \
      node -e "JSON.parse(require(\"node:fs\").readFileSync(\"/tmp/orca-recipe.json\",\"utf8\"))" >/dev/null 2>&1 && { cat /tmp/orca-recipe.json; exit 0; }; \
      kill -0 "$pid" 2>/dev/null || { cat /tmp/orca-serve.log >&2; exit 1; }; sleep 0.25; \
    done; cat /tmp/orca-serve.log >&2; echo "serve recipe JSON timed out" >&2; exit 1')"

# 4. print serve's JSON enriched with userData (single object on stdout)
node -e 'const p=JSON.parse(process.argv[1]); console.log(JSON.stringify({...p, schemaVersion:1,
  userData:{...p.userData, provider:"vercel-sandbox", resourceId:process.argv[2], snapshotId:process.argv[3]}}))' \
  "$recipe_json" "$name" "$snapshot_id"
trap - EXIT
```

--------------------------------

### Install and update agent skills via CLI

Source: https://github.com/stablyai/orca/blob/main/docs/site/content/docs/remote-servers.mdx

Use these commands to manage agent skills directly from the server shell when the Settings UI is unavailable.

```bash
orca skills install --skill orca-cli --skill orchestration
orca skills update --all
```

--------------------------------

### Set up folder workspace

Source: https://github.com/stablyai/orca/blob/main/skill-guides/orchestration/references/placement-and-remote.md

Registers an existing folder as a workspace. The folder must be a valid Git repository; a plain directory is rejected.

```text
ORCA project setup-folder --project <project_id> --host <host_id> --path <abs_path> --kind folder --json
```

--------------------------------

### Run reproduction script

Source: https://github.com/stablyai/orca/blob/main/docs/audits/daemon-stream-retention/README.md

Execute the reproduction script from the worktree root after installing dependencies. This script bundles the DaemonStreamDataBatcher and uses loopback TCP sockets to measure queue behavior.

```sh
ORCA_BACKGROUND_LAUNCH=1 node docs/audits/daemon-stream-retention/reproduce.mjs
```
Tokens:
Raw