The idea behind Orca goes like this: if one coding agent can solve a task with a sixty percent probability, it’s cheaper to run three different agents in parallel and pick the best result than asking one three times. The problem is that three agents in one working copy will stomp on each other. Orca takes care of this literally — for each task its own git worktree, its own branch, its own directory on disk, its own terminal.
The authors call this not an IDE, but an ADE — Agent Development Environment. The difference is not just marketing: Orca has no own model or subscription; you bring yours — Claude Code, Codex, Cursor CLI, anything else — and Orca provides the wrapper around them.
This is a complete guide: installation, working model, all major subsystems with concrete steps and hotkeys, the full CLI, remote modes, ready-made recipes — and separately what isn’t written about on the landing page.
Project at a glance. Orca is built by Stably (Y Combinator, winter 2022, San Francisco, according to YC — a four-person team). Repository stablyai/orca, license MIT, about 40k stars and 2.8k forks at the time of writing. Tech stack — TypeScript + Electron. Product is free, there is a separate enterprise tariff.
What’s inside. 1 — Orca model. 2 — installation. 3 — first session. 4 — navigation. 5 — common files between worktrees. 6 — agents (including GLM connection and account switching). 7 — review, commit, PR. 8 — editor, viewers, explorer. 9 — browser and Design Mode. 10 — terminal. 11 — four run modes. 12 — CLI and orchestration. 13 — mobile app. 14 — notifications. 15 — settings and telemetry. 16 — five ready-made recipes. 17 — what breaks. 18 — sober assessment.
Part 1. Orca Model: Four Levels
Before installing, it’s worth understanding the hierarchy — it explains almost all of the interface behavior.
Diagram based on onorca.dev documentation
Repository. Local checkout you add with the button Add Repo. It has a base ref — usually origin/main — from which new worktrees are branched by default. It can be changed in the repository settings.
Worktree. The key entity. The documentation’s wording is blunt: “every task gets its own on-disk copy of the repo via git worktree.” These are real Git worktrees, not an abstraction on top — you can enter the directory with a normal terminal and work with standard git.
Lifecycle: Create → Work → Review → Ship → Archive/Delete. Creation is asynchronous: the dialog closes immediately, Git operations finish in the background.
A worktree can be started from the repository’s base ref, from another local branch, from a specific SHA, or from a remote branch — Orca will pull it in itself. The branch name is derived from the task name or from the attached GitHub/Linear/Jira ticket; emoji shortcodes like :rocket: become a readable fragment of the name (rocket). In the Advanced tab you can set the branch name manually.
In the sidebar, worktrees are grouped by projects, with filters: dormant workspaces, default branches, branches created via the CLI, detached HEAD states. Multiple selection with Cmd/Ctrl-click enables group operations.
Tabs, Panels, and Splits. Documentation wording: “Tabs group into panes; panes split into layouts.”
- A tab is a single entity: a terminal, editor buffer, browser, diff. Tabs can be dragged within a group and between groups.
- A split is created by dragging a tab to the edge of the panel: to the right — horizontal split, to the bottom — vertical. Nesting is unlimited.
- Terminal tabs can also share inside themselves — via the tab menu or a header button.
- Pinned boundaries do not shift when resizing the window; their positions are remembered per worktree.
- Each worktree has its own layout and survives context switches and app restarts.
| Action | macOS | Windows / Linux |
|---|---|---|
| Next / previous tab (any type) | Cmd+Shift+] / [ |
Ctrl+Shift+] / [ |
| Next / previous tab of the same type | Cmd+Option+] / [ |
Ctrl+Alt+] / [ |
| Previous recently used tab | Ctrl+Tab |
Ctrl+Tab |
| Close all file tabs | Cmd+Option+W |
Ctrl+Alt+W |
| Split right | Cmd-\ |
Ctrl-\ |
| Split down | Cmd-Shift-\ |
Ctrl-Shift-\ |
Agent-session. “One CLI agent in one terminal in one worktree.” Orca monitors state and draws a glyph:
| Indicator | Value |
|---|---|
| Spinner | agent is running |
| Amber question mark | waiting for your action — permission or input |
| Emerald check / dot | finished or quietly active |
| Red dot | blocked, interrupted, error |
| Gray dot | idle |
| Nothing | ordinary shell, agent not recognized |
Status is determined not by text heuristics, but via terminal OSC headers and status hooks emitted by Claude Code, Codex, and compatible agents. So an exotic agent may have no indicator at all — this is not a bug, but a lack of integration.
The session lifecycle in the docs is described as: launch from the picker → OSC header handling update phase → idle detection that triggers a notification → exit, after which a Restart chip appears.
Part 2. Installation
Desktop — macOS (Apple Silicon and Intel), Windows, Linux.
# macOS, Homebrew
brew install --cask stablyai/orca/orca
# Arch Linux, AUR
yay -S stably-orca-bin
Direct downloads from GitHub releases:
orca-macos-arm64.dmg — macOS Apple Silicon
orca-windows-setup.exe — Windows
orca-linux.AppImage — Linux (there's also a .deb)
What happens on the first run. Orca asks for access to the home directory to work with repositories, imports existing Claude, Codex, and Ghostty configurations if they exist, and shows an empty workspace — add your first repository.
Updates. Auto-update is enabled, the default channel is stable. When you click on “Check for Updates” modifiers give access to other channels: Shift — fresh RC pre-release, Cmd/Ctrl — build with performance tag, Option (macOS) — validated local builds.
Releases come out almost daily. As of August 12, 2026, the changelog on the site shows 1.4.180 (August 11). The GitHub releases page at the time of check returned a newer version — the discrepancy is due to asset publication delays and caching; rely on the changelog and the built-in updater.
Platform notes. On macOS the build is signed and notarized — first-run confirmation prompts are normal. On Windows the shell by default (PowerShell, cmd, WSL) is chosen in Settings → Terminal.
Part 3. The first session: three agents for one task
This is the scenario Orca is designed for. Step by step, as in the official tutorial.
- Add a repository. Click Add Repo in the sidebar, choose a local checkout. Orca reads the git state and takes the default branch as base ref.
- Create a worktree. The “+” icon next to the repository name. Enter a task description — if you skip, Orca will generate a sea-themed name. A launcher will open with your default agent (or an empty terminal if configured that way).
- Choose an agent. In the terminal — a combo box to choose: Claude Code, Codex, Cursor CLI and others. Orca will launch the CLI agent with the correct working directory and your credentials.
- Repeat twice. Three worktrees, three different agents, the same prompt.
- Arrange the panels. Drag tabs to the right or bottom edge — you’ll get splits. See all three at once.
- Compare and ship. Each worktree has its own diff. Annotate the best, commit, push, create a PR. The losing worktrees are removed with one click along with their branches.
Justification from the documentation, and it’s honest: “Different agents make different mistakes. Running the same task in parallel is cheaper than sequential retries and surfaces disagreement as a signal.” The discrepancy between agents is itself a useful signal: if three did the same, the task is simple; if they diverged — where they diverged is where you need to look more closely.
The economics of this approach depend on your plan. Three agents for one task — a triple spend of limits. On a five-hour window plan you’ll hit the ceiling faster than you’d expect, and Orca honestly shows this in the status bar (see part 6).
Part 4. Navigation when there are ten worktrees
Three search tools, each with its own scope.
| What | Keys | What it searches |
|---|---|---|
| Quick Open | Cmd-P / Ctrl-P |
files of the current worktree; ranked by recency plus match quality, file names first; gitignored — in a second pass |
| New tab OmniBox | the “+” button in the tab bar | open tabs, files, URLs and agents in one field; an already open file is not duplicated, it switches to the existing tab |
| Jump Palette | Cmd-J / Ctrl-J |
all worktrees and all tabs at once |
Jump Palette is the main tool when you have ten worktrees. What it shows:
- recent chats and terminals, up to six, by activity;
- recent worktrees by last focus time;
- projects and groups of repositories;
- basically all worktrees, grouped by repository;
- cached headers and numbers of GitHub PR (
#123) and GitLab merge request (!123); - open tabs by aliases like —
terminal,simulator.
Inside the palette:
Enter— go to;Shift-Enter— open in a new split instead of replacing the current panel;Tab— filter by host or project;Cmd-1…Cmd-6(Ctrl-1…Ctrl-6) — quick jump to recent sessions by number.
All shortcuts can be remapped in Settings → Shortcuts.
Part 5. Splitting files between worktrees
The most common practical pain: a new worktree is a clean checkout, thus without node_modules, without .env, without venv. Orca provides three mechanisms, and they complement each other.
Worktree Shared Paths (Settings → Repository) — materialize gitignore directories into the new worktree: on macOS via APFS clone-copy, on other systems via symlinks.
orca.yaml — the field worktree.sharedDirectories for large rebuildable trees like node_modules.
.worktreeinclude — a file listing gitignored paths that should be copied, not symlinked.
The difference between copy and symlink is fundamental here. node_modules can be shared by symlink — rebuilding it is identical. But .env with a local port or a SQLite database must be copied: if three agents write to the same file through a symlink, worktree isolation becomes a fiction, and you’ll spend half a day debugging race conditions.
Création hooks. In Settings → Repository → Hooks you can attach commands that run after creating a worktree — a typical use is: npm install, environment restoration, migrations.
Part 6. Agents
Who is supported and to what depth
| Agent | Level of integration |
|---|---|
| Claude Code | deep: usage, hot-swap accounts, hooks, subagents |
| Claude Agent Teams | disabled by default, enabled in settings |
| Codex | deep: usage, hot-swap, continuation of sessions |
| Cursor CLI | first class: run from the combo box, full state definition via OSC, Restart chip on exit |
| GitHub Copilot CLI, Aider, Cline, Continue | auto-configuration |
Beyond them are agents Orca knows and launches automatically, but without accounting for consumption and account switching: Grok, OpenCode, Pi, OMP, Gemini, Antigravity, Ante, Goose, Amp, Kilocode, Kiro, Charm Crush, Auggie, Autohand, Codebuff, Command Code, Devin, Droid (Factory), Kimi, Mistral Vibe, MiniMax, Qwen Code, Rovo Dev, Hermes, OpenClaw, Trae. Plus any terminal agent manually — Orca ultimately just keeps the PTY.
Permissions: the most important place in the whole guide
Orca by default supplies agents with flags of full autonomy. The exact list from the documentation:
| Agent | Default flag |
|---|---|
| Claude | --dangerously-skip-permissions |
| Codex | --dangerously-bypass-approvals-and-sandbox |
| Others (Gemini and others) | --yolo |
This literally means: the agent runs commands in your directory without prompts. It won’t “ask before rm -rf”, won’t “show the command.” The flag is named dangerously not for show.
The mode is globally switchable in Settings → Agents → Agent Permissions (Yolo ↔ Manual) and separately for each agent — the run arguments are edited there as well. Before running the first worktree on a real project — go there and see what’s selected.
Separately about the fact that a worktree is not a sandbox. It’s just a normal directory on your disk with your rights. The agent can see your entire home directory, your SSH keys, ~/.aws, shell history. Worktree isolation solves conflicts between agents, not the problem of untrusted code.
If you’re running an agent on someone else’s repository or with MCP servers pulling external content, use a Cloud VM on a worktree (part 11) or a separate machine via SSH. We discussed the boundaries of this model in the topic “Agent in ‘allow everything’ mode: container, microVM or a separate machine”.
Claude Code
Setup and connection — three steps:
npm i -g @anthropic-ai/claude-code
# then the usual login from any terminal
```Next, Orca itself finds the config `~/.claude`. Launch — open a terminal in any worktree and choose Claude Code from the combo box; the working directory will become the worktree.
What the integration provides:
- **Usage.** Orca reads local consumption state from `~/.claude` and shows in the status bar the current usage and proximity to the rate limit.
- **Multiple accounts** with one-click switching, including in the middle of an active session.
- **Subagents and Agent Teams** are shown as expandable child lines in the worktree agents list and in the Agent Dashboard.
- **Hooks and memory files** at the repository level.
### Codex
Installation — per OpenAI's official documentation, then log in from the terminal; Orca reads credentials from `~/.codex`. Launch — choose Codex from the combo box, the session starts in the worktree directory.
Features:
- **Multiple accounts.** “System default” is your actual login in `~/.codex`; additional (managed) accounts get isolated storage.
- **Windows/WSL.** Codex works through WSL, home directories of accounts are isolated here: `~/.local/share/orca/codex-accounts/<id>/home`.
- **Subagents** are shown as child lines with a chevron.
- **«Continue in New Session…»** — menu item that launches a new session, injecting a limited handoff-prompt from the previous transcript. Useful when the context is overflowing and you don’t want to drop the thread.
- **Restart** restarts the agent with the same account, if the switch did not switch the active one earlier.
### Switching accounts (hot-swap) — step by step
*Orca screenshot, [onorca.dev](https://www.onorca.dev/docs/agents/codex-hot-swap)*
1. Authenticate each Codex account in the usual way through the terminal — credentials will be stored in `~/.codex`.
2. Open **Settings → Agents → Codex Accounts**. Orca will show all found accounts along with usage metrics and limits.
3. Assign meaningful labels — “personal”, “work”.
4. Switching — click the Codex status chip in the status bar to open the account switcher.
Behavior nuances:
- **New** sessions pick up the selected account; **already running** sessions retain the original account until restart.
- For managed accounts, Orca mirrors settings from `~/.codex/config.toml` into runtime-home. If the source file is missing, empty, or unreadable — a warning is shown and the last successfully synchronized settings are kept.
- The Claude switch works identically, using `~/.claude` as the data directory.
### Cursor CLI
Installed according to Cursor documentation, logs in once, then Orca finds it in the system `PATH`. Important caveat from the docs: **model selection is entirely on the Cursor CLI side; Orca does not override it** — configure inside the CLI itself.
### Connecting GLM-5.2 and other OpenAI-compatible providers
A separate documentation page that’s easy to miss, but practical. Active Z.ai CodePlan subscription with access to GLM Coding Plan is required.
**For Claude Code** — environment variables in `~/.claude/settings.json`:
CLAUDE_CODE_AUTO_COMPACT_WINDOW=1000000
ANTHROPIC_DEFAULT_HAIKU_MODEL=glm-4.5-air
ANTHROPIC_DEFAULT_SONNET_MODEL=glm-5.2[1m]
ANTHROPIC_DEFAULT_OPUS_MODEL=glm-5.2[1m]
The suffix `[1m]` includes the option with context up to a million tokens. For coding, it’s recommended to set effort to `max`.
**For OpenAI-compatible wrappers** — OpenCode, Cline, Kilo Code, Roo Code, Droid:
| Parameter | Value |
|---|---|
| Base URL | `https://api.z.ai/api/coding/paas/v4` |
| Model name | `glm-5.2` |
| Context window | `1000000` |
| Image support | disable if image support is not explicitly documented |
**For OpenClaw** — edit `~/.openclaw/openclaw.json`: add GLM-5.2 to the list of models with `contextWindow: 1000000` and `maxTokens: 131072`, then restart the gateway:
```bash
openclaw gateway restart
This is exactly the case where a “subscription of your own” from Orca’s philosophy yields practical benefits: the tool does not force you to pay specifically Anthropic or OpenAI. But check your provider’s terms — proxying someone else’s model as an Anthropic-compatible API lives only as long as the gateway supports it.
Agent Dashboard
Enabled in Settings → Experimental → Agent Dashboard. Two views:
- Dashboard — Kanban with columns Needs You, Working, Done, Idle (the last hidden by default).
- Agent Map — topological visualization: worktree, nested projects, with a line showing the agent’s origin if known.
Filters: by project, by workspace status, by PR/MR status. On the card — agent icon and session name, preview of the last message, project icon, worktree name and its age, color indication (amber — attention needed, green — finished).
Session history and resumption
The Agent Session History panel — right sidebar, tab Agents. In the header a counter like “12 shown · 47 recent” and a search bar: filters by session name, working directory, branch, model, and the preview text.
Scope: Workspace (current worktree) / Project (active project) / All (all sessions found across all agents).
View Options: choose specific agents — Claude, Codex, Hermes, Pi, OMP, Cursor, Gemini, Antigravity, Rovo Dev, Copilot, OpenCode, Grok, OpenClaw, Devin, Droid, Kimi; sort by Last updated or Created; group by Project, Folder, or Agent; toggle “Hide empty sessions”.
Actions on a session line: Resume (opens a new terminal in the session’s cwd and runs the agent’s resume command), copy resume command, copy session ID or log path, open or show the log file, open the working directory.
Where transcripts are stored:
Codex ~/.codex/sessions
Claude ~/.claude
OpenCode ~/.local/share/opencode/opencode.db
Resume requires a local workspace — remote workspaces cannot directly execute a resume command.
Hibernation
Dormant Orca background agent terminals are put to sleep, and when returning to the worktree they are brought back up. Conditions: the agent is in the done state (finished its turn and is not waiting for anything), idle timeout has elapsed, no key presses, the agent type is supported — Claude, Codex, Gemini, Antigravity, OpenCode, Pi, MiMo Code, Droid, Grok, Devin, OMP.
Settings — Settings → Experimental → Agent hibernation, a window from 1 minute to 24 hours, default 30 minutes. The countdown starts from the last done; any keystroke, new output, or returning to the tab resets it.
Fair wake-up: Orca restarts the CLI with the same resume flags as the session history — claude --resume <id>, codex resume <id> and so on, — therefore the dialogue, working directory and provider session continue from the same place.
Non-summarizable terminals do notHibernate: Cursor CLI, Hermes, Copilot, Trae — they simply keep on living.
Cost and quota tracking
Tracking is available for Claude Code, Codex, Gemini, OpenCode, Kimi Code and MiniMax.
In the status bar: current usage relative to the active account plan, window reset times — five-hour, daily, weekly (and “Claude Fable weekly” where applicable), and a warning indicator when crossing the 80 % threshold.
Click opens a popover: all tracked providers with icon, name, plan, nearest reset and bars for each window, sorted so that the tightest limit is on top. Two modes — Detailed (full bars, captions, percentages) and Compact (only the tightest window). In Settings → Appearance you choose whether to show “% used” or “% remaining”.
In the Stats block cost estimates for known model families may be shown; lines marked with “• inferred pricing” are calculated using Orca’s local price table, not the provider’s billing.
Data is taken from the local state that each agent maintains on disk — ~/.claude, ~/.codex and similar paths. No API calls and no additional authorization. Plus: nothing unnecessary goes anywhere. Minus: the freshness of figures is determined by when the agent updated its accounting, not by real time.
Chat UI on top of the terminal
An experimental addon over the terminals of supported agents: Claude, Codex, Grok, OMP. OMP sessions open directly in the Chat UI.
Enable: Settings → Experimental → Chat UI → turn on, optionally set Default view = Chat UI for new tabs of supported agents. Switch Chat UI ↔ terminal — from the agent panel.
What it provides:
- Composer: sending messages, stopping the current move, attachments of files and pictures;
- drafts and attachments survive disconnects and reconnections;
/opens slash commands and detected skills, filtered for a specific agent;- pills of model and option selection: Claude model list is taken from the host-installed CLI; Codex switches the pill model (under the hood sends
/model <id>); Grok — model with-mflag at launch or/modelmid-session, reasoning effort--reasoning-effortat launch or/effortmid-session; - structured permission cards and Claude questions (AskUserQuestion) render directly in the transcript, you can answer from the composer.
Literal author’s caveat: «Transcript fidelity, streaming, and terminal parity are still under active tuning. Prefer the raw TUI when you need every OSC/status detail». That is, today Chat UI is a convenience, not a source of truth. When every detail of output matters — view the raw terminal.
Hooks and memory
Orca does not invent its format but reads existing conventions: the folders .claude/ and .codex/ in the repository, memory files CLAUDE.md (Claude) and AGENTS.md (Codex) in the root or in nested directories — they are edited inline via the file explorer.
Agent status hooks (working / waiting / done) are managed in Settings → Agents → Agent status hooks, there is also a CLI:
orca agent hooks status --json
orca agent hooks on --json
orca agent hooks off --json
Endpoints are stored locally and re-fetched on every call, so long-lived sessions keep reaching the live Orca server even after the application restarts. On Windows and POSIX the storage format is different: endpoint.cmd versus endpoint.env.
Part 7. Review, Commit, and Shipping
Parallel agents are pointless if you don’t read what they wrote. The review part in Orca is considerably better implemented than in the average “AI editor.”
Diff viewer
A combined diff is shown for all staged, unstaged, and untracked files at once, by default relative to the start-from ref.
| Key | Action |
|---|---|
j / k |
navigate files |
n / p |
navigate hunks |
F7 / Shift+F7 |
navigate changes |
s |
stage a hunk |
c |
comment on a line |
What it can do:
- image diffs — three modes: side-by-side, swipe, and onion-skin;
- HTML preview — for working HTML files, the combined diff has an “Open Preview to the Side”;
- conflict resolution — three-way view with inline editing;
- visual staging — by hunks and by individual lines, i.e.,
git add -pwith a mouse; - changing the base for comparison — from start-from ref to any commit, branch, or base ref, right from the diff toolbar;
- collapsible file tree with a resizable panel width that is remembered across sessions.
Line wrapping in the diff is off by default. It can be toggled from the actions menu in the editor header or globally in Settings → General → Diff Word Wrap. In the standard Monaco editor, wrapping is on by default — these are two separate settings, and it can be confusing.
Annotating AI diffs
Steps:
- Hover the cursor over a diff line — a
+appears in the gutter. - Click it or press
cwhen the cursor is on the desired line. - Write a note — markdown is supported.
Cmd-Enterto save,Escto cancel.
Comments are attached to lines and track code edits. Threads can be resolved; unresolved ones are sent in the next batch.
Sending to the agent — the “Send to agent” button at the top of the diff: all line comments are aggregated into a single prompt, and a selection menu appears — whether to have the same agent continue or to launch a new one.
Two clarifications about the hotkey, which many people get wrong. These are two different commands:
- Add Review Note — add a note. Default binding:
Cmd+Shift+A(macOS) /Ctrl+Shift+A(Windows/Linux). - Send Review Notes to Agent — send the batch to the agent. By default, no key is assigned. If you want to bind one, configure it in Settings → Shortcuts.
Batching here is not cosmetic. If you send the agent notes one by one, it can bounce between conflicting edits: one note fixes the first, but breaks the second. The batch lets it see all requirements at once. This is a case where a UI solution truly affects the quality of the result.
Attribution
Orca tracks code provenance line-by-line: provenance is recorded when the agent changes files with its tools. In the AI diff viewer, lines from the AI are marked with a discreet marker in the gutter; if a human later edits the line, authorship returns to the human.
Literally from the documentation: “Attribution is local to Orca — it doesn’t get committed to git.” In other words, the data lives inside Orca and does not get into the repository. You can export it by exporting the diff metadata from the toolbar.
Why: to know where to look more carefully; to conduct audits where you need to separate machine code from human; not to re-read the same thing three times that was written by hand.
Commit, Push, and Create PR
The commit panel sits next to the diff viewer — per the docs, “commit, push, and open the review without leaving Orca.”
Commit:
- Stage changes by hunks or by files directly from the diff.
- Write the message by hand or click “Generate with AI”.
- Click Commit — or
Cmd-Enter(macOS) /Ctrl-Enter(Windows/Linux).
Pre-commit hooks run automatically. If a hook fails, you get “Fix with AI”: the agent receives the hook output, the commit message, and the list of staged files and tries to fix.
Push: the Push button pushes the branch to origin and, on the first push, sets up the upstream. For rewritten history, use the explicit action “Force push with lease”, which shows the number of commits and upstream branch name before executing; underneath it uses --force-with-lease, i.e., protection against overwriting someone else’s commits.
PR: after pushing, the Source Control panel shows an option to create a hosted review with the base branch, title, description, and draft status. The button “Generate pull request details with AI” composes the title and description based on the diff of the branch and commits.
Conflicts: during merge or rebase, you can choose “Resolve with AI” alongside manual resolution.
AI Action Recipes
All four AI actions above are configurable recipes, not hard-coded prompts. They live in Settings → Git & Source Control → Action recipes.
| Recipe | What it does |
|---|---|
| Generate with AI | commit message |
| Generate pull request details with AI | PR title and description |
| Fix with AI | fix after pre-commit hook failure |
| Resolve with AI | resolve merge/rebase conflicts |
Templates have variables — documentation mentions {stagedFiles}, {linkedIssue}, {patch}.
Practical meaning: if your team uses a specific commit message format — Conventional Commits, a ticket number prefix, a mandatory line like Refs: — don’t prompt the agent every time; once, rewrite the recipe to match your format. This is exactly the spot where five minutes of setup saves hundreds of edits manually.
GitHub, GitLab, and others
They integrate with GitHub, GitLab, Bitbucket, Azure DevOps, and Gitea (Settings → Integrations); GitHub is the most deeply integrated — Actions and issues.
- Hosted review is available from the Source Control panel after push; related reviews show status open / merged / closed in the sidebar, with a button “Open review page in browser.”
- PR actions menu: copy link, close, reopen.
- GitHub checks and comments render inline within the PR tab; GitLab pipelines show bridge- and child-jobs with trace logs. You can reply to a thread directly from the panel.
- “Fix broken checks” gives the agent details of failed checks.
- Auto-merge for GitHub PR: the method follows the repository default — Squash and merge / Create merge commit / Rebase and merge. The option is hidden for drafts, closed, conflicted, and unstable PRs.
- Failed GitHub Actions are shown as red chips on the worktree with clickable job logs.
- Issues: viewing, filtering, and editing GitHub and GitLab issues; creating a worktree from an issue pre-fills the task name and retains linkage.
- GitHub Projects — full project views with filtering by the source repository.
- In newer versions there are stacked pull requests — we discussed the mechanics of “stacks” in a separate topic (GitHub добавил stacked pull requests: как «стопки» PR ускоряют ревью больших изменений).
Linear — step-by-step onboarding
- Settings → Integrations → Linear.
- Paste your personal API token from Linear → Settings → API.
- Choose the required teams.
What appears:
- Task drawer — unified view of issues from GitHub and Linear in a single list.
- Mode «Has Workspace» filters issues already bound to local worktrees; clicking such a line opens the workspace.
- When creating a worktree from a Linear issue, an interactive composer opens: the name is filled automatically, the issue ID is attached, and the branch name is taken from Linear’s own suggestion, not the slug of the title. In the details menu there is “Copy suggested branch name”.
- Issue management: status, assignee, priority (Linear icons), labels, estimate.
- When the agent starts, inline images and media from issue descriptions and comments are pulled in.
- Text in dialogs is preserved, even if the dialog is closed with Escape, Cancel, or clicking outside.
- Long lists — pagination with the “Load more” button. Display settings (list/board, grouping, filters) survive restarts, and the last used task source is remembered per repository.
- Status synchronization — opt-in for each team: moves the issue to “In Progress” when creating a worktree.
- For agents: the command
orca linearand the skillorca-linearwith create / update / list / relations operations, context flags--activityand--full.
Jira — step-by-step integration
- Open the sidebar Tasks, select Jira in the source switcher.
- Click «Connect Jira».
- Choose deployment type: Cloud or Self-hosted.
Cloud: Site URL (for example https://example.atlassian.net), Atlassian account email, and the API token, which can be obtained at id.atlassian.com → Security → API tokens.
Self-hosted: base URL (including path if Jira is not at the domain root) and authentication by one of two methods — Bearer PAT (recommended for modern installations) or username + password (Basic auth, for legacy).
You can connect several Atlassian sites at once; in the Tasks header a site switcher with the option “All sites” appears.
Features: unified view of issues from different sources, inline status editing, assignee and priority, and custom fields; comments directly from the inbox; saving drafts of new issues within a session; creating a worktree with auto-binding; inserting the issue URL.
Literally: “Your Atlassian API token or self-hosted credentials are encrypted via the OS keychain and stored locally.” Tokens live in the system keychain, not in an открытым текстом config, — which does not negate ordinary hygiene: grant tokens minimum rights and do not generate one common token for the whole team.
When GitHub starts complaining
A dedicated documentation page about GitHub errors — useful because it contains concrete numbers.
| Budget bucket | What it covers | Authenticated limit |
|---|---|---|
| REST (core) | PR/issue requests, checks metadata | 5,000 per hour |
| GraphQL | Projects/Tasks requests | 5,000 points per hour |
| Search | search-based lists | 30 per minute |
These are hourly budgets per user, shared across all tools — Orca, your gh in the terminal, and the agent pulling gh, all draw from the same pool.
Diagnostics:
gh api rate_limit --jq '.resources | {core, graphql, search}'
gh api user -i 2>&1 | head -40
gh auth status -h github.com
Environment-variable conflicts are resolved like this:
unset GITHUB_TOKEN GH_TOKEN
gh auth logout -h github.com
gh auth login -h github.com
gh api user --jq '{login, id}'
Important note from the docs: the section Settings → Git → GitHub API Budget shows only a pilot value, which may look “healthier” than the real REST call state. If there is a discrepancy, trust live error messages rather than the number in the settings.
Common causes of hitting the limit: several Orca windows updating data simultaneously; agents automating gh; heavy tasks with fan-out across multiple repositories; third-party apps on the same token.
Part 8. Editor, views and files
Monaco
Editor — Monaco, the same engine as in VS Code. Autosave triggers on focus loss and during pauses; there is no unsaved changes indicator — because you don’t need it.
| Shortcut | Action |
|---|---|
Cmd-D |
select next occurrence |
Cmd-F |
search in file |
Cmd-Shift-F |
search across the whole worktree |
Cmd-Click |
go to definition (language-dependent) |
Alt+Z |
toggle word wrap |
Changes View Mode — mode from the editor tab menu: shows a diff HEAD vs. working tree directly in the editor, with the same navigation (n / p through hunks, s to stage).
Settings: word wrap enabled by default (Settings → General → Editor Word Wrap; separate setting for diff); minimap disabled by default (Settings → Appearance); editor font here as well — empty means “use terminal font.”
Directly quoted authors: “Orca is intentionally editor-first, not IDE-first — run type-checkers and linters in a terminal pane.” There is no language server, no built-in debugger, and no integration with a test runner here and no plans for it. If you’re hoping for a JetBrains replacement — this isn’t it.
Markdown editor
Screenshot of Orca, onorca.dev
Files .md open in a rich editor: toolbar, inline preview, autocompletion of internal links. Switching to raw Monaco — Cmd-Shift-M.
- Slash menu. Typing
/on an empty line yields headers, lists, code blocks, callout blocks, images, mermaid diagrams and toggle blocks. Commands/toggle-textand/toggle-h1…/toggle-h5create collapsible blocks that are saved as portable markdown via<details>/<summary>. - Wiki links. Typing
[[triggers auto-completion of relative paths inside the worktree. - Search by rendered text, not by syntax. The query “Install” will find both
# Install, and the equivalent<h1>Install</h1>. - Front matter. YAML and TOML are shown by default; hidden from the file via the menu “…” → “Hide front matter”.
- Table of contents — the tree icon in the editor header, the collapsible outline by headings, works in both rich-, and preview-mode.
Working with tables:
| Key | Action |
|---|---|
Tab / Shift-Tab |
move between cells; pressing Tab after the last cell adds a row |
Enter |
move down; after the last cell adds a row |
Backspace in an empty line |
delete the line, and if the line is the last — delete the whole table |
Backspace in an empty cell |
move to the previous cell |
Share as Artifact — publishing a markdown public link via the Orca account. Requires enabling in Settings → Artifacts → “Allow publishing public artifact links” (disabled by default). Management — on the Artifacts page in the sidebar, from CLI:
orca artifacts share ./notes.md --json
orca artifacts update ./notes.md --json
orca artifacts list --json
orca artifacts unshare ./notes.md --json
orca artifacts delete <id> --json
Viewers
| Format | What it can do |
|---|---|
| Mermaid | render inline in Markdown preview; separate .mmd files open in their own viewer with pan and zoom |
| scroll, zoom, text selection; scroll position is preserved within the session and reset when Orca is restarted | |
.png .jpg .svg .webp .gif |
view plus image-diff mode for side-by-side comparison |
.csv .tsv |
tabular viewer with column sorting and quick search; switches to raw text for cell editing |
.ipynb (beta) |
rendered Markdown, syntax highlighting, cell output; editing writes back to the file with nbformat preservation so diffs stay clean |
File Explorer
On the left of each worktree, it watches the filesystem in real time. Sorting is — natural, taking numbers into account: 9, 99, 100, not lexicographic.
Dragging from outside:
- files from Finder/Explorer into the tree — copied;
- images into the Markdown editor — inserted at the cursor position;
- files to the terminal agent — the path is pasted into the prompt;
- in SSH-worktrees files are automatically uploaded to the remote host.
Git integration: files are highlighted by status (untracked, modified, staged, ignored). Context menu: discard, stage, rename, „Copy Path“, „Copy Relative Path“ (Cmd+Option+Shift+C / Ctrl+Alt+Shift+C).
File operations: “Copy” puts the file into the system clipboard; for remote files there is “Download”, for folders — “Download Folder” (not available in the web client).
Search: right-click a folder → „Find in Folder“, or select the folder and press Cmd-Shift-F / Ctrl-Shift-F.
Session Recovery
What gets restored: open worktrees from the sidebar, panel layouts with nested splits and focus for each worktree, running agent processes (live in a background daemon, Orca reconnects), scrollback of terminals — including output accumulated while the app was closed, the last focused worktree and tab.
| Scenario | What happens with agents |
|---|---|
Cmd-Q |
continues running |
| Auto-restart on update | not affected |
| App crash | warm reconnect, daemon kept sessions |
| Host reboot | layouts and last scrollback restored |
To start fresh — close the worktree before exiting: Orca restores closed ones as closed.
Part 9. Browser and Design Mode
Each worktree has its own browser — a real Chromium panel inside the window: address bar, history, devtools. Tabs are scoped to the worktree, sessions are preserved between launches — cookies can be imported from Chrome or Edge in one click to avoid logging in again.
Helpful tips: hard reload with cache bypass (for frontend iterations), Cmd-F find on page, Cmd-T new tab, Cmd-Shift-T reopen closed tab, shelf of downloads, customizable routing of links (open in Orca or in system browser, with Shift inversion), viewport emulation via Chrome DevTools Protocol.
Design Mode
From the documentation: Design Mode “turns the Orca browser into a pointer-to-code tool”. Turn on the toggle in the browser toolbar, the cursor turns into a pipette, hovering highlights the element under it, clicking captures it.
What exactly is captured on click:
- HTML element — its outer structure plus surrounding context;
- computed CSS properties — colors, fonts, margins;
- cropped screenshot of that element;
- source file and line number — available when source maps are present in dev mode.
All of this is sent in one attachment to the active agent terminal. Then the cycle repeats: the agent edits the source → hot-reload triggers → click again to verify.
This is arguably Orca’s most underrated feature. The usual way to explain to an agent “this button looks off” is to write a paragraph and hope. Here the agent gets the exact node, its CSS and its coordinates in the source. Literally from the docs: “the same context a human reviewer would want.” The number of iterations is roughly like between “somewhere around login” and a stack trace.
Browser Profiles
A profile is a separate browser identity: logged-in user, its own cookie jar, its own user-agent.
Creation: Settings → Browser → Profiles → «Add profile». Cookies, user-agent, and viewport sizes are configured. After creation, the profile is selected from the browser toolbar; all tabs inside the panel inherit the active profile, and agent commands in the browser use it as well.
Each profile stores separate storage partitions for cookies, localStorage and cache — data does not leak between profiles.
From CLI:
orca tab profile list --json
orca tab profile create --no-ua-spoof
Recommendation from the documentation, subtle yet useful: for some authorization flows it’s better to keep the native user-agent Electron, rather than spoofing Chrome — compatibility is higher. UA spoofing often breaks login rather than helps.
Separately, it’s important to understand that this is not an anti-detect browser: the isolation here is about ease of working with multiple accounts, not about resisting fingerprinting. For real anti-detects we have a full guide on Octo Browser at [Octo Browser: полное руководство — отпечатки, прокси, куки, автоматизация через API].
Part 10. The Terminal
Under the hood xterm.js — the same engine as in VS Code, with tweaks for agent-based scenarios. Terminals live in tabs within a shared split system; agent tabs show identity and live state.
| Action | Shortcut |
|---|---|
| New terminal tab | Cmd-T |
| New agent tab | Cmd-Alt-T (macOS) |
| Close tab | Cmd-W |
| Split right | Cmd-\ |
| Split down | Cmd-Shift-\ |
| Floating terminal | Cmd+Option+A / Ctrl+Alt+A |
| Scrollback search | Cmd-F |
Notes:
- OSC 52 is enabled by default — clipboard works from the TUI over SSH: copy from tmux and Neovim on the remote machine.
- Copy Context in the context menu — yields a limited excerpt from the terminal panel (handy for pasting a log piece to an agent).
- Import themes: Ghostty config (theme, font, cursor) is picked up on first launch; Warp themes are scanned from default directories and arbitrary YAML folders.
- Floating terminal — global shell over everything, not tied to the active worktree; convenient for orchestration and background runs, startup directory and UI location are configurable.
- Quick Commands — saved commands (
npm run dev) and reusable prompts for Claude/Codex, with Global or Project scope and grouping by remote hosts. - Windows: configurable default shell (PowerShell / cmd / WSL), fallbacks for one-off shells without changing the default, path translation for WSL.
- Layouts: conversion of JIS yen (¥) to backslash and Korean won (₩) to backtick on macOS, support for kitty keyboard protocol for modifiers.
Part 11. Where the agents actually run: four modes
Diagram based on onorca.dev documentation
| Mode | Where it runs | What it’s for |
|---|---|---|
| Local | your desktop | everyday development, fast iteration |
| SSH target | remote host via SSH | dev boxes, GPU hosts, always-on VPS |
| Remote Orca Server | machine running Orca or orca serve |
shared persistent runtime, mobile access, automation |
| Cloud VM | a disposable VM/sandbox for each workspace | isolated ephemeral agent compute |
A Orca screenshot, onorca.dev
SSH targets
Setup: Settings → SSH → Add Target → host, user, port, and identity file if needed. Importing from ~/.ssh/config is supported, including Include files. When creating a worktree, choose the target in the “Run on” field — a git worktree is created on the remote machine, and agents go there as well.
Dependencies on the remote host. Orca installs a native relay there, so you need Node, network, and toolchain:
# Debian / Ubuntu
sudo apt-get install -y build-essential python3
# Fedora / RHEL
sudo dnf install -y make gcc gcc-c++ python3
# Alpine
sudo apk add build-base python3
# Arch
sudo pacman -S --needed base-devel python
What it provides:
- Status chips on remote worktrees: green — connected, yellow — reconnecting, red — disconnected.
- PTY resilience. Closing the desktop app no longer kills remote sessions. On reconnect, detached PTYs return to tabs in the attached state with scrollback. Default grace period — 5 minutes, configurable per target.
- Connection reuse enabled by default (can be disabled if policy forbids multiplexing); proxy and jump host can be configured in the Advanced Connection block.
- Passwords phrases stay in memory for the duration of the Orca session and are wiped on close; an option for longer TTL is available in SSH settings.
- Ports tab — right sidebar, shortcut
Cmd+Shift+I. Scans/proc/net/tcpon the remote machine. Privileged remote ports are automatically remapped locally: remote 80 → local 10080. Port forwards survive restarts and reconnects. - Files: download files and folders by right-clicking in explorer, drag-and-drop with auto-upload to the host.
- Open a remote worktree in VS Code via Remote-SSH.
Authentication: Kerberos/GSSAPI and FIDO2 hardware keys (ed25519-sk, ecdsa-sk) go through the system OpenSSH; regular Ed25519, ECDSA and RSA go through Orca’s built-in transport.
Remote Orca Server
Here the entire runtime moves to a separate machine, while clients can be multiple — laptop, phone, browser.
Recommended path — desktop app plus Tailscale:
- On the server: Settings → Remote Orca Servers → “Advertise this app as a server” → New Link.
- Choose the Tailscale address (usually
100.x.y.z), generate an access link. - On the client: Settings → Remote Orca Servers → Add Server, paste the link.
For headless machines — headless mode:
# basic startup
orca serve --pairing-address 100.64.1.20
# with a fixed port
orca serve --port 6768 --pairing-address 100.64.1.20
# with the ability to pair a phone
orca serve --pairing-address 100.64.1.20 --mobile-pairing
Agent accounts are registered directly on the server — client logins do not migrate there:
orca account add --agent claude
orca account add --agent codex
orca account list
Direct quote from the documentation: never expose the Orca port to the public Internet. Only via Tailscale, WireGuard, trusted LAN, or SSH tunneling. The pairing link is a password: each client gets a separate revocable token, active grants are visible under “Shared Server Access,” revoke with the trash icon.
The mode is labeled as beta. Since the other end runs an agent with the flag --dangerously-skip-permissions, take this warning seriously.
Cloud VM for a workspace
An experimental mode, enabled in Settings → Experimental → Cloud VM. Each worktree gets a disposable sandbox described by the repository itself: the orca.yaml file plus lifecycle scripts.
Providers and targets mentioned in the docs: Vercel Sandbox, Fly, Modal, SSH hosts, Docker.
The authors suggest delegating setup to the agent — literally the phrase:
Use the orca-per-workspace-env skill to set up a per-workspace environment for this repo
This is the only one of the four modes that provides true agent isolation from your machine. And a fundamental caveat: Orca does not sell hosted solutions — any remote mode runs on your machines and in your cloud accounts.
Part 12. CLI: where real automation begins
CLI is not a GUI add-on, but a full interface to a running Orca instance. Registered under Settings → General → Orca CLI. Almost every command accepts --json.
To verify everything is in place:
command -v orca
orca status --json
Selectors
Half of the commands accept an object selector. The syntax is uniform:
| Selector | What it means |
|---|---|
active or current |
the current worktree from which the call originates |
id:<repoId> |
явный идентификатор |
path:/abs/path/to/worktree |
путь на файловой системе |
branch:feature-name |
имя ветки |
issue:123 |
номер issue |
id:<repoId>::<absolute-worktree-path> |
удалённый (серверный) селектор для федеративных сценариев |
Базовое и репозитории
orca open --json
orca status --json
orca repo list --json
orca repo add --path /abs/path/to/repo --json
orca repo show --repo id:<repoId> --json
orca repo set-base-ref --repo id:<repoId> --ref origin/main --json
orca repo search-refs --repo id:<repoId> --query main --limit 10 --json
Worktree
orca worktree list --repo id:<repoId> --json
orca worktree ps --json
orca worktree current --json
orca worktree show --worktree active --json
orca worktree create --repo id:<repoId> --name fix-login --issue 123 --json
orca worktree create --name child-task --agent codex --prompt "..." --json
orca worktree rm --worktree id:<worktreeId> --force --json
Терминалы
Самое интересное, потому что отсюда агент может управлять другим агентом:
orca terminal list --worktree active --json
orca terminal show --terminal <handle> --json
orca terminal read --terminal <handle> --cursor <cursor> --limit 1000 --json
orca terminal send --terminal <handle> --text "continue" --enter --json
orca terminal wait --terminal <handle> --for tui-idle --timeout-ms 300000 --json
orca terminal create --worktree active --title "tests" --command "npm test" --json
orca terminal split --terminal <handle> --direction horizontal --command "npm run dev" --json
orca terminal rename --terminal <handle> --title "runner" --json
orca terminal switch --terminal <handle> --json
orca terminal close --terminal <handle> --json
Файлы
orca file open src/App.tsx --worktree active --json
orca file diff src/App.tsx --staged --worktree active --json
orca file open-changed --mode both --worktree active --json
Браузер
По сути встроенный Playwright для агента:
orca goto --url http://localhost:3000 --worktree active --json
orca snapshot --worktree active --json
orca click --element @e3 --worktree active --json
orca fill --element @e1 --value "email@example.com" --worktree active --json
orca wait --text "Welcome" --worktree active --json
orca screenshot --worktree active --json
orca full-screenshot --worktree active --json
orca pdf --worktree active --json
orca console --limit 50 --worktree active --json
orca network --limit 50 --worktree active --json
orca capture start --worktree active --json
orca set device --name "iPhone 12" --worktree active --json
orca tab list --worktree active --json
orca tab create --url http://localhost:3000 --worktree active --json
orca tab switch --index 1 --worktree active --json
Мобильные эмуляторы
iOS Simulator и Android через adb:
orca emulator list --worktree active --json
orca emulator attach "<device-name-or-udid>" --worktree active --json
orca emulator tap 0.5 0.7 --worktree active --json
orca emulator type "hello" --worktree active --json
orca emulator gesture '[{"type":"begin","x":0.5,"y":0.8},{"type":"move","x":0.5,"y":0.4},{"type":"end","x":0.5,"y":0.2}]' --worktree active --json
orca emulator button home --worktree active --json
orca emulator rotate landscape_left --worktree active --json
orca emulator exec --command "tap 0.5 0.7" --worktree active --json
orca emulator kill --worktree active --json
orca emulator shutdown --worktree active --json
Оркестрация: агент, который командует агентами
Отдельный слой для случаев, когда, цитируя документацию, «you need ownership, completion tracking, or a DAG». Включается в Settings → Experimental.
Сущности:
- Run — долгоживущее пространство имён и почтовый ящик координатора. Дословно: «Never schedules or places workers» — сам ничего не планирует.
- Task — единица работы со спецификацией, зависимостями и статусом:
pending,ready,dispatched,completed,failed,blocked. - Dispatch — одна попытка выполнения задачи на конкретном терминале, владеет жизненным циклом.
- Message — почта во входящем: типы
status,dispatch,worker_done,escalation,question,heartbeat. - Decision gate — вопрос координатора, блокирующий задачу до ответа.
Создание и запуск:
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
orca orchestration worker-start --task <taskId> --worktree new-child --name billing-audit --agent codex --setup run --json
orca orchestration worker-start --task <taskId> --worktree current --agent claude --model <opaque-model-id> --effort high --json
Ожидание и подтверждение сообщений:
orca orchestration check --wait --types worker_done,escalation,question --timeout-ms 900000 --json
orca orchestration check --ack <deliveryId> --wait --types worker_done,escalation,question --timeout-ms 900000 --json
Завершение работы воркером:
orca orchestration send \
--type worker_done \
--subject "Completed mobile audit" \
--body "Fixed footer overlap; no follow-ups." \
--task-id <taskId> \
--dispatch-id <dispatchId> \
--outcome succeeded \
--files-modified "src/app/settings/Billing.tsx" \
--json
The worker is obliged to send worker_done exactly once and with both identifiers — the task and the dispatch. If you specify only the task ID, the old retry will close someone else’s dispatch, and you will get a task marked as completed, which no one actually did. This is the most insidious error in the entire orchestrator, because it doesn’t crash, it lies quietly.
Inspection, stopping, retries:
orca orchestration worker-show --dispatch <dispatchId> --json
orca orchestration worker-read --dispatch <dispatchId> --limit 50 --json
orca orchestration worker-stop --dispatch <dispatchId> --json
orca orchestration worker-release --dispatch <dispatchId> --json
orca orchestration worker-retain --dispatch <dispatchId> --json
orca orchestration worker-start --task <taskId> --retry-of <dispatchId> --worktree current --agent codex --json
Group mailing. Addresses: @all, @idle, @claude, @codex, @opencode, @gemini, @droid, @grok, @cursor, @worktree:<id>.
orca orchestration send --to @all --subject "Heads up" --body "Pausing dispatches for a review." --json
orca orchestration send --to @idle --subject "Anyone free?" --json
Question to the coordinator and decision gates:
orca orchestration ask \
--to <coordinatorHandle> \
--question "Should I update the shared component or only this page?" \
--options "shared,page-only" \
--timeout-ms 600000 \
--json
orca orchestration gate-create \
--task <taskId> \
--question "Merge the shared button change into the task branch?" \
--options '["yes","no"]' \
--json
orca orchestration gate-resolve --id <gateId> --resolution "yes" --json
Задачи и сброс состояния:
orca orchestration task-list --json
orca orchestration task-update --id <taskId> --status blocked --result '{"reason":"waiting on credentials"}' --json
orca orchestration dispatch-show --task <taskId> --preamble --json
orca orchestration reset --tasks --json
orca orchestration reset --messages --json
orca orchestration reset --all --json
Федеративные воркеры — задачи на разных машинах через флаг --on:
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
```A comprehensive reference for the flags the agent can obtain itself: `orca skills get orchestration --full`. The deprecated `orca orchestration run` and `run-stop` no longer work.
### Worktree checkpoints
Each worktree has a free-text comment field — a snapshot of what’s happening here right now. Literally from the documentation: «it's the pattern we recommend for keeping human collaborators in the loop without forcing chat».
```bash
orca worktree set --worktree active \
--comment "fix implemented; running integration tests" \
--workspace-status in-progress \
--json
orca worktree current --json
Statuses: todo, in-progress, in-review, completed plus arbitrary identifiers.
Recommended comment format — first the action and place, then the status and next step. Example straight from the docs:
added debounce to SearchBar onChange (src/components/SearchBar.tsx); ready for review—goal: reduce redundant API calls per #298
Good moments for a checkpoint: finished a piece of implementation, confirmed or refuted a hypothesis, finished a review, hit a blocker (permissions, external dependencies), moved from research to patching.
[warn]
Another documentation recommendation: before overwriting the comment, read the current one first via orca worktree current --json. There may be human-written context with goals and constraints — an agent that overwrites it won’t break the code, but will break communication.
Scheduled automations
orca automations create \
--name "Weekday triage" \
--trigger weekdays \
--time 09:00 \
--prompt "Triage new issues and summarize blockers" \
--provider codex \
--repo my-repo \
--disabled \
--json
| Flag | Purpose |
|---|---|
--trigger |
presets hourly, daily, weekdays, weekly or a cron expression or an RRULE string |
--time |
time of day |
--timezone |
IANA time zone, defaulting to the runtime time zone |
--repo / --workspace / --project / --host |
where exactly to run |
--prompt / --provider |
what and by which agent |
--precheck |
shell command test; non-zero exit code — the run is skipped and marked as skipped |
--reuse-session |
continue in the previous terminal instead of a new one for each run |
--missed-run-grace-minutes |
window for missed runs |
--disabled |
create as disabled |
--source-context ''` |
binding task/provider to host or account; null clears |
orca automations list --json
orca automations show <automationId> --json
orca automations edit <automationId> --enabled --json
orca automations edit <automationId> --fresh-session --json
orca automations run <automationId> --json
orca automations runs --id <automationId> --json
orca automations remove <automationId>
Recommended order from the documentation: create with --disabled, verify via list / show, run manually via run, and only then enable. An automation that starts the agent with full autonomy flag on a live repository every morning at nine is not what you want to tune in production.
Computer Use
Managing native applications through the accessibility tree, screenshots, and UI actions. Status — beta. Requires Accessibility permissions on all platforms and additionally Screen Recording on macOS, granted to the application Orca Computer Use.
orca status --json
orca computer permissions --json
orca computer capabilities --json
The main loop, literally from the docs: “read the app’s current state, act on a specific element, then re-read state to verify the result”.
orca computer list-apps --json
orca computer get-app-state --app com.spotify.client --json
orca computer click --app com.spotify.client --element-index 42 --json
An application is specified in three ways: bundle ID (preferred, com.microsoft.edgemac), name (Spotify, if unambiguous) or PID (pid:<number>, last resort). For multi-window apps — --window-id (more stable) or --window-index.
All actions:
orca computer click --app <app> --element-index <i> --json
orca computer set-value --app <app> --element-index <i> --value "text" --json
orca computer type-text --app <app> --text "text" --json
orca computer press-key --app <app> --key Return --json
orca computer hotkey --app <app> --key CmdOrCtrl+A --json
orca computer paste-text --app <app> --text "text" --json
orca computer scroll --app <app> --element-index <i> --direction down --json
orca computer drag --app <app> --from-x 100 --from-y 100 --to-x 300 --to-y 300 --json
orca computer perform-secondary-action --app <app> --element-index <i> --action <name> --json
Authors recommend: prefer semantic actions (click, set-value, perform-secondary-action) to raw type-text and press-key — they hit the accessibility element directly and survive focus changes, which keyboard input cannot handle.
Sensitive values are passed via stdin to avoid exposing them in the shell history:
printf '%s' "$TEXT" | orca computer set-value \
--app com.apple.Safari --element-index 7 --value-stdin --json
Screenshots: get-app-state by default returns both the tree and the image. --json writes bytes to disk and returns the path in screenshot.path; --no-screenshot speeds up and lightens the response; --restore-window expands a minimized window before capture.
Element indices are sparse and bound to the last state snapshot. They cannot be invented or cached: after any navigation or redraw you must call get-app-state again. An agent that saves one call and reuses an index will click the wrong place — and you may not immediately know where.
Skills
Orca provides skill packages for agents. They are arranged in a hybrid manner: the agent receives a lightweight stable SKILL.md which tells it three things — determine the CLI executable for this session, load the full guide via orca skills get <topic>, and prefer --json, not guessing flags from memory. The full guide is loaded from the running CLI, so flags do not diverge from the app version.
| Skill | What it provides |
|---|---|
orca-cli |
worktree, terminals, files, automations, built-in browser |
orchestration |
runs, tasks, workers, messages, integration gateways |
computer-use |
native applications through the accessibility tree |
orca-linear |
reading and writing Linear tickets |
orca-emulator |
iOS Simulator |
orca-emulator-android |
Android via adb |
orca-per-workspace-env |
environment recipes per workspace |
# install via the general skill manager
npx skills add https://github.com/stablyai/orca --skill orca-cli --global
npx skills update orca-cli orchestration computer-use --global
# the same from Orca itself (also on headless hosts)
orca skills list
orca skills get orca-cli
orca skills get orchestration --full
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
Flags: --global (default), --local (project-local only), --agent<name>[,<name>…], --all, --dry-run, --json.
MCP servers are registered in Settings → Integrations → MCP and become available within those agent CLIs that MCP supports.
Part 13. Mobile app
Positioning is honest and literal: “The mobile app is intentionally not a full editor — it’s a remote control for the desktop you already have running.” It’s a remote control, not a workstation.
Distribution: iOS — App Store and TestFlight (preview channel); Android — APK on GitHub Releases (as of writing version 0.0.37). Status — beta.
Pairing steps:
- On the desktop, open pairing from the account/status menu and obtain a one-time code.
- On the phone, select Pair and paste the code (works with a deep link).
- Choose Orca Relay if available (requires account login), or the address on the local network.
- As a result, a device token is created for this phone.
What it can do:
- Monitoring: all worktrees with agent status (working / done / waiting on input) across all connected hosts; the full file tree, including nested paths; agent sessions in the Chat UI or in a raw terminal.
- Terminal: reading the scrollback with rendering of mermaid diagrams, selecting and copying with long press, several extra keys with
Tab,Shift+Taband Live mode, text zoom 50–200 %, auto-complete and auto-correct toggles. - Interaction with the agent: text responses, photos, files or dictation; run saved Quick Commands; switch agent accounts and view usage/rate-limit; spend Codex rate-limit reset credits, if any.
- Workspaces: create from phone in Smart, GitHub, Linear, GitLab, Branch, Name modes; edit the displayed name and host address without re-pairing; mass close tabs with a long press (skips “dirty” markdown tabs and pinned).
- Review: view changes, staging and unstaging, commit.
- Browser with Web / Mobile responsive toggle.
- Push notifications on agent completion.
Settings: Settings → Chat UI → “Open sessions in Chat UI” (default for device); Settings → Terminal → text size, auto-complete and auto-correct.
Part 14. Notifications and activity feed
Notifications. When an agent transitions from working to idle, Orca triggers in three ways at once: a system notification, a sound, and a badge on the workspace. The header permanently shows a bell with unread items across all worktrees — clicking takes you to the relevant worktree and panels; on macOS the count is duplicated by a Dock badge. A notification can be marked unread with a right-click if you’re not ready to handle it.
Settings — Settings → Notifications: enable/disable individual categories, a custom sound for each category (file on disk or built-in), volume. Supported formats: MP3, WAV, OGG, M4A, AAC, FLAC. One selected file applies to all delivered desktop notifications.
Activity feed (item Agents in the sidebar, enabled by default) — threaded feed of agent completions, blocked states, previewed responses, and events of worktree creation across all workspaces. Threads are grouped by status, running agents pinned at the top; the item shows an unread badge. Focus for filtering — Cmd+F / Ctrl+F.
A note that will save you ten minutes of confusion: if focus is in the built-in terminal, Cmd+F goes to the terminal (searching scrollback), not the feed filter. First click the feed.
Part 15. Settings, privacy and telemetry
There are many settings sections; here are the ones you should visit right after installation.
| Section | Reason to visit |
|---|---|
| Agents → Agent Permissions | Yolo or Manual, plus startup arguments for each agent. The most important checkbox in the entire app |
| Git & Source Control | resolver base ref, commit signing, auto-rename branches, Action recipes, GitHub API Budget |
| Repository | base ref, hooks, Worktree Shared Paths |
| General | Orca CLI registration, update channel, Diff Word Wrap, Editor Word Wrap, UI zoom |
| Terminal | font, theme, import Ghostty/Warp, OSC 52 |
| Notifications | categories, sounds, volume, PR check notifications |
| Integrations | GitHub OAuth, Linear API, Jira, MCP servers |
| Browser | profiles, default zoom, default Design Mode, link routing |
| Voice | dictation: Parakeet TDT v3, Whisper, GPT-4o and other models, Toggle/Hold modes |
| Artifacts | publishing files via public link — disabled by default |
| SSH | targets, TTL passphrase phrases, reuse of connections, Kerberos |
| Experimental | Agent Dashboard, hibernation, Chat UI, Cloud VM, orchestration, plugins, Activity |
| Shortcuts | full remapping of the keymap |
Telemetry
Collected: lifecycle events (app opening), how a repository is added and a workspace created — without names and paths, type of agent started and where from — without prompts or output, broad error categories, changes to settings from a whitelist, consent status. Each event includes Orca version, OS type, CPU architecture, release channel, and a random anonymous local identifier.
Explicitly not sent: file paths, repository names, branches, URLs, commit messages; prompts, responses and terminal content; raw error messages and stack traces; accounts; IP addresses and precise geolocation; any free text from input fields.
It can be disabled in three ways:
# Settings → Privacy → Share anonymous usage data (disable)
export DO_NOT_TRACK=1
export ORCA_TELEMETRY_DISABLED=1
Recipient — PostHog Cloud (US region).
The phrasings in this documentation section are unusually specific — instead of “we respect your privacy,” it lists exactly what goes out and what doesn’t. This is a vendor statement, not the result of an independent audit; but to verify it, just run mitmproxy on your machine — the code is open, the behavior reproducible.
Part 16. Five ready-made documentation recipes
Official step-by-step scenarios. Useful in that they show how the authors themselves expect to use this.
Recipe 1. Race of three agents on one task
- Create three worktrees from the same starting point:
fix-bug,fix-bug-2,fix-bug-3. - Run in each one its own agent — for example, Claude Code, Codex and Cursor CLI.
- Send the same prompt to all three.
- Arrange the panels so you can see progress in parallel.
- Compare diffs, annotate the best with Annotate AI Diff.
- Commit the chosen implementation and create a PR.
- Delete the losing worktrees with one click.
Recipe 2. How to read an AI diff
- Open the diff in your worktree.
j/k— navigate files. For each, ask yourself three things: is the change needed at all? is it minimal? does it fit the codebase style?con a line — add a comment. Documentation recommends writing full sentences.- “Send to agent” — send everything in one batch with one prompt.
- Watch the indicator: yellow — waiting, green — working.
- Re-open the diff, see pinned comments, mark resolved, add new ones.
- Repeat until the diff is clean, then commit.
Authors’ thesis: “Reviewing an AI diff well is the difference between shipping fast and shipping bugs”.
Recipe 3. Jump between ten worktrees
Cmd-J, type a fragment of the task name.Enterto go,Shift-Enterto open in split,Tabto filter by host or project.- Watch the colored dots in the sidebar: green — agent active, yellow — waiting for input.
- Restart chip to restart completed agents — especially after system sleep.
- Move through completed tasks via notifications.
- Delete merged worktrees immediately — “one click, and the worktree and branch are deleted,” otherwise the palette grows.
Recipe 4. Fix a UI bug via Design Mode
- Open the browser panel in the worktree, go to the page with the bug.
- Enable Design Mode.
- Click on the broken element — it goes to the agent chat with a rich attachment.
- Describe what you want in words. An example straight from the docs: «this padding is too tight, increase to match the cards above».
- The agent edits the source, hot-reload updates the page.
- Click again to verify, repeat if necessary.
- Commit when satisfied.
Recipe 5. Remote worktree over SSH
Setup: Settings → SSH → add host → Test connection → make sure the host has git → add the repository, specifying the SSH target as its location (or open the remote folder via the file picker).
Work: create a worktree (Orca runs git worktree add remotely) → start the agent, it runs on the remote host, not on your laptop → edit files inline with auto-save to the remote filesystem → view the diff, commit and push from your laptop as usual.
Key property, word-for-word: «Laptop sleeps, Wi‑Fi drops — the agent keeps running remotely. Orca reconnects and re-attaches the terminal. Nothing lost».
Part 17. What breaks
The agent does not start — run its CLI manually in a terminal to separate the authorization issue from the Orca issue; check that the binary is in PATH (Settings → Agents); press Restart on the tab.
The diff shows something else — the refresh button on the diff toolbar rereads the worktree. External git operations (rebase, reset) are not seen between Orca updates.
A worktree isn’t created — git fetch origin, if start-from ref isn’t pulled; remove the existing worktree for this branch or pick a new name.
orca: command not found — register the CLI in Settings → General → Orca CLI; on macOS ensure that ~/.local/bin is in PATH.
SSH terminal not coming up — the remote machine needs Node and network to install relay, and on Linux also toolchain (see distro-specific commands in Part 11); after installation reconnect to rebuild native modules.
Folder not downloaded over SSH — on systems without recursive SFTP use tar / scp.
«Open in VS Code» inactive — works for SSH worktrees, but not for Remote Orca Server; settings should have VS Code or Insiders, not Cursor and not a command with multiple arguments.
Kerberos blocked — check the ticket with klist and ensure GSSAPIAuthentication yes in the OpenSSH config.
Browser responds with browser_no_tab — open a tab via orca tab create --url ... or manually.
Slowness — close unnecessary worktrees and browser tabs.
Logs: Help → Open Logs. Feedback: Help → Send Feedback, GitHub Issues, or Discord.
About maturity. In the tracker at the time of writing there are about 540 open issues, and recent headlines show typical problem areas: terminal rendering (CSI-u leak in Grok, TUI width in headless mode), macOS permissions (repeated TCC prompt for SSH agent), ghosted worktrees, DaemonProtocolError loops, false confirmation prompts in Codex, inability to work with WSL and Windows projects simultaneously.
This is a normal picture for a product that ships daily. But if you expect a tool to offer VS Code-level predictability — don’t rely on a working project on day one.
Part 18. Realistically: who needs this, and who doesn’t
Orca fits well with a specific profile: you have subscriptions for two to three agents, you’ve already run into agents fighting over a working copy, and you read diffs. The documentation states clearly: the tool is designed for developers who “actively review code changes, manage commits carefully, and maintain organized worktrees.” Everything in the UI — attribution, annotations, visual staging, AI Action Recipes — is geared toward review, not “generate an app for me.”
It doesn’t fit if: you work with one agent on one task (then all the worktree overhead is pure overhead); you have a slow machine (Electron plus Chromium plus N terminals plus N agents is gigabytes); you need isolation from the agent rather than between agents (a container is needed, not a worktree); you’re waiting for a full IDE — the authors explicitly say type-checkers and linters are run manually in the terminal.
And two questions worth answering honestly.
On limits. Parallel execution multiplies resource use. If you have one Claude Max, the “three agents race” recipe will practically turn into one agent and two idle worktrees. The only honest way out is either different providers for different worktrees (and the GLM recipe from Part 6 will help) or accept that your parallelism will be double, not triple.
On trust. The default full autonomy flags are a deliberate product choice in favor of speed. It’s justified up to the moment when the agent works with your code on your machine under your prompt. As soon as external content enters the chain — issue from someone else’s repository, a page from a browser, an MCP server — the threat model changes, but the flag stays the same. A fresh reminder of what this looks like in practice is a breakdown of encrypted reasoning blocks and the agent’s timeline in Hugging Face infrastructure.
If you answer “I understand and accept” to both points — Orca provides the best tooling around terminal agents today, and it’s free and open. If not — start with one agent in a container, and add parallelism later.
Sources
- Official Orca Documentation — sections install, model (worktrees, tabs-panes-splits, agents-sessions, session-restore, quick-open), agents (supported, claude-code, codex, codex-hot-swap, cursor-cli, glm-agent, native-chat, session-history, hibernation, usage-tracking, hooks-memory), review (diff-viewer, annotate-ai-diff, attribution, commit-push, github, linear, jira), editing (monaco, markdown, viewers, file-explorer), browser (overview, design-mode, profiles), terminal, ways-to-run, ssh, remote-servers, cli (overview, reference, orchestration, automations, computer-use, worktree-checkpoints, skills), mobile, notifications, activity, recipes, settings, telemetry, troubleshooting, github-errors
- StablyAI/orca (MIT) repository
- Orca changelog
- Stably AI (Orca) profile on Y Combinator
- Project issue tracker
Screenshots and interface videos are official project materials from onorca.dev; diagrams of the model and run modes are authors’.
Who has already run parallel agents — what did you settle on: Orca, bare git worktree with scripts, or separate containers per task? And the main question: has the “race of three agents” actually paid off in terms of limits, or does one still work in practice while two sit idle for the sake of it?