# Orca — full corpus # LLM Wiki An open-source template for building LLM-powered knowledge bases, following [Andrej Karpathy's "LLM Wiki" pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f). You provide raw sources. The LLM reads them, writes structured wiki pages, cross-links everything, and maintains it over time. You never edit the wiki directly — you curate sources and ask questions. ## How It Works The system has three layers: ``` raw/ Sources you collect (articles, transcripts, notes, PDFs) wiki/ LLM-written & maintained pages (summaries, concepts, entities, syntheses) CLAUDE.md Schema that tells the LLM how to structure everything ``` Three operations drive the workflow: | Operation | Trigger | What happens | |-----------|---------|--------------| | **Ingest** | "ingest raw/my-source.txt" | LLM reads the source, creates a summary page, creates/updates concept and entity pages, adds cross-links, updates the index and log | | **Query** | Ask any question | LLM searches the wiki, synthesizes an answer with citations, optionally creates a synthesis page for novel insights | | **Lint** | "lint" or "health check" | LLM audits all pages for orphans, contradictions, missing links, incomplete sections, and low-confidence claims — fixes what it can, reports the rest | ## Quick Start 1. **Clone this repo** ```bash git clone https://github.com/YOUR_USERNAME/llm-wiki.git my-knowledge-base cd my-knowledge-base ``` 2. **Customize CLAUDE.md** for your domain - Update the Purpose section with your topic - Replace the placeholder tagging taxonomy with your own categories - Adjust confidence level descriptions if needed - Everything else (workflows, page formats, linking rules) works as-is 3. **Drop sources into `raw/`** - Text files, transcripts, articles, notes — any plain text - These are immutable once added; the LLM never modifies them 4. **Tell the LLM to ingest** ``` ingest raw/my-first-source.txt ``` The LLM will create summary pages, concept pages, entity pages, cross-links, and update the index. 5. **Ask questions** ``` What are the key differences between X and Y? ``` The LLM answers from the wiki, citing specific pages. 6. **Run health checks** ``` lint ``` The LLM audits the wiki and fixes issues. ## Directory Structure ``` . ├── CLAUDE.md # Schema — the LLM's instructions ├── raw/ # Your source documents (immutable) └── wiki/ ├── index.md # Master catalog of all pages ├── log.md # Append-only activity log ├── dashboard.md # Dataview dashboard (Obsidian) ├── analytics.md # Charts View analytics (Obsidian) ├── flashcards.md # Spaced repetition cards ├── summaries/ # One page per source document ├── concepts/ # Concept and framework pages ├── entities/ # People, tools, organizations, etc. ├── syntheses/ # Cross-cutting analyses and comparisons ├── journal/ # Research/session journal entries │ └── template.md # Journal entry template └── presentations/ # Marp slide decks ``` ## Enhancements This template includes several extras beyond the core wiki pattern: ### Dataview Dashboard (`wiki/dashboard.md`) Live queries that surface low-confidence pages, recent updates, concepts by tag, and pages with the most sources. Requires the [Dataview](https://github.com/blacksmithgu/obsidian-dataview) Obsidian plugin. ### Charts View Analytics (`wiki/analytics.md`) Visual analytics with pie charts, bar charts, and word clouds. Requires the [Charts View](https://github.com/caronchen/obsidian-chartsview-plugin) Obsidian plugin. ### Mermaid Diagrams Use Mermaid code blocks in any wiki page to create flowcharts, sequence diagrams, or concept maps. Native support in Obsidian and GitHub. ### Marp Slides (`wiki/presentations/`) Create slide decks from markdown using [Marp](https://marp.app/). Drop presentation files in this directory. ### Research Journal (`wiki/journal/`) Track your research sessions, experiments, or applied work with the included template. The LLM can reference journal entries when answering queries. ### Spaced Repetition (`wiki/flashcards.md`) Flashcards in the format used by the [Spaced Repetition](https://github.com/st3v3nmw/obsidian-spaced-repetition) Obsidian plugin. Ask the LLM to generate flashcards from any wiki page. ### MCP Server This repo works with Claude Code's MCP server capabilities. Point an MCP-compatible client at this repo and the LLM can read/write the wiki programmatically. ## Customizing for Your Domain The schema in `CLAUDE.md` is domain-agnostic. To adapt it: 1. **Purpose** — Describe your knowledge domain in one paragraph 2. **Tagging taxonomy** — Replace placeholder categories with your own (e.g., for a cooking KB: `cuisine`, `technique`, `ingredient`, `equipment`) 3. **Confidence levels** — Adjust the descriptions to match your domain's evidence standards 4. **Entity types** — Update the entity page description to match what entities mean in your domain (people, tools, companies, etc.) 5. **Journal template** — Customize `wiki/journal/template.md` for your workflow Everything else — page format, linking conventions, workflows, rules — is universal and works across domains. ## Example Domains This template works for any knowledge-intensive topic: - **Research notes** — papers, experiments, methodologies - **Book analysis** — themes, characters, author techniques - **Competitive analysis** — companies, products, market trends - **Course notes** — lectures, readings, key concepts - **Personal development** — frameworks, habits, book summaries - **Technical documentation** — APIs, architectures, design patterns - **Hobby deep-dives** — any subject you want to master ## License MIT --- title: "Knowledge Base Index" type: index updated: 2026-09-09 orca_version_verified: "v1.4.199" --- # Orca Knowledge Base Orca is a desktop application for running multiple AI coding agents in parallel, each isolated in its own git worktree. This KB documents the docs site as captured on 2026-09-09 and the release train through `v1.4.199`. Master catalog of all wiki pages. Every page in the wiki must have an entry here. ## Concepts | Page | Tags | Confidence | Updated | |------|------|------------|---------| | [agents-and-sessions](concepts/agents-and-sessions.md) | agents, sessions, hibernation, session-restore, resume | medium | 2026-09-09 | | [browser-and-design-mode](concepts/browser-and-design-mode.md) | browser, design-mode, profiles, chromium, automation | medium | 2026-09-09 | | [computer-use](concepts/computer-use.md) | computer-use, accessibility, desktop-automation, cli, permissions | medium | 2026-09-09 | | [diff-review](concepts/diff-review.md) | diff, review, annotate, attribution, commit | medium | 2026-09-09 | | [editing](concepts/editing.md) | editor, monaco, markdown, viewers, file-explorer | medium | 2026-09-09 | | [hooks-and-memory](concepts/hooks-and-memory.md) | hooks, memory, claude-md, agents-md, setup | medium | 2026-09-09 | | [installation](concepts/installation.md) | installation, homebrew, aur, appimage, mobile | medium | 2026-09-09 | | [issue-trackers-and-github](concepts/issue-trackers-and-github.md) | github, gitlab, linear, jira, code-review | medium | 2026-09-09 | | [mobile-companion](concepts/mobile-companion.md) | mobile, pairing, android, relay, remote | medium | 2026-09-09 | | [notifications-and-inbox](concepts/notifications-and-inbox.md) | notifications, agents-feed, status, hooks, triage | medium | 2026-09-09 | | [orca-cli](concepts/orca-cli.md) | cli, automation, agents, scripting, setup | medium | 2026-09-09 | | [orchestration](concepts/orchestration.md) | orchestration, multi-agent, cli, workers, coordination | medium | 2026-09-09 | | [remote-servers](concepts/remote-servers.md) | remote, orcad, pairing, headless, tailscale | medium | 2026-09-09 | | [scheduled-automations](concepts/scheduled-automations.md) | automations, scheduling, cli, agents, hosts | medium | 2026-09-09 | | [skills-and-mcp](concepts/skills-and-mcp.md) | skills, mcp, sharing, security, agents | medium | 2026-09-09 | | [ssh-worktrees](concepts/ssh-worktrees.md) | ssh, remote, worktrees, terminals, security | medium | 2026-09-09 | | [tabs-panes-and-layouts](concepts/tabs-panes-and-layouts.md) | tabs, panes, layout, shortcuts, navigation | medium | 2026-09-09 | | [terminal](concepts/terminal.md) | terminal, ghostty, ime, shortcuts, quick-commands | medium | 2026-09-09 | | [usage-and-rate-limits](concepts/usage-and-rate-limits.md) | usage, rate-limits, accounts, codex, claude-code | medium | 2026-09-09 | | [ways-to-run](concepts/ways-to-run.md) | orca, deployment, remote, ssh, worktrees | medium | 2026-09-09 | | [what-is-orca](concepts/what-is-orca.md) | orca, overview, parallel-agents, worktrees, positioning | medium | 2026-09-09 | | [worktree-checkpoints](concepts/worktree-checkpoints.md) | worktrees, checkpoints, cli, status, collaboration | medium | 2026-09-09 | | [worktrees](concepts/worktrees.md) | worktrees, git, isolation, sidebar, orca-yaml | medium | 2026-09-09 | ## Entities | Page | Tags | Confidence | Updated | |------|------|------------|---------| | [orca-cli-reference](entities/orca-cli-reference.md) | cli, reference, commands, flags, automation | medium | 2026-09-09 | | [settings-reference](entities/settings-reference.md) | settings, configuration, reference, panes, shortcuts | medium | 2026-09-09 | | [supported-agents](entities/supported-agents.md) | agents, drivers, claude-code, codex, cursor | medium | 2026-09-09 | ## Summaries | Page | Tags | Confidence | Updated | |------|------|------------|---------| | [docs-catalog](summaries/docs-catalog.md) | catalog, documentation, coverage, map | high | 2026-09-09 | | [release-digest](summaries/release-digest.md) | releases, versions, cadence, changelog | high | 2026-09-09 | ## Syntheses | Page | Tags | Confidence | Updated | |------|------|------------|---------| | [execution-and-trust-boundaries](syntheses/execution-and-trust-boundaries.md) | ssh, remote, security, isolation, execution-state | medium | 2026-09-09 | | [the-parallel-agent-loop](syntheses/the-parallel-agent-loop.md) | workflow, worktrees, review, shipping, parallel-agents | medium | 2026-09-09 | ## Statistics - **Total pages**: 30 - **Concepts**: 23 - **Entities**: 3 - **Summaries**: 2 - **Syntheses**: 2 - **Sources ingested**: 166 immutable raw captures - **High confidence**: 2 - **Medium confidence**: 28 - **Low confidence**: 0 --- title: "Agent Sessions, Hibernation and Restore" type: concept tags: [agents, sessions, hibernation, session-restore, resume] created: 2026-09-09 updated: 2026-09-09 sources: ["raw/web_community-agents-sessions-orca-docs.md", "raw/web_community-agent-hibernation-orca-docs.md", "raw/web_community-session-restore-orca-docs.md", "raw/web_community-agent-session-history-orca-docs.md", "raw/web_community-supported-agents-orca-docs.md", "raw/web_community-agents-feed-orca-docs.md", "raw/web_community-review-an-ai-diff-line-by-line-orca-docs.md"] confidence: medium --- # Agent Sessions, Hibernation and Restore ## What counts as a session "An **agent session** is one CLI agent running in one terminal in one worktree." Orca tracks its lifecycle "so you always know which sessions are working and which are idle — without you having to click into each tab to check." The documented lifecycle has four beats: 1. **Launch** — pick an agent from the combobox; Orca spawns the CLI. 2. **Work** — OSC titles update state; terminal output scrolls with search, copy, and Ghostty theming. 3. **Idle** — Orca detects the working→idle transition and fires an agent-finished notification. 4. **Exit** — the process ends; the **Restart** chip appears. ## State glyphs Agent tabs and worktree rows share status glyphs: | Glyph | Meaning | | --- | --- | | Spinner | working | | Amber question mark | waiting on you (permission / needs input); sidebar "Needs You" counts use the same glyph | | Emerald check (dashboard) or emerald dot (sidebar) | done / quiet active | | Red dot | blocked, interrupted, or failed | | Gray dot | idle | | No indicator | plain shell, not a recognized agent CLI | "State is detected from the terminal's OSC title sequence and agent hooks, which Claude Code, Codex, and several other agents emit." If a session shows no indicator, "the agent CLI in that session isn't one Orca recognizes — start it through the agent combobox rather than typing the binary by hand." **Documentation conflict:** the recipe page "Review an AI diff line-by-line" says "The state dot will go yellow (waiting for more input) or green (working)," which inverts green relative to the Agents & sessions reference above (green = done, spinner = working). Trust the reference page; the recipe's parenthetical appears to be an error. ## Launch defaults are full-autonomy "Orca launches every supported agent with its full-autonomy permission flag pre-applied — Claude with `--dangerously-skip-permissions`, Codex with `--dangerously-bypass-approvals-and-sandbox`, Gemini with `--yolo`, and the equivalent for each other agent in the picker. The intent is that the worktree itself is the sandbox." The supported-agents page widens the `--yolo` list: "`--yolo` for Gemini / Cursor / Crush / Kimi / Rovo Dev / Hermes / GitHub Copilot / Command Code, plus the equivalent flag for every other agent that exposes one." To change it: **Settings → Agents**, expand the agent's row, edit its **launch arguments**; a **Reset** button restores the shipped flag. Globally, **Settings → Agents → Agent Permissions** switches "all uncustomized agents between **Yolo** and **Manual**." The carve-out is explicit: "If you already overrode a specific agent's launch arguments or environment, Orca leaves that agent alone so the global switch doesn't erase your custom command." ## The Restart chip "When an agent exits (clean or crash), the tab shows a **Restart** chip. One click rehydrates the same agent with the same working directory. Codex's restart chip also preserves the current account." ## Hibernation: stopping idle agents without losing them "Agent hibernation lets Orca quietly stop those terminals once they've been done and untouched long enough, then resume the same session the next time you open the worktree." It is an experimental toggle (**Settings → Experimental → Agent hibernation**). The gating list is conjunctive — Orca hibernates "only… when **all** of the following are true": - The agent is in a **done** state — finished its last turn and not waiting on input. - The terminal isn't in the active worktree or any worktree currently rendering a foreground terminal. - It hasn't received keystrokes since the agent finished. - The agent is one with a **resumable session**: "Claude, Codex, Gemini, Antigravity, OpenCode, Pi, MiMo Code, Droid, Grok, Devin, or OMP." - It's been idle for at least the configured idle window (default 30 minutes). - No mobile session is currently driving the terminal. - No orchestration Dispatch is still unsettled (`pending`, `dispatched`, or unknown). "Sleep is allowed again after runtime-confirmed `completed`, `failed`, or `circuit_broken`." - "No live subagent / teammate roster remains on the pane (provider 'done' alone is not enough while children are still attached)." "A terminal that fails any check stays running. If a worktree has multiple agent panes, they hibernate together as a unit so a partially-paused worktree never ships." **Tuning:** under the *Agent hibernation* toggle, **Hibernate after** sets the idle minutes. Default `30 minutes`; range `1 minute` to `24 hours`. "The clock starts from the agent's last **done** update; any keystroke, new output, or returning to the agent's terminal tab resets it." **Limitation, stated as such:** "Only the listed resumable agents hibernate. Cursor CLI, Hermes, Copilot, Trae, and other non-resumable terminals are left running." Manual sleep from the sidebar behaves the same way on resume: it "keeps **finished** and **interrupted** resumable sessions so reopening the worktree can still relaunch with the same resume flags." To find sleeping worktrees, use the sidebar filter menu, or assign **Toggle Sleeping Workspaces** under **Settings → Shortcuts** (it ships unbound). Resuming is automatic: opening a hibernated worktree relaunches the CLI "with the same resume flags it would use from **Agent Session History** — `claude --resume `, `codex resume `, and so on… Resume also reuses the launch command, arguments, and private environment captured when Orca first opened the agent." If resume fails (transcript deleted, provider rotated the session ID) "the terminal opens to a fresh prompt and the previous transcript stays available under the agent's session history." ## Session restore across app restarts Session restore is a different mechanism from hibernation, and the distinction is the daemon. **What gets restored:** open worktrees; tabs and splits (pane layout per worktree, including nested splits and the focused tab); running agent processes; terminal scrollback "including output produced while Orca was closed"; and the focused worktree and tab. The load-bearing sentence: "A background daemon owns the PTYs, so closing the app window doesn't kill Claude Code, Codex, or any other agent CLI mid-task. On next launch, Orca warm-reattaches to the same processes." **What does not survive:** "The daemon dies when the host does, so anything that takes the whole machine down — reboot, OS update, kernel panic, hard power-off — ends every running agent. On next launch the worktrees, tabs, splits, and last-known scrollback come back, but the agent processes themselves are gone." A daemon crash while Orca is closed has the same effect for the sessions it held. Daemon survives (agents keep running): `Cmd-Q`, auto-updater relaunch, and an Orca app crash. Daemon dies (layout still restores): host reboot. ## Agent Session History Orca "scans the on-disk session transcripts that supported agent CLIs leave behind and lists them in a right-sidebar panel called **Agent Session History**." Open the right sidebar and switch to the **Agents** tab; the header shows a count like `12 shown · 47 recent` and a search box that filters "by session title, working directory, branch, model, or preview text." **Scope toggle:** `Workspace` / `Project` / `All`. Note the asymmetry: "Remote workspaces can browse local history, but resume actions only run from local workspaces." **View options** control which CLIs are scanned (Claude, Codex, Hermes, Pi, OMP, Prime Agent, Cursor, Gemini, Antigravity, Rovo Dev, Copilot, OpenCode, Grok, OpenClaw, Devin, Droid, Kimi), plus **Sort** (`Last updated` or `Created`), **Group** (`Project`, `Folder`, or `Agent`), and **Hide empty sessions**. Row actions and their exact resume commands: - **Resume** — "opens a new terminal in the session's `cwd` and runs the agent's resume command (e.g. `claude --resume `, `codex resume `, `pi --session `, `prime-agent --resume `, `cursor-agent --resume `, `acli rovodev run --restore `). Codex sessions also re-export `CODEX_HOME` when the original session set one." - **Resume in New Chat** — for eligible local Claude and Codex sessions only. "Claude must resume in its original workspace; Codex can resume in another workspace." Doing so moves the conversation into structured chat, and "terminal **Resume** is no longer available for that session afterward." - **Copy resume command**, **Copy session ID** / **Copy log path**, **Open log** / **Reveal log**, **Open cwd**. Pi is the documented exception: it "resumes from the on-disk session file reported by its hooks (`--session `), not from a bare session id. If that file is missing, Resume is unavailable for that row even when a session id exists." Transcript sources named by the docs: "Codex's `~/.codex/sessions`, Claude's `~/.claude` history, Cursor's session log, OpenCode's legacy session files or `~/.local/share/opencode/opencode.db`, and so on." Use **Refresh Session History** in the header to rescan on demand. ## Triage surfaces The **Agent Dashboard** (**Settings → Experimental → Agent Dashboard**) is "a kanban of agents across worktrees" with columns **Needs You**, **Working**, **Done**, and **Idle** — the last being "quiet agents that have not reported completion for about 30 minutes," **hidden by default** and enabled from the dashboard's own board settings gear, "not from global Experimental settings." A **Toggle Agent Dashboard** shortcut exists with no default binding. The **Agents** sidebar entry opens a threaded feed of agent events across worktrees; it "is on by default," and `Cmd+F` / `Ctrl+F` focuses the feed filter — "When the embedded terminal has focus, the same shortcut stays with the terminal instead." ## Related pages - [worktrees](worktrees.md) — the container a session lives in - [terminal](terminal.md) — the PTY, shortcuts, and Restart chip's home - [hooks-and-memory](hooks-and-memory.md) — the hooks that report working/waiting/done - [tabs-panes-and-layouts](tabs-panes-and-layouts.md) — what session restore rebuilds ## Sources Agents & sessions, agent hibernation, session restore, agent session history, supported agents, and agents feed docs pages, fetched 2026-09-09. --- title: "Per-Worktree Browser and Design Mode" type: concept tags: [browser, design-mode, profiles, chromium, automation] created: 2026-09-09 updated: 2026-09-09 sources: ["raw/web_community-per-worktree-browser-orca-docs.md", "raw/web_community-design-mode-orca-docs.md", "raw/web_community-browser-use-profiles-orca-docs.md", "raw/web_community-fix-a-ui-bug-with-design-mode-orca-docs.md", "raw/web_community-settings-reference-orca-docs.md", "raw/github_doc-readme-md.md", "raw/web_community-html-mermaid-pdf-image-viewers-orca-docs.md"] confidence: medium --- # Per-Worktree Browser and Design Mode ## One browser per worktree "Every Orca worktree has its own browser. It's a real Chromium window — address bar, history, devtools — embedded in a pane. Tabs are scoped to the worktree, so the app you're building against stays out of the way of your other work." Scoping is symmetric with the rest of the pane model (see [tabs-panes-and-layouts](tabs-panes-and-layouts.md)): "Tabs are filtered per worktree. Switching worktrees restores that worktree's browser tabs and scroll positions." ### Controls - Address bar with history and fuzzy URL completion. "Non-URL text searches with your **Default Search Engine** — the same engine the **new-tab omnibox** uses. Prefix a query with `?` in the `+` field to force search." - Back / forward / reload / stop. "Hover the reload control for the normal-reload shortcut; right-click (or long-press) for **Reload** and **Hard Reload** with their shortcuts — hard reload bypasses the cache when you're iterating on local frontend assets." - `Cmd-F` — find in page. - `Cmd-T` — new tab, scoped to this worktree. - `Cmd-Shift-T` — reopen last closed tab. Popup handling: "Page links that use `target=_blank` and ordinary unnamed popups open in new Orca tabs, using the opener tab's browser profile. Named or OAuth-style popups can still open in a separate window." HTML previews and browser tabs convert into each other in place — see [editing](editing.md) for the preview side of that behavior. **Viewport-size emulation:** "Set a custom viewport size on a browser tab to test responsive layouts without resizing the whole pane. Orca uses Chrome DevTools Protocol device emulation under the hood, so the page sees the emulated dimensions in `window.innerWidth` and media queries." **Downloads** appear "in a shelf under the toolbar while they are active or recently completed," with cancel, open, show-in-folder, and dismiss actions. **Share as artifact:** local HTML files opened in the worktree browser can mint a public view link, "same opt-in gate and management surface as Markdown," limited to `10 MiB` per file. One caveat: "Relative HTML assets are not uploaded — share a self-contained file or use absolute asset URLs." ## Where the traffic goes on remote workspaces For a workspace on a paired Remote Orca Server, "new browser pages render on this desktop by default while HTTP(S), WebSocket, DNS, and loopback traffic still go through the remote host. Input, selection, and popups stay native to this device without changing the page's network identity. The host indicator in the browser toolbar shows where traffic is going." Under **Settings → Browser → Remote server workspaces**, choose **This device** or **Server (streamed)**. The polarity matters: "The choice applies to new pages only; it does not move a page that is already open." If a locally rendered remote page cannot start, "**Reopen on server** opens a new server-hosted page at its last address (signed-in or form state may differ)." For SSH workspaces, **Browse through SSH workspace hosts** "controls whether browser traffic and DNS go through the workspace's SSH host or this device. Downloads from a client-hosted remote page stay on the remote workspace host, and uploads are staged there before the page receives them." ## Link routing Under **Settings → Browser → Link Routing**, choose whether http(s) links from the terminal, markdown, and editor open in Orca's per-worktree browser or the system browser. "A nested **Hold Shift…** toggle inverts that default for one click with the platform modifier (`⇧⌘-click` on macOS, `Shift+Ctrl+click` on Windows / Linux): - When links open in **Orca**, the modifier sends one link to the system browser. - When links open in the **system browser**, turn the toggle on so the modifier opens one link in Orca's built-in browser instead (plain click stays system)." Remote capability is conditional: "A capability-verified paired runtime or an eligible SSH workspace can offer the same Orca/system-browser choice for its terminal links. Links from older runtimes remain system-browser only." See [terminal](terminal.md) for the link-action popover. ## Design Mode "Design Mode turns the Orca browser into a pointer-to-code tool. Toggle it on, click any UI element on the rendered page, and the element drops into the agent chat as rich context — with its DOM, computed styles, and a screenshot." Turn it on from the **Design Mode** toggle in the browser toolbar: "Your cursor becomes a picker; hovering highlights the element under it." What a click captures — note the hedge on the fourth item: - "The element's HTML (outer and a small neighborhood)." - "Its computed CSS — colors, fonts, spacing." - "A cropped screenshot of the element." - "The source file/line **if a dev-mode source map is available**." "All of that ships into the active agent terminal as one attachment, and you type what you want changed." **Annotation tray:** "Use the annotation tray to keep several notes on the page before sending them to the agent. Hover a note and choose **Edit** to change its comment or intent inline; choose **Save** or **Cancel** when you're done." Defaults for Design Mode live under **Settings → Browser → Design Mode defaults**, alongside a **Devtools opt-in** and **Default Zoom** ("zoom level applied to newly opened browser tabs; per-tab adjustments via Cmd-wheel are remembered separately"). ### The documented loop The recipe page compresses it: open the worktree's browser pane and navigate to the buggy page → toggle **Design Mode** on → click the broken element, which "lands in the agent chat as a rich attachment" → type the fix you want ("this padding is too tight, increase to match the cards above") → "The agent edits the source. Hot reload refreshes the browser." → click the element again to verify → repeat → commit. Why the docs claim it is fast: "No screenshot, no DOM hunting, no selector copying. The agent gets the HTML, computed CSS, and a cropped image of the exact element you pointed at — the same context a human reviewer would want." ## Browser-use profiles "Browser-use profiles let you run the Orca browser with a specific identity — a logged-in user, a particular cookie jar, a custom user-agent. Useful when an agent needs to log in, reproduce a session-specific bug, or emulate multiple users." Create one under **Settings → Browser → Profiles**: "Click **Add profile**, give it a name. Optionally seed it with cookies, a user-agent, and a viewport size." **User-agent spoofing.** "For sites that reject Orca's default Chrome-shaped UA (some Google sign-in flows), create a profile that keeps the **native Electron user agent** instead of spoofing. Default profiles still use the cleaned Chrome UA for broader Cloudflare compatibility." From the CLI: ``` orca tab profile create --no-ua-spoof ``` **Cookie import and the Google carve-out.** "Import cookies from Chrome or Edge (or from a cookie file) into a profile from Settings or the browser toolbar. Orca replaces existing cookies only for domains included in the import, so sign-ins for unrelated sites in the same profile stay intact." The exception is stated twice in the docs and should not be smoothed over: "Google cookies are excluded — import menus show **Google logins aren't imported** and tell you to **Sign in to Google directly in Orca.**" After an import that skipped Google cookies, "a separate warning names the host that ran the import: open a browser in Orca on that host with the same profile, then sign in." **Passkeys.** "When a site requests a discoverable passkey from a USB security key and the key offers multiple accounts, Orca opens an account picker instead of silently canceling the sign-in." Limitation, verbatim: "Platform passkeys stored by the operating system are not available in Orca yet; this flow is for external FIDO security keys." **Using and isolating a profile.** "Pick the profile from the browser toolbar. All tabs in that pane use it until you switch. Agent-driven browser commands inherit the active profile." Isolation is per-partition: "Each profile has its own storage partition — cookies, local storage, cache. Profiles don't leak into each other." ## Automation from agents "The browser is also scriptable by agents via the **Orca CLI** — `orca snapshot`, `orca click`, `orca fill`, and so on. Same browser you interact with, same tabs." The README lists the same verbs under its Orca CLI feature: "script every workflow with `orca worktree create`, `snapshot`, `click`, and `fill`." ## Related pages - [editing](editing.md) — HTML previews and the document-chip address bar - [terminal](terminal.md) — terminal link actions and the Orca/system browser choice - [worktrees](worktrees.md) — the scope that owns these tabs - [what-is-orca](what-is-orca.md) — where Design Mode sits in the product story ## Sources Per-worktree browser, Design Mode, browser-use profiles, the Design Mode recipe, settings reference, and README, all fetched 2026-09-09. --- title: "Computer Use" type: concept tags: [computer-use, accessibility, desktop-automation, cli, permissions] created: 2026-09-09 updated: 2026-09-09 sources: ["raw/web_community-computer-use-orca-docs.md", "raw/github_doc-skill-guides-computer-use-md.md", "raw/web_community-orca-cli-reference-orca-docs.md", "raw/github_issue-bug-orchestration-and-computer-use-failing-to-complete.md", "raw/github_doc-skill-guides-orca-cli-md.md"] confidence: medium --- # Computer Use The `orca computer` CLI lets an agent inspect and control native desktop apps — list running apps, read accessibility trees, click controls, set values, type text, scroll, and take screenshots. Use it when a task needs to operate the OS or a third-party app rather than a terminal or the built-in browser. ## What it is *not* for The skill guide draws three boundaries, and getting them wrong is the common mistake: - Orca's **embedded browser** is driven by `orca-cli` browser commands (`orca goto`, `orca snapshot`, `orca click`, …), not by `orca computer`. - **Page-only automation** of external pages belongs to a page-automation tool such as Playwright or CDP. - `orca computer` is for OS/window-level inspection and input in visible local app windows — native apps, external browser windows (Chrome, Edge, Safari), and app webviews — and should be used for a website only when the page is in an external desktop browser window that needs desktop-level control. The `orca-cli` guide adds the reverse rule: desktop control asked for by name is `ORCA computer ...`, never a browser command. ## First-time setup ``` orca status --json orca computer permissions --json orca computer capabilities --json ``` If `permissions` reports anything missing, grant Accessibility (and Screen Recording on macOS) to **Orca Computer Use** in System Settings, then re-run `permissions --json` to confirm. When an error names one specific permission, the narrower forms are `orca computer permissions --id accessibility --json` and `orca computer permissions --id screenshots --json`. ## The snapshot → act → snapshot loop Every interaction reads the app's current state, acts on a specific element, then re-reads 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 ``` Element indexes are scoped to the latest `get-app-state` result and **may be sparse**. In `--json` output, read the tree from `result.snapshot.treeText`. Do not invent indexes from `elementCount` — it is only a count. Indexes are short-lived and go stale after delays, navigation, focus changes, scrolling, window changes, or app re-rendering, so refresh state before reusing one. ## Selecting an app and a window Prefer bundle IDs returned by `list-apps`. App names work when unambiguous (`--app Spotify`); use `--app pid:` only when bundle ID and name both collide. For apps with multiple windows or ambiguous titles, run `list-windows` first. Prefer stable `--window-id` when the listed id is not `none`; otherwise use `--window-index`. Once a window is chosen, pass the same selector to `get-app-state` and later actions until the target window changes. ``` orca computer list-windows --app com.microsoft.edgemac --json orca computer get-app-state --app com.microsoft.edgemac --window-id --json orca computer click --app com.microsoft.edgemac --window-id --element-index 12 --json ``` ## Available actions ``` orca computer click --app --element-index --json orca computer set-value --app --element-index --value "text" --json orca computer type-text --app --text "text" --json orca computer press-key --app --key Return --json orca computer hotkey --app --key CmdOrCtrl+A --json orca computer paste-text --app --text "text" --json orca computer scroll --app --element-index --direction down --json orca computer drag --app --from-x 100 --from-y 100 --to-x 300 --to-y 300 --json orca computer perform-secondary-action --app --element-index --action --json ``` Prefer semantic actions (`click`, `set-value`, `perform-secondary-action`) over raw `type-text` or `press-key` — they target accessibility elements directly and survive focus changes that keyboard input doesn't. Use `press-key` for single/navigation keys such as Return, Escape, Tab, and arrows; use `hotkey` only for one modifier chord plus one key such as `CmdOrCtrl+A` or `CmdOrCtrl+Shift+P`. For modifier-clicks use `click --modifiers `; never synthesize separate modifier-down and modifier-up commands around a click, because an interruption can leave a modifier logically held. When accessibility targeting fails, fall back carefully to coordinates (`--x` / `--y`, or `--from-element-index` / `--to-element-index` for drags). Coordinates are window-local. ## Verification is separate from success This is the rule most worth internalising. The skill guide distinguishes: - `verified` — the changed value was read back. - `unverified (accessibility action unasserted)` — the accessibility call succeeded but no post-state assertion was made. - `unverified (synthetic input)` — input was fired into the void and is unverifiable. - Missing verification metadata is unverified, including responses from older runtimes. **Never report an unverified action as success.** If it could have sent, submitted, bought, or deleted something, say the effect is unproven. The guide also sets a consent floor: do not push, submit forms, send messages, buy items, delete data, change account settings, or expose secrets unless the user explicitly asked for that action, and if an app contains sensitive content, read only what the user requested. ## Sensitive input Pass secrets through stdin so they don't land in shell history: ``` printf '%s' "$TEXT" | orca computer set-value --app com.apple.Safari --element-index 7 --value-stdin --json ``` `--text-stdin` works the same way for `type-text` and `paste-text`. One caveat the skill guide adds: on **Linux and Windows**, action payloads still pass through a short-lived local operation file, so avoid sending secrets there unless the user explicitly asked for them. ## Screenshots `get-app-state` returns an accessibility tree and, by default, a screenshot. With `--json` the image bytes are written to disk and the path returned in `screenshot.path` rather than embedded; if that path is absent, use the inline base64 `result.screenshot.data`. Pretty output does not save images. Pass `--no-screenshot` when pixels aren't needed (faster, smaller payload) and `--restore-window` to bring a hidden or minimized window into view before capture. If the screenshot reports `scale` other than `1`, convert visual pixels before acting: ``` action_x = screenshot_pixel_x / screenshot.scale action_y = screenshot_pixel_y / screenshot.scale ``` On Linux and Windows, screenshots may come from the visible desktop region for the target window bounds, so `--restore-window` matters more there; if you cannot take focus, trust the tree over potentially occluded pixels. ## App-specific notes - **Browsers** (Edge, Chrome, Safari): set the address/search field directly, then press Return — do not assume raw typing went to the address bar. Large tab strips may show only the active tab plus an "inactive browser tabs omitted" marker; treat that as intentional noise reduction. - **Browser-hosted forms** such as Gmail compose: verify the focused UI element after each field action, because page text fields can expose accessibility actions without moving DOM focus. Prefer `paste-text` into the verified focused field for draft bodies. - **Spotify**: refresh after playback clicks; the UI often changes asynchronously. - **Slack**: the accessibility tree may be shallow while the screenshot contains useful information. Reading visible Slack UI is fine when requested; sending messages or triggering workflows still needs explicit permission. ## Error vocabulary The guide lists stable error ids and the right response to each: `app_not_found` (re-run `list-apps`; for a web app such as Gmail choose the desktop browser app/window, because `orca computer` app selectors refer to desktop apps, not website names), `app_blocked` (stop — intentionally blocked), `window_not_found` / `window_stale`, `window_not_focused` (retry once with `--restore-window`, then stop retrying restore), `element_not_found` (stale index), `unsupported_capability`, `action_not_supported`, `value_not_settable`, `element_not_clickable`, `invalid_argument` (fix the flags; do not retry unchanged), `action_timeout`, `screenshot_failed`, and `accessibility_error`. ## Installing the skill ``` npx skills add https://github.com/stablyai/orca --skill computer-use ``` The shipped `computer-use` skill packages the same command surface with safety guidance. See [Skills and MCP](skills-and-mcp.md) for how skills are picked up. ## Known rough edge Issue #10775 reports a Windows 11 user unable to get Orchestration and Computer use working while following the onboarding checklist, after uninstalling and reinstalling Orca; the reporter says the same failure hit Orchestration, Linear, and Computer use together, and a full delete-and-reinstall did not help. Upstream closed #10775 as completed on 2026-07-30, cross-referenced by PR #11033 — `fix(skills): stop a bounded plugin-cache walk from flagging every skill (#10775)`. **Analysis:** that PR confirms the reading below, which this wiki reached independently before checking: the fact that three separate *skill-backed* surfaces failed together pointed at skill install/resolution rather than at computer use itself — see the `npx skills update` failure documented on [Skills and MCP](skills-and-mcp.md), which is Windows-specific. ## Related pages - [Orca CLI](orca-cli.md) - [Orca CLI reference](../entities/orca-cli-reference.md) - [Skills and MCP](skills-and-mcp.md) - [Orchestration](orchestration.md) ## Sources `raw/web_community-computer-use-orca-docs.md`, `raw/github_doc-skill-guides-computer-use-md.md`, `raw/web_community-orca-cli-reference-orca-docs.md`, `raw/github_issue-bug-orchestration-and-computer-use-failing-to-complete.md`, `raw/github_doc-skill-guides-orca-cli-md.md`. --- title: "Reviewing and Shipping an AI Diff" type: concept tags: [diff, review, annotate, attribution, commit] created: 2026-09-09 updated: 2026-09-09 sources: ["raw/web_community-diff-viewer-orca-docs.md", "raw/web_community-annotate-ai-diff-orca-docs.md", "raw/web_community-attribution-orca-docs.md", "raw/web_community-commit-push-from-orca-orca-docs.md", "raw/web_community-review-an-ai-diff-line-by-line-orca-docs.md", "raw/web_community-settings-reference-orca-docs.md", "raw/web_community-monaco-editor-autosave-orca-docs.md"] confidence: medium --- # Reviewing and Shipping an AI Diff ## The diff viewer "Orca's diff viewer is designed for serious review of AI-generated code — not a quick glance. Every worktree has a built-in diff against its start-from ref." Documented features: - **Combined diff** across all staged, unstaged, and untracked files. - **Line numbers** for both sides, toggleable. - **Image diffs** — "side-by-side, swipe, and onion-skin modes for binary images." - **HTML preview** — in `View all` / combined diffs, "HTML sections that still exist in the working tree show **Open Preview to the Side** (eye) next to the always-visible open-file control… Deleted HTML and commit-only combined surfaces skip the eye." - **Merge-conflict UI** with three-way view and inline resolution. - **Staging by hunk or line** — "same as `git add -p` but visual." - **Show Whitespace**, from the diff viewer actions menu. **Scoping:** "The diff shows changes against the worktree's start-from ref by default. You can switch to comparing against any commit, branch, or the base ref from the diff toolbar." **Word wrap** is off by default for diffs. Toggle **Word Wrap** from the `⋯` actions menu in the diff editor header, or set the global default under **Settings → General → Diff Word Wrap** — "Both controls share the same setting — toggling from the editor flips it everywhere." This is a separate setting from **Editor Word Wrap**, which is on by default for file editors (see [editing](editing.md)). **File tree:** combined diffs can show a collapsible file tree beside the hunks; drag its resize handle "(or use arrow keys on the handle; Shift multiplies the step)" and the width is remembered across sessions. ### Diff keyboard shortcuts | Key | Action | | --- | --- | | `j` / `k` | next / previous changed file | | `n` / `p` | next / previous hunk | | `F7` / `Shift+F7` | next / previous change in the active editor | | `s` | stage the hunk under the cursor | | `c` | start a comment (Annotate AI Diff) | The same `n`/`p`/`s` chords work inside a file editor's **Changes view mode**, which flips a file into an in-tab HEAD-vs-working-tree diff. ## Annotate AI Diff "Annotate AI Diff is Orca's inline review loop for agent-generated code. You leave comments on any line of any AI-generated hunk, then send them back to the agent as a single batch for revision — no copying line numbers, no context-switching." Leaving a comment: hover any line in the diff, and "A `+` appears in the gutter. Click it (or press `c` with the cursor on the line)." Type feedback — markdown supported — then "`Cmd-Enter` to save, `Esc` to cancel." Comments "pin to the exact line; Orca tracks them across edits so they follow the line if the diff shifts." Sending the batch: click **Send to agent** at the top of the diff. "Orca composes a single prompt with all your comments, line-anchored, then opens a **Send notes to** menu for the worktree's available agents. Pick the agent that should revise the change, or start a new agent from the same menu." The shortcut **Send Review Notes to Agent** "is unbound by default so it won't collide with other chords" — assign it under **Settings → Shortcuts**; it "works even while the editor is focused." The rationale for batching, stated by the docs: "Sending comments one at a time causes the agent to swing back and forth. Batching keeps the feedback coherent: one round of thinking, one revision pass, and a much higher hit rate." After a revision, "Comments stay pinned after the agent revises — use them to verify the fix." Click **Resolve** to collapse a thread; "Unresolved comments are part of the next batch if you hit **Send** again." The recipe page compresses the whole loop: open the diff, walk it with `j`/`k`, drop comments with `c` ("full sentences work best"), **Send to agent**, watch the agent revise, re-open the diff, "resolve the ones that are fixed and leave follow-ups on the rest. Repeat until clean, then commit." ## Attribution "Orca tracks provenance on every line it sees an agent touch, so when you read a diff you can tell at a glance which lines were written by a human and which came from an AI." Mechanically: "When an agent writes to a file through its tooling, Orca records the ranges. The diff viewer renders AI-originated lines with a subtle marker in the gutter. Human edits on top of AI code flip the attribution back to human." Note the scope limit — this is local metadata, not repository content: "Attribution is local to Orca — it doesn't get committed to git. If you want persistent attribution, export the diff metadata from the diff toolbar." The qualifier "every line it sees an agent touch" is doing real work: attribution depends on the agent writing through its tooling, so edits Orca does not observe will not be marked. ## Commit Stage by hunk or by file from the diff, then "Write a commit message in the bottom panel, or use **Generate with AI** when you want Orca to draft one from the staged changes." Commit with `Cmd-Enter` (macOS) / `Ctrl-Enter` (Windows / Linux) "when focus is in Source Control and the primary action is Commit." "Pre-commit hooks from the repo run as usual. If a hook fails Orca surfaces the output inline." When a commit fails, **Fix with AI** "start[s] the default agent in the active worktree with the hook output, attempted commit message, and staged file list." The boundary is explicit: "The agent gets a repair prompt only — it is not asked to bypass hooks, commit, push, or open a review." Amending is deliberate friction: "Amending is explicit — **Commit → Amend**. Orca won't amend commits that have already been pushed unless you confirm." ## Push and force-push "**Push** pushes the worktree's branch to `origin`, setting upstream the first time. If the branch is behind, Orca will not silently force-push." After a rebase, amend, or squash, "the Source Control panel surfaces **Force push with lease** as an explicit, separate action — never as a fallback for plain Push. The label shows the commit count being replaced and the upstream branch name… Force push uses `--force-with-lease`, so a stale local view of the remote aborts the push instead of clobbering someone else's commits." ## The Source Control panel The sidebar panel exposes stage/discard, a commit message box, and **Commit**, **Push**, **Pull**, or **Sync** as one-click actions; "Paths render as UTF-8 even when they contain non-ASCII characters." The branch context row "shows the current branch (or detached HEAD) stacked above the compare base (`branch → base`)." When the branch has a usable merge base, a chip shows lines added and removed against that fork point — "one ranged diff, not a sum of staged/unstaged areas." Hovering gives a **Code breakdown** when the host publishes splits: `Source`, `Tests`, and `Generated` (generated only when non-zero) — and the docs flag the method: "path heuristics only, not content analysis." "The panel's primary button at the bottom shifts with state… **Stage Files** when there are unstaged changes, then **Commit**, then **Push** / **Pull** / **Sync** depending on how the branch sits against its upstream." For conflicts, Source Control shows **Resolve with AI** next to **Review conflicts**, and offers **Abort merge** or **Abort rebase** for an in-progress operation you no longer want. Right-click a changed file for **Copy Path** / **Copy Relative Path** (relative to the worktree root). ## Per-repo AI action recipes **Generate with AI**, **Generate pull request details with AI**, **Fix with AI**, and **Resolve with AI** "are all Source Control AI actions — each one is backed by an **action recipe** that picks the agent, CLI arguments, and prompt template Orca runs when you trigger the action." Edit them under **Settings → Git & Source Control → Action recipes**, "either as your global default or scoped to the current repository." Template variables, verbatim. For commit messages: `{basePrompt}`, `{branch}`, `{stagedFiles}`, `{stagedPatch}`, `{linkedIssue}`. PR details additionally support `{baseBranch}`, `{currentTitle}`, `{currentBody}`, `{commitSummary}`, `{changedFiles}`, and `{patch}`. One gotcha the docs call out: "`{linkedIssue}` expands to the workspace-linked **GitHub issue number**, or empty when none is linked (including pure Linear/GitLab workspaces). Prefer instructional phrasing — a bare `Fixes #{linkedIssue}` becomes `Fixes #` when unlinked." Repository overrides are sticky: "When a repository has its own recipe for an action, saving changes to the global default won't touch it," and the settings pane surfaces a **Repository overrides** note listing which repos diverge. ## Handing off to a hosted review Once pushed, the Source Control panel's hosted review action creates the PR or MR — see [issue-trackers-and-github](issue-trackers-and-github.md) for provider behavior, stacked PRs, and checks. ## Related pages - [worktrees](worktrees.md) — the start-from ref the diff compares against - [editing](editing.md) — Changes view mode and editor word wrap - [issue-trackers-and-github](issue-trackers-and-github.md) — PR creation and checks - [agents-and-sessions](agents-and-sessions.md) — which agent receives the review batch ## Sources Diff viewer, Annotate AI Diff, Attribution, Commit & push, review recipe, Monaco editor, and settings reference docs pages, fetched 2026-09-09. --- title: "Editing Files in Orca" type: concept tags: [editor, monaco, markdown, viewers, file-explorer] created: 2026-09-09 updated: 2026-09-09 sources: ["raw/web_community-monaco-editor-autosave-orca-docs.md", "raw/web_community-rich-markdown-editor-orca-docs.md", "raw/web_community-html-mermaid-pdf-image-viewers-orca-docs.md", "raw/web_community-file-explorer-external-drag-drop-orca-docs.md", "raw/web_community-settings-reference-orca-docs.md", "raw/web_community-quick-open-jump-palette-orca-docs.md"] confidence: medium --- # Editing Files in Orca ## Editor-first, not IDE-first "Orca's code editor is Monaco — the same editor VS Code uses — with a few Orca-specific tweaks." The scope is stated plainly: "Syntax highlighting ships for the languages Monaco supports out of the box. Orca is intentionally editor-first, not IDE-first — run type-checkers and linters in a terminal pane." **Autosave is the default and there is no dirty state:** "Files save on blur and after short idle periods. There is no 'dirty' dot because there are no unsaved changes in normal flow." (The one place the docs mention dirty tabs is mobile markdown tabs, which bulk-close actions skip.) ## Editor shortcuts and settings | Chord | Action | | --- | --- | | `Cmd-D` | select next occurrence | | `Cmd-F` / `Cmd-Shift-F` | file find / worktree find | | `Cmd-Click` | go to definition (where supported by language extensions) | | `Alt+Z` | toggle Word Wrap (same as VS Code; remappable under **Settings → Shortcuts**) | "File find seeds the search box from the current selection when text is selected." **Word wrap:** "File editors wrap long lines by default." Toggle from the editor tab's `⋯` menu, `Alt+Z`, or **Settings → General → Editor Word Wrap**. "This setting is separate from **Diff Word Wrap**, which only affects diff editors" — and note the opposite defaults: editor wrap on, diff wrap off (see [diff-review](diff-review.md)). **Minimap:** available under **Settings → Appearance**; "It's off by default." **Editor font:** "By default the editor and diff views use the same font as the terminal. Leave **Editor Font Family** empty under **Settings → Appearance** to keep that link; set a font to override editors only (UI font stays separate)." **Changes view mode:** toggle it "in any editor tab to flip the file into an in-tab HEAD-vs-working-tree diff without leaving your cursor position. Same shortcuts as the **Diff viewer** — `n`/`p` to walk hunks, `s` to stage." Files are opened from Quick Open (`Cmd-P`) or the `+` omnibox — see [tabs-panes-and-layouts](tabs-panes-and-layouts.md). ## The rich markdown editor "Markdown files open in a rich editor by default — slash menu, toolbar, inline previews for images and code, internal link autocomplete. Toggle to raw Monaco whenever you want with `Cmd-Shift-M`." Two documented fallbacks to the raw editor, both hedged: "For files larger than `600 KB`, Orca opens the raw editor first to keep typing responsive. Choose **Open anyway** in the fallback banner when you want the rich editor for that file; the choice lasts until you close its tab." And: "Files that use Markdown constructs the rich editor cannot safely preserve still stay in the raw editor." **Slash menu:** type `/` on an empty line for "headings, lists, code blocks, callouts, images, mermaid diagrams, and toggle blocks." Use `/toggle-text` for collapsible notes, "or `/toggle-h1` … `/toggle-h5` when the toggle summary should read like a heading level." Portability is preserved: "Orca saves toggles as portable `
` / `` markdown so the file still previews outside Orca." **Internal links:** "Type `[[` to start a wiki-style link. Orca autocompletes file paths within the worktree and inserts a relative link." **Search:** "In-editor markdown search respects rendered text, not raw markdown — so searching for 'Install' finds a heading whether written as `# Install` or `

Install

`." **Review annotations:** select rendered text to add an annotation without switching to raw markdown; "Orca keeps the note tied to the selected source range." **Add Review Note** defaults to `Cmd+Shift+A` / `Ctrl+Shift+A` and is remappable. **Front matter:** "YAML and TOML front matter is shown in the rich editor and rendered preview by default." The editor's **More actions** (`…`) menu toggles **Hide front matter** / **Show front matter**, "per-file, so hiding it on one document doesn't hide it on the rest." **Tables:** | Key | Behavior | | --- | --- | | `Tab` / `Shift-Tab` | Next / previous cell; Tab past the last cell inserts a row | | `Enter` | Move to the cell below; on the last row, add a row | | `Backspace` on a fully empty row | Delete the row (or the whole table if it is the last row) | | `Backspace` in an empty cell when the row still has content | Step to the previous cell | "When the caret is in a table, the rich-editor toolbar shows one-click **row and column insert/delete** controls. Right-click a table cell for the same structure commands… (the Table submenu only appears when the target is a table cell)." **Table of contents:** the tree icon in the editor header opens "a heading outline pinned to the left of the editor… Available in rich and preview modes." **Share as artifact:** publishes the open Markdown file "as a public view link through your signed-in Orca account. Files up to `10 MiB` are supported. Requires **Settings → Artifacts → Allow publishing public artifact links** (off by default)." Agents and scripts can use `orca artifacts share|update|list|delete`. Orca also "registers Markdown files as an available **Open With** app on macOS, Windows, and Linux without taking over your existing default editor." ## Viewers for non-code files **HTML.** Open a local, SSH, or paired-runtime `.html` file with **Open in Orca Browser** or **Open Preview to the Side**. "Orca renders the document locally in a sandboxed browser tab and reads the file and its relative assets through the workspace's file connection." Security posture is explicit: "The preview asks before reading additional folders, and grants only the folders you approve for that tab. External HTTP(S) links require confirmation and open in a normal Orca browser tab; downloads are disabled inside document previews." The preview's document chip doubles as an address bar: "Edit it and enter a web URL to turn that tab into a normal browser tab; enter a workspace HTML path from a browser tab to turn it back into a preview. **Back** crosses between the two when there is no intervening page history." Two constraints for remote work: "On paired runtimes, the HTML file must be inside the worktree. Very old paired servers may render the document without binary assets; update the server if remote images do not load." **Mermaid.** "Mermaid diagrams render inline inside markdown preview. Standalone `.mmd` files open in a dedicated viewer with pan/zoom." **PDF.** Scroll, zoom, text selection. "Scroll position is restored when you switch away from a PDF tab and come back (including close-and-reopen in the same session) — page plus mid-page offset." Note the limit: "Positions are session-only and clear when Orca restarts." **Images.** `.png`, `.jpg`, `.svg`, `.webp`, `.gif`, with an image-diff mode comparing two versions side-by-side. **CSV / TSV.** `.csv` and `.tsv` "open in a table viewer with sortable columns and quick search… Use the toolbar to flip back to the raw text view if you need to edit cells directly." **Jupyter.** `.ipynb` files "open in a notebook viewer with rendered markdown, syntax-highlighted code cells, and saved outputs. Editing cells writes back to the on-disk `.ipynb` while preserving nbformat, so diffs stay clean." ## File explorer "The file explorer lives on the left side of each worktree. It tracks your on-disk files in real time — create, rename, delete, and move all map to filesystem operations, so external changes (say, from the agent) show up instantly." Sort order is specified: "Directory listings sort directories first, then files, with **natural (numeric-aware) name order** — `9`, `99`, `100` instead of lexicographic `100`, `99`. The same ordering applies to SSH, remote runtime, Source Control tree nodes, folder pickers, and the mobile file tree." Files are colored by git status (untracked, modified, staged, ignored). Right-click for discard, stage, rename, **Copy Path**, and **Copy Relative Path** (`Cmd+Option+Shift+C` / `Ctrl+Alt+Shift+C` by default; remappable). **Copy** on a single file "place[s] the file itself on the OS clipboard. For SSH worktrees, Orca first stages the remote file locally, then writes that staged file reference to the clipboard; remote folders are excluded." **Find in Folder:** right-click a folder → **Find in Folder**, "or… select a folder in the file explorer and press `Cmd-Shift-F` on macOS or `Ctrl-Shift-F` on Windows and Linux." **Download (SSH / remote):** right-click a remote file → **Download**, "or a remote folder → **Download Folder** when the connection supports recursive transfer… Not available in the web client. Local worktrees do not show this action." ## External drag-and-drop Three documented drops: - "Drop files from Finder/Explorer into the file tree to copy them in." - "Drop an image into a markdown editor to insert it at the cursor." - "Drop files onto an agent terminal to paste their paths at the prompt." For SSH worktrees, "drag-drop also works — Orca uploads the file to the remote host before completing the drop, so the agent sees the file as a real on-disk path." ## Related pages - [diff-review](diff-review.md) — reviewing what you (or an agent) just changed - [tabs-panes-and-layouts](tabs-panes-and-layouts.md) — Quick Open and editor tabs - [browser-and-design-mode](browser-and-design-mode.md) — where HTML previews open - [terminal](terminal.md) — the pane you run linters and type-checkers in ## Sources Monaco editor & autosave, rich markdown editor, HTML/Mermaid/PDF/image viewers, file explorer & external drag-drop, and settings reference docs pages, fetched 2026-09-09. --- title: "Agent Hooks and Memory Files" type: concept tags: [hooks, memory, claude-md, agents-md, setup] created: 2026-09-09 updated: 2026-09-09 sources: ["raw/web_community-agent-hooks-memory-orca-docs.md", "raw/web_community-settings-reference-orca-docs.md", "raw/web_community-agents-sessions-orca-docs.md", "raw/github_doc-docs-reference-windows-setup-shell-md.md", "raw/web_community-orca-cli-reference-orca-docs.md", "raw/github_issue-bug-windows-grok-agent-hooks-flash-a-visible-console-and-ste.md", "raw/github_issue-bug-orca-hooks-fail-after-updating-codex-to-v0-144-3-session.md", "raw/github_issue-building-orca-for-raspberry-pi-5-ubuntu-arm64-works-with-no-.md"] confidence: medium --- # Agent Hooks and Memory Files ## The posture: read, respect, don't own "Orca plays nicely with the agent hook and memory conventions Claude Code and Codex already use — it reads them, respects them, and gives you a UI for the ones that make sense in an IDE context." That sentence sets the boundary for everything below. There are three distinct kinds of hook in play, and conflating them causes most of the confusion: 1. **Your repo's own agent hooks** — the `.claude/` and `.codex/` configuration you already keep in the repository. 2. **Worktree setup hooks** — Orca-owned commands that run after a worktree is created. 3. **Orca-managed agent *status* hooks** — machine-generated hooks that report working / waiting / done back into the Orca UI. ## Per-repo hooks you already have "Orca reads each repo's `.claude/` and `.codex/` configuration. Hooks you already have will run when Orca launches the agent in a worktree of that repo." ## Memory files stay the agent's "Claude's `CLAUDE.md` and Codex's `AGENTS.md` (at repo root or nested) are left alone — they belong to the agent. Orca surfaces them in the file explorer like any other file so you can edit them inline." There is no Orca-managed memory store in these docs. Anything an agent remembers across sessions comes from the agent's own conventions (memory files, and the on-disk transcripts that [agent session history](agents-and-sessions.md) resumes from), not from Orca. ## Worktree setup hooks "Configure commands to run automatically after a worktree is created — e.g. `pnpm install`, `direnv allow`, or a script that restores `.env` files. Set them under **Settings → Repository → Hooks**." The same settings pane also lists "Auto-run commands on worktree create." From the CLI, `orca worktree create` takes a `--setup` flag: "`--setup run|skip|inherit` controls repo setup hooks; `inherit` follows the repo policy." ``` 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 ``` Setup hooks are the natural companion to the shared-path mechanisms on [worktrees](worktrees.md) — shared paths supply the gitignored trees, setup hooks rebuild anything that must be regenerated per checkout. ### The Windows setup-runner shell rule This is the highest-value gotcha in the sources, because it silently changes which language your setup script runs in. "On native Windows, Orca writes the `orca.yaml` setup script (and the issue command) to a generated runner file and types a launch command into a terminal. The runner is a **`.cmd` batch file by default**, exactly as it has been since setup hooks shipped." A script opts into bash by starting with a `#!` interpreter line: ```yaml scripts: setup: | #!/usr/bin/env bash [ -f .env ] || cp .env.example .env pnpm install ``` Without that line, the script keeps running under `cmd.exe`: ```yaml scripts: setup: | copy .env.example .env xcopy /E assets dist ``` The design reason is explicitly *not* the terminal preference: "`terminalWindowsShell` says which shell _interactive terminals_ open in. It says nothing about the language a project's setup script is written in." The same rule applies to the per-user setup command in **Settings → repository hooks** (`repo.hookSettings.scripts.setup`): "it is merged into the same script that reaches the runner, so a POSIX one-liner stored there needs its own `#!` line to run under bash on Windows." Two details about what the `#!` line does: "The generated runner is always executed by bash (`bash `; Git Bash on native Windows), on every platform," and its option flags are replayed with `set`, so `#!/usr/bin/env -S bash -euo pipefail` really does get `pipefail` — but "Only the flags `set` itself accepts (`[--abefhkmnptuvxBCHP] [-o option]`) are replayed; invocation-only ones such as `-l` are dropped." The interpreter name beyond "is this a POSIX shell" is not honored: `#!/bin/sh` and `#!/bin/zsh` scripts run under bash. Failure mode when bash is unavailable (a PowerShell/cmd terminal, or an SSH-to-Windows host): "the `#!` script is **not** executed under cmd. The generated `.cmd` runner prints why and exits 1, because running the interpreter-agnostic prefix of a bash script… and only failing at the first bash-only line leaves a half-set-up worktree that looks finished." ## Orca-managed agent status hooks "**Settings → Agents → Agent status hooks** controls the Orca-managed hooks that report working / waiting / done into the UI." These are what drive the state glyphs described in [agents-and-sessions](agents-and-sessions.md) — "State is detected from the terminal's OSC title sequence and agent hooks." Turning the setting off "removes those managed hooks and stops reinstalling them; turning it back on restores them **without restarting Orca** (on Windows, the WSL hook relay follows the same live gate)." CLI equivalents, verbatim from the docs page: ``` orca agent hooks status|on|off --json ``` The settings reference states the same commands as `orca agent hooks on|off|status`. **Settings → Agents** also carries "Startup hooks per agent," listed alongside the installed-agents toggles and the Claude/Codex account lists. ### Surviving a restart "Hook endpoints are written to disk (`{userData}/agent-hooks/endpoint.env` on POSIX, `endpoint.cmd` on Windows) and re-sourced on every hook invocation, so long-lived agent sessions keep reaching the live Orca server even after an app restart — no more dead-port POSTs from a PTY that outlived the previous session." ## What the managed hooks look like on disk The docs do not publish the generated hook layout, but several bug reports do. Treat the following as observed detail from user reports on specific versions, not as a documented interface. From issue #14828 (Windows, Grok, Orca 1.4.184): "`%USERPROFILE%\.grok\hooks\orca-status.json` registers 9 events (`SessionStart`, `UserPromptSubmit`, `Stop`, `StopFailure`, `SessionEnd`, `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `Notification`)" pointing at a PowerShell launcher that calls `%USERPROFILE%\.orca\agent-hooks\grok-hook.cmd`. That relay in turn "POSTs to `http://127.0.0.1:%ORCA_AGENT_HOOK_PORT%/hook/grok` via `curl.exe`, with header `X-Orca-Agent-Hook-Token`." The reported symptom of that shape: "a black console window flashes for a fraction of a second and takes foreground. Anything typed into the Orca terminal at that moment goes into the flash instead of Grok." Upstream closed #14828 as completed on 2026-08-21. During the thread two competing follow-up PRs were noted, with a commenter observing "The two overlap and should not both merge." Worth knowing: a fresh report of the same class landed on the closed thread on 2026-08-23, so treat the symptom as recurring-but-addressed rather than permanently gone. From issue #8645 (Windows, Codex v0.144.3, Orca 1.4.138.0): every prompt produced `SessionStart hook (failed) / error: hook exited with code 1` and the same for `UserPromptSubmit` and `Stop`. Diagnosis in-thread: "The generated entries contain CMD-only syntax (`if exist`, `call`, `%SystemRoot%`) in the generic `command` field," with no Windows-specific `commandWindows` field, so PowerShell rejected them. A later comment reports resolution: "After updating to Orca 1.4.141, startup regenerated all six managed hooks to the directly spawnable `%USERPROFILE%\.orca\agent-hooks\codex-hook.cmd` form," and a full lifecycle run then completed with no hook failures. The same thread names the Orca-managed `CODEX_HOME` as `%APPDATA%\orca\codex-runtime-home\home`. From the Raspberry Pi 5 / Ubuntu arm64 build report: `agent-hooks` can crash with `EACCES` on a root-owned `~/.gemini`, logging `[agent-hooks] Failed to install gemini managed hooks:` and the same for `antigravity`. The reporter rates it "Medium" severity. **Analysis:** the practical takeaway is that managed-hook installation writes into each agent's own dotfile directory, so a dotfile owned by another user (a `sudo` run that created it as root, for instance) blocks installation for that agent while leaving the rest working. ## Practical checklist - Repo hooks: keep them in `.claude/` and `.codex/`; Orca runs them when it launches the agent. - Memory: `CLAUDE.md` and `AGENTS.md` are yours; Orca will not rewrite them. - Setup: put per-worktree bootstrap in **Settings → Repository → Hooks** or `orca.yaml` scripts, and on Windows add a `#!` line if the script is POSIX. - Status: if the UI stops showing working/waiting/done, check `orca agent hooks status --json` before blaming the agent. - CLI creates: pass `--setup run|skip|inherit` explicitly when scripting worktree creation. ## Related pages - [agents-and-sessions](agents-and-sessions.md) — what the status hooks feed - [worktrees](worktrees.md) — shared paths and `.worktreeinclude`, the other half of setup - [terminal](terminal.md) — the Windows shell setting that does *not* choose your runner language - [installation](installation.md) — importing `~/.claude` and `~/.codex` on first launch ## Sources Agent hooks & memory docs page, settings reference, agents & sessions, the Windows setup-runner shell reference, the Orca CLI reference, and GitHub issues #14828, #8645, and the Raspberry Pi 5 build report — all fetched 2026-09-09. --- title: "Installing Orca" type: concept tags: [installation, homebrew, aur, appimage, mobile] created: 2026-09-09 updated: 2026-09-09 sources: ["raw/web_community-install-orca-docs.md", "raw/github_doc-readme-md.md", "raw/web_community-install-orca-mobile-on-android-orca-docs.md", "raw/github_doc-docs-reference-headless-linux-server-md.md", "raw/github_doc-docs-reference-linux-glibc-compatibility-md.md", "raw/web_community-terminal-orca-docs.md", "raw/web_community-settings-reference-orca-docs.md"] confidence: medium --- # Installing Orca Every command, package name, asset filename, and URL below is reproduced exactly as it appears in the Orca documentation and README as fetched on 2026-09-09. Nothing here is reconstructed from memory. Where the docs and the README disagree, both readings are given. ## Desktop download links The docs describe Orca as a desktop app offered for macOS, Windows, and Linux, with an "Email yourself a link" flow on the download page. The README lists the direct release assets: | Target | Asset URL | | --- | --- | | macOS Apple Silicon | `https://github.com/stablyai/orca/releases/latest/download/orca-macos-arm64.dmg` | | macOS Intel | `https://github.com/stablyai/orca/releases/latest/download/orca-macos-x64.dmg` | | Windows (.exe) | `https://github.com/stablyai/orca/releases/latest/download/orca-windows-setup.exe` | | Linux AppImage | `https://github.com/stablyai/orca/releases/latest/download/orca-linux.AppImage` | | All builds | `https://github.com/stablyai/orca/releases/latest` | The docs also list `.deb` and `.rpm` as Linux download options alongside the AppImage. The headless-server guide names an arm64 AppImage asset as `orca-linux-arm64.AppImage`. Download page: `https://onorca.dev/download`. Older versions: GitHub Releases. ## macOS — Homebrew cask Orca "is also published as a Homebrew cask, auto-bumped on every stable release": ```bash brew install --cask stablyai/orca/orca ``` `brew upgrade --cask orca` picks up new stable builds. The cask tracks the **stable** channel — for RC builds the docs point you at the GitHub Releases links or the in-app **Check for Updates** flow. macOS builds are "signed and notarized. On first launch, macOS may still ask you to confirm — that's normal for Electron-based apps." ## Arch Linux — AUR The README's package-manager block, verbatim: ```bash # Arch Linux (AUR) — or stably-orca-git to build from source yay -S stably-orca-bin ``` So the two package names are `stably-orca-bin` (prebuilt) and `stably-orca-git` (builds from source). The README shows only the `yay` invocation; no other AUR helper is named in `raw/`. ## Windows Install with `orca-windows-setup.exe` (the README's "Windows (.exe)" asset) or from the download page. Shell configuration after install: the Terminal doc says "The default shell on Windows is configurable between PowerShell, Command Prompt, and WSL under **Settings → Terminal**. WSL is offered automatically when `wsl.exe --status` succeeds." The install page says only "The default shell can be set to PowerShell or CMD under **Settings → Terminal**. Most users want PowerShell," and the settings reference likewise lists "Windows default shell (PowerShell or CMD)." **Analysis:** the three pages are inconsistent about whether WSL is a selectable default. The Terminal page is the most specific (it names the `wsl.exe --status` probe), so treat WSL as available but verify in your build rather than assuming it. For repos on a WSL filesystem (`\\wsl.localhost\...`), "Orca launches through `wsl.exe -d `. For Windows-path repos opened in WSL, Orca translates the cwd to `/mnt//...` and drops you into a login bash." ## Linux Choose the AppImage "if you want Orca to update itself. The `.deb` and `.rpm` packages report available updates and give you the package-manager command to install them; quit Orca before running that command." **The Linux CLI is named `orca-ide`, not `orca`** — "so it does not conflict with the GNOME Orca screen reader." The headless guide adds detail: `orca-ide` never shadows the screen reader at `/usr/bin/orca`; "The `.deb` and `.rpm` packages put `orca-ide` on `PATH` themselves at install time; with the AppImage it arrives as `~/.local/bin/orca-ide` when the CLI is registered." Platform floor: "Orca's Linux builds target **stock Ubuntu 20.04 and newer** — glibc 2.31 and libstdc++ `GLIBCXX_3.4.28` (also Debian 11, RHEL 9), on both x64 and arm64." ### Headless server prerequisites (Ubuntu / Debian) The supported deployment matrix for `orca serve` "covers Ubuntu 20.04, 22.04, and 24.04 and current Debian stable — anything with glibc 2.31 or newer." Install the Electron dependencies before running it — this command is **for Ubuntu 24.04 and newer and Debian 13 and newer**: ```bash sudo apt-get update sudo apt-get install -y \ curl file jq xvfb zlib1g-dev ca-certificates git \ libgtk-3-0t64 libnss3 libatk1.0-0t64 libatk-bridge2.0-0t64 libgbm1 libasound2t64 \ libxtst6 libcups2t64 libdrm2 libxkbcommon0 libpango-1.0-0 libcairo2 libatspi2.0-0t64 \ libxcomposite1 libxdamage1 libxfixes3 libxrandr2 libxrender1 libx11-xcb1 \ libxcb-dri3-0 libxss1 ``` On Ubuntu 20.04, Ubuntu 22.04, and Debian 12, substitute the unsuffixed names: `libgtk-3-0t64` → `libgtk-3-0`, `libatk1.0-0t64` → `libatk1.0-0`, `libatk-bridge2.0-0t64` → `libatk-bridge2.0-0`, `libasound2t64` → `libasound2`, `libcups2t64` → `libcups2`, `libatspi2.0-0t64` → `libatspi2.0-0`. "The substitution is not symmetric, so use the list that matches the release." FUSE: "On Ubuntu 20.04 and 22.04, install `libfuse2` to execute the AppImage through FUSE. On Ubuntu 24.04 and Debian 13 the package is `libfuse2t64`… FUSE is optional: without it, use the AppImage's supported extraction path." Manual AppImage placement, verbatim from the guide: ```bash sudo mkdir -p /opt/orca sudo curl -L https://github.com/stablyai/orca/releases/latest/download/orca-linux.AppImage \ -o /opt/orca/orca-linux.AppImage sudo chmod +x /opt/orca/orca-linux.AppImage ``` Without FUSE, extract as root because the install directory is root-owned: ```bash cd /opt/orca sudo ./orca-linux.AppImage --appimage-extract sudo chmod -R a+rX /opt/orca/squashfs-root /opt/orca/squashfs-root/AppRun serve --port 6768 ``` The `chmod` is required whenever the extraction runs as a different user than the server. ## Mobile companion **iOS** — App Store: `https://apps.apple.com/us/app/orca-ide/id6766130217`; TestFlight: `https://testflight.apple.com/join/YjeGMQBA`. **Android** — the README links "Android APK 0.0.48" at `https://github.com/stablyai/orca/releases/download/mobile-android-v0.0.48/app-release.apk`, with an install guide at `https://www.onorca.dev/docs/android-apk`. That guide's steps: 1. "Open the **Orca download page** in Chrome or another full browser and select **Android**." 2. "When the download finishes, open your browser's **Downloads** or your device's **Files → Downloads**, then tap `app-release.apk`." 3. "Follow Android's installation prompt. If asked, allow only the browser or Files app to install unknown apps, then turn that permission off after Orca is installed." Two documented Android snags: a link opened inside Discord or GitHub may not download — choose **Open in browser** / **Open in Chrome**; and on a Samsung Galaxy, if **Auto Blocker** prevents the install, "open **Settings → Security and privacy → Auto Blocker**, temporarily turn it off, install Orca, then turn it back on. Do not disable Play Protect." **Version note:** 0.0.48 is the APK version the README linked as of 2026-09-09; it is an Android companion build number, not the desktop version. Do not read it as a desktop release pin. ## First launch and updates On first launch Orca will: "Ask for access to your home directory so it can add repos"; "Offer to import `~/.claude`, `~/.codex`, and Ghostty terminal settings if present"; and "Drop you on an empty landing screen where you add your first repo." Orca auto-updates by default, tracking the **stable** channel. "There is no permanent in-app opt-in for the RC channel." Modifier clicks on **Check for Updates** (**Settings → General → Updates**, or the app / Help menu): | Modifier | Effect | | --- | --- | | `Shift+click` | Include the latest **RC** prerelease | | `Cmd+click` (macOS) / `Ctrl+click` (Windows/Linux) | Latest **perf**-tagged prerelease | | `Option+click` (macOS only) | Pick a **validated local macOS build** that passes Orca's compatibility checks | Register the bundled command-line tool for shells and agents under **Settings → General → Orca CLI**. ## Related pages - [what-is-orca](what-is-orca.md) — what you just installed - [terminal](terminal.md) — Ghostty/Warp theme import and the Windows shell setting - [worktrees](worktrees.md) — the first thing you create after adding a repo ## Sources Install page, README, Android APK guide, headless Linux server reference, glibc compatibility reference, terminal page, and settings reference — all as of 2026-09-09. --- title: "Hosted Reviews, Issues and Task Drawers" type: concept tags: [github, gitlab, linear, jira, code-review] created: 2026-09-09 updated: 2026-09-09 sources: ["raw/web_community-hosted-reviews-issues-actions-orca-docs.md", "raw/web_community-linear-items-drawer-orca-docs.md", "raw/web_community-jira-items-drawer-orca-docs.md", "raw/web_community-troubleshooting-github-errors-orca-docs.md", "raw/web_community-settings-reference-orca-docs.md", "raw/web_community-commit-push-from-orca-orca-docs.md"] confidence: medium --- # Hosted Reviews, Issues and Task Drawers ## The premise "Hosted code review is a first-class part of the worktree. Orca links worktrees to their pull requests or merge requests, surfaces review state inline, and lets you triage issues without leaving the app." Providers connect from **Settings → Integrations**. "GitHub has the deepest Actions and issue support; GitLab merge requests and issues use the same worktree review flow." Bitbucket Cloud connects from the same pane with **Email & API token** or an **Access token**; "Orca verifies the credential before saving and can create pull requests from Source Control. Bitbucket Cloud has no draft PRs, so the composer hides the Draft toggle." Environment variables win: "`ORCA_BITBUCKET_*` environment variables still win over a saved credential" — and on a Remote Orca Server, "set the env vars on the server instead," since saved credentials stay on the machine that saved them. "Azure DevOps and Gitea pull requests appear in the worktree sidebar and the Checks panel alongside GitHub, GitLab, and Bitbucket." ## Reviews attached to a worktree Open a hosted review from the Source Control panel "once a worktree has been pushed — confirm the base branch, title, description, and draft state before creating it." See [diff-review](diff-review.md) for the commit and push half. Once linked, review state lives in the sidebar: "Linked reviews show up in the sidebar with status so you can tell whether the branch is still open, merged, or closed." The branch context row shows a compact **Open review page in browser** link when Orca has a URL — "one click jumps to the review on GitHub, GitLab, Bitbucket, Azure DevOps, or Gitea without opening the internal PR view." Alternatively, from a linked review or issue's overflow menu, **Open in Orca browser** opens its URL "in the current worktree's browser tab" (see [browser-and-design-mode](browser-and-design-mode.md)). Provider-specific actions: - GitHub PRs: the sidebar PR actions menu can "copy the review link, close the review, or reopen it after confirming the state change." - Draft GitHub PRs and GitLab MRs: **Mark ready for review** or **Close**. For GitLab, "the action removes its Draft/WIP state; merge and auto-merge remain unavailable while the review is still a draft." - Linked GitLab MRs: the review-link menu in the Checks sidebar offers **Unlink MR** or **Link another MR**. Inside the PR tab: "GitHub checks, reviews, and comments open inline in a PR tab; GitLab merge requests and issues open in the same review surface." You can "reply to any comment in a review thread, not only the root comment." GitHub PR conversation and inline review-thread comments carry "a reaction picker matching GitHub's eight reactions (👍 👎 😄 😕 ❤️ 🎉 🚀 👀)… GitLab comments stay unchanged." Grouped PR comment sections sort newest-first; "The Timeline tab stays oldest-first." For GitLab pipelines, the **Checks** side panel "includes bridge and child pipeline jobs (not only top-level jobs). Expanding a job loads that job's trace (log) when available." ## Auto-merge and stacked pull requests **Auto-merge** is GitHub-only in these docs: the PR view's merge button offers **Enable auto-merge** "so GitHub merges the branch automatically once its requirements (checks, required reviews) pass. The merge method follows the repository's default and is one of `Squash and merge`, `Create merge commit`, or `Rebase and merge` — methods the repo disallows aren't shown." With a merge queue on the base branch, "the same control reads **Merge when ready** and adds the PR to the queue instead." The visibility rule is negative and worth quoting: "The auto-merge control is hidden for PRs GitHub reports as draft, closed, conflicting, or unstable, and for repos that don't allow auto-merge — in those cases you'll only see the manual merge action." **Stacking.** When you create a GitHub PR "whose selected base already has an open PR, the composer offers **Stack this PR above #N**." Checking it "creates a GitHub Stack (or extends the parent's existing stack) and changes the submit label to **Create PR in stack** (or **Create draft PR in stack** / **Push & Create PR in stack**)." Scope limits: "The option is GitHub-only and appears only when the executing host supports stacked creation. GitLab merge requests and Bitbucket pull requests stay single-PR create." For a registered stack, "the PR sidebar shows a collapsible **Stack #N** map: your position in the stack, stack size, and the stack base branch," with per-layer status (open, draft, checks pending/failed, review needed, conflicts, merged, closed). Stack-aware merge replaces the single-PR label with "**Merge through #N · M PRs** (or **Queue through #N · M PRs** when the repo uses a merge queue). That action covers the current PR and every PR below it in the stack… Atomic stack merge fails closed — if any layer cannot merge, none merge." Note the exclusion: "Ordinary dependent PR chains without GitHub-registered stack metadata keep the normal single-PR merge flow." ## Issues, Actions and Tasks "The issue drawer lets you browse, filter, and edit GitHub and GitLab issues from within Orca." Creating a worktree from a GitHub issue or PR "opens the interactive workspace composer (not a silent background create) so issue-command automation, SSH targets, and folder workspaces work the same as other create paths." For GitHub issues, "the details dialog has an **Activity** section that interleaves comments with timeline events — assignments, mentions, cross-references, state changes, and project column moves." For GitLab, "the drawer lists open issues from the selected project and can narrow the list to issues assigned to you." **Actions:** "Failed GitHub Actions checks show up as a red chip on the worktree. Click through to see the failing job logs inline." When a PR has failing checks, **Fix broken checks** from the PR view "hand[s] the failed check names and links to an agent." **Tasks:** "Orca surfaces a full GitHub Projects view under the **Tasks** sidebar entry — browse project cards across repos, filter by source repo, see draft pull request status, and create a worktree from any card." ## Linear drawer Setup: **Settings → Integrations → Linear** → "Paste a personal API token from **Linear → Settings → API**" → "Pick the team(s) you want to see." "The task drawer shows GitHub and Linear issues in one combined view." Useful modes and behaviors: - **Has Workspace** mode "list[s] only issues already linked to a local worktree or folder workspace. Rows with an attached workspace open that workspace; you can still start a new one from the same issue when you need a second checkout." - Branch naming: "When Linear exposes a branch name for the issue, Orca uses that as the worktree branch (same naming Linear would suggest), not only a slug of the title." The issue detail menu can **Copy suggested branch name**. - Relinking after create: use **Edit Worktree Details** → the **Issue** field with the **Linear** chip, "or paste a Linear URL." Constraint: "GitHub and Linear share that one field — saving a new link replaces the previous provider link." - Issue detail views edit "status, assignee, priority, labels, and estimate," with Linear's own priority icons. - Prompt context: "When you launch an agent from a Linear issue, Orca includes any inline images and media embedded in the issue's description, comments, and sub-issues in the prompt context." - Draft retention: **New Linear issue** and **New Linear project** keep their text if you dismiss the dialog — "Text restores when you reopen the dialog in the same app session; drafts clear after a successful create and **do not survive an app restart**." - Layout choices persist across restarts (list vs board, group-by, order-by, visible columns, attribute filters), and "Attribute filters are stored **per Linear workspace**." Agents get a CLI surface: "Agents can read and write Linear through `orca linear` (and the `orca-linear` skill). That surface includes MCP-compatible create/update and list filters (`save-issue`, `list-issues`, relation add/remove) plus issue context flags such as `--activity` and `--full`." ## Jira drawer Connect from the **Tasks** sidebar entry — "Jira sits next to GitHub and Linear by default, even before any credentials are saved." Click **Connect Jira**, then choose **Cloud** or **Self-hosted (Server / Data Center)**. **Cloud** wants: **Jira Cloud site URL** (e.g. `https://example.atlassian.net`), **Atlassian email**, and an **Atlassian API token** — "create one at `id.atlassian.com → Security → API tokens`." **Self-hosted** wants a **Jira base URL** ("including path if Jira is not at `/`") and an auth method: **Personal access token** — "Bearer PAT (preferred on modern Server/DC)" — or **Username and password** ("Basic auth for older instances without PATs"). "You can connect more than one Atlassian site. The Tasks header has a site picker once a site is connected; choose **All sites** to combine issues across them." To hide Jira entirely, use **Settings → Tasks**. Creating work from Jira: paste a Jira issue URL (`https://…/browse/ABC-123`) into the Create workspace name field, or switch the field to **Jira** search. "Orca fills the workspace name, links the issue, and shows the key + summary on the worktree card with **View on Jira**." Multi-site handling is explicit: "when more than one connected site matches the URL origin, Orca asks which site to use; when none match, it says the site is not connected." Across all three providers, "Orca remembers your last-used task source (GitHub, Linear, or Jira) per repo." ## When GitHub data stops refreshing "Orca talks to GitHub through the **GitHub CLI (`gh`)** on your machine (or remote Orca host). When PR status, checks, issues, or Tasks fail to refresh, the cause is almost always GitHub auth, permissions, or API rate limits — not a broken PR panel by itself." The docs' quick triage, condensed to the first action for each symptom: | Symptom | First thing to try | | --- | --- | | "rate limit exceeded (core)" | Wait for reset; stop extra `gh` / agent / Orca usage; check **Settings → Git → GitHub API Budget** | | `gh auth` prompts / auth unavailable | `gh auth status`, then `gh auth login` | | HTTP 403 that is not a rate limit | Re-auth with `repo` scope (and needed org SSO); confirm browser access to the PR | | HTTP 404 / "repository is unavailable" | Check `git remote -v` and browser access | | Timeouts / unreachable | Check `githubstatus.com`; retry off VPN | | "GitHub CLI is unavailable" | Install `gh` and restart Orca | The rate-limit point that catches people: "GitHub gives each **authenticated user** a shared hourly budget. **Every tool on that account shares it**: Orca, `gh` in terminals, Claude/Codex/Grok agents that call `gh`, CI scripts, browser extensions, and other apps." REST (core) is documented with a typical authenticated limit of 5,000 / hour. ## Related pages - [diff-review](diff-review.md) — commit, push, and PR-body generation - [worktrees](worktrees.md) — linking an issue at create time and branch derivation - [browser-and-design-mode](browser-and-design-mode.md) — opening a review in the worktree browser ## Sources Hosted reviews/issues/Actions, Linear items drawer, Jira items drawer, GitHub error troubleshooting, commit & push, and settings reference docs pages, fetched 2026-09-09. --- title: "Mobile Companion" type: concept tags: [mobile, pairing, android, relay, remote] created: 2026-09-09 updated: 2026-09-09 sources: ["raw/web_community-mobile-companion-orca-docs.md", "raw/web_community-install-orca-mobile-on-android-orca-docs.md", "raw/github_doc-mobile-readme-md.md", "raw/web_community-remote-orca-servers-orca-docs.md", "raw/github_issue-bug-mobile-qr-pairing-never-connects.md", "raw/github_issue-bug-orca-relay-for-mobile.md", "raw/github_issue-bug-mobile-connection-issue.md"] confidence: medium --- # Mobile Companion The Orca mobile companion is an iOS/Android app that pairs with your desktop Orca and gives a **read-mostly** view of running agents — agent status, recent terminal scrollback, and the controls you actually want from a phone. Pairing is one-time and **the desktop is always the source of truth**. The docs state the design intent directly: "The mobile app is intentionally not a full editor — it's a remote control for the desktop you already have running." ## What you can do from the phone - See every worktree, its agent, and its current status (working / done / waiting on input). Mobile lists worktrees from every host you're connected to — local desktops and remote Orca servers — in a single view. - Browse the workspace's full file tree, including deeply nested paths. - Open supported agent sessions in `Chat UI` (a chat-style transcript) or the raw terminal. - Hydrate recent terminal scrollback. Markdown in chat-style views can render `Mermaid` diagrams when the message includes them. - Select, copy, and paste text from the mobile terminal view — long-press to select, share-sheet to paste back into a reply. - Use the terminal accessory row for awkward keys including `Tab` and `Shift+Tab`, or switch to `Live` when each typed character should go straight to the active terminal. - Send a short reply (`continue`, `yes`, free-text) when an agent is waiting on input, attach a photo or file, or dictate. In `Live` mode, dictated text is inserted into the active terminal **without pressing Return for you**. - Run `Quick Commands` from the session tab strip — the same saved list as desktop, synced both ways. - Open a browser session in `Web` or `Mobile` view. - Open Source Control for a worktree to review changed files, stage or unstage, and commit. - Switch the active agent account and see usage / rate-limit state; when Codex has earned reset credits, spend one from the accounts screen (see [Usage and rate limits](usage-and-rate-limits.md)). - Create a workspace with the same Smart source modes as desktop: Smart, GitHub, Linear, GitLab, Branch, and Name. - Get push notifications when an agent finishes, mirroring desktop notifications (see [Notifications and inbox](notifications-and-inbox.md)). ## Installing on Android Android is distributed as an APK, not through Play: 1. Open the Orca download page in Chrome or another full browser and select `Android`. 2. When the download finishes, open your browser's `Downloads` or your device's `Files → Downloads`, then tap `app-release.apk`. 3. Follow Android's installation prompt. If asked, allow only the browser or Files app to install unknown apps, then **turn that permission off after Orca is installed**. Two documented install snags: - **Download never starts or finishes.** If the link opened inside Discord, GitHub, or another app, choose `Open in browser` / `Open in Chrome`, or copy it into a full browser, then start the Android download again. - **Samsung Galaxy Auto Blocker.** If Auto Blocker prevented the install, open `Settings → Security and privacy → Auto Blocker`, temporarily turn it off, install Orca, then turn it back on. The docs add: **do not disable Play Protect.** ## Pairing On desktop, open Orca's pairing flow from the account / status menu; Orca shows a one-time pairing code. On mobile, open the companion app, choose `Pair`, then paste the code — or follow a deep link from the desktop straight into the mobile pairing screen. The docs recommend **Orca Relay** for pairing when it is available; sign-in is required for Relay only. The local network address picker is optional on Relay (expand it when you want a LAN fast path), while LAN pairing still needs an address. The pairing exchange establishes a device token for that phone, and you must keep the desktop reachable on the path you chose. Closing the desktop app drops a direct/LAN session until you reopen it. Relay-backed pairing follows the desktop Relay connection. ### From a headless server For a host running `orca serve`, request a mobile-scoped QR code and link: ``` orca serve --pairing-address 100.64.1.20 --mobile-pairing ``` Keep the phone on the same tailnet, open Orca Mobile, choose `Pair`, and scan the terminal QR code or paste the printed link. See [Remote Orca Servers](remote-servers.md). ### Editing a paired host without re-pairing On the hosts list, tap the host card's `⋯` button (or long-press the card) and choose `Edit host`: - **Name** — display name on this phone only. - **Address** — IP, `host:port`, or `ws://` / `wss://`. A missing port keeps the current port, **or defaults to `6768`**. Address edits only change where this phone connects; they do **not** re-pair, and the pairing token stays the same. Saving an address change reconnects to the new endpoint. This is the documented fix for a desktop that moves between home LAN and Tailscale. ## Chat UI on mobile For chat-capable agents (Claude, Codex, and others Orca recognizes), a session can open in `Chat UI` instead of the raw terminal. - **Device default** — on first launch mobile asks how sessions should open on this phone; change it later under `Settings → Chat UI → Open sessions in Chat UI`. **The default is terminal until you choose Chat UI.** - **Per-session** — long-press a session tab and choose `Switch to chat view` or `Switch to terminal view`; that override sticks for the tab without changing the device default. - **Composer** — type a reply, `@` mention workspace files, use agent-aware `/` slash commands from the shared catalog (Claude vs Codex sets, with descriptions), attach a photo, or dictate. Attached images appear as removable thumbnails and ride along on send, including image-only and multi-image sends. - **Model and session options** — a pill row shows the current model and session options, including direct Codex model selection, without dropping into the raw terminal. - **Desktop still owns the agent** — Chat UI is a view over the paired desktop session, not a separate cloud agent. ## Terminal settings on the phone A dedicated `Terminal settings` screen (`Settings → Terminal`) exposes: - **Text size** — a 50%–200% baseline zoom the WebView applies on top of fit-to-width. Pinch-to-zoom snaps to the same presets and persists. Per-device; it does not change the desktop terminal. - **Autocomplete & autocorrect** — **off by default** so the OS never rewrites commands, flags, or paths in the command bar. The live keyboard-capture input streams raw keystrokes either way. ## Protocol versioning is a hard gate The phone and desktop speak a versioned mobile protocol. If either side is too old, mobile **blocks that host** and points you at the App Store (iOS) or GitHub Releases (Android APK or desktop), then back to hosts. After updating, refresh the connection; if the message persists, remove the host and pair again. The repo README explains why this exists: mobile updates lag desktop by 24–48h via the App Store, so both sides exchange version numbers on `status.get` "so a genuinely incompatible combo can hard-block instead of silently misbehaving." Constants live in `src/shared/protocol-version.ts` (`DESKTOP_PROTOCOL_VERSION`, `MIN_COMPATIBLE_MOBILE_VERSION`) and `mobile/src/transport/protocol-version.ts` (`MOBILE_PROTOCOL_VERSION`, `MIN_COMPATIBLE_DESKTOP_VERSION`). The README states that at the time it was written, "all four are set so `evaluateCompat` always returns `{ kind: 'ok' }` — nothing blocks. The wire format is in place to flip a switch when needed." Bumps are for breaking changes only — a removed RPC method or required parameter mobile uses, a changed meaning (units, nullability) of a field mobile reads, or changed encryption, framing, or auth handshake — and explicitly **not** for new RPC methods, new optional fields, or new event types in `terminal.subscribe`. ## Known limits and reported problems The docs' own troubleshooting list: - **Stuck spinner on a worktree** — the phone tracks a heartbeat from the desktop agent process; if the desktop says idle but the phone shows working, force-refresh the worktree row. - **Pairing fails** — desktop and phone must be signed into the same Orca account, and pairing codes expire after a few minutes. - **Authentication failed / pairing invalid** — the desktop no longer accepts this device token (for example after desktop cleared paired devices). Try `Retry` on the banner first, since transient rejections can recover without re-pairing; if it keeps failing, use `Re-pair` from desktop or `Remove` the host and pair again. - **Quick Commands unavailable** — update the paired desktop so it advertises the quick-commands capability. The same applies to the Quick Commands launcher, which is disabled when the paired desktop is too old. - **Can't reach desktop** — phone and desktop must share a network path (LAN, Tailscale, or the pairing path you used). Three community reports add detail the docs do not: - **Relay off-LAN failures.** Issue #10425 reports pairing through Orca Relay failing with "the relay can't be reached and it's falling back to local." A maintainer replied: "Turns out it's our server got overloaded. Too many users. We're rolling out a self-hosting version this week. Also trying to scale out our server." A later comment reports the same class of failure on iOS where same-Wi-Fi pairs and connects but cellular-only does not. Issue #16448 is a further cluster of the same shape, with a maintainer comment suggesting it may be the same Relay failure as #16238 (`relay director move was not strictly newer`) and one user reporting "direct LAN works but not relay." Both #10425 and #16448 are closed as completed upstream — a maintainer closed #16448 on 2026-09-05 with "This was resolved! Though you may need to re-auth". The separate relay-director issue #16238 referenced from that thread is the one that remained open. Re-authenticating is the documented first step if pairing fails on a current build. - **Windows firewall blocks LAN pairing.** Issue #8371 reports Android QR pairing timing out after ~25s with "Couldn't connect within 25s" and "WebSocket closed." The most detailed maintainer analysis concludes the socket never opened at all — retries closing every ~10 seconds match React Native Android's OkHttp 10-second TCP connect timeout — and names the likely cause as **Windows Defender Firewall dropping inbound TCP to Orca on port 6768**, noting that having no third-party antivirus does not disable Defender Firewall and that a Public network profile can block an allowance scoped to Private. The decisive test given is to open `http://:6768` in Chrome on the phone: a timeout confirms a firewall/routing/AP-isolation problem. The stated interim workaround is Tailscale on both machines with the `100.x.x.x` address selected in Orca's **Network Interface** menu, then regenerating the QR code. A maintainer opened a follow-up (#8439) for a Windows-only pairing-page improvement offering a UAC-gated Private-network firewall rule; **PR #8439 merged on 2026-07-13**, and the parent issue #8371 closed as completed on 2026-07-15 via merged PR #8846. The firewall diagnosis above remains the right first check, but the in-app affordance now exists. - **Do not share the QR.** A maintainer's request in that thread is worth repeating as a rule: don't share the QR code or full pairing code, since those contain credentials. ## Development notes The repo README documents the local dev topology: Orca desktop/Electron hosts the mobile WebSocket RPC server on port `6768`, and Expo Metro serves the React Native app on port `8081`. Pairing in dev goes through `Settings > Mobile`, and the mobile host endpoint is confirmed as `ws://:6768` — with `ws://10.0.2.2:6768` for the Android emulator. The QR encodes the connection endpoint, device token, and TLS fingerprint. A mock server is available on port 6768 with token `mock-device-token` for developing without a desktop instance. ## Related pages - [Remote Orca Servers](remote-servers.md) - [Ways to run Orca](ways-to-run.md) - [Notifications and inbox](notifications-and-inbox.md) - [Usage and rate limits](usage-and-rate-limits.md) - [Supported agents](../entities/supported-agents.md) ## Sources `raw/web_community-mobile-companion-orca-docs.md`, `raw/web_community-install-orca-mobile-on-android-orca-docs.md`, `raw/github_doc-mobile-readme-md.md`, `raw/web_community-remote-orca-servers-orca-docs.md`, `raw/github_issue-bug-mobile-qr-pairing-never-connects.md`, `raw/github_issue-bug-orca-relay-for-mobile.md`, `raw/github_issue-bug-mobile-connection-issue.md`. --- title: "Notifications and Inbox" type: concept tags: [notifications, agents-feed, status, hooks, triage] created: 2026-09-09 updated: 2026-09-09 sources: ["raw/web_community-notifications-inbox-orca-docs.md", "raw/web_community-agents-feed-orca-docs.md", "raw/web_community-agents-sessions-orca-docs.md", "raw/web_community-agent-hooks-memory-orca-docs.md", "raw/github_issue-bug-no-processing-indicators.md", "raw/web_community-settings-reference-orca-docs.md"] confidence: medium --- # Notifications and Inbox Orca's premise for notifications is that it runs **agents, not just terminals**, so it knows when an agent actually finishes versus when it's just paused. The docs put the use case plainly: queue three agents, walk away, come back when the first one is done. Three surfaces sit on top of the same signal — per-worktree notifications and the header bell, the cross-worktree **Agents** feed, and the optional Agent Dashboard. ## The underlying signal Agent state is detected from the terminal's **OSC title sequence** and **agent hooks**, which Claude Code, Codex, and several other agents emit. Agent tabs and worktree rows share a set of glyphs: - **Spinner** — working - **Amber question mark** — waiting on you (permission / needs input); sidebar "Needs You" counts use the same glyph - **Emerald check** (dashboard) or **emerald dot** (sidebar) — done / quiet active - **Red dot** — blocked, interrupted, or failed - **Gray dot** — idle - **No indicator** — plain shell, not a recognized agent CLI If status indicators are missing entirely, the docs' first answer is that the agent CLI in that session isn't one Orca recognizes: start it through the agent combobox rather than typing the binary by hand. `Settings → Agents → Agent status hooks` controls the Orca-managed hooks that report working / waiting / done into the UI. Turning the setting off removes those managed hooks and stops reinstalling them; turning it back on restores them **without restarting Orca** (on Windows, the WSL hook relay follows the same live gate). The CLI equivalents are `orca agent hooks status|on|off --json`. Hook endpoints are written to disk — `{userData}/agent-hooks/endpoint.env` on POSIX, `endpoint.cmd` on Windows — and re-sourced on every hook invocation, so long-lived agent sessions keep reaching the live Orca server even after an app restart. ## Agent-finished pings When an agent transitions from working to idle, Orca fires a notification: system notification, sound, and a chip on the worktree. Turn off specific categories (system, sound, chip-only) under `Settings → Notifications`. You can also pick a **custom desktop notification sound per category** — point at any audio file on disk or pick from Orca's built-in set. Supported formats are MP3, WAV, OGG, M4A, AAC, FLAC, and **one file applies to all delivered desktop notifications**. When you use a custom sound, set its playback volume from the same settings pane. The settings reference also lists notification categories for PR check failures and update-available. ## The persistent bell The header bell shows unread notifications across all worktrees. Clicking a notification jumps to the matching worktree and pane. On macOS the same unread count is mirrored as a badge on the Dock icon, so pending agent pings are visible without bringing Orca to the foreground. Right-click a notification to **mark unread** — useful when you've triaged something but want to come back to it later. ## The Agents feed The `Agents` entry in the sidebar opens a threaded feed of agent events across every worktree — completions, blocking questions, unread state, and worktree creation. It complements the per-worktree notifications view by giving one chronological surface to triage from. The entry is **on by default**. It shows an unread badge when new events have arrived since your last visit; clicking an entry jumps to the matching worktree and pane — the same handoff Orca does from a system notification. `Cmd+F` (macOS) or `Ctrl+F` (Windows/Linux) focuses the feed filter, except when the embedded terminal has focus, where the shortcut stays with the terminal. Each entry is one of: an agent finishing a turn (either idle or blocked on a question), a new worktree being created, or an agent that's been waiting on input long enough to surface as blocking. Entries carry a short preview of the agent's most recent response so you can skim without opening every thread, and threads are grouped by status with running agents pinned at the top. The feed does **not** replace the header bell or system notifications — those still fire on agent-finished pings. The docs describe the feed as the catch-up surface for when you've been away. ## The Agent Dashboard `Settings → Experimental → Agent Dashboard` adds a kanban of agents across worktrees, openable in-window beside the sidebar or as a pop-out. Columns are `Needs You` (waiting on a permission or question), `Working`, `Done`, and `Idle`. `Idle` covers quiet agents that have not reported completion for about 30 minutes and is **hidden by default** on the board; enable `Show idle agents` from the dashboard **board settings** control (gear) on the in-window or pop-out surface — not from global Experimental settings. In-window and pop-out stay in sync. `Toggle Agent Dashboard` has **no default binding** and can be assigned under `Settings → Shortcuts`; it works while a terminal, editor, or browser tab has focus. Cards show a host badge for SSH workspaces and paired Remote Orca Servers — for example `SSH host · openclaw` or `Remote Orca host · Build Mac`. Local workspaces show no host badge. `Needs You` cards tint amber and can show the pending question summary; `Done` cards tint green; other states stay neutral so tint means "look here." Clicking a card opens or focuses that agent's live terminal. Workspace status stays in the toolbar filter only — cards no longer show a per-worktree status dot. Worktree cards still inline agent rows with the same glyphs when the experimental board is off. ## Reported rough edge: the missing "thinking" indicator Issue #9040 reports that on version 1.4.141 the left-hand nav stopped showing a working indicator while the model was thinking — "It does, however, show the orange bell when it's done, just no thinking indicator" — which the reporter called "pretty fundamental if you run more than just a couple of agents." A detailed comment marked **"Status: PARTIAL — derivation-level root cause proven with a passing unit test"** attributes it to the shared agent-status normalizer keeping a lead payload at `state: 'done'` even when it still carries a live *working subagent*, so the sidebar dot resolves to done (bell) rather than working (spinner). Done-gating existed only for Claude at the time, so generic/relay/custom producers reporting lead completion while a child kept working landed as `done`. Upstream closed #9040 as completed on 2026-07-27. Note that PR #9048, which the thread describes as the fix in progress, was **closed without merging** on 2026-08-05 — the behavior was resolved through other work, so do not go looking for #9048 in a changelog. The derivation-level diagnosis above still explains the mechanism. **Analysis:** the failure mode generalizes beyond that one bug. Because notification state is *derived* from per-pane agent status, anything that reports a lead as finished while children keep working will under-report activity — which is exactly the situation [orchestration](orchestration.md) and subagent-capable agents create. When the stakes are high, the orchestration verdicts (`live` / `unverifiable` / `exited`) are the authoritative source, not a sidebar dot. ## Related pages - [Orchestration](orchestration.md) - [Worktree checkpoints](worktree-checkpoints.md) - [Mobile companion](mobile-companion.md) — push notifications mirror desktop - [Supported agents](../entities/supported-agents.md) - [Settings reference](../entities/settings-reference.md) ## Sources `raw/web_community-notifications-inbox-orca-docs.md`, `raw/web_community-agents-feed-orca-docs.md`, `raw/web_community-agents-sessions-orca-docs.md`, `raw/web_community-agent-hooks-memory-orca-docs.md`, `raw/github_issue-bug-no-processing-indicators.md`, `raw/web_community-settings-reference-orca-docs.md`. --- title: "Orca CLI" type: concept tags: [cli, automation, agents, scripting, setup] created: 2026-09-09 updated: 2026-09-09 sources: ["raw/web_community-orca-cli-overview-orca-docs.md", "raw/web_community-orca-cli-reference-orca-docs.md", "raw/github_doc-skill-guides-orca-cli-md.md", "raw/web_community-install-orca-docs.md", "raw/web_community-troubleshooting-faq-orca-docs.md", "raw/web_community-remote-orca-servers-orca-docs.md", "raw/web_community-orca-skills-registry-mcp-orca-docs.md", "raw/web_community-settings-reference-orca-docs.md"] confidence: medium --- # Orca CLI The Orca CLI is the `orca` command-line interface for scripting a running Orca editor from any shell. It talks to a running Orca runtime — use it when a shell script or agent needs to inspect worktrees, launch terminals, open files, automate the built-in browser, or report progress back into Orca. This page covers what it is, how to install and verify it, and how it addresses hosts; the complete command surface lives on [Orca CLI reference](../entities/orca-cli-reference.md). The skill guide states the boundary plainly: use `orca` when Orca's running editor/runtime is the source of truth, and plain shell tools when Orca state does not matter. ## Install and register The CLI ships with the desktop app. The docs give two different registration locations, and the discrepancy is worth knowing before you go hunting: - The **CLI overview** says: "It ships with the desktop app; register it under `Settings → General → Orca CLI`." The settings reference agrees, listing `Orca CLI` under the **General** pane as "register the bundled command-line tool for shells and agents." - The **CLI reference** page says: "Register the CLI under `Settings -> Experimental -> CLI`." Verify the registration worked: ``` command -v orca orca status --json ``` If Orca is not already running, the reference suggests: ``` orca open --json orca status --json ``` If the shell reports "command not found," the troubleshooting page says to register the CLI under `Settings → General → Orca CLI`; on macOS it installs a shim into `~/.local/bin`, so make sure that directory is on your shell's `PATH`. ### Executable name is not always `orca` Three variants appear in the sources and matter for scripts: - On Linux the CLI is named `orca-ide` so it does not conflict with the GNOME Orca screen reader. - In dev builds (`pnpm dev`), after `pnpm build:cli` the dev CLI is `orca-dev`, and `./config/scripts/orca-dev.mjs` invokes it worktree-locally without depending on the `/usr/local/bin` symlink. Plain `orca` targets any installed production Orca. - The hybrid skill stubs tell agents to resolve the executable for the session in this order: `ORCA_CLI_COMMAND`, `orca-dev`, Linux `orca-ide`, else `orca`. The skill guides use `ORCA` as a placeholder for whatever the agent resolved, and instruct agents to substitute it rather than create a shell variable — and to use the same executable for a whole run. ## What it is for The overview lists the surface: create and inspect worktrees, drive agent terminals, open files and diffs, automate the built-in browser, run scheduled automations, share HTML/Markdown artifacts, and control Orca-native tools from scripts or AI agents. The reference groups the same ground as runtime, repos, worktrees, terminals, files, built-in browser, desktop computer use, mobile emulator, Linear, skills, account, artifacts, and automations/environments/hooks. Three of those areas have their own pages here: [Orchestration](orchestration.md) for tracked multi-agent work, [Scheduled automations](scheduled-automations.md), and [Computer use](computer-use.md). ## Authentication and accounts There are two distinct "auth" surfaces, and confusing them is easy: - **Agent provider accounts.** On a host running Orca (`orca serve` or the desktop app), `orca account add` registers managed Claude/Codex accounts when the remote client cannot use `Add account` — remote runtime scope disables that button. `account add` runs `claude login` / `codex login` in *this* terminal on the host, then registers the captured credentials with the local runtime. Codex uses device authorization so the browser can finish on another machine. The reference is explicit: run these on the machine that owns the accounts, not through a client-only remote session. See [Usage and rate limits](usage-and-rate-limits.md). - **The Orca account.** Artifact publishing goes through the signed-in Orca account (`Settings → Artifacts → Orca account`, described as the same account family as Orca Relay). Viewing a public artifact link does not require sign-in; create/list/update/delete do. Publishing is **off by default** — a human must enable `Settings → Artifacts → Allow publishing public artifact links` on the device, and there is no CLI flag that grants the gate. A denied publish or update fails with `artifact_sharing_disabled`; the skill guide says not to retry, because the answer will not change until a human acts. `list`, `unshare`, and `delete` stay available so old links remain auditable and revocable. ## Selectors and hosts Most commands accept selectors instead of long IDs. `active` and `current` resolve to the enclosing Orca-managed worktree from the shell's current directory or terminal context, so the reference advises explicit selectors in scripts that may run outside the target worktree. A worktree id is a **two-part address**, `::` — for example `repo-123::/Users/me/orca/fix-login`. The skill guide is emphatic that `repo-123` alone names only the repo, and that the whole `id` field from `worktree create --json` or `worktree list --json` must be copied forward. For remote runtimes the reference prefers full server-side selectors such as `id:::` or `path:`, because the local shell's current directory may not exist on the runtime host. To target a machine: ``` orca host list --json ``` The result includes this machine, its registered SSH targets, and paired Remote Orca Servers. Use `--host local` for this machine, `--host ssh:` for an SSH target, and `--environment ` for a paired server. SSH labels and paired-server names also resolve when they are unique; use the IDs from `host list` when names collide. If a machine name is put on the wrong selector, Orca reports the matching machine and the flag to use instead of returning an empty result. ## Agent habits the docs recommend - Prefer `--json` for automation and agent calls; human-readable output is for quick terminal checks. - Prefer selectors over parsing UI labels. - Read terminal state before sending input unless the next input is obvious. - Use worktree comments for progress checkpoints — see [Worktree checkpoints](worktree-checkpoints.md). - Use [Orchestration](orchestration.md) for tracked multi-agent dispatches instead of ad hoc terminal prompts. - If the CLI is missing, the skill guide says to state that explicitly rather than inspecting source files first. The skill packages also carry a "do not guess" rule: if an older CLI rejects a newer flag, fall back to `ORCA --help` and keep the documented rules rather than inventing arguments. Command flags live in the binary, so `orca skills get orca-cli` returns the guide matched to the installed version. ## Installing the matching agent skill ``` npx skills add https://github.com/stablyai/orca --skill orca-cli orca skills install --skill orca-cli ``` The second form is the headless path (no Settings UI) and does not contact the Orca runtime. See [Skills and MCP](skills-and-mcp.md). ## Interaction with remote execution On an SSH host, `orca` is a shim that proxies back to the *client's* runtime — see [SSH worktrees](ssh-worktrees.md). When the client disconnects, `orca …` on that host fails with `No owning Orca client is connected to the relay`, even though the PTY it was managing stays live. On a paired Remote Orca Server the control plane is host-local instead. ## Related pages - [Orca CLI reference](../entities/orca-cli-reference.md) — every command and flag - [Orchestration](orchestration.md) - [Scheduled automations](scheduled-automations.md) - [Computer use](computer-use.md) - [Skills and MCP](skills-and-mcp.md) - [Worktree checkpoints](worktree-checkpoints.md) ## Sources `raw/web_community-orca-cli-overview-orca-docs.md`, `raw/web_community-orca-cli-reference-orca-docs.md`, `raw/github_doc-skill-guides-orca-cli-md.md`, `raw/web_community-install-orca-docs.md`, `raw/web_community-troubleshooting-faq-orca-docs.md`, `raw/web_community-remote-orca-servers-orca-docs.md`, `raw/web_community-orca-skills-registry-mcp-orca-docs.md`, `raw/web_community-settings-reference-orca-docs.md`. --- title: "Orchestration" type: concept tags: [orchestration, multi-agent, cli, workers, coordination] created: 2026-09-09 updated: 2026-09-09 sources: ["raw/web_community-orchestration-orca-docs.md", "raw/github_doc-skill-guides-orchestration-md.md", "raw/github_doc-skill-guides-orca-cli-md.md", "raw/github_doc-docs-reference-ssh-execution-boundary-md.md", "raw/github_issue-bug-strange-behavior-i-think-when-using-orchestrator-and-sub.md"] confidence: medium --- # Orchestration Orchestration is Orca's structured multi-agent layer, driven entirely from the `orca orchestration` CLI surface: a **Run** (namespace plus coordinator inbox), **Tasks**, **Dispatches**, supervised **workers**, messages, and decision gates. Use it when you need ownership, completion tracking, or a DAG. For one-off prompts the docs say to use `orca terminal send`; for full ownership handoffs without supervision, use worktree/terminal commands from the `orca-cli` skill. ## The core model - **Run** — durable namespace and home inbox. Never schedules or places workers. - **Task** — a work item with a spec, dependencies, and status: `pending`, `ready`, `dispatched`, `completed`, `failed`, or `blocked`. - **Dispatch** — one attempt of a task on a terminal; lifecycle authority for `worker_done` / heartbeat. - **Message** — inbox mail (`status`, `dispatch`, `worker_done`, `escalation`, `question`, `heartbeat`, …). - **Decision gate** — a coordinator-owned question that blocks a task until it is resolved. Completion authority comes from the active dispatch context, so worker completion and heartbeat messages should include both `taskId` and `dispatchId`. The skill guide restates this as a safety floor: lifecycle authority comes from the active Dispatch, not a terminal title, copied ID, old database row, provider transcript, or visible pane. Task IDs printed in terminals, such as `task_...`, are clickable links; clicking one asks the Orca runtime for the task's current dispatch and focuses the assigned terminal, including when the task lives in a remote or SSH runtime. ## Classifying the role first The skill guide's first instruction is to decide which role you are in, because the wrong one produces the wrong commands: | Current context | Role | Route | |---|---|---| | User explicitly asks to supervise, monitor, wait for results, track completion, coordinate a DAG, use a decision gate, or manage ask/reply | Coordinator | Use the supervised loop | | Prompt contains a live injected preamble with Task and Dispatch IDs | Dispatched worker | Follow the preamble and worker obligations | | User asks to hand off ownership or start another agent/worktree without supervision | Handoff owner | Use `orca-cli`; create no Run, Task, or Dispatch and do not monitor completion | | A message carries a legacy authority label | Compatibility operator | Load the legacy contract reference before any lifecycle mutation | | No live preamble and no explicit supervision | Ordinary terminal agent | Do not emit lifecycle messages | Model or effort selection does not make a handoff supervised. The `orca-cli` guide adds the mirror-image rule: `orca orchestration task-create`, `orca orchestration dispatch --inject`, and `orca orchestration check --wait` are *forbidden* for full handoffs, because `task-create` records coordinator-owned tracking state — if a task row is needed, the request was actually for supervised orchestration. ## The supervised loop The docs' preferred loop creates a Run, creates work, starts workers, and then waits: ``` 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 --worktree current --agent codex --json orca orchestration worker-start --task --worktree new-child --name billing-audit --agent codex --setup run --json orca orchestration check --wait --types worker_done,escalation,question --timeout-ms 900000 --json orca orchestration check --ack --wait --types worker_done,escalation,question --timeout-ms 900000 --json ``` The skill guide notes that `worker-start --spec` creates the Task and its attempt in one call, and that `task-create` plus `worker-start --task ` is for planned fan-out with dependencies or a retry of a known Task. It advises using dependencies only for real ordering and preferring parallel waves over chains deeper than three or four steps; nested workers obey a depth limit, and a new Run does not reset the caller's depth. `worker-start` is the normal path, composing placement, terminal readiness, prompt injection, and supervised resource ownership. `dispatch --inject` leaves an operator-created process unsupervised and is described as only for an expressiveness gap. ### Per-worker model and effort ``` orca orchestration worker-start --task --worktree current --agent claude --model --effort high --json ``` `--model` accepts opaque provider model IDs for **Claude, Codex, and Cursor only**. `--effort` requires `--model` and only applies when that agent/model supports the level. Neither flag can combine with `--terminal` (reuse an existing pane). Overrides apply to that launch only and show under `launch.requested` / `launch.effective` in the start receipt. Federated starts need a worker host that advertises launch-preference support. ## Worker obligations Dispatched workers receive a preamble that tells them how to communicate. The docs and skill guide agree on the contract: - Send `worker_done` **exactly once**, from the dispatched terminal, even on failure, with explicit `--outcome succeeded` or `--outcome failed`. Never encode failure only in prose. - Include both task and dispatch IDs so stale retries cannot complete the wrong dispatch. - Include a short `--body` summary: what was done, what was found, what remains (the skill guide asks for a three-sentence executive summary). - Send `heartbeat` messages during long active work, only at the cadence in the preamble. A heartbeat proves liveness, not completion. - Use `orca orchestration ask` for blocking questions instead of local TUI prompts — never open a local question TUI the coordinator cannot answer. - Read coordinator follow-ups at natural checkpoints and once more immediately before `worker_done`, with `orca orchestration check --terminal --json`. - Append `--files-modified` and `--report-path` only with real values when applicable. After `worker_done`, end the turn and idle; do not poll or start new work. A direct user instruction after completion starts new user-owned work and takes precedence over the idle rule. A completion message looks like: ``` orca orchestration send --type worker_done --subject "Completed mobile audit" --body "Fixed footer overlap; no follow-ups." --task-id --dispatch-id --outcome succeeded --files-modified "src/app/settings/Billing.tsx" --json ``` A blocking question: ``` orca orchestration ask --to --question "Should I update the shared component or only this page?" --options "shared,page-only" --timeout-ms 600000 --json ``` With `--json`, `ask` prints a single JSON object so workers can pipe it to `jq -r .answer`. ## Messaging, inboxes, and gates Default `check` returns the bound Run's oldest unacked Delivery (FIFO) and replays that batch until `--ack`. `--peek` / `--all` do not consume mail. A consuming `check` names its caller with `--terminal `, never `--from`, and omits it inside the coordinator's own Orca terminal. Group addresses are `@all`, `@idle`, `@claude`, `@codex`, `@opencode`, `@gemini`, `@droid`, `@grok`, `@cursor`, `@worktree:` — **never for `worker_done` / heartbeat**. PowerShell users must quote them: `--to "@all"`. While a wait is active, the CLI emits small JSON heartbeat lines to stderr every 15 seconds; stdout remains the final command result. Decision gates are for when the coordinator has created a task DAG and wants to block a task until a decision is recorded: ``` orca orchestration gate-create --task --question "Merge the shared button change into the task branch?" --options '["yes","no"]' --json orca orchestration gate-resolve --id --resolution "yes" --json ``` ## Settling workers: reuse, retain, or release After an accepted success or failure report, the skill guide requires exactly one of three actions immediately: reuse the same proven agent terminal for a follow-up Dispatch, record user-requested retention with `worker-retain`, or run `worker-release`. `worker-release` archives inspectable output, then closes only that coordinator-owned agent terminal. Release is post-settlement cleanup, not cancellation — only an accepted settlement authorizes it. The docs warn: do not leave completed worker terminals open just to re-read output (use `worker-read` after `worker-release`), and do not substitute a broad `terminal close` when release returns `release_pending` or `release_unknown` — follow the receipt's recovery action. A valid `worker_done` settles the Task and Dispatch automatically, so it should not be followed by `task-update --status completed`. Enumerate terminals still owing a decision with `worker-list --run --terminal-state reclaimable --json` and do not end the coordinator turn until it returns none. Retry placement is explicit — `--retry-of` does not inherit `--on` or the worktree: ``` orca orchestration worker-start --task --retry-of --worktree current --agent codex --json ``` ## Liveness, and why absence is not proof This is the sharpest rule in the whole surface, and it comes from the same execution-boundary reference that governs SSH: preserve the verdicts `live` / `unverifiable` / `exited`, and treat contact loss as *not* process death. The skill guide layers it: - `worker-list`'s `projection.liveness` is the fleet verdict for the agent. - `worker-show`'s `observation.status` is PTY liveness only. A live terminal can still hold a dead or stuck agent. - `unverifiable` is absence, including when `worker-show` reports `agentWait` null. **Absence never authorizes stop, abandon, retry, or release** — keep waiting or inspect. A timeout or empty result is a checkpoint, not a failure. After three consecutive empty waits, the guide says to stop waiting blindly and enumerate with `orca orchestration worker-list --include-remote --json`, acting on each row's `projection.attention` categories, `projection.attention.requiresAction`, and the literal `projection.nextAction` argv. A `none` `nextAction` has no argv to run: read `liveness.reason` and keep waiting with `check --wait`. Only positive proof the agent stopped — `exited` liveness, the worker's own observation of process exit, or a transcript whose final agent turn sent no `worker_done` — justifies leaving the wait and choosing `worker-stop` or `worker-abandon` explicitly. Also worth noting: a successful `orchestration send` proves durable enqueue; its wake or nudge is best-effort attention only and does not prove the recipient read or accepted it. ## Task-spec contract Every Task spec must be self-contained and name its **Target** (files, component, or environment in scope), **Change** (the concrete result), **Constraints** (invariants, compatibility rules, do-not-touch boundaries), **Ownership** (what this worker may edit and any coordination boundary), and **Observable acceptance** (the test, output, or evidence that proves completion). ## Reset and recovery ``` orca orchestration dispatch-show --task --json orca orchestration dispatch-show --task --preamble --json orca orchestration task-list --json orca orchestration task-update --id --status blocked --result '{"reason":"waiting on credentials"}' --json orca orchestration reset --tasks --json orca orchestration reset --messages --json orca orchestration reset --all --json ``` `reset` affects runtime-global orchestration state; the docs say not to run it while another coordinator is active unless that is the intended cleanup. The retired `orchestration run` command is not an alias for Run creation. ## Where orchestration state lives The execution-boundary reference states that orchestration state — Runs, Tasks, Dispatches, mailboxes — is **client-resident**. On an SSH host that means an agent should not depend on `orca` for anything it must finish while the client is away, because every `orca …` command there fails once the client disconnects. See [SSH worktrees](ssh-worktrees.md) and [Remote Orca Servers](remote-servers.md) for the two different boundaries. ## Known rough edge: the prompt that needs a manual Enter Issue #14347 reports that launching a sub-agent from Codex's `/orchestration` command opens the agent and displays the prompt but does not execute it until a human presses Enter, "sometimes it does run on its own, but that's very rare." Maintainer comments mark it a duplicate of #13821, describing the same `input_accepted` ≠ submitted failure and noting `worker-start --agent` leaving the injected prompt sitting in the TUI. A later comment says "I've made some improvements to our prompt submission reliability, it will be released within 48h," so this may be addressed in builds after that comment; upstream closed #14347 and its duplicate #13821 as completed on 2026-08-14, alongside merged PR #14575 (`fix(orchestration): wait for Codex composer render`). The documented defence is in the CLI contract itself: `accepted: true` proves input acceptance, not a started turn. A text-plus-Enter agent prompt returns a durable request ID and additive stages `input_accepted`, then `turn_started` once the agent's turn is proven. A default send observes for 0 seconds, so a receipt that stops at `input_accepted` is expected and its warning means "unproven", not "failed". Pass `--wait-submit ` when you need proof of submission; a timeout returns queued/input-accepted truth without resending, and after an ambiguous transport failure you repeat the exact command with the reported `--retry-request `. Never resend on silence. ## Related pages - [Orca CLI](orca-cli.md) - [Orca CLI reference](../entities/orca-cli-reference.md) - [Worktree checkpoints](worktree-checkpoints.md) - [Skills and MCP](skills-and-mcp.md) - [Supported agents](../entities/supported-agents.md) ## Sources `raw/web_community-orchestration-orca-docs.md`, `raw/github_doc-skill-guides-orchestration-md.md`, `raw/github_doc-skill-guides-orca-cli-md.md`, `raw/github_doc-docs-reference-ssh-execution-boundary-md.md`, `raw/github_issue-bug-strange-behavior-i-think-when-using-orchestrator-and-sub.md`. --- title: "Remote Orca Servers" type: concept tags: [remote, orcad, pairing, headless, tailscale] created: 2026-09-09 updated: 2026-09-09 sources: ["raw/web_community-remote-orca-servers-orca-docs.md", "raw/github_doc-docs-reference-orcad-operations-md.md", "raw/github_doc-docs-reference-remote-wire-compatibility-md.md", "raw/github_doc-docs-reference-headless-linux-server-md.md", "raw/github_issue-feature-how-to-use-agent-of-remote-linux-server.md", "raw/github_issue-bug-orca-remote-server-memory-usage-and-cpu-usage-are-too-hi.md", "raw/github_issue-bug-remote-environment-disconnection-floods-the-ui-with-repe.md"] confidence: medium --- # Remote Orca Servers A Remote Orca Server lets one computer do the work while another computer provides the UI. The server keeps the projects, worktrees, terminals, tabs, provider accounts, and agent sessions; your laptop connects to that running Orca instance. This is the opposite ownership model from [SSH worktrees](ssh-worktrees.md), where your laptop's Orca stays the runtime owner. ## What has to live on the server Install and authenticate Codex, Claude Code, OpenCode, `git`, and any provider CLIs on the **server computer**. A login on your laptop does not automatically carry over. Remote sessions use the server's `PATH`, home directory, and credentials — not the client's. On a headless `orca serve` host, register managed Claude/Codex accounts from the server shell, because the remote client disables `Add account`: ``` orca account add --agent claude orca account add --agent codex orca account list ``` Agent skills can be installed or refreshed without a Settings UI: ``` orca skills install --skill orca-cli --skill orchestration orca skills update --all ``` ## Recommended path: desktop app plus Tailscale The docs call the easiest setup the Orca desktop app on both computers connected through Tailscale, and state you do not need `orca serve` for this path. Requirements: Orca installed and updated on both computers, Tailscale installed on both, both signed in to the same tailnet, and the server computer awake, online, and running Orca. Tailscale gives the server a private address that usually starts with `100.`, and Orca puts that address first in its connection-address picker. **On the server:** `Settings → Remote Orca Servers` → under `Advertise this app as a server`, click `New Link` → for `Connection address` select the Tailscale address (usually `100.x.y.z`) → `Generate Access Link` → copy the link under `Pair another Orca client`. If the Tailscale address is missing, confirm Tailscale is connected and use the refresh button beside `Connection address`. **On the client:** `Settings → Remote Orca Servers` → `Add Server` → enter a recognizable name → paste the access link → `Add Server`. If the saved server shows `Disconnected`, click `Connect`. Adding a server saves it without forcing every new project onto it. Open `Advanced → Active Server` only when you want server-routed projects, terminals, provider checks, and browser or mobile handoff to use that server by default. Once connected, terminals, agent processes, files, worktrees, and session state live on the server computer. The documented consequences: agents keep running when the client laptop sleeps or disconnects; the server needs the repository, tools, and credentials those agents use; the server must stay awake and connected to the tailnet; reconnecting returns you to the server-owned workspace, tab, and visible-pane state without duplicating paired tabs; and projects you delete on the server disappear from every paired client's sidebar. When several paired clients share a server, the sidebar filter can offer `Hide other-client workspaces`. ## Access and security Orca creates a separate, revocable token for each paired client, listed on the server under `Shared Server Access`. Clicking the trash button beside a grant revokes it and disconnects active clients using it immediately. Generating another link replaces the previous **unused** link; clients that already paired keep their own grants until you revoke them. Two hard warnings from the docs: do not forward the Orca port directly to the public internet — prefer Tailscale, WireGuard, a trusted LAN, SSH forwarding, or an authenticated tunnel; and do not select `127.0.0.1` for another computer, because that address only works on the server itself. Keep Tailscale ACLs or grants as narrow as your setup allows. ## `orca serve` Use `orca serve` when the host should run without the desktop window — a headless Linux server or a service-managed VM. For a MacBook or desktop you can leave signed in, the in-app setup is described as simpler. ``` orca serve --pairing-address 100.64.1.20 orca serve --port 6768 --pairing-address 100.64.1.20 orca serve --pairing-address 100.64.1.20 --mobile-pairing ``` The command starts the Orca runtime without opening the desktop window, runs in the foreground until you press `Ctrl-C`, prints the bound endpoint and a runtime pairing URL, and uses `--pairing-address` only for the address clients should dial. Add `--port 6768` when a firewall, tunnel, or service definition requires a fixed port. Paste the printed pairing URL into `Settings → Remote Orca Servers → Add Server` on the client. `--mobile-pairing` requests a mobile-scoped QR code and link — keep the phone on the same tailnet, open Orca Mobile, choose `Pair`, and scan or paste (see [Mobile companion](mobile-companion.md)). Use only one host mode at a time: if the Orca desktop app is already sharing that computer, do not start a second `orca serve` process for the same setup. If `orca serve` advertises the wrong address, stop it and restart with an address the client can reach. Do not use a wildcard address or `127.0.0.1` for a remote client. | | Desktop app on the server | `orca serve` | |---|---|---| | Best for | An old laptop, Mac mini, or desktop | A headless Linux box, VM, or managed service | | Setup | Settings and buttons | Terminal command and service configuration | | Server window | Open | None | | Access link | New Link → Generate Access Link | Printed in the terminal | | Lifetime | While the desktop app is running | While the foreground process or service is running | ### Headless Linux specifics The repo's headless-Linux reference adds detail the docs site does not. Current Orca builds start Xvfb automatically for `orca serve` when no `DISPLAY` is set, **but Xvfb must be installed first**; a separate D-Bus session is not required. When `DISPLAY` is set, Orca uses that display instead of starting a competing Xvfb, provided the socket exists and any X lock file names a running process — a `DISPLAY` whose lock names a dead process is refused and `orca serve` exits, so unset `DISPLAY` to let Orca start its own Xvfb. The supported matrix covers Ubuntu 20.04, 22.04, 24.04 and current Debian stable, i.e. glibc 2.31 or newer. `--pairing-address` is only the address advertised to clients; it does not change the listener bind address. It accepts a reachable LAN/Tailscale hostname or IP, or a complete reverse-proxy URL such as `https://orca.example.com/runtime` (`http(s)` is normalized to `ws(s)`). Wildcard addresses such as `*`, `0.0.0.0`, and `::` cannot be advertised. For supervisors, `--json` produces one compact ready line with `"type": "orca_server_ready"`, `boundEndpoint`, `advertisedEndpoint`, and a `pairing` object. When the server is usable but cannot mint an offer, `pairing` stays an object with `available:false`, a stable `reason`, and operator `guidance` — it is never silently omitted. Stable reasons are `disabled_by_operator`, `websocket_unavailable`, `device_registry_unavailable`, `e2ee_key_unavailable`, and `invalid_advertised_endpoint`. Issue #5899 records a community setup of exactly this shape, and one commenter's caveat is worth reading against the newer reference above: at the time of writing they said `orca serve` still inherited Electron's display dependency and needed `xvfb-run orca serve …` on a box with no X server. Another commenter reported running the Debian package with `export DISPLAY=:99`, `LIBGL_ALWAYS_SOFTWARE=1`, `ELECTRON_DISABLE_GPU=1`, then `orca-ide serve --pairing-address `. **Analysis:** the reference doc's automatic-Xvfb behaviour supersedes the manual `xvfb-run` workaround for current builds, but the `LIBGL_ALWAYS_SOFTWARE=1` environment variable still appears in the reference's own foreground and systemd examples. ## `orcad` operations `orcad` is the Orca runtime served from plain Node, and the repo reference is explicit that a deployment is **two long-lived processes**, not one: | | orcad | terminal daemon | |---|---|---| | Started by | the supervisor | orcad, detached | | Owns | RPC, git, worktrees, persistence | every local PTY | | Lifetime | one supervised run | detached from orcad, not its service | | Endpoint | `ws://:` | `/daemon/daemon-v.sock` | Because orcad detaches the daemon and calls `disconnectDaemon()` rather than `shutdownDaemon()`, a PID-scoped update, rollback, or restart is non-destructive to live work. **Process detachment is not service isolation**, though: a daemon forked by orcad and every PTY it owns remain in the same systemd service cgroup, and `KillMode=mixed` does *not* preserve them — it signals only the main process, then `SIGKILL`s everything remaining in the cgroup at the stop timeout. `KillMode=control-group` is destructive too, and `KillMode=process` is not a supported preservation mechanism. **Bind policy.** `--bind `, default `127.0.0.1`. Only literal IPs are accepted; hostnames are refused because DNS would decide which interface got bound. `localhost` maps to `127.0.0.1`; `0.0.0.0` / `::` are the explicit opt-ins to network reach, and the startup log says so on every launch. The bind is pinned, not defaulted — a mobile pairing offer that would normally rebind to all interfaces is refused while the bind is pinned to loopback, reporting `network_exposure_failed`. **Data root and lock.** The data root is `$ORCA_USER_DATA`, else `$XDG_DATA_HOME/Orca`, else `~/.orca`. Before touching the profile index or store, orcad takes `/orcad.lock` and refuses to start with one of `orcad_data_root_wrong_owner`, `orcad_data_root_shared`, `orcad_instance_lock_held`, `orcad_instance_lock_foreign_identity`, or `orcad_data_root_unusable`. A root that is merely too permissive and that Orca owns is tightened to `0700` rather than refused; Windows is exempt from the owner and mode checks. **Supervision contract.** Readiness is one JSON line on stdout (`--json`) with `type: "orca_server_ready"`, published after the listener is bound and the daemon verdict is in — there is no separate readiness socket, and the start timeout should be generous because a cold daemon launch can take tens of seconds. `SIGTERM` or `SIGINT` starts a graceful stop; a second signal exits immediately with code 1. Exit codes: `0` clean shutdown (restart per policy), `1` startup or shutdown failure (restart with backoff), `78` configuration fault — bind address, data root, instance lock — which the supervisor should **not** restart (put it in systemd's `RestartPreventExitStatus`). Diagnostics go to stderr; the detached daemon writes NDJSON to `/logs/daemon.log`, suppressed by `ORCA_DIAGNOSTICS_DISABLED=1`, and that file's rotation is not implemented. **Daemon supervision.** A daemon already answering the endpoint is adopted, not replaced, unless it is unhealthy, foreign, or built from a superseded bundle *and* owns no live sessions — code freshness always defers to live work. Crash-loop containment allows at most **5 launches per 60s rolling window** per orcad run, after which launches are refused with `daemon_crash_loop`; the window slides, and an operator-initiated daemon restart clears it. **Before a cgroup-wide stop**, the reference requires a census: obtain a fresh `orca-ide terminal list --json` using the same OS account and home as the daemon, invoking the installer's absolute launcher path so `sudo`'s `secure_path` cannot hide a per-user registration — for example `sudo -Hu orca /home/orca/.local/bin/orca-ide terminal list --json`. A safe empty census is untruncated, has an explicit `hostScope`, covers every affected execution host, and lists no terminals on them. Anything ambiguous makes the result `unverifiable`: defer the stop. Orca does not yet provide an atomic census-and-stop fence. **Health.** The readiness payload carries a `health` object including `buildHash`, `buildVersion`, `nodeVersion` / `nodeAbi`, and a `terminalDaemon` block whose `state` is `live | degraded | absent`. `state` is `live` only when the self-test passed **and** `ownsFreshSessions` is true. `coverage: 'pty-spawn'` is the full round trip; `coverage: 'handshake'` is **win32 only**, where the spawn probe returns without spawning anything. Explicitly **not** covered, per the reference: a continuous health endpoint, systemd-isolated daemon supervision, a libc health slot, a published `degradations[]` collection, credential administration, pinned-port fail-closed behaviour (a pinned `--port` still falls back to an OS-assigned port on conflict), reconciling `webClientUrl` with reachability under the loopback default, state-schema rollback rules, and daemon log rotation. ## Mixed versions are the normal state The remote-wire reference opens by saying users update client and host independently, so **mixed versions are the normal state, not an edge case**. Three rules govern changes: 1. A new optional JSON field on an existing frame is safe — decoders ignore unknown keys — but only for as long as every reader treats it as optional. 2. A new stream opcode is **not** safe and must be negotiated. An unknown opcode returns `null` from the decoder and the frame is dropped without an error, so the feature behind it appears to hang. The shipped pattern is `SetOutputPaused` (opcode 16): the client advertises support in the `Subscribe` frame's `capabilities`, the host echoes `capabilities: { outputPause: 1 }` on the `subscribed` event, and each side acts only after that echo. Opcode numbers are permanent. 3. Changing *what the host publishes* breaks old clients with no wire change at all — a field the host stops populating, a value whose meaning or nullability changes, or a frame it starts or stops sending on an existing path. Practically, the docs' troubleshooting advice matches: update Orca on both computers if the server row reports an incompatible protocol version, and in the automations UI connected hosts that need a newer Orca server stay visible but disabled with an `Update server` message. ## Reported rough edges - **Resource usage.** Issue #6288 reports high memory and CPU on a remote server with only three projects, plus a suspected memory leak on another machine. A maintainer's reply attributes much of it to concurrent agents ("sometimes a single agent might take 200 - 800MB") and points at the Resource Manager and the agent sleep feature, which is said not to lose session history or status. Upstream closed #6288 as completed on 2026-06-28. A 2026-07-28 follow-up split the remaining behavior into two narrower issues — #6667 (CPU thrash) and #6564 (preload listener leak) — so a current-build report of this shape belongs on one of those rather than the original. - **Disconnect noise.** The reporter on issue #11392 said the remote Orca server experience felt like it had been gradually getting worse and that they had moved to plain SSH because of typing lag and frequent disconnections — see [SSH worktrees](ssh-worktrees.md) for the same thread's detail. ## Related pages - [Ways to run Orca](ways-to-run.md) - [SSH worktrees](ssh-worktrees.md) - [Mobile companion](mobile-companion.md) - [Orca CLI](orca-cli.md) - [Orca CLI reference](../entities/orca-cli-reference.md) ## Sources `raw/web_community-remote-orca-servers-orca-docs.md`, `raw/github_doc-docs-reference-orcad-operations-md.md`, `raw/github_doc-docs-reference-remote-wire-compatibility-md.md`, `raw/github_doc-docs-reference-headless-linux-server-md.md`, `raw/github_issue-feature-how-to-use-agent-of-remote-linux-server.md`, `raw/github_issue-bug-orca-remote-server-memory-usage-and-cpu-usage-are-too-hi.md`, `raw/github_issue-bug-remote-environment-disconnection-floods-the-ui-with-repe.md`. --- title: "Scheduled Automations" type: concept tags: [automations, scheduling, cli, agents, hosts] created: 2026-09-09 updated: 2026-09-09 sources: ["raw/web_community-scheduled-automations-orca-docs.md", "raw/web_community-orca-cli-overview-orca-docs.md", "raw/web_community-orca-cli-reference-orca-docs.md", "raw/github_issue-bug-automations-still-having-blank-terminal.md"] confidence: medium --- # Scheduled Automations Orca automations run a prompt on a schedule from the CLI, so recurring triage, review, and maintenance tasks can start without you opening a worktree by hand. The docs' own arc for the feature is: create a **disabled** automation, inspect it, and run it manually when you're ready. ## Create it disabled first ``` 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 ``` `--trigger` accepts presets such as `hourly`, `daily`, `weekdays`, and `weekly`, plus cron expressions or RRULE strings. Use `--timezone ` when the schedule should follow a specific IANA timezone instead of the runtime default. ## Choosing where a run happens Three target shapes are documented, and they are not interchangeable: - `--repo ` — when each run should create or select work in a repository. - `--workspace ` — when the automation should run inside an existing Orca worktree instead. - `--project ` with `--host ` — when the automation should run on a specific project host setup rather than only `--repo` / `--workspace`. When you omit both target flags, Orca resolves the enclosing worktree from the current shell directory **when it can**. A cron-triggered, workspace-targeted example: ``` orca automations create \ --name "Nightly status" \ --trigger "0 18 * * 1-5" \ --prompt "Summarize today's changes" \ --provider claude \ --workspace active \ --disabled ``` And a host-targeted one: ``` orca automations create \ --name "Remote triage" \ --trigger daily \ --time 09:00 \ --prompt "Triage open issues" \ --provider claude \ --project \ --host \ --disabled \ --json ``` Use `--project-host-setup ` when you already have a setup id. Optional `--source-context ''` pins task/provider data to a host/account, and passing `null` on edit clears it. ## Prechecks A precheck skips scheduled work when a cheap shell probe fails — a non-zero exit records a **skipped** run rather than a failed one: ``` orca automations create \ --name "PR review" \ --trigger hourly \ --precheck "gh pr list --json number -q .[0].number" \ --prompt "Review requested PRs" \ --provider codex \ --repo my-repo \ --disabled \ --json ``` ## Session reuse For automations that target an existing worktree, `--reuse-session` makes later runs continue in the previous live automation terminal instead of starting from a blank terminal each time: ``` orca automations create \ --name "Inbox digest" \ --trigger hourly \ --prompt "Summarize unread mail" \ --provider codex \ --workspace active \ --reuse-session \ --disabled ``` `orca automations edit --fresh-session --json` switches the automation back to a fresh terminal per run. ## Missed-run grace ``` orca automations edit --missed-run-grace-minutes 30 --json ``` ## Review, enable, and run on demand ``` orca automations list --json orca automations show --json orca automations edit --enabled --json orca automations run --json orca automations runs --id --json ``` `edit` changes the name, prompt, provider, target, schedule, or enabled state. `remove` deletes an automation **and its run history**. Trigger a run manually to check the prompt and target before waiting for the next scheduled time. If a run fails before it opens a workspace or reconnects to its target, open that run in Orca and click `Rerun` to queue a fresh manual run for the same automation. ## Managing automations across hosts The desktop `Automations` page loads schedules from this computer and supported connected Orca hosts into one table. The `Host` column shows where each automation is stored and scheduled; `Filters → Host` shows one or more hosts, and `All hosts` returns to the full view. When you create an automation in the desktop UI, `Create on` chooses its host **before** you choose a project, and the project picker then shows projects available on that destination. Connected hosts that need a newer Orca server stay visible but disabled, with an `Update server` message, instead of disappearing from the picker — see [Remote Orca Servers](remote-servers.md) for why mixed versions are the expected state. External automations that live on an SSH host still appear as jobs you can manage, including delete, when that host is disconnected — you do not need an active SSH session just to remove a schedule. ### Finding things in a large list The search field filters by `name`, `project`, or `prompt` text. `Filters` narrows by `Host`, `Enabled` or `Paused` state, last-run outcome (`Failed`, `Succeeded`, or `Never ran`), or one or more `Agents`; active filters appear as removable pills above the table. The table shows host, last-run result, and relative time; clicking the `Name` or `Last run` column sorts (name alphabetically, last run newest first by default). Keyboard navigation: with the list open, type in the search field and press `ArrowUp` / `ArrowDown` to move the selection through visible matching rows (the list keeps the selected row in view). Across the automation details, `Enter` opens the selected automation or run, `ArrowUp` / `ArrowDown` move through run history, `ArrowLeft` / `ArrowRight` switch between Overview and Runs, and `Escape` returns from the detail view to the list. ## Known rough edge: the blank automation terminal Issue #2989 tracks a long-running problem where an automation launches, the agent appears in the sidebar or agents view and runs, but clicking `View run` opens an empty terminal. The issue was closed once as "happening on an old Orca version" and then **reopened** with "still occuring," and later comments report reproductions on v1.4.80 and v1.4.88. The most detailed comment narrows it precisely: the symptom appeared with Workspace = **existing** worktree (independent of the Fresh/Reuse toggle), while Workspace = **new_per_run** showed the agent window correctly. The stated reason is that a `new_per_run` worktree has exactly one tab — the background agent session — so activation reveals it, whereas in an existing worktree the background session's tab id is not surfaced as the active visible tab and activation falls back to opening a fresh empty terminal while the agent keeps running in a detached background PTY. Two commenters' workarounds were to connect to the agent from the agents view, or to use the `new_per_run` worktree mode. Upstream closed #2989 as completed on 2026-07-28, alongside merged PR #10818 (`fix(automations): bind agent terminal output before publishing, and launch SSH folder workspaces on their own host`). The reproductions above are against older builds and should not be expected on current ones; the mechanism is kept here because it explains the failure shape, and note that the reproductions are against builds well behind the release notes captured in this KB. **Analysis:** if you rely on automations for unattended work, prefer a per-run workspace or plan to pick the session up from the agents surface rather than from `View run` — the agent process itself is reported as healthy in every account of this bug; only the tab binding is not. ## Related pages - [Orca CLI](orca-cli.md) - [Orca CLI reference](../entities/orca-cli-reference.md) - [Orchestration](orchestration.md) - [Remote Orca Servers](remote-servers.md) - [Notifications and inbox](notifications-and-inbox.md) ## Sources `raw/web_community-scheduled-automations-orca-docs.md`, `raw/web_community-orca-cli-overview-orca-docs.md`, `raw/web_community-orca-cli-reference-orca-docs.md`, `raw/github_issue-bug-automations-still-having-blank-terminal.md`. --- title: "Skills and MCP" type: concept tags: [skills, mcp, sharing, security, agents] created: 2026-09-09 updated: 2026-09-09 sources: ["raw/web_community-orca-skills-registry-mcp-orca-docs.md", "raw/github_doc-docs-reference-sharing-agent-skills-md.md", "raw/github_doc-docs-reference-agent-skill-provider-paths-md.md", "raw/github_doc-docs-reference-agent-skill-sharing-threat-model-md.md", "raw/github_doc-docs-reference-admin-agent-skill-sharing-md.md", "raw/github_issue-bug-npx-skills-update.md"] confidence: medium --- # Skills and MCP Orca ships **skills** that agents install into their skill directories, and registers **MCP servers** that expose external tools to compatible agent CLIs. The two are separate mechanisms with separate settings surfaces, and only the first is Orca-authored. ## Hybrid discovery stubs, not full guides The design decision that shapes everything else: public install packages are **hybrid discovery stubs** — short `SKILL.md` files that tell the agent *when* to engage Orca and how to load the full guide from the running CLI. Command flags live in the binary "so they cannot drift from the app version." After `npx skills add`, agents see a stub that says to resolve the CLI executable for the session (`ORCA_CLI_COMMAND`, `orca-dev`, Linux `orca-ide`, else `orca`), load the full guide with `orca skills get ` (or `--full` for the long guide), and prefer `--json` while not inventing flags from memory. ``` orca skills list orca skills get orca-cli orca skills get orchestration --full orca skills get orca-linear --json ``` `skills show` is an alias for `skills get`. Add `--json` when an agent needs deterministic output for automation. ## The installable skills | Skill | Use it for | |---|---| | `orca-cli` | Worktrees, terminals, files, automations, embedded browser | | `orchestration` | Multi-agent Runs, tasks, supervised workers, messages, gates | | `computer-use` | Desktop apps via accessibility trees and safe UI actions | | `orca-linear` | Linear ticket read/write through `orca linear` | | `orca-emulator` | iOS Simulator control | | `orca-emulator-android` | Android emulator/device via adb | | `orca-per-workspace-env` | Per-workspace environment recipes (`orca.yaml`) | Each installs the same way, for example: ``` npx skills add https://github.com/stablyai/orca --skill orca-cli --global ``` Default agent setup usually installs `orca-cli`, `computer-use`, and `orchestration`. The `orca-linear` skill's legacy install name `linear-tickets` still resolves. Any repo with a `skills//SKILL.md` file can be installed via `npx skills add`, so internal repos can carry company-specific skills. ## Headless installs On headless hosts (SSH, containers, CI, `orca serve`) with no Settings UI, the local CLI wrappers resolve the same `npx` commands, add non-interactive flags, and **do not need a running Orca runtime**: ``` orca skills install 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 ``` Default scope is `global` (`--global`); pass `--local` for the current project only. `install` targets agents Orca detects on the host plus the shared `.agents/skills` directory; use `--agent [,…]` or `--agent universal` to override, and note that if no agent is detected, `--agent` is required. `update` only refreshes skills that are **already installed**. `--dry-run` prints the resolved command, and `--json` is only valid with listing or `--dry-run`. ## Keeping skills fresh in the app When Orca ships a newer skill package than the one installed globally, the app can show an `update available` nudge (and `Needs attention` when a copy is out of date somewhere the updater cannot safely rewrite), open an `Update skills` dialog listing placements and skip reasons, then run `npx --yes skills update --global -y` headlessly with no embedded terminal. The run stays in the **background** — closing the dialog does not cancel it — and a status-bar segment shows progress. The manual equivalent is: ``` npx skills update orca-cli orchestration computer-use --global ``` Prefer the in-app updater when Orca offers it, so the same global placements the app scanned get rewritten. Rows marked `Skipped` explain why a skill cannot be updated automatically (for example missing source registration). ### A real update failure worth knowing Issue #6162 reports `npx skills update` finding both Orca global skills and then failing both with only `✗ Failed to update orchestration` / `✗ Failed to update orca-cli`, on Windows with Node 24. The diagnosis in the thread places the bug **upstream in the skills CLI**, not in Orca's skill contents: `skills@1.5.13` re-invokes itself with `spawnSync(process.execPath, [...], { shell: process.platform === 'win32' })`, which on Windows + Node 24 triggers `DEP0190` and concatenates rather than escapes arguments, so a Node path containing spaces breaks the child command — while the updater hides the child's stderr. The stated workaround is to bypass the nested update path: ``` npx skills add https://github.com/stablyai/orca --skill orchestration --global --yes npx skills add https://github.com/stablyai/orca --skill orca-cli --global --yes ``` Upstream closed #6162 as completed on 2026-08-13, and PR #10436 (`fix(skills): stop promising a skill update the command cannot deliver`) merged on 2026-07-24. During the thread a maintainer said a fix "will be in next release, usually within 24 hours," while a later comment said earlier Windows-path work (#6307) rewrote the native Windows skill-update path and that they were "still treating this as open until the remaining update/install failure modes are sorted." Treat it as partially addressed, not closed. A second failure mode appears in the same thread: `✗ orca-cli → PromptScript: PromptScript does not support global skill installation`. ## Where installed skills actually land The provider-paths reference is deliberately conservative: V1 supports only providers whose paths are independently established by official documentation, and the registry "is not copied or synchronized from a community path table." | Provider | Detection | Global canonical support | Workspace support | Orca placement | |---|---|---|---|---| | Codex | `codex` CLI found through Orca's host-owned PATH detection | Reads `$HOME/.agents/skills` directly | Reads `.agents/skills` from the current directory through the repository root | Canonical copy only | | Claude Code | `claude` CLI found through Orca's host-owned PATH detection | Reads `$HOME/.claude/skills` | Reads `.claude/skills` from the launch directory through the repository root, plus nested directories as files are accessed | Relative directory symlink on POSIX, directory junction on Windows, or verified independent-copy fallback | Codex therefore needs no provider-specific placement. Claude Code does not document `.agents/skills` as a discovery root, so Orca reconciles its documented `.claude/skills` path back to the canonical copy. **Orca never replaces a path it does not own.** If alias creation is unavailable, the verified copy fallback is tracked in the install receipt so update and removal can detect drift. Separately, Orca's skill UI scans installed skill homes for Claude, Codex, Agent Skills, and OMP (`~/.omp/agent/skills`), so skills placed there show up without a manual symlink. Adding a provider to the registry requires official documentation links, a record of whether the provider reads `.agents/skills` directly, verification on macOS, Linux, native Windows and WSL, exercise of local/paired-runtime/SSH path resolution, and tests for alias denial, broken owned aliases, independent-copy drift, update, rollback and removal. Automated upstream path-table synchronization is explicitly forbidden. ## Sharing private skills between hosts `Skills → Share skills` publishes one skill or a bundle behind **one unlisted, revocable link**. Publishing and link management require an Orca account in the desktop app. Review the included files, scripts, executables, digest, and optional release notes before publishing; each published version is **immutable**, so later local edits do not silently change what recipients install. Installing from a link shows a preview before changing any files: verify author and organization, review version, release notes, included skills, scripts, executable files, and digest, select all or a subset, choose the destination machine and global-or-workspace scope, then review new/unchanged/updated/conflicting skills before confirming. Supported destinations include the local machine, paired Orca runtimes, WSL, and SSH hosts, and **the destination runtime resolves its own home and workspace paths**, so folder workspaces and remote filesystems do not borrow paths from the client machine. Conflict handling: **Keep local** is the default when an existing skill differs, and Orca replaces modified content only after you explicitly choose to discard it. `Skills → Manage installs` inspects managed skills and their immutable version history — installing the latest version is an update, selecting an older retained version is a rollback, and both use the same protected install transaction. An interrupted install is recovered on restart. Removal (`Manage installs → Remove`) removes only copies and provider placements Orca owns and can verify; modified or unowned files are preserved and reported. Revocation blocks new previews and download grants, but **a grant issued immediately before revocation can remain usable for up to five minutes**, and revocation does not remove copies recipients already installed. Removing a local install does not revoke its share or delete its Cloud package, and revoking or deleting Cloud data does not reach into recipients' machines. Agents can publish an explicitly named set from the CLI **only after a human enables** the separate, default-off `Settings → Share Skills → Allow agents and the Orca CLI to publish skill links` permission: ``` orca skills installed --json orca skills share --skill frontend --skill testing --bundle-name "Team Toolkit" --json ``` `skills installed` returns safe selectors without exposing local paths. `skills share` accepts exact discovery IDs or unambiguous names; it does **not** accept arbitrary paths or `--all`. ### Retention Upload grants expire after 15 minutes; abandoned upload bytes leave quarantine after one day; issued download grants expire after five minutes; published versions have no automatic age-based deletion; deleting a package revokes its links before unreferenced objects are deleted; deleted GCS objects stay operator-recoverable through a seven-day soft-delete window; installed copies remain until someone removes them on each destination machine. Organization legal or retention requirements can override normal rollback and deletion timing. ## The threat model and the upstream boundary The threat-model document opens with a status line that should be read literally: "implementation baseline for security and privacy review. This document does not constitute security approval." Its external rollout gate "remains closed until those findings are resolved or explicitly accepted." Three framing statements matter for anyone deciding whether to use shared skills: 1. **Private means unlisted.** An unpredictable active share ID is a *bearer credential*. Both the user docs and the admin guide say to treat the link like a credential and keep the durable share ID out of tickets, logs, analytics, and support bundles. Missing, expired, revoked, deleted, and unauthorized resources all return the same non-disclosing response, so Orca does not confirm whether a private package exists. 2. **V1 is not end-to-end encrypted from Orca Cloud operators.** 3. **A skill is code from its author.** `SKILL.md` can change agent behavior, and packaged scripts may be executed later by a user or agent — although the installer itself never executes package content, and archive validation completes before any destination mutation. Install only from people you trust, and review unexpected scripts or executable files. The security invariants the model commits to include: deterministic package identity binding normalized paths, exact bytes, executable state and immutable IDs; accepting only the `manifest.json` plus `skill/` envelope; destination paths resolved by the runtime that owns the host or workspace; unowned or modified local content never silently replaced or deleted; immutable, generation-fenced final objects reachable only through fresh ACL checks and short-lived grants; no remote caller able to turn a desktop-local path into remote filesystem authority; interrupted transactions converging to a verified old or requested version; logs and support bundles excluding package contents and private authorization or filesystem data; and independent kill switches for Cloud sharing, downloading and remote installation. Threats explicitly registered include archive traversal and decompression exhaustion (TM-02), forged manifests (TM-03), a client escaping a destination root or choosing another home/WSL distro/SSH path (TM-04), overwriting unowned or locally modified content (TM-05), grant leakage through redirects or DNS confusion (TM-07), cross-tenant disclosure through content-addressed deduplication (TM-10), a compromised renderer or old client sending credentials or unknown opcodes to a host (TM-11), provider aliases or junctions escaping canonical storage (TM-13), and skill instructions being mistaken for trusted Orca code (TM-14). Each carries a **residual release gate** that is still open — for example TM-09's "human authorization review and organization-departure policy approval remain required." **Analysis:** the practical upstream boundary is that Orca guarantees *delivery* integrity — the bytes you preview are the bytes you install, and the installer will not run them — but makes no claim about the *content*. The trust decision stays with the recipient, and revocation is one-way: it stops new installs and leaves existing ones alone. Operationally, the admin guide notes that upload, download, and remote-install operations have independent kill switches, that the narrowest affected operation should be disabled first, and that existing local discovery and installs continue to work when they are. It also records an unresolved policy gap: "The product does not yet encode a universal ownership-transfer or legal-retention policy," so until that decision is made, preserve metadata and soft-deleted generations rather than guessing. ## MCP servers Model Context Protocol (MCP) servers expose external tools to compatible agents. Register MCP endpoints under `Settings → Integrations → MCP`; those tools appear inside agent CLIs that support MCP. That is the whole documented surface — MCP servers are agent-side tooling Orca registers, not part of the Orca skill package format. ## Related pages - [Orca CLI](orca-cli.md) - [Orchestration](orchestration.md) - [Computer use](computer-use.md) - [Settings reference](../entities/settings-reference.md) - [Supported agents](../entities/supported-agents.md) ## Sources `raw/web_community-orca-skills-registry-mcp-orca-docs.md`, `raw/github_doc-docs-reference-sharing-agent-skills-md.md`, `raw/github_doc-docs-reference-agent-skill-provider-paths-md.md`, `raw/github_doc-docs-reference-agent-skill-sharing-threat-model-md.md`, `raw/github_doc-docs-reference-admin-agent-skill-sharing-md.md`, `raw/github_issue-bug-npx-skills-update.md`. --- title: "SSH Worktrees" type: concept tags: [ssh, remote, worktrees, terminals, security] created: 2026-09-09 updated: 2026-09-09 sources: ["raw/web_community-ssh-worktrees-orca-docs.md", "raw/web_community-work-on-a-remote-machine-over-ssh-orca-docs.md", "raw/github_doc-docs-reference-ssh-execution-boundary-md.md", "raw/github_doc-docs-reference-ssh-host-key-verification-md.md", "raw/web_community-troubleshooting-faq-orca-docs.md", "raw/github_issue-bug-remote-environment-disconnection-floods-the-ui-with-repe.md", "raw/github_issue-bug-pasting-images-into-an-agent-cli-not-working-using-remot.md"] confidence: medium --- # SSH Worktrees An SSH worktree runs agents and `git worktree` on a remote host while the editor, diff, and UI stay on your laptop. Your laptop's Orca remains the runtime owner — that is the difference from a [Remote Orca Server](remote-servers.md), where the far machine owns everything. ## Adding a target From `Settings → SSH`: 1. Click `Add Target`. The host form opens in a modal (not inline under the list), so Host, Advanced, and Save stay reachable even with a long host list. Edit uses the same dialog and shows the target label plus `user@host:port`. 2. Fill in host, user, port, and optional identity file — or open the `OpenSSH config` picker in the same dialog to search `~/.ssh/config` (including `Include`d files), pick one host, and prefill the form. Hosts already saved in Orca show an `In Orca` badge. 3. If the key is passphrase-protected, Orca prompts the first time. 4. Click `Test` to verify connectivity, then `Save`. Dirty add/edit forms ignore outside clicks so an accidental click away does not discard your fields; use Escape, Cancel, or × to discard. Passphrases are held in memory for the life of the Orca session and cleared when Orca closes; you can opt into a longer TTL under SSH settings. Under `Advanced Connection`, `Reuse SSH connection for faster setup` is enabled by default and uses OpenSSH connection reuse on macOS and Linux so setup commands do not each pay a fresh SSH handshake. Turn it off only for hosts whose SSH policy rejects multiplexed sessions. ### Transports that are not the built-in client Two cases hand the connection to the OS OpenSSH binary instead of Orca's built-in ssh2 client: - **Kerberos / GSSAPI** — if a host in OpenSSH config sets `GSSAPIAuthentication yes`, Orca prefers the system OpenSSH transport for that target. Keep a valid Kerberos ticket (`kinit` / your org's SSO) before connecting. There is no separate "Kerberos mode" switch for config-imported hosts; `ssh -G` carries the flag through. - **FIDO2 / security keys** — hardware-backed identities (`ed25519-sk`, `ecdsa-sk`, including agent-backed security keys) also use system OpenSSH. Regular Ed25519, ECDSA, and RSA keys stay on the built-in transport. If OpenSSH is not available on the machine, those FIDO2 targets cannot authenticate until it is installed and on `PATH`. ## Host key verification Orca checks built-in SSH connections against your effective OpenSSH `known_hosts` files and keys it previously saved. Existing matches connect silently. With the default policy, Orca accepts and remembers a host on first contact and shows its fingerprint; `StrictHostKeyChecking yes` rejects unknown hosts, while `no` / `off` accepts without saving a trust record. A changed, revoked, or unexpectedly different key type is rejected *before* Orca asks for a password or key passphrase. For a `known_hosts` mismatch, Orca provides the appropriate `ssh-keygen -R` command, including the bracketed host and port when needed. The design reference behind this behaviour records several decisions worth knowing: - Orca **reads** your `known_hosts` as a trust source but never writes to it; accepted keys go to a dedicated store, scoped to **host + port + key type** rather than to a target id. - Consequently `ssh-keygen -R host` clears `known_hosts` but not Orca's own record. For a host Orca only ever knew itself, the rejection names the store file directly. - Outcomes are `match | mismatch | revoked | ca-only | unknown-type-known-host | unknown`. `mismatch` and `revoked` hard-fail with no override in the failure surface; recovery lives in target settings, deliberately not in the failure dialog. - `ca-only` was **reversed after review** and is treated as first contact, matching OpenSSH's own `HOST_NEW` verdict for a CA-covered host presenting a plain key. The residual risk is accepted, not resolved: certificate validation is Phase 2 work. - A `known_hosts` file that exists but will not open connects while recording nothing; an *absent* file is the normal fresh-profile case and is not treated the same way. Known gaps the reference lists explicitly: WSL (a distro's `known_hosts` is unreachable, so WSL users get first-contact treatment for hosts they already verified inside the distro), `CheckHostIP` (candidates are formed from the hostname only), and `UpdateHostKeys` (read but unused, so a rotated key is a hard failure the user resolves by hand). ## The SSH execution boundary The repo reference states one rule: **the execution host owns everything that touches execution** — tools, credentials, identity, environment, processes, and artifacts. The client owns the UI, transport, and Orca control-plane state, but is not authoritative for execution state. Two consequences are called non-negotiable: no silent substitution (an operation on a remote `repoPath` must never fall back to running on the client), and no asserting what you cannot observe. What runs where, as documented: | Concern | Executes on | |---|---| | PTYs, agent CLIs | remote (children of the detached relay daemon, not of the ssh channel) | | git (status, diff, log, fetch, push, commit, branch, worktree) | remote | | filesystem, watching, search | remote | | repo setup hooks (`--setup`) | remote, identical policy to local | | commit-message / PR-field AI generation | remote, using the remote agent CLI and its auth | | `gh` / GitHub API, `glab` / GitLab | **client** — the reference flags this as inconsistent with the rule; PRs carry the client's identity | | the `orca` CLI inside a remote terminal | **client runtime** — control plane only | The vocabulary is fixed: `live` / `unverifiable` / `exited`. `exited` requires positive evidence of absence from the host that owns the process; a transport failure can only ever produce `unverifiable`. ### The control-plane consequence On an SSH host, `orca` is a shim at `~/.orca-relay/bin/orca` that proxies back to the client's runtime over the relay socket. When the client disconnects, every `orca …` command run on the SSH host fails with `No owning Orca client is connected to the relay`. The PTY stays `live`; its control plane does not. Orchestration state (Runs, Tasks, Dispatches, mailboxes) is client-resident for the same reason, so the reference advises: an agent on an SSH host should not depend on `orca` for anything it must finish while you are away — **commit and push early**. ## Disconnects, reconnects, and source recovery Remote worktrees show a chip with live SSH status — green connected, yellow reconnecting, red disconnected. While an SSH host is still connecting, Orca can list workspaces from persisted local metadata so the sidebar is not empty until the live provider comes up; those rows refresh to authoritative remote state once the connection settles. Disconnects do not kill running agents. Orca reconnects and re-attaches, replaying scrolling output and restoring full-screen app panes from their rendered frame instead of returning them blank or fragmented. When a host drops, the affected workspace card can show an inline `Connect` / reconnect control. If an SSH relay drops with a "Multiplexer disposed" style failure, Orca recovers automatically instead of leaving the pane stuck until you restart. Closing the desktop app no longer kills remote PTY sessions: they are leased through the relay running on the remote host. On reconnect, leased PTYs are restored to their tabs in the `attached` state with scrollback intact. A short grace period (**5 minutes by default, configurable per target**) gives the relay time to ride out a quick reconnect before tearing down detached sessions. The execution-boundary reference documents the grace window differently and more precisely, and the two should be read together rather than merged: the shipped default is `0` = keep alive until reset; if "keep terminals alive until reset" is unchecked, the configurable range is **60s–7d** and the form defaults to **24h**. It also warns that no command reports which setting is in effect for a target, so a remote at N hours since disconnect should be treated as `unverifiable`, not `exited`. Reconnect replays a bounded buffer (`REPLAY_BUFFER_MAX`, a 102,400-code-unit tail) — output beyond that is lost to the client even though the process was never interrupted. ### Updating Orca strands relay-backed terminals A third outcome exists that is neither survival nor stop. The relay's install directory, and therefore its socket path, is namespaced by a content hash of the relay bundle, and the daemon refuses any client whose bundle hash differs. So the first reconnect after an app update deploys a new relay at a path the incumbent was never listening on. Every PTY the incumbent owns becomes `unverifiable` — running, unreachable, and never `exited` — and the pane falls back to a cold-restore agent resume, or to a bare shell when no resumable provider session was captured. The reference notes this failure does not exist in the peer/runtime model, whose daemon endpoint is namespaced by a semantic protocol version. **Analysis:** This is the strongest practical argument in the docs for pushing long, unattended runs onto a [Remote Orca Server](remote-servers.md) rather than an SSH target — auto-update is normal, and on SSH it silently orphans in-flight work. ## Files, editors, and ports - **Downloads.** Right-click in the SSH worktree file explorer: `File → Download` (native save dialog) and `Folder → Download Folder` (recursive, desktop only). Folder download appears only when the connection advertises recursive folder transfer (typically full SFTP); connections that stay on system-OpenSSH-only transfer may still download *files* but not show `Download Folder`. This is a desktop-only action — the web client doesn't expose Download because it relies on Electron's save dialog. - **VS Code Remote-SSH.** The worktree menu's `Open in` list can hand the remote path to VS Code Remote-SSH when your configured app is VS Code or VS Code Insiders (`code` / `code-insiders`, or a direct path to those launchers). Orca launches it as `--remote ssh-remote+ `, and the entry may show a `Remote SSH` badge. Not supported for this remote path: Cursor, Zed, compound shell commands, or opening via a Remote Orca Server active runtime — those stay `Local only`. - **Port forwarding.** For remote worktrees the right sidebar shows a `Ports` tab (toggle with `Cmd+Shift+I`). Orca scans `/proc/net/tcp` on the remote and lists listening ports under `Detected`; one click forwards them. Forwards persist across app restarts and SSH reconnects, and privileged remote ports auto-remap locally (e.g. remote 80 → local 10080). ## Linux hosts without a C/C++ toolchain On first connect Orca installs a small relay on the remote. Remote terminals need a native `node-pty` module; Linux packages often compile on the host, while macOS/Windows relays use prebuilds. If the remote is missing `make`, a `C++ compiler`, and `python3`, Orca still finishes connect for **files, git, and the editor**, but **remote terminals will not work** until build tools are installed. Install hints Orca may surface: - 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` Install the tools, then reconnect so the relay can install native modules. The troubleshooting page adds: confirm the remote has Node and network access for the first-time relay install. ## Known rough edges - **Reconnect flooding.** Issue #11392 reports that a remote runtime reached over Tailscale, when the laptop sleeps or the network drops, can print the same timeout and reconnection errors continuously until the UI is nearly unusable — and that the terminal in the affected agent session could remain stuck and stop accepting input even after the connection was restored. The reporter's workaround was to close the session, create a new one, and resume the previous session. The raw issue file does not record a resolution, and the reporter later said the same class of problem appeared on a Remote Orca Server; upstream closed #11392 as completed on 2026-08-28. - **Image paste.** Issue #6364 reports pasting images into an agent CLI failing under a Remote Host, with the reporter noting image paste "worked as expected (and very well) using just normal SSH host." No fix is recorded in the raw file. ## Related pages - [Ways to run Orca](ways-to-run.md) - [Remote Orca Servers](remote-servers.md) - [Orca CLI](orca-cli.md) - [Settings reference](../entities/settings-reference.md) ## Sources Docs-site snapshot fetched 2026-09-09 (`raw/web_community-ssh-worktrees-orca-docs.md`, `raw/web_community-work-on-a-remote-machine-over-ssh-orca-docs.md`, `raw/web_community-troubleshooting-faq-orca-docs.md`), repo references `raw/github_doc-docs-reference-ssh-execution-boundary-md.md` and `raw/github_doc-docs-reference-ssh-host-key-verification-md.md`, and the issue reports `raw/github_issue-bug-remote-environment-disconnection-floods-the-ui-with-repe.md` and `raw/github_issue-bug-pasting-images-into-an-agent-cli-not-working-using-remot.md`. --- title: "Tabs, Panes and Navigation" type: concept tags: [tabs, panes, layout, shortcuts, navigation] created: 2026-09-09 updated: 2026-09-09 sources: ["raw/web_community-tabs-panes-split-layouts-orca-docs.md", "raw/web_community-quick-open-jump-palette-orca-docs.md", "raw/web_community-settings-reference-orca-docs.md", "raw/web_community-terminal-orca-docs.md", "raw/web_community-jump-between-10-worktrees-orca-docs.md", "raw/web_community-session-restore-orca-docs.md", "raw/web_community-per-worktree-browser-orca-docs.md"] confidence: medium --- # Tabs, Panes and Navigation ## The layout model "Orca's pane system is designed for watching multiple agents work without losing context. Tabs group into panes; panes split into layouts." A tab holds exactly one thing — "a terminal, an editor buffer, a browser, a diff, a PR" — and tabs live inside a **tab group**. Drag a tab up-down within a group to reorder; drag it onto another group to move it. "An active-tab color bar marks which pane is focused." The key scoping rule: "Each worktree owns its own tab layout. Switching worktrees swaps the entire pane tree — your browser tab, terminal, and diff reappear exactly as you left them." That layout is also what [session restore](agents-and-sessions.md) rebuilds on the next launch. ## Splitting Drag a tab to the edge of a pane to create a split: - **Right edge** — splits left/right (horizontal split). - **Bottom edge** — splits top/bottom (vertical split). "Splits nest. You can have an agent terminal on the left, a diff view on the top-right, and a browser tab on the bottom-right — all at once." Any tab type can split with any other: "agent terminal, diff, browser, editor, PR view all coexist in one pane tree." Terminal tabs additionally split *inside* the tab: "Use the terminal tab menu for **Split terminal right** or **Split terminal down**, or use the split button in the active terminal pane header for a right split." The keyboard equivalents documented on the terminal page are `Cmd-\` (split right) and `Cmd-Shift-\` (split down). **Pinned boundaries:** "Pane boundaries stay where you put them. Resizing the window doesn't shuffle your layout; boundary positions are saved per worktree." ## Tab keyboard defaults These are the defaults on **new installs**; "Existing installs keep customized overrides in `~/.orca/keybindings.json`." Remap under **Settings → Shortcuts**. | Action | macOS | Linux / Windows | | --- | --- | --- | | Next / previous tab (all types) | `Cmd+Shift+]` / `Cmd+Shift+[` | `Ctrl+Shift+]` / `Ctrl+Shift+[` | | Next / previous tab (same type) | `Cmd+Option+]` / `Cmd+Option+[` | `Ctrl+Alt+]` / `Ctrl+Alt+[` | | Previous recent tab | `Ctrl+Tab` | `Ctrl+Tab` | | Close all editor file tabs in the active worktree | `Cmd+Option+W` | `Ctrl+Alt+W` | Terminal- and browser-scoped tab shortcuts documented elsewhere: `Cmd-T` opens a new terminal tab in the current worktree (and, in a browser pane, a new browser tab scoped to that worktree), `Cmd-W` closes the current tab, and `Cmd-Shift-T` reopens the last closed browser tab. `Cmd-Alt-T` (macOS) opens a new agent tab using your default agent; "On Linux and Windows this chord ships unbound; assign one under **Settings → Shortcuts** (search for 'New agent tab')." ## Quick Open (`Cmd-P`) "File search scoped to the current worktree. Type a fragment; Orca ranks by recency plus match score and opens the file in a new editor tab." Rows "lead with the **filename** and truncate the parent directory when space is tight (hover for the full path)." Note the deliberate inclusion, not exclusion: "Gitignored files are included in results — they're surfaced as a second pass after tracked matches, so the files you frequently quick-open (build outputs, env files) stay reachable without polluting the top of the list." ## The new-tab omnibox (`+`) The tab strip's `+` opens an omnibox that searches "**open tabs**, files, URLs, and agents in one field (placeholder: `Search open tabs, files, URLs, agents…`)." Three behaviors worth knowing: - "Matching an already-open editor tab prefers that tab over a duplicate file result, so you jump to the open buffer instead of opening a second copy." - It also searches "this worktree's browser history," ranked by match closeness and recency. - Typing a web search opens it in the worktree browser with your **Default Search Engine**. "A single token still ranks file matches first; a multi-word phrase promotes the search row. Prefix the query with `?` to skip file and tab matching and search immediately." ## Worktree Jump Palette (`Cmd-J`) "Jump across every worktree and every tab in one search." The empty-input placeholder reads `repo/worktree` — "type either half and Orca filters accordingly." Once you start typing, "search includes non-archived worktrees even if they are hidden by the sidebar's current filters." Press `Tab` inside the palette for a host and project filter menu. "Selected hosts and projects narrow the result set and show as chips you can remove one at a time; closing the palette clears the filter so the next open is unscoped." What the results contain: - **Recent Chats & Terminals** — with an empty query, "up to six recent agent/terminal sessions ranked by activity (needs-you first, then done, then idle)." The idle tab you are already viewing is omitted, "a current tab still appears when it is working, waiting on you, or has unread activity." Digit shortcuts `Cmd-1`–`Cmd-6` (macOS) / `Ctrl-1`–`Ctrl-6` (Windows / Linux) jump to the first rows. "Membership and order freeze when the palette opens so rows don't shuffle under the cursor." - **Recent Worktrees**, ordered by last focus. - Projects and repo groups. - Every worktree grouped by repo once you type. - Worktrees matched "by cached GitHub PR title or number (`#123`) and cached GitLab merge request title or number (`!123`) when that review metadata is already available." - Every open tab, "scoped first by current worktree, then globally." Type aliases such as `terminal` or `simulator` match those tab types. When a query hits both tabs and worktrees, "the palette interleaves a short preview of each section so neither primary list is buried"; a section's `N more` row expands 20 entries at a time, and "Changing the query resets the expanded sections." Two actions that are easy to miss: `Shift-Enter` on a worktree "opens it in a new split instead of swapping the current pane," and when the query matches no existing worktree the palette offers a **Create worktree** row using the typed text as the name — "Existing matches stay selected first, so pressing Enter still jumps when a real result is available." A **Search** button at the top of the sidebar opens the same palette for mouse-driven users. ## The ten-worktree workflow The docs' recipe for scale, condensed: `Cmd-J` and type a fragment of the task name — "Enter jumps; Shift-Enter opens in a split. Press `Tab` to filter by host or project when the list is large." Then scan the sidebar for state (see [agents-and-sessions](agents-and-sessions.md)), use the **Restart** chip to mass-resume agents that exited after a laptop sleep, and drain the "agent finished" queue from the persistent bell — "click a notification, it jumps you to the worktree." The page's hygiene advice is explicit: "Delete merged worktrees aggressively… Leaving dozens of merged worktrees around just slows down the palette." ## Related pages - [worktrees](worktrees.md) — the sidebar filters that Jump Palette deliberately bypasses - [terminal](terminal.md) — terminal splits, the floating terminal, Quick Commands - [editing](editing.md) — what Quick Open opens - [agents-and-sessions](agents-and-sessions.md) — the live attention badges the palette reuses ## Sources Tabs/panes/split-layouts, Quick Open & Jump Palette, settings reference, terminal, and jump-between-10-worktrees docs pages, fetched 2026-09-09. --- title: "The Orca Terminal" type: concept tags: [terminal, ghostty, ime, shortcuts, quick-commands] created: 2026-09-09 updated: 2026-09-09 sources: ["raw/web_community-terminal-orca-docs.md", "raw/github_doc-readme-md.md", "raw/web_community-settings-reference-orca-docs.md", "raw/github_issue-bug-terminal-selecting-a-single-chinese-char-by-number-key-i.md", "raw/github_issue-bug-issues-with-korean-input-in-the-terminal.md", "raw/github_issue-bug-macos-automatic-period-substitution-injects-into-the-ter.md", "raw/web_community-tabs-panes-split-layouts-orca-docs.md"] confidence: medium --- # The Orca Terminal ## What the terminal actually is The docs are precise: "Orca's terminal is the same xterm.js-based terminal VS Code uses, with a few additions tuned for AI-agent workflows." A user bug report on issue #12099 (2026-08) corroborates the stack — "Terminal renderer: xterm.js `@6.0.1-beta.287` + WebGL." The README markets the same component differently: "**Terminal Splits** — Ghostty-class terminals with WebGL rendering, infinite splits, and scrollback that survives restarts." **Analysis:** "Ghostty-based" is a widely repeated description of Orca's terminal, but nothing in these sources says the terminal is built on Ghostty. What the sources do support is that it is *Ghostty-compatible in three concrete ways*: it imports Ghostty's theme, font, and cursor config; it advertises the kitty keyboard protocol so modifier-aware keys behave "the same in Orca as they do in Ghostty, WezTerm, or your native terminal"; and the README calls it "Ghostty-class." Treat the engine as xterm.js and the Ghostty relationship as configuration and key-handling parity. ## Splits, tabs and shortcuts Terminals are ordinary tabs — see [tabs-panes-and-layouts](tabs-panes-and-layouts.md) — so "Splitting a terminal pane gives you two shells side by side." Terminal-specific defaults: - `Cmd-T` — new terminal tab in the current worktree. - `Cmd-Alt-T` (macOS) — new agent tab using your default agent. "On Linux and Windows this chord ships unbound; assign one under **Settings → Shortcuts** (search for 'New agent tab')." Each supported agent also has its own per-agent "New agent tab" action you can bind directly. - `Cmd-W` — close the current tab. - `Cmd-\` — split right. - `Cmd-Shift-\` — split down. - `Cmd-F` — find in scrollback, with "Match highlighting, case, regex, and match navigation." Agent terminal tabs "show the agent identity plus live state: working, waiting for input, completed, or completed-but-unread. For Claude and Codex, tab titles can also show the **AI Vault conversation name**… when Orca can map the pane to that session — manual renames still win." ## The floating terminal "The floating terminal is a global shell surface that's always one chord away, regardless of which worktree or tab you're on. It's on by default for new installs." Toggle it with `Cmd+Option+A` (macOS) / `Ctrl+Alt+A` (Linux/Windows) — "The same chord focuses the panel if it's already open and dismisses it if it's already focused." The trigger button can move to the status bar under **Settings → Terminal → Floating terminal**, and the same setting sets the starting working directory (`~` by default). "The floating panel hosts its own tabs and supports orchestration setup — kick off background runs without claiming a worktree pane." The settings reference lists the same surface under a **Floating Workspace** pane — **Enable Floating Workspace**, **Terminal Directory** (`~` = home), and **Toggle Button Location**, noting "the keyboard shortcut works regardless of button placement." ## Clipboard, links and context **TUI clipboard (OSC 52).** "Many terminal UIs (Zellij, tmux, Neovim, fzf, Grok) copy via `OSC 52` instead of OS clipboard APIs. Orca allows those writes **by default** so copy-from-remote/TUI works over SSH the same way as locally." Toggle: **Settings → Terminal → Allow TUI Clipboard Writes (OSC 52)**. **Link actions.** "A plain click on a terminal link (HTTP/OSC 8 URL, file path, workspace, terminal, or task handle) opens a compact action popover instead of navigating immediately." Local web links, and links owned by an eligible SSH workspace or capability-verified paired runtime, offer **Orca Browser** and **System Browser**; "older runtimes stay system-only." `Cmd`-click (macOS) / `Ctrl`-click (Windows / Linux) "still opens directly." Turn the popover off under **Settings → Browser → Show terminal link actions** — "With it off, opening a link requires the modifier-click." **Copy Context.** Right-click a terminal and choose **Copy Context** "to copy a bounded transcript from that pane." The tab context menu's **Copy Session ID** copies the session identifier. ## Themes and rendering Themes live under **Settings → Terminal**; Orca "ships a library of popular themes and lets you customize any of them." **Ghostty import** — theme, font, and cursor config on first launch, re-runnable from **Settings → Terminal → Import from Ghostty**. **Warp theme import** — **Import themes from Warp** in the terminal-theme picker. "Orca scans Warp's theme directory for the current OS (`~/.warp/themes` on macOS, `$XDG_DATA_HOME/warp-terminal/themes` on Linux, `%APPDATA%\warp\Warp\data\themes` on Windows) and lets you pick which YAML themes to import." **Import from YAML** points the same picker at any folder of Warp-format `.yaml`/`.yml` files. **Color contrast** — under **Settings → Terminal → Rendering → Color Contrast**, choose `Automatic` to keep text legible, `Off` "to preserve your theme's dim and Powerline colors," or `Custom` "to set a contrast target from 1 to 21." ## Shell selection on Windows and WSL "The default shell on Windows is configurable between PowerShell, Command Prompt, and WSL under **Settings → Terminal**. WSL is offered automatically when `wsl.exe --status` succeeds. The `+` dropdown on the tab bar also shows a submenu so you can open a one-off tab in any shell without changing your default." (The settings reference summarizes this pane more narrowly as "Windows default shell (PowerShell or CMD)" — see [installation](installation.md) for that discrepancy.) "For repos on a WSL filesystem (`\\wsl.localhost\...`), Orca launches through `wsl.exe -d `. For Windows-path repos opened in WSL, Orca translates the cwd to `/mnt//...` and drops you into a login bash." ## Key handling and known input/IME behavior Orca "advertises the kitty keyboard protocol, so terminal apps see real `Shift+Enter`, `Ctrl+Enter`, and other modifier-aware keystrokes." For Japanese JIS keyboards on macOS, enable **Settings → Terminal → JIS Yen (¥) to Backslash (\\)** "if you want the physical Yen key to send a backslash in terminal sessions." CJK input is the terminal's documented weak spot. These are user-reported issues, not vendor documentation — treat them as a checklist of known symptoms rather than current behavior. Upstream closed #9803 and #12099 as completed (2026-08-17 and 2026-08-18; PR #15429 `fix(terminal): stop a Hangul-terminating digit being eaten as a candidate pick` merged 2026-08-19), while **#11504 was closed as *not planned*** — `NSAutomaticPeriodSubstitutionEnabled` is a macOS text-input setting rather than an Orca bug, so the `defaults write` workaround below is the fix, not a stopgap: **macOS period substitution with a CJK input source (#11504).** With a Korean input source, typing a space can commit "a space **plus a period**." The mechanism: macOS "Add period with double-space" (`NSAutomaticPeriodSubstitutionEnabled`) "is **on by default**. It is applied by the text input system, which Chromium text fields participate in — including xterm's helper textarea. Native terminals do not use that text system, so they never see the substitution." A captured event trace in the thread shows one space is enough, because "The Hangul IME folds the space into the composition," so the substitution fires on the commit. Reported workarounds, in the order the thread established them: ```bash # verify the OS setting defaults read -g NSAutomaticPeriodSubstitutionEnabled # → 1 means on # global workaround (verified to stop it; affects every app) defaults write -g NSAutomaticPeriodSubstitutionEnabled -bool false # app-scoped: reported ineffective on 1.4.161, reported working on 1.4.164 defaults write com.stablyai.orca NSAutomaticPeriodSubstitutionEnabled -bool false ``` The GUI equivalent is System Settings → Keyboard → Text Input → Input Sources → Edit → "Add period with double-space." **Korean IME on Windows (#9803).** Reporters on Windows 11 build 26200 with the built-in Korean 2-set IME describe the cursor advancing one syllable late and "stray line breaks mid-word," across "all 5 CLI agent tabs we run (Claude Code, Codex, OpenCode, Antigravity, Grok) — so it is the integrated terminal layer, not any specific agent TUI." Two commenters narrowed it to a `1.4.162 → 1.4.163` regression and reported that rolling back to `v1.4.162` — plus deleting `%LOCALAPPDATA%\orca-updater\pending` to stop the update reapplying — "fully restores normal Korean typing." An earlier comment in the same thread hypothesizes that a periodic repaint from PTY state wipes the IME preedit, and explicitly labels itself unverified: "I have not verified this against the source." **Chinese candidate selection on Linux/ibus (#12099).** "selecting a **single Chinese character** from the IME candidate window using the **number keys** causes the committed character to disappear immediately. Selecting with the **mouse** works fine, and selecting multi-character words by number keys works fine." Stated user workaround: "select single characters with the mouse." ## Quick Commands "Quick Commands save terminal commands you run often, such as `npm run dev`, `pnpm test`, or a project-specific setup script. They can also save reusable agent prompts for launch-time prompt agents such as Claude and Codex." Create them from **Settings → Quick Commands** or the tab bar's **Add command** button. Each has "a label, command text, and scope" — `Global` everywhere, or `Project` to show it only in worktrees for a specific repo. "The tab-bar button opens a fresh terminal tab and runs the command; the terminal context menu can insert commands into the current terminal." With a paired Remote Orca Server, "the picker can show **local and remote** collections side by side, labeled by host." The distinction to hold onto: "**Saved on** is where the command is stored; running a command still executes in the terminal or workspace where you invoke it — so a client-owned command can run inside a remote worktree." Older servers that don't advertise multi-host Quick Commands "fall back to the local-only list." ## Related pages - [tabs-panes-and-layouts](tabs-panes-and-layouts.md) — splits and tab chords - [agents-and-sessions](agents-and-sessions.md) — the state the agent tab shows - [browser-and-design-mode](browser-and-design-mode.md) — where terminal links can open - [installation](installation.md) — Ghostty import at first launch ## Sources Terminal docs page, README feature wall, settings reference, and GitHub issues #12099, #9803, and #11504, all fetched 2026-09-09. --- title: "Usage and Rate-Limit Tracking" type: concept tags: [usage, rate-limits, accounts, codex, claude-code] created: 2026-09-09 updated: 2026-09-09 sources: ["raw/web_community-usage-rate-limit-tracking-orca-docs.md", "raw/web_community-hot-swap-codex-accounts-orca-docs.md", "raw/web_community-codex-in-orca-orca-docs.md", "raw/web_community-claude-code-in-orca-orca-docs.md", "raw/web_community-settings-reference-orca-docs.md", "raw/web_community-mobile-companion-orca-docs.md", "raw/github_issue-can-t-add-codex-account-codex-cli-not-found.md", "raw/web_community-remote-orca-servers-orca-docs.md", "raw/web_community-orca-cli-reference-orca-docs.md"] confidence: medium --- # Usage and Rate-Limit Tracking Orca reads **local** usage state for Claude Code, Codex, Gemini, OpenCode, Kimi Code, and MiniMax and surfaces it in the status bar, so you know how close you are to a rate limit before an agent stalls. ## What is shown, and how fresh it is The readout covers current usage against the active account's plan, time to reset for 5-hour, daily, weekly, and Claude Fable weekly windows (where applicable), and a warning chip when you cross **80%** of a limit. The mechanism is the important caveat. Orca reads the local usage state each agent maintains on disk — under `~/.claude`, `~/.codex`, and the Gemini/OpenCode equivalents. **No API calls, no extra auth.** The docs draw the consequence explicitly: "the readout is only as fresh as the agent's own bookkeeping — numbers update when the agent writes, not in real time." The MiniMax path is the exception in the settings surface: `Settings → Integrations → MiniMax` takes a pasted MiniMax session cookie (from `platform.minimax.io/console/usage`) to enable local usage and rate-limit tracking for the MiniMax CLI, with optional group ID and usage models fields overriding the defaults picked from the cookie. ## The usage roster Clicking the usage segment in the status bar opens the `Usage` popover. It lists every tracked provider (icon · name · plan · soonest reset · per-window bars), **sorted so the tightest limit is first**. The header refresh control re-reads local usage state. Two densities are available: `Detailed` (full bars, labels, and percentages for every window) and `Compact` (only the tightest window per provider). Under `Settings → Appearance`, `Usage percentages` chooses whether numbers read as `% used` or `% remaining` on the status-bar roster. Rows without live numbers show a short status instead: `Loading usage…`, `not signed in`, `Usage unavailable`, `No usage data`, or a provider-specific error. Claude and Codex rows can drill into account switching, and `Manage accounts` opens Settings. ## Multi-account accounting The status bar **always reflects the active account**. Other configured accounts are visible in the account switcher with their own usage. ## Codex account hot-swap Running multiple Codex accounts to maximize tokens is described as common, and Orca hot-swaps the active account in one click with no re-login and no config editing. **Setup.** Log into each Codex account from a terminal at least once so the auth sits under `~/.codex`. Open `Settings → Agents → Codex Accounts`; Orca lists all detected accounts with their usage and current limit, and each can be given a friendly label. **Swapping.** Click the Codex chip in the status bar to open the account switcher and pick an account. Any **new** Codex session launched after that uses it; sessions already running keep their original account until restarted. The documented rules and gotchas: - Swapping is instant — Orca rewrites the active credential pointer, it does **not** re-authenticate. - Existing Codex processes keep their current account until restart. - Usage readouts in the status bar follow the currently-active account. - The restart chip preserves the active account at the time of restart. If you swapped accounts mid-session and want to restart with the new one, use the account switcher first, then restart. **System default vs managed accounts.** The `System default` row is your current host Codex login under `~/.codex` — the same home a bare `codex` outside Orca would use. Managed accounts added in Orca do **not** rewrite that login; they get their own home under Orca's account data so credentials and rollouts stay isolated. Select System default when you want launches to match a terminal `codex` outside Orca. **When config edits seem ignored.** For managed Codex accounts, Orca mirrors settings from your real `~/.codex/config.toml` into the active runtime home. If that source file is missing, empty (for example cloud-sync still downloading), or unreadable, Accounts shows a warning and Codex keeps the **last successfully synced** settings until the source is healthy again. Fix the file at the path named in the banner, then relaunch or reselect the account. **Windows / WSL.** On Windows, Orca can run Codex either from your host install or from a WSL distro. Adding a WSL-hosted Codex account creates an isolated account home inside the distro (under `~/.local/share/orca/codex-accounts//home`), maps it back to the host as a `\\wsl.localhost\\...` path for auth reads, and routes launches, hot-swap, and rate-limit fetches through the selected distro. If Codex isn't installed in the target distro, the `Add account` dialog fails with an actionable message naming the distro that is missing the binary. ## Claude Code accounts The Claude account switcher "works identically — different data directory (`~/.claude`), same UX." Orca supports multiple Claude accounts and can swap between them in one click, matching the Codex flow. Switching accounts works even with live Claude sessions running: Orca holds the in-progress switch behind a guard so you don't trigger overlapping auth refreshes. Orca picks up `~/.claude` automatically, with no extra config needed. ## Headless hosts On a machine running Orca without a usable Settings UI — `orca serve` or a remote-scoped client where `Add account` is disabled — accounts are registered from the server shell: ``` orca account list orca account add --agent claude orca account add --agent codex ``` `account add` runs `claude login` / `codex login` in *that* terminal on the host, then registers the captured credentials with the local runtime. Codex uses device authorization so the browser can finish on another machine. Run these on the machine that owns the accounts — see [Remote Orca Servers](remote-servers.md). ## From the phone On the companion app, the host `Accounts` screen carries the same switcher and usage readout, including inline usage for inactive accounts and reset countdowns when a provider reports reset timestamps for its session or weekly window. Switching there switches on the paired desktop. When the active Codex account has earned **rate-limit reset** credits, the accounts screen shows how many are available and when the next one expires, plus a `Use reset` action. Confirming spends one credit for the current Codex target (host or WSL distro) and refreshes eligible rate-limit windows. The phone journals the attempt so a retry after a flaky connection does not double-spend. Outcomes include success, nothing eligible to reset, no credit left, or that a reset was already applied. See [Mobile companion](mobile-companion.md). ## Estimated cost The Stats breakdown may show `estimated cost` for known model families, including Claude 5-class and Codex GPT-5.6 rows. Rows marked `• inferred pricing` use **Orca's local price table, not a live bill from the provider**. The docs' own advice: prefer the provider console for authoritative spend. ## Reported rough edge: adding a Codex account Issue #589 reports Orca failing to find the Codex CLI when adding an account, and a second reporter on the same thread hitting `Codex account update failed. spawn EINVAL` — reported on both Windows and macOS, on Orca 1.1.25 with Codex v0.120.0. A maintainer's last comment in the raw file says "we haven't done a release yet but will do one soon. If it persists afterwards, I'll be happy to take another look," upstream closed #589 as completed on 2026-04-16 via merged PR #702. **Analysis:** the reported Orca version (1.1.25) is far behind the releases captured elsewhere in this KB, so this is most useful as a symptom shape — `spawn EINVAL` on account add points at how Orca invokes the provider CLI, not at the account data — rather than as a live limitation. ## Related pages - [Supported agents](../entities/supported-agents.md) - [Remote Orca Servers](remote-servers.md) - [Mobile companion](mobile-companion.md) - [Settings reference](../entities/settings-reference.md) - [Orca CLI](orca-cli.md) ## Sources `raw/web_community-usage-rate-limit-tracking-orca-docs.md`, `raw/web_community-hot-swap-codex-accounts-orca-docs.md`, `raw/web_community-codex-in-orca-orca-docs.md`, `raw/web_community-claude-code-in-orca-orca-docs.md`, `raw/web_community-settings-reference-orca-docs.md`, `raw/web_community-mobile-companion-orca-docs.md`, `raw/github_issue-can-t-add-codex-account-codex-cli-not-found.md`, `raw/web_community-remote-orca-servers-orca-docs.md`, `raw/web_community-orca-cli-reference-orca-docs.md`. --- title: "Ways to Run Orca" type: concept tags: [orca, deployment, remote, ssh, worktrees] created: 2026-09-09 updated: 2026-09-09 sources: ["raw/web_community-ways-to-run-orca-orca-docs.md", "raw/web_community-what-is-orca-orca-docs.md", "raw/web_community-remote-orca-servers-orca-docs.md", "raw/web_community-ssh-worktrees-orca-docs.md", "raw/github_doc-docs-reference-ssh-execution-boundary-md.md"] confidence: medium --- # Ways to Run Orca Orca is a desktop IDE for running multiple AI coding agents side by side, where every task gets its own git worktree, agent terminal, and browser tab. The docs describe four places a worktree's agents and files can actually live. Choosing between them is the single largest architectural decision when setting Orca up, because it decides who owns the running processes when your laptop goes away. ## The four modes The `Ways to run Orca` page presents these as a map, with deep dives on linked pages: | Mode | Where files and agents live | Who owns the machine | Best for | |---|---|---|---| | Local | Your desktop | You | Day-to-day coding, fast iteration | | SSH target | A remote host you connect to over SSH | You (or your team) | Dev boxes, GPU hosts, always-on VPS | | Remote Orca Server | A machine running Orca desktop or `orca serve` | You (or your team) | Persistent shared runtime, mobile, automation | | Cloud VM / per-workspace environment | A disposable VM/sandbox per workspace | Your cloud account (BYO provider) | Isolated, ephemeral agent compute | A stated constraint runs through all of them: Orca does **not** sell managed VPS hosting, and remote modes always use machines and cloud accounts you control. The product overview repeats this — Orca is "not a hosted VPS product." You can mix modes in one install: local worktrees for quick edits, SSH for a GPU box, and a recipe for CI-like isolation. ### 1. Local desktop Install Orca, open a project, create worktrees. Agents, terminals, and the browser run on the same machine as the UI. This is described as the default path for most people. ### 2. SSH targets Point Orca at any SSH host — the docs name a beefier Mac mini, a Linux VPS, a GPU box, or a cloud sandbox with SSH. Add the host under `Settings → SSH`, test the connection (git must be available on the host for repo worktrees), then pick that host under `Run on` when creating a worktree. Agents and `git worktree` run on the remote; the editor, diff, and UI stay on your laptop. The type-ahead lists ready hosts and, for hosts that are connected but not yet set up for this project, non-selectable `setup-needed` rows. See [SSH worktrees](ssh-worktrees.md) for setup, host-key policy, and what survives a disconnect. ### 3. Remote Orca Servers Keep Orca running on a machine you control — the docs list an old laptop, Mac mini, home server, cloud VPS, or team box. The **server** owns projects, worktrees, terminals, and agent processes; clients are the UI. Pair a laptop, browser client, or phone to that runtime. The documented easiest setup is Orca and Tailscale on both computers, then `Settings → Remote Orca Servers → Advertise this app as a server → New Link` on the server and `Add Server` on the client. For a headless Linux server or service-managed VM, `orca serve` is the alternative. See [Remote Orca Servers](remote-servers.md). ### 4. Cloud VMs (per-workspace environments) Each worktree can boot its own on-demand environment — a cloud sandbox, VM, or local Docker container — from a `recipe` checked into the repo (`orca.yaml` plus lifecycle scripts). Create spins it up; suspend/resume/destroy tear it down. Orca is described as a thin wrapper: your provider account, images, and billing stay yours. In the product UI this surface is labeled `Cloud VM` under `Settings → Experimental`. Providers the docs say people wire today include Vercel Sandbox, Fly, Modal, plain SSH hosts, and local Docker. Connection is either `Orca server` (the recipe starts `orca serve` and returns a pairing URL) or `SSH` (the recipe returns connection details Orca dials). Two gotchas are called out. Recipes only show up for workspace create once the `environmentRecipes` entry is on the project's `primary` checkout of `orca.yaml` — not only a feature branch; doctor and live provision can still run from any branch while you iterate on scripts. And the setup path runs through an agent: enable `Cloud VM` under `Settings → Experimental`, install or update the per-workspace environment skill if needed, then ask your agent to "Use the orca-per-workspace-env skill to set up a per-workspace environment for this repo." ## SSH targets versus Remote Orca Servers This is the comparison the docs spend the most space on, because the two look similar and behave differently: | | SSH worktrees | Remote Orca Server | |---|---|---| | Runtime owner | Laptop Orca | Remote machine (Orca desktop or `orca serve`) | | Disconnect | Agents keep running on the host; laptop reattaches | Full session state lives on the server | | Multi-client | One laptop drives the host | Laptop, web, mobile, and automation can share the same runtime | | Typical setup | Import SSH config, pick `Run on` | Share the server app or run `orca serve`, then pair with a URL | The engineering reference states the rule more sharply and adds a warning: an SSH host and a paired runtime (`orca environment`) imply opposite boundaries — the first is a dumb execution host driven by your client, the second is a peer that owns its own control plane. Registering the same machine both ways splits its worktrees across two identities, makes `terminal list` return different sets depending on `--environment`, and "reliably confuses both humans and agents." **Pick one per machine.** For work that must continue while you are offline, the same reference recommends the peer/headless-runtime model on the remote host rather than direct SSH, because its control plane is host-local. ## Choosing The docs give a short decision guide: - **Stay local** if the laptop is fast enough and agents are short-lived. - **SSH** if you already have a VPS or dev box and want agents there without installing a second Orca runtime. - **Remote Orca Server** if you want one always-on Orca runtime for mobile, browser, and automation. - **Cloud VM / per-workspace environments** if each task should get a fresh, recipe-defined sandbox that dies with the worktree. **Analysis:** The decision guide keys off *runtime ownership*, not raw compute. If the only question is "where do the CPU cycles happen," SSH answers it with less setup. The moment a second client — a phone, a browser, a scheduled automation — needs the same live session, SSH stops being sufficient, because the docs place orchestration state and the `orca` control plane on the client in that mode (see [SSH worktrees](ssh-worktrees.md)). ## Related pages - [SSH worktrees](ssh-worktrees.md) - [Remote Orca Servers](remote-servers.md) - [Mobile companion](mobile-companion.md) - [Orca CLI](orca-cli.md) - [Settings reference](../entities/settings-reference.md) ## Sources Drawn from the docs-site snapshot fetched 2026-09-09 (`raw/web_community-ways-to-run-orca-orca-docs.md`, `raw/web_community-what-is-orca-orca-docs.md`, `raw/web_community-remote-orca-servers-orca-docs.md`, `raw/web_community-ssh-worktrees-orca-docs.md`) and the repo reference `raw/github_doc-docs-reference-ssh-execution-boundary-md.md`. --- title: "What Orca Is" type: concept tags: [orca, overview, parallel-agents, worktrees, positioning] created: 2026-09-09 updated: 2026-09-09 sources: ["raw/web_community-what-is-orca-orca-docs.md", "raw/github_doc-readme-md.md", "raw/web_community-ways-to-run-orca-orca-docs.md", "raw/web_community-your-first-3-agent-session-orca-docs.md", "raw/web_community-race-three-agents-on-the-same-task-orca-docs.md", "raw/web_community-mobile-companion-orca-docs.md", "raw/web_community-how-to-use-glm-5-2-in-orca-ade-orca-docs.md"] confidence: medium --- # What Orca Is ## The one-line definition, as the docs state it The Orca docs open with: "Orca is a desktop IDE for running multiple AI coding agents side by side. Every task gets its own git worktree, its own agent terminal, and its own browser tab — so you can fan out work across Claude Code, Codex, Cursor CLI, and friends without stashing, branch-juggling, or losing flow." The project README uses a different framing for the same thing — "The AI Orchestrator for 100x builders. Run Codex, ClaudeCode, OpenCode or Pi side-by-side — each in its own worktree, tracked in one place." Orca calls itself an **ADE — Agent Development Environment**. Upstream states this directly: the `onorca.dev` homepage title is "Orca — The agent development environment", its meta description opens "Orca is the Agent Development Environment (ADE) for shipping with coding agents", and the footer of every docs page repeats the longhand. The docs' own working definition is "a desktop IDE for running multiple AI coding agents side by side." **Analysis:** the label is doing real work rather than being marketing. What distinguishes an ADE from an IDE here is the primary unit: an agent in an isolated checkout, rather than a file in a project. That is the assumption the rest of this wiki is organised around. ## The parallel-agent model The unit of parallelism is the git worktree, not the tab. From the worktrees doc: "every task gets its own on-disk copy of the repo via `git worktree`. This is what makes parallel agents safe — they never step on each other's files." The docs' hero workflow ("Your first 3-agent session") is three worktrees on the same task: 1. Add a repository; Orca reads the repo's git state and picks up your default branch as its **base ref** — the ref every new worktree branches from. 2. Create a worktree, pick a **start-from** ref, and launch an agent from the agent combobox. 3. Repeat twice more, so you have `fix-login-race` → Claude Code, `fix-login-race-2` → Codex, `fix-login-race-3` → Cursor CLI. 4. Paste the same prompt into each. "Three branches. Three diffs. Same prompt." 5. Drag a worktree's tab to the right or bottom edge of a pane to split, and watch all three. 6. Review each diff, annotate the winner, commit and push; delete the two losers — "one click removes the worktree and branch." The recipe page states the rationale plainly: "Different agents make different mistakes. Running the same task in parallel is cheaper than sequential retries and surfaces disagreement as a signal. Where three agents agree, the answer is probably right. Where they split, you've found the hard part." See [worktrees](worktrees.md) for the isolation model and [agents-and-sessions](agents-and-sessions.md) for how Orca tracks each agent's state. ## How it positions against a plain terminal or an IDE The docs are explicit about what Orca is *not*: - **Not a model.** "Orca runs agents you already use — bring your own Claude, Codex, or OpenCode subscription." - **Not a git replacement.** "Every worktree is a real git worktree. You can `cd` in and use plain git whenever you want." - **Not a hosted VPS product.** "Orca runs on your desktop by default. Remote compute uses machines and cloud accounts you control." Against a plain terminal, the difference is bookkeeping: Orca tracks agent state per session (working / waiting / done), restores tab and split layouts per worktree, and keeps a daemon that owns the PTYs so agents survive quitting the app. Against a conventional IDE, the difference is scope — the Monaco editor doc says "Orca is intentionally editor-first, not IDE-first — run type-checkers and linters in a terminal pane." There is no language-server story in these docs; there is a diff-review story. See [editing](editing.md) and [diff-review](diff-review.md). Agent support is deliberately open: "Works with **any CLI agent** — if it runs in a terminal, it runs in Orca." The built-in picker ships preconfigured entries (Claude Code, Codex, Grok, Cursor CLI, GitHub Copilot CLI, OpenCode, Gemini, Pi, and many more), with deeper integration — usage tracking, hooks, account hot-swap — noted per agent. ## Who it is aimed at "Orca is designed for people who already write code for a living and want to use AI as leverage — not as a replacement. It assumes you read diffs, care about commits, and keep a worktree tidy. If you're looking for a no-code tool, Orca is not that." ## The surfaces: desktop, mobile, remote **Desktop** is the default and the source of truth. It ships for macOS, Windows, and Linux — see [installation](installation.md). **Mobile** is a companion, not a second editor. The docs describe "an iOS/Android app that pairs with your desktop Orca and gives you a read-mostly view of running agents — agent status, recent terminal scrollback, and the controls you actually want from a phone (replying to a prompt, sleeping a worktree, reviewing source control, switching agent accounts). Pairing is one-time and the desktop is always the source of truth." The page closes the point: "The mobile app is intentionally not a full editor — it's a remote control for the desktop you already have running." **Remote** is four modes, laid out in "Ways to run Orca": | Mode | Where files and agents live | Who owns the machine | | --- | --- | --- | | Local | Your desktop | You | | SSH target | A remote host you connect to over SSH | You (or your team) | | Remote Orca Server | A machine running Orca desktop or `orca serve` | You (or your team) | | Cloud VM / per-workspace environment | A disposable VM/sandbox per workspace | Your cloud account (BYO provider) | The same doc adds the constraint that makes this a positioning claim rather than a feature list: "Orca does **not** sell managed VPS hosting. Remote modes always use machines and cloud accounts you control." Modes can be mixed in one install — "local worktrees for quick edits, SSH for a GPU box, and a recipe for CI-like isolation." ## Related pages - [installation](installation.md) — every platform path, verbatim - [worktrees](worktrees.md) — the isolation model underneath everything above - [agents-and-sessions](agents-and-sessions.md) — session lifecycle and state glyphs - [tabs-panes-and-layouts](tabs-panes-and-layouts.md) — how you watch several agents at once - [diff-review](diff-review.md) — the review half of the loop ## Sources Documentation as published on onorca.dev and the `stablyai/orca` README, fetched 2026-09-09. Claims here are single-source docs statements unless noted; confidence is medium. --- title: "Worktree Checkpoints" type: concept tags: [worktrees, checkpoints, cli, status, collaboration] created: 2026-09-09 updated: 2026-09-09 sources: ["raw/web_community-worktree-checkpoints-orca-docs.md", "raw/github_doc-skill-guides-orca-cli-md.md", "raw/web_community-orca-cli-reference-orca-docs.md", "raw/web_community-orca-cli-overview-orca-docs.md"] confidence: medium --- # Worktree Checkpoints Every Orca worktree carries a lightweight, free-text `comment` field visible in the UI — a status snapshot of what the worktree is doing right now. Agents can update it from the CLI, and the docs call it the recommended pattern for keeping human collaborators in the loop without forcing chat. ## The pattern ``` orca worktree set --worktree active --comment "reproduced auth failure; testing credential-chain fix" --json ``` That is the whole mechanism. There is no separate checkpoint object, no history, and no notification — it is one mutable string on the workspace card. The skill guide describes it the same way: "A worktree comment is the short status line on the workspace card." ## Card status Alongside the free-text comment, set the workspace card status when the phase changes: ``` orca worktree set --worktree active \ --comment "fix implemented; running integration tests" \ --workspace-status in-progress \ --json ``` Statuses are `todo`, `in-progress`, `in-review`, `completed` — **or a custom id your workspace uses**. The skill guide phrases the same list as "defaults are `todo`, `in-progress`, `in-review`, `completed`," so treat the four as defaults rather than a closed set. ## When to check in The docs list five good checkpoint moments: - Finished a meaningful slice of implementation. - Confirmed or refuted a hypothesis. - Completed a code review. - Hit a blocker (waiting on external input, upstream bug, missing access). - Transitioning from investigation to fix, or fix to verify. The skill guide compresses this to "update after a repro, fix, validation, handoff, or blocker. Keep it short and current." ## Format The docs give one formatting rule: **the first line is the action** — what just happened, where, and the status or next step. Comments can span multiple lines, with context below: ``` orca worktree set --worktree active --comment "added debounce to SearchBar onChange (src/components/SearchBar.tsx); ready for review goal: reduce redundant API calls per #298" --json ``` ## Read before you write The comment field is shared with humans, so the docs warn that it may already hold user-written context. Read it first so you don't clobber goals or constraints: ``` orca worktree current --json ``` Preserve what's still valid, drop what's stale, and weave in your update. The skill guide adds an error-handling nuance: a failed comment update is not an error to surface unless the user asked for Orca state. **Analysis:** that makes checkpoints deliberately best-effort. They are a communication channel, not a durable record — an agent should never block or retry a task because a checkpoint write failed, and a human should never treat a missing checkpoint as evidence about what the agent did. ## Where checkpoints fit against orchestration Checkpoints and [orchestration](orchestration.md) messages solve different problems and the docs keep them separate: | | Worktree comment | Orchestration `worker_done` / `heartbeat` | |---|---|---| | Audience | Humans reading the sidebar | The coordinator's inbox | | Durability | Overwritten in place | Delivered, replayed until acked | | Authority | None — informational | Settles the Task and Dispatch | | Failure handling | Not worth surfacing | Must be reported; absence is `unverifiable` | The CLI reference lists worktree comments under "Agent habits" alongside the advice to use orchestration for tracked multi-agent dispatches instead of ad hoc terminal prompts — i.e. comments are the *lightweight* half of that pair, not a substitute for the tracked half. ## Related commands Other `worktree set` fields appear in the skill guide and are useful alongside a comment: ``` orca worktree set --worktree id::: --display-name "My Task" --json orca worktree set --worktree active --workspace-status in-review --json ``` Note the worktree id form: `::`. A bare repo id is not a worktree id. See [Orca CLI](orca-cli.md) for the full selector rules. ## Related pages - [Orca CLI](orca-cli.md) - [Orca CLI reference](../entities/orca-cli-reference.md) - [Orchestration](orchestration.md) - [Notifications and inbox](notifications-and-inbox.md) ## Sources `raw/web_community-worktree-checkpoints-orca-docs.md`, `raw/github_doc-skill-guides-orca-cli-md.md`, `raw/web_community-orca-cli-reference-orca-docs.md`, `raw/web_community-orca-cli-overview-orca-docs.md`. --- title: "Worktrees as the Isolation Unit" type: concept tags: [worktrees, git, isolation, sidebar, orca-yaml] created: 2026-09-09 updated: 2026-09-09 sources: ["raw/web_community-worktrees-orca-docs.md", "raw/web_community-your-first-3-agent-session-orca-docs.md", "raw/web_community-orca-cli-reference-orca-docs.md", "raw/web_community-worktree-checkpoints-orca-docs.md", "raw/github_issue-bug-child-worktree-grouping-in-sidebar.md", "raw/github_issue-bug-worktree-in-a-monorepo-can-not-see-files-and-git-changes.md", "raw/web_community-settings-reference-orca-docs.md", "raw/web_community-ways-to-run-orca-orca-docs.md"] confidence: medium --- # Worktrees as the Isolation Unit ## Why a worktree and not a branch "Orca is worktree-native. Instead of branching and stashing on one checkout, every task gets its own on-disk copy of the repo via `git worktree`. This is what makes parallel agents safe — they never step on each other's files." The model has three parts: - Each repo has a **base ref** (usually `origin/main`). - Each worktree has a **start-from ref** — what it branches off. - Each worktree has its own branch, its own files on disk, and its own agent terminals. Everything else in Orca is scoped to that unit: "agent terminals, editor tabs, browser tabs, terminal panes all scoped to this worktree." See [tabs-panes-and-layouts](tabs-panes-and-layouts.md) and [browser-and-design-mode](browser-and-design-mode.md). Deleting a worktree "removes both the directory and the branch (with confirmation)." ## The per-feature lifecycle The docs give five phases: **Create** (task name, start-from picker, optional GitHub / Linear / Jira / GitLab link) → **Work** → **Review** (diff against the start-from ref, Annotate AI Diff, Attribution) → **Ship** (commit, push, open PR, wait on checks, all inline) → **Archive or delete**. Creation is asynchronous: "Submitting the Create Worktree dialog closes it immediately — the `git fetch` and `git worktree add` work continues in the background while you keep using Orca." The new worktree appears in the sidebar with a progress row; you can switch away, watch progress, or cancel from the in-tab panel. "If creation fails, the panel surfaces the error with a Retry." The start-from picker accepts the repo's base ref, another local branch, a specific commit SHA, or an existing remote branch (Orca will fetch and check it out). ## Making a fresh checkout usable: shared paths and copied files "A brand-new worktree is a clean checkout. Dependencies, caches, and local secrets that live in gitignored paths are missing until you recreate them." Orca closes that gap three ways: 1. **Worktree Shared Paths** (per repo, **Settings → Repository**) — "paths materialize from the primary checkout into each new worktree (APFS clone-copy on macOS when possible, otherwise a symlink)." 2. **`worktree.sharedDirectories` in `orca.yaml`** — a repo-checked-in list of *gitignored directories* to share the same way (symlink/share, not copy). "Entries must exist as directories in the primary checkout **and** be gitignored; tracked or missing paths are skipped." 3. **`.worktreeinclude` at the repo root** — a list of *gitignored files or directories to copy* (not symlink) into each new worktree. "Blank lines and `#` comments are allowed. Only **literal** paths are supported today — globs and negation are skipped with a warning. Paths that are tracked, missing, or not gitignored are not copied." Precedence, stated exactly: "`orca.yaml` shared directories **add to** the per-user Worktree Shared Paths list; they never replace it. Paths already shared/linked are not re-copied from `.worktreeinclude`." ```yaml # orca.yaml (repo root) worktree: sharedDirectories: - node_modules - .cache ``` ``` # .worktreeinclude (repo root) .env .env.local .vscode/settings.json ``` ## Branch naming "By default Orca derives the new worktree's branch name from the workspace name you type, or from the linked GitHub PR, Linear/Jira issue, or GitLab MR when the workspace is created from one of those." To set one explicitly, expand the **Advanced** drawer in the Create Worktree dialog and use the **Branch name** field (placeholder `feature/my-branch`). Important polarity: "The Branch name field is only offered when you're creating from a typed workspace name or a base branch. When the workspace is tied to a tracked work item, the branch is derived from that item — a linked GitHub PR even re-resolves the branch at submit — so Orca hides the field to avoid a silently-ignored override." Workspace names accept Slack-style shortcodes (`:rocket:`). "The display name keeps the emoji; when Orca derives a git branch name it rewrites known emoji to readable shortcodes (e.g. 🚀 → `rocket`)." Leaving the name blank names the worktree after a marine creature. ## Parent and child worktrees The **Advanced** drawer also "lets you choose an active worktree from the same repository as the new workspace's **Parent workspace**. This only nests the workspaces in Orca's sidebar; it does not change Git history or branches. Orca excludes archived workspaces and choices that would create a cycle." From the CLI: "When `worktree create` runs from inside an Orca-managed worktree, Orca records the new worktree as a child when it can infer the relationship. Pass `--parent-worktree active` to be explicit, or `--no-parent` when the new work is independent." Grouped operations follow the lineage. When a worktree has nested children (from orchestration or `worktree create` with a parent) the context menu can offer **Sleep with Descendants (N)** and **Delete with Descendants…**. Note the hedges: sleep with descendants "closes active panels on the selected workspace and every validated nested child in the same project, repo, and host — only workspaces with live terminals or browser tabs are targeted for sleep," and "Stale lineage links, cycles, and children across host or repo boundaries are excluded." **Resolved upstream (closed 2026-09-04):** issue #11007 reported that child worktrees stopped rendering as an indented group under their parent card after an update — each child "now appears looking just like the main worktree," identifiable only by a **Remove from Parent** entry in the right-click menu, and new children are created at the top of the list rather than below the parent. A maintainer replied "it might be some data persistent issue during update… Looking into fixing it ASAP!" The same thread notes that **Set parent worktree** "only shows me other worktrees of the same project" — consistent with the docs' "from the same repository" wording, but a limitation for people who parent across repos. ## Sidebar organization "The sidebar groups worktrees by **project** by default." The header has its own filter input, separate from global search. The filter menu groups host and project scope under a shared **Show** section, then hide toggles for: **Sleeping** workspaces (each project's entry-point / main workspace stays visible under this filter), **Except default branch** (only while *Hide sleeping* is on), **Default branch** workspaces, **Automation-created**, **CLI-created** (created via `orca worktree create`; hover the card for an **Orca CLI** provenance detail), **Other-client** workspaces (shared Remote Orca Server), and **Detached HEAD** workspaces. Text search and the Worktree Jump Palette (`Cmd-J`) "still reach workspaces hidden only by these filters once you type a query." Other sidebar mechanics worth memorizing: - Pin a worktree to the top of its project; right-click for archive / sleep / delete. - Keyboard delete: hover a worktree or folder workspace and press `Cmd-Shift-Backspace` (macOS) or `Ctrl-Shift-Backspace` (Windows / Linux); "the normal confirmation dialog still appears." - Hold `Cmd` (`Ctrl` on Linux/Windows) while clicking to multi-select, or `Shift` for a contiguous range; right-clicking any selected worktree applies the action to the whole selection. - Double-click a worktree title to rename inline; double-clicking elsewhere on the card opens the full edit dialog. ## Cleanup and preserved branches **Resource Manager → Clean up workspaces** lists local worktrees, main worktrees, folder workspaces, and workspaces on disconnected SSH hosts, with status, recent activity, size, Git state, and linked review before you select anything. Bulk deletion has one safety valve: "If git refuses to drop a local branch because it may contain unmerged commits, Orca keeps those branches and shows a toast such as **Review N Branches**." Unselected branches stay in the repository; "workspace folders are not restored." ## Checkpoints: the free-text comment field "Every Orca worktree carries a lightweight, free-text **comment** field visible in the UI." Agents update it from the CLI: ``` orca worktree set --worktree active --comment "reproduced auth failure; testing credential-chain fix" --json ``` Card status can move with it: ``` orca worktree set --worktree active \ --comment "fix implemented; running integration tests" \ --workspace-status in-progress \ --json ``` Statuses: `todo`, `in-progress`, `in-review`, `completed` "(or a custom id your workspace uses)." Read before writing with `orca worktree current --json` so an agent does not clobber human-written goals. ## Escape hatches and pitfalls Plain git still works: "Every Orca worktree is a real git worktree. You can open a terminal in it and use `git status`, `git rebase`, `git cherry-pick`, and anything else — Orca picks up the changes next render." Worktrees you create yourself with `git worktree add` "stay external until you show them in Orca." A repo that hides them shows a **hidden worktrees** card; click it to open **Non-Orca worktrees** and choose **Show**. Global defaults for external-worktree sources (Claude Code worktrees, GSD worktrees, other locations, custom absolute-path locations) live under **Settings → General → Workspace**; "new global custom roots start hidden." **Multi-repo pitfall (single-source, user report):** issue #6357 describes importing a non-git parent folder containing four independent repos as a project group, then finding that "the folder-workspace task ran with cwd = the original imported folder… so the agent edited directly on each repo's primary branch… instead of creating isolated worktrees," while a per-repo task did create a real worktree. The same report saw `selector_not_found` errors in the diff and file viewers for that setup. This is a bug report on Orca 1.4.98, not documented behavior — treat folder workspaces over multi-repo groups as the case to verify before trusting isolation. ## Related pages - [agents-and-sessions](agents-and-sessions.md) — what runs inside a worktree - [tabs-panes-and-layouts](tabs-panes-and-layouts.md) — `Cmd-J` and the per-worktree pane tree - [diff-review](diff-review.md) — the diff is scoped to the start-from ref - [hooks-and-memory](hooks-and-memory.md) — worktree setup hooks that run after create ## Sources Worktrees doc, first-session walkthrough, CLI reference, worktree-checkpoints doc, settings reference, and GitHub issues #11007 and #6357, all as of 2026-09-09. --- title: "Orca CLI Reference" type: entity tags: [cli, reference, commands, flags, automation] created: 2026-09-09 updated: 2026-09-09 sources: ["raw/web_community-orca-cli-reference-orca-docs.md", "raw/web_community-orca-cli-overview-orca-docs.md"] confidence: medium --- # Orca CLI Reference Every command, subcommand, and flag documented on the Orca CLI reference page as of the docs snapshot fetched **2026-09-09**, plus the small number that appear only on the CLI overview page (marked *overview only*). Nothing here is reconstructed from memory — if a flag is absent below, it was absent from those two pages. Flags evolve with the binary. The docs' own instruction is to run `orca linear --help`, `orca --help`, or `orca skills get ` for the version-matched list. For conceptual framing — install, registration, executable naming, auth — see [Orca CLI](../concepts/orca-cli.md). Orchestration commands are documented separately on [Orchestration](../concepts/orchestration.md) and do **not** appear on the CLI reference page. ## Verifying the runtime ``` command -v orca orca status --json orca open --json ``` Use `--json` when another tool will parse the result; human-readable output is for quick terminal checks. ## Selectors Most commands accept selectors instead of requiring long IDs: ``` orca repo show --repo id: --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 ``` `active` and `current` resolve to the enclosing Orca-managed worktree from the shell's current directory or terminal context. Use explicit selectors in scripts that may run outside the target worktree. For remote runtimes, prefer full server-side selectors such as `id:::` or `path:`, because the local shell's current directory may not exist on the runtime host. ## Choosing a host ``` orca host list --json ``` The result includes this machine, its registered SSH targets, and paired Remote Orca Servers. Host flags: | Flag | Targets | |---|---| | `--host local` | this machine | | `--host ssh:` | an SSH target | | `--environment ` | a paired server | SSH labels and paired-server names also resolve when they are unique; use the IDs from `host list` when names collide. If you put a machine name on the wrong selector, Orca reports the matching machine and the flag to use instead of returning an empty result. ## Runtime commands ``` orca open --json orca status --json orca serve --port 6768 --pairing-address 100.64.1.20 --json ``` `orca serve` starts a 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`. ## Repos ``` orca repo list --json orca repo add --path /abs/path/to/repo --json orca repo show --repo id: --json orca repo set-base-ref --repo id: --ref origin/main --json orca repo search-refs --repo id: --query main --limit 10 --json ``` Set the repo base ref before creating lots of worktrees so new tasks branch from the right place by default. ## Worktrees ``` orca worktree list --repo id: --json orca worktree ps --json orca worktree current --json orca worktree show --worktree active --json orca worktree create --repo id: --name fix-login --json orca worktree create --name child-task --agent codex --prompt "Investigate the flaky login test" --json orca worktree set --worktree active --comment "reproduced failure; testing token refresh fix" --json orca worktree rm --worktree id: --force --json ``` *Overview only:* ``` orca worktree create --repo id: --name my-task --issue 123 --json orca worktree set --worktree active --comment "reproduced bug" --json orca worktree rm --worktree id: --force --json ``` ### Parentage When `worktree create` runs from inside an Orca-managed worktree, Orca records the new worktree as a child **when it can infer the relationship**. Pass `--parent-worktree active` to be explicit, or `--no-parent` when the new work is independent. ### Agent startup flags ``` 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 ``` `--agent` launches the selected agent in the first terminal. `--prompt` sends initial work to that agent. `--setup run|skip|inherit` controls repo setup hooks; `inherit` follows the repo policy. ## Terminals ``` orca terminal list --worktree active --json orca terminal show --terminal --json orca terminal read --terminal --json orca terminal read --terminal --screen --json orca terminal read --terminal --cursor --limit 1000 --json orca terminal send --terminal --text "continue" --enter --json orca terminal wait --terminal --for tui-idle --timeout-ms 300000 --json orca terminal create --worktree active --title "tests" --command "npm test" --json orca terminal split --terminal --direction horizontal --command "npm run dev" --json orca terminal rename --terminal --title "runner" --json orca terminal switch --terminal --json orca terminal close --terminal --json ``` *Overview only:* ``` orca terminal list --json orca terminal read --json orca terminal send --text "continue" --enter --json orca terminal wait --for tui-idle --timeout-ms 30000 --json orca terminal create --worktree path:/projects/app --command "npm test" --json orca terminal split --direction vertical --command "npm run dev" --json ``` Omit `--terminal` to target the active terminal in the current worktree. Read before sending when you are not sure what the terminal is waiting for. ### Host identity in `terminal list` `terminal list` reports each terminal's `executionHostId` **when Orca can verify it**, plus a result-level `hostScope` with covered and omitted host IDs. Treat a missing host identity or scope as `unverifiable`, **not** local. A missing terminal is evidence that it exited **only** when its execution host is listed in `hostScope.hostIds`. ### Reading output By default `terminal read` returns the accumulated output stream with terminal escapes stripped, so programs that redraw lines can appear as stacked fragments. Use `--screen` when you need the currently rendered frame; the response's `source` identifies `stream`, `screen`, or `screen-unavailable`. Screen reads have no history to page, so **`--screen` and `--cursor` are mutually exclusive**. For long output, use cursor reads: save `nextCursor` from one stream read, then pass it back with `--cursor` to fetch only new output. ## Files ``` 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 ``` Paths are relative to the selected worktree. `open-changed` reads git status and opens changed files in edit, diff, or both modes. Use `--worktree ` when the shell's current directory is not inside the target worktree. ## Built-in browser These control Orca's embedded browser tab for the selected worktree. They do **not** control Chrome, Safari, or the Orca desktop UI. Snapshot → act → snapshot: ``` 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 protected]" --worktree active --json orca wait --text "Welcome" --worktree active --json orca screenshot --worktree active --json ``` Refs such as `@e3` come from `snapshot`. Re-snapshot after navigation, tab switches, clicks that change the page, and any stale-ref error. Tab and capture commands: ``` orca tab list --worktree active --json orca tab create --url http://localhost:3000 --worktree active --json orca tab switch --index 1 --worktree active --json orca capture start --worktree active --json orca console --limit 50 --worktree active --json orca network --limit 50 --worktree active --json orca full-screenshot --worktree active --json orca pdf --worktree active --json ``` Use `orca exec --command "" --json` **only** for browser actions that do not have a typed Orca command yet. Device emulation: ``` orca set device --name "iPhone 12" --worktree active --json orca screenshot --worktree active --json ``` *Overview only* — browser profiles isolate tab session state (cookies, local storage, logged-in identities). The CLI exposes profile commands under `orca tab profile`: ``` orca tab profile list --json ``` then use `create`, `set`, `clone`, or `use-default` as needed. ## Desktop computer use ``` orca computer permissions --json orca computer list-apps --json orca computer get-app-state --app com.apple.Safari --json orca computer click --app com.apple.Safari --element-index 12 --json orca computer paste-text --app com.apple.Safari --text "hello" --json ``` The CLI reference lists only these five. The fuller command surface — `capabilities`, `list-windows`, `set-value`, `type-text`, `press-key`, `hotkey`, `scroll`, `drag`, `perform-secondary-action`, and their flags — is documented on [Computer use](../concepts/computer-use.md), sourced from the computer-use docs page and skill guide. ## Mobile emulator These control iOS Simulator devices through Orca's worktree-scoped bridge. The docs say to use them instead of raw `serve-sim` or `simctl` when an agent is operating from inside Orca, so lifecycle and active-device state stay attached to the current worktree. ``` orca emulator list --worktree active --json orca emulator attach "" --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 ``` Coordinates are normalized from `0` to `1`. Prefer `tap` for single taps, and use `gesture` for drags or multi-step touch input. Pass `--device ` or `--emulator ` when a script must target a specific simulator instead of the worktree's active emulator. ## Linear The `orca linear` surface is what agents use via the `orca-linear` skill (legacy install name `linear-tickets` still works). Prefer `--json`. Linked worktrees resolve with `--current`. ### Read ``` orca linear issue --current --full --json orca linear issue ENG-123 --comments --children --relations --activity --json orca linear search "auth bug" --workspace all --json orca linear list --filter assigned --limit 10 --json orca linear list-issues --team ENG --state started --assignee me --json orca linear list-issues --query auth --updated-at -P7D --cursor --workspace --json orca linear team list --json orca linear team states --team ENG --json orca linear team labels --team ENG --json orca linear project list --query launch --json ``` `--full` expands comments, children, attachments, relations, and activity. Section flags (`--comments`, `--children`, `--attachments`, `--relations`, `--activity`) work individually. ### MCP-style write Omit id/`--current` to create; creating requires `--team` and `--title`. ``` orca linear save-issue --team ENG --title "Fix auth" --priority high --json orca linear save-issue ENG-123 --state "In Progress" --assignee me --json orca linear save-issue --current --project null --due-date null --json orca linear relation add ENG-1 --related ENG-2 --type blocks --json orca linear relation remove ENG-1 --related ENG-2 --type related --json ``` `save-issue` labels **replace** the full label set (Linear MCP `save_issue` semantics). Literal `null` clears assignee, estimate, due date, project, or parent. ### Field helpers (still valid) ``` orca linear status set --current --to "In Progress" --json orca linear assignee set --current --me --json orca linear priority set ENG-123 --to high --json orca linear estimate set --current --to 3 --json orca linear due-date set --current --to 2026-08-01 --json orca linear label add --current --label backend --json orca linear comment add --current --body "Investigating regression" --json orca linear attach --current --url https://example.com/repro --title "Repro" --json orca linear create --title "Flaky login test" --team ENG --priority high --json ``` Run `orca linear --help` or `orca skills get orca-linear` for the version-matched list. Pass an explicit issue id (e.g. `ENG-123`) when a script may run outside an Orca-linked worktree. ## Skills (local, no runtime required) ``` orca skills list orca skills get orca-cli orca skills get orchestration --full orca skills install --skill orca-cli --skill orchestration orca skills install --all --dry-run orca skills update --all ``` `install` / `update` shell out to the same `npx skills` commands Settings uses. **They do not contact the Orca runtime.** See [Skills and MCP](../concepts/skills-and-mcp.md) for the full flag set, including `--agent`, `--global`, `--local`, and `--dry-run` semantics. ## Account (host-local runtime) On a headless host running Orca (`orca serve` or the desktop app), add managed Claude/Codex accounts when the remote client cannot use `Add account` — remote runtime scope disables that button: ``` orca account list orca account add orca account add --agent codex ``` Bare `orca account add` is Claude by default. `account add` runs `claude login` / `codex login` in **this** terminal on the host, then registers the captured credentials with the local runtime. Codex uses device authorization so the browser can finish on another machine. Run these on the machine that owns the accounts — not through a client-only remote session. ## Artifacts Publishes HTML or Markdown through the signed-in Orca account. Viewing a public link does not require sign-in; create/list/update/delete do. **Publishing is off by default** — a human must enable `Settings → Artifacts → Allow publishing public artifact links` on the device, and there is **no CLI flag that grants the gate**. `list`, `unshare`, and `delete` stay available so you can audit or revoke links after turning publishing off. ``` orca artifacts share ./report.html --json orca artifacts share ./notes.md --json orca artifacts update ./notes.md --json orca artifacts unshare ./notes.md --json orca artifacts list --json orca artifacts list --cursor --json orca artifacts delete --json ``` Rules: - Accepted files: `.html`, `.htm`, `.md`, `.markdown`. - Shared artifact content is limited to **10 MiB** per file. - `share` stores the edit token in the active Orca profile and does not print it. - `update` / `unshare` resolve by the same local path and profile that originally shared the file. - `list` is paged (`nextCursor` → `--cursor`). `delete` takes the artifact id from `list` and does not need the original file. - Relative HTML assets are **not** uploaded — share self-contained HTML or absolute asset URLs. - Denied publish/update fails with `artifact_sharing_disabled`; fix Settings instead of retrying. The desktop equivalents are `Share as artifact` on an open local HTML or Markdown file, and the sidebar `Artifacts` page. ## Automations, environments, and hooks Scheduled prompts: ``` orca automations list --json orca automations create --name "Daily review" --trigger daily --time 09:00 --prompt "Review open changes" --provider codex --repo id: --disabled --json orca automations run --json ``` The reference lists only these three; the full automations flag set (`--trigger`, `--time`, `--timezone`, `--workspace`, `--project`, `--host`, `--project-host-setup`, `--source-context`, `--precheck`, `--reuse-session`, `--fresh-session`, `--missed-run-grace-minutes`, `--enabled`, plus `show`, `edit`, `remove`, `runs`) is documented on [Scheduled automations](../concepts/scheduled-automations.md). Remote runtime environments: ``` orca environment add --name work-laptop --pairing-code "orca://pair?code=..." --json orca environment list --json orca environment rm --environment --json ``` Agent status hooks: ``` orca agent hooks status --json orca agent hooks on --json orca agent hooks off --json ``` ## Agent habits The reference closes with five rules: - Prefer `--json` for automation and agent calls. - Prefer selectors over parsing UI labels. - Read terminal state before sending input unless the next input is obvious. - Use worktree comments for progress checkpoints — see [Worktree checkpoints](../concepts/worktree-checkpoints.md). - Use [Orchestration](../concepts/orchestration.md) for tracked multi-agent dispatches instead of ad hoc terminal prompts. ## Related entities - [Supported agents](supported-agents.md) — what `--agent` and `--provider` can name - [Settings reference](settings-reference.md) — where the CLI is registered and where publishing is gated ## Sources `raw/web_community-orca-cli-reference-orca-docs.md` (primary) and `raw/web_community-orca-cli-overview-orca-docs.md` for the entries marked *overview only*. --- title: "Settings Reference" type: entity tags: [settings, configuration, reference, panes, shortcuts] created: 2026-09-09 updated: 2026-09-09 sources: ["raw/web_community-settings-reference-orca-docs.md", "raw/web_community-install-orca-docs.md", "raw/web_community-ssh-worktrees-orca-docs.md", "raw/web_community-agent-hibernation-orca-docs.md", "raw/web_community-agents-sessions-orca-docs.md"] confidence: medium --- # Settings Reference ## Overview Orca's settings are grouped into panes, all searchable with `Cmd-,` then typing a keyword. This page transcribes the settings-reference page as of the docs snapshot fetched **2026-09-09**, pane by pane, with key names exactly as the docs write them. Where another docs page adds a value the settings page omits (a default, a range), that is noted inline. ## General - **Orca CLI** — register the bundled command-line tool for shells and agents. (Note: the CLI reference page instead says to register the CLI under `Settings -> Experimental -> CLI`. See [Orca CLI](../concepts/orca-cli.md).) - **Updates** — check for and install updates. Modifier clicks on `Check for Updates`: | Modifier | Effect | |---|---| | `Shift+click` | Include the latest `RC` prerelease | | `Cmd+click` (macOS) / `Ctrl+click` (Windows/Linux) | Latest `perf`-tagged prerelease | | `Option+click` (macOS only) | Pick a `validated local macOS build` (compatibility-checked). Failures surface as "Could Not Use Local Build" with `Choose Another Build`. | The install page adds context: Orca auto-updates by default, tracking the `stable` channel, and there is **no permanent in-app opt-in for the RC channel** — the modifier clicks are the mechanism, and they also work from the app / Help menu. - **Open in menu** — choose apps on the worktree `Open in` menu. VS Code / Insiders enable `Remote SSH` open for SSH worktrees; other editors remain local-path only. - **UI zoom** — per-install UI scale. - **Default new-worktree name** — custom prefix or marine creatures. - **Editor Word Wrap** — default wrap for file editors (**on by default**). Toggle from a file tab's `⋯` menu or `Alt+Z`. Separate from `Diff Word Wrap`. ## Appearance - Theme, accent color, density. - Font family for UI; editor font is opt-in (empty = follow terminal font; set a value to override file editors and diffs only). - Editor minimap toggle. - Status bar toggles, including `Resource Manager` (CPU/memory/sessions, daemon controls, workspace disk scans). - **Usage percentages** — show provider limits as `% used` or `% remaining` on the status-bar roster. - **App Icon** — cycle between Classic, Watercolor, and Blue for the icon shown in the Dock and window switcher. - **Language** — primary Interface control. Switch between System (follows the OS), English, 中文（简体）, 한국어, 日本語, or Español. Settings search also matches native words for "language" (语言 / 語言 / 언어 / 言語 / Idioma) so you can find Language while the UI is still in English. ## Git - Default base ref resolver. - Commit signing options. - Editor for external git tools. - **Auto-Rename Branch From Work** — rename Orca-generated creature branches after an agent starts work. - **GitHub API Budget** — remaining REST (core), Search, and GraphQL quota from the local `gh` CLI. Useful when PR checks or Tasks stop refreshing. ## Terminal - Font, theme, cursor style, padding. - Ghostty import. - **Warp theme import** — bring in Warp YAML themes with `Import themes from Warp` (auto-discovers Warp's themes folder per OS) or `Import from YAML` for any folder of Warp-format theme files. - **JIS Yen (¥) to Backslash (\\)** for macOS Japanese keyboards. - **Windows default shell** (PowerShell or CMD). The install page notes "Most users want PowerShell." - **Allow TUI Clipboard Writes (OSC 52)** — **on by default**. Lets Zellij, tmux, Neovim, fzf, Grok (and similar) write the system clipboard over the PTY, including over SSH. Turn off if you prefer the older lockdown. ## Quick Commands - Saved terminal commands and agent-prompt presets, scoped globally or to a project. Each row has a copy control for the command body. - Scope filters for reviewing and editing the command list. The same list syncs to the mobile companion — see [Mobile companion](../concepts/mobile-companion.md). - With remote or multi-host setups, commands are grouped by the Orca host that owns them (`Saved on`). Host ownership is separate from Global/Project scope **and** from where the command runs. ## Agents - **Installed agents** — detected CLIs you can enable or disable, so launch menus only show the CLIs you want to use. - **Agent Permissions** — choose `Yolo` for fewer CLI permission prompts, or `Manual` to keep each agent's own approval flow **for agents you haven't customized**. - Claude and Codex account lists. - Startup hooks per agent. - **Agent status hooks** — show working / waiting / done states in Orca. The toggle takes effect **without restarting the app** (including the Windows WSL hook relay). CLI: `orca agent hooks on|off|status`. - **Keep computer awake** — `On` (stay awake continuously), `Agent` (stay awake while an agent is working), or `Off`. The same control lives on the desktop status bar as `Caffeinate` (coffee icon). **Hidden on paired web clients.** - **Skill freshness** — the Agents pane and skill cards still show full status. Sidebar navigation only badges skills that need action (`Update available`, `Needs attention` / review); healthy, loading, and optional not-installed rows stay quiet. `Update` in the dialog refreshes global skills in the background (no terminal); progress appears on the status bar, and closing the dialog does not cancel the run. ## Browser - Profiles (see Browser-use profiles). - **Default Zoom** — zoom level applied to newly opened browser tabs (per-tab adjustments via Cmd-wheel are remembered separately). - Design Mode defaults. - Devtools opt-in. - **Remote server workspaces** — choose `This device` to render new paired-runtime browser pages on this desktop, or `Server (streamed)` to render them on the server. Traffic **always** goes through the remote server, and the choice applies to **new pages only**. - **Browse through SSH workspace hosts** — send browser traffic and DNS through each workspace's SSH host. Turn it off to browse from this device instead. - **Link Routing** — open http(s) links from the terminal, markdown, and editor in Orca's browser or the system browser. Nested `Hold Shift…` inverts that default for one click (`⇧⌘-click` / `Shift+Ctrl+click`). - **Show terminal link actions** — **on by default**. A plain click on a terminal link opens a compact action popover. Turn off to require `⌘`-click / `Ctrl`-click. - **Default Search Engine** — used when you type non-URL text in the browser address bar or the `new-tab omnibox`. ## Artifacts - **Orca account** — sign in (same account family as Orca Relay) to publish and manage shared files. - **Allow publishing public artifact links** — **off by default**. Device-wide gate: when on, you, agents, and the `orca` CLI on this machine can upload HTML/Markdown up to **10 MiB** and mint public view links. Turning it off does **not** delete existing links. - **Show Artifacts** / sidebar shortcut — open the Artifacts list to search, preview, copy, or delete account-owned links. - **Ask Before Deleting Artifacts** — optional confirmation before breaking a public link. - Share from an open local HTML page or Markdown editor with `Share as artifact`, or via `orca artifacts …` — see [Orca CLI reference](orca-cli-reference.md). ## Integrations - GitHub OAuth. - Linear API token. - **Jira** — Cloud (email + API token) or self-hosted Server/Data Center (PAT or username/password). - **Bitbucket Cloud** — `Connect` with `Email & API token` (default) or an `Access token`. Orca verifies the credential before saving. `ORCA_BITBUCKET_*` environment variables **take precedence and hide Connect / Disconnect**. Saved credentials stay on this machine — on a Remote Orca Server, set the env vars on the server instead. - **MiniMax** — paste a MiniMax session cookie (from `platform.minimax.io/console/usage`) to enable local usage and rate-limit tracking for the MiniMax CLI. Optional group ID and usage models fields override the defaults picked from the cookie. - **MCP servers** — see [Skills and MCP](../concepts/skills-and-mcp.md). ## Notifications - Agent-finished: system, sound, chip. - Custom desktop notification sound per category. - PR check failures. - Update available. ## Voice - **Enable Voice Dictation** — requires microphone permission (macOS may open Privacy & Security). - **Microphone** — pick which input device dictation uses. Defaults to the system mic. If the chosen mic is unplugged or missing, Orca falls back to the system default and shows a non-blocking notice. - **Dictation mode** — `Toggle` (press shortcut to start/stop) or `Hold` (hold shortcut to talk). - **Speech Model** — download/select an on-device model, or use cloud OpenAI models after pasting an API key: - `Parakeet TDT v3` (recommended) — multilingual European languages, offline. - `Parakeet TDT v2` — English, faster. - `Zipformer` family — bilingual ZH+EN streaming; streaming EN/ZH; `Zipformer Streaming KO` (Korean). - `Paraformer Bilingual` — Chinese dialects + English. - `Parakeet TDT-CTC JA` — Japanese. - `SenseVoice` — ZH / EN / JA / KO / Cantonese with auto language detection. - `Whisper Tiny` — 90+ languages, lower accuracy. - `GPT-4o mini / GPT-4o Transcribe` — cloud; needs OpenAI key under the same pane. - While listening, a `Listening…` pill shows a `Stop` control; in toggle mode the tooltip also shows the dictation shortcut. ## SSH - SSH worktrees, targets, passphrases, default identity file. - Advanced: proxy / jump host; **`Reuse SSH connection for faster setup`** (system OpenSSH multiplexing; **default on**). - Kerberos hosts: `GSSAPIAuthentication` from OpenSSH config drives system OpenSSH auth. The SSH page adds detail this pane omits: targets are added with `Add Target` in a modal, `Test` verifies connectivity before `Save`, passphrases are held in memory for the life of the Orca session with an opt-in longer TTL, and connection reuse should be turned off only for hosts whose SSH policy rejects multiplexed sessions. See [SSH worktrees](../concepts/ssh-worktrees.md). ## Remote Orca Servers - Pair and connect to remote Orca runtimes. - Advertise this desktop app as a server and create revocable access links. - Advanced default runtime selection for server-routed projects, terminals, and provider checks. The remote-servers page names the specific controls: `Advertise this app as a server` → `New Link` → `Connection address` → `Generate Access Link` → `Pair another Orca client`; `Add Server` on the client; `Shared Server Access` for revoking grants; and `Advanced → Active Server` for the default routing. See [Remote Orca Servers](../concepts/remote-servers.md). ## Shortcuts Full keymap — every binding remappable. | Action | Default | |---|---| | `Toggle Sleeping Workspaces` | **ships unbound** | | `Toggle Workspace Board` | **ships unbound** (existing bindings for `workspace.openBoard` continue to work) | | Close all editor tabs | `Cmd+Option+W` (macOS) / `Ctrl+Alt+W` (Windows / Linux) | | Next/previous tab across all types (new installs) | `Cmd+Shift+]` / `Cmd+Shift+[` (Ctrl on Linux/Windows) | | Same-type next/previous (new installs) | `Cmd+Option+]` / `Cmd+Option+[` | | Previous recent tab (new installs) | `Ctrl+Tab` | | `Add Review Note` | `Cmd+Shift+A` (macOS) / `Ctrl+Shift+A` (Windows / Linux) | | `Send Review Notes to Agent` | **ships unbound** | | `Delete workspace` | `Cmd+Shift+Backspace` (macOS) / `Ctrl+Shift+Backspace` (Windows / Linux) | Existing installs keep customized tab-navigation overrides under `~/.orca/keybindings.json`. For `Delete workspace`, hover the sidebar workspace you mean to delete; Orca still asks for confirmation. The agents-and-sessions page adds one more unbound entry: `Toggle Agent Dashboard` has no default binding and works while a terminal, editor, or browser tab has focus. ## Repository - Per-repo base ref and hooks. - Auto-run commands on worktree create. - Repo icons for the sidebar: choose an icon, full searchable emoji picker, uploaded image, website favicon, or GitHub avatar, then pick a preset or custom hex badge color. - Source Control AI overrides for commit messages, pull request details, and branch names. - **Worktree Shared Paths** — gitignored paths to materialize from the primary checkout into each new worktree (APFS clone-copy on macOS when possible, otherwise symlink). Complements repo-checked-in `worktree.sharedDirectories` in `orca.yaml` and `.worktreeinclude`. ## Floating Workspace - **Enable Floating Workspace** — global surface for terminal, browser, and markdown tabs that are **not** tied to a repo worktree. - **Terminal Directory** — start directory for new floating terminal tabs (`~` = home). - **Toggle Button Location** — where the floating-workspace toggle appears; the keyboard shortcut works regardless of button placement. ## Plugins (Experimental) - **Plugin system** — `Settings → Plugins`. Turn the system on, then review and enable each plugin individually. **Nothing runs until you consent.** - **Marketplaces** — add a git marketplace source, browse plugins, preview capabilities (panels, commands, language packs, VM recipes), install, update, or roll back. - Plugin workers **always run on this computer**; SSH workspace actions still route through Orca. - Capability and API shapes may change; treat third-party plugins as untrusted software. ## Experimental Features not yet stable — behavior may change. - **Activity Page** — Slack-style worktree feed for agent events. - **Compact worktree cards** — hide redundant second lines in the sidebar while the layout is still experimental. - **Agent hibernation** — pause idle background agents and auto-resume them on reopen. The hibernation page adds the tuning control `Hibernate after`, with a **default of 30 minutes** and a range of **1 minute to 24 hours**, whose clock starts from the agent's last `done` update and resets on any keystroke, new output, or return to the terminal tab. - **Agent Dashboard** — kanban of Needs You / Working / Done agents (optional Idle), with search and project/workspace/PR filters; open in-window or as a pop-out. `Show idle agents` lives on the dashboard board settings control, **not here**. - **Chat UI** — optional chat surface on supported agent terminals. - **Cloud VM** — show setup controls and workspace `Run on` targets for repo-owned, on-demand environments (cloud sandboxes, VMs, or local Docker). Setup guide and recipe install live under this experimental toggle. See [Ways to run Orca](../concepts/ways-to-run.md). ## Related entities - [Orca CLI reference](orca-cli-reference.md) - [Supported agents](supported-agents.md) Related concepts: [SSH worktrees](../concepts/ssh-worktrees.md), [Remote Orca Servers](../concepts/remote-servers.md), [Skills and MCP](../concepts/skills-and-mcp.md), [Notifications and inbox](../concepts/notifications-and-inbox.md), [Usage and rate limits](../concepts/usage-and-rate-limits.md). ## Sources `raw/web_community-settings-reference-orca-docs.md` (primary), with additions from `raw/web_community-install-orca-docs.md`, `raw/web_community-ssh-worktrees-orca-docs.md`, `raw/web_community-agent-hibernation-orca-docs.md`, and `raw/web_community-agents-sessions-orca-docs.md`. --- title: "Supported Agents" type: entity tags: [agents, drivers, claude-code, codex, cursor] created: 2026-09-09 updated: 2026-09-09 sources: ["raw/web_community-supported-agents-orca-docs.md", "raw/web_community-claude-code-in-orca-orca-docs.md", "raw/web_community-codex-in-orca-orca-docs.md", "raw/web_community-cursor-cli-in-orca-orca-docs.md", "raw/web_community-how-to-use-glm-5-2-in-orca-ade-orca-docs.md", "raw/web_community-agent-hibernation-orca-docs.md", "raw/web_community-agent-session-history-orca-docs.md", "raw/web_community-agents-sessions-orca-docs.md", "raw/github_doc-skill-guides-orca-cli-md.md", "raw/github_issue-bug-windows-grok-agent-hooks-flash-a-visible-console-and-ste.md", "raw/github_issue-other-claude-code-agent-teams-spawn-hidden-tmux-sessions-ins.md", "raw/github_issue-bug-antigravity-cli-does-not-respond-to-navigation-keys-in-o.md", "raw/web_community-settings-reference-orca-docs.md", "raw/web_community-orca-cli-reference-orca-docs.md"] confidence: medium --- # Supported Agents ## Overview Orca works with **any CLI agent** — the agent combobox just launches a process in a terminal. The list below is the set that ships **preconfigured in the built-in agent picker** with one-click launch/setup; deeper hooks, status, usage tracking, and account switching are noted where supported. An agent started by typing its binary by hand rather than through the combobox may show no status indicator at all. ## The picker roster Transcribed from the supported-agents page as of 2026-09-09. The "Notes" column is the docs' own capability shorthand. | Agent | Notes | Docs | |---|---|---| | Claude Code | Deep integration: usage, hot-swap, hooks | Anthropic | | Claude Agent Teams | Disabled by default — enable under Settings → Agents to launch via `orca claude-teams` with native panes for each teammate | Anthropic | | Codex | Deep integration: usage, hot-swap | OpenAI | | Grok | Auto-setup | xAI | | GitHub Copilot CLI | Auto-setup | GitHub | | OpenCode | Auto-setup, status | OpenCode | | Pi | Auto-setup, hooks, status | Pi | | OMP | Auto-setup, hooks, status | OMP | | Prime Agent | Auto-setup, hooks, status, session history | Prime Intellect | | Gemini | Auto-setup | Google | | Antigravity | Auto-setup, hooks, status | Google | | Ante | Auto-setup, status | Ante | | Aider | Auto-setup | Aider | | Goose | Auto-setup | Block | | Amp | Auto-setup | Amp | | Kilocode | Auto-setup | Kilo | | Kiro | Auto-setup | Kiro | | Charm Crush | Auto-setup | Charm | | Auggie | Auto-setup | Augment | | Autohand | Auto-setup | Autohand | | Cline | Auto-setup | Cline | | Codebuff | Auto-setup | Codebuff | | Command Code | Auto-setup, status | Command Code | | Continue | Auto-setup | Continue | | Cursor CLI | Deep integration | Cursor | | Devin | Auto-setup | Devin | | Droid (Factory) | Auto-setup, hooks, status | Factory | | Kimi | Auto-setup | Moonshot | | Mistral Vibe | Auto-setup | Mistral | | MiniMax | Auto-setup, usage tracking, rate-limit tracking | MiniMax | | Qwen Code | Auto-setup via the installed `qwen` executable | Qwen | | Rovo Dev | Auto-setup | Atlassian | | Hermes | Auto-setup | Nous | | OpenClaw | Auto-setup | OpenClaw | | Trae | Auto-setup via `traecli` (TRAE CN CLI) | Trae | ## Characteristics ### The permissions default Orca pre-fills each supported CLI's permission-bypass flag for new launches: - `--dangerously-skip-permissions` for Claude - `--dangerously-bypass-approvals-and-sandbox` for Codex - `--yolo` for Gemini / Cursor / Crush / Kimi / Rovo Dev / Hermes / GitHub Copilot / Command Code - plus the equivalent flag for every other agent that exposes one The stated reasoning: worktrees are disposable, so an agent running in its own checkout can experiment without re-confirming every shell command, and you can still cherry-pick or discard the diff before merging. The agents-and-sessions page phrases the same idea as "the worktree itself is the sandbox." `Settings → Agents → Agent Permissions` switches all **uncustomized** agents between `Yolo` and `Manual`. If you already overrode a specific agent's launch arguments or environment, Orca leaves that agent alone so the global switch doesn't erase your custom command. To restore prompts for one agent only, edit that agent's default arguments or environment in Settings — a non-empty custom value is treated as an explicit override that opts the agent out of future permission-mode migrations. A `Reset` button next to the launch-arguments field restores the shipped flag. ### Agent ids for the CLI The `orca-cli` skill guide says `--agent ` launches that agent in the first terminal, and that **known ids include** `claude`, `codex`, `omp`, `pi`, `grok`, "and other installed TUI agents" — an open list, not a closed one. Orchestration group addresses cover a partly different set: `@claude`, `@codex`, `@opencode`, `@gemini`, `@droid`, `@grok`, `@cursor`. For `terminal wait --for tui-idle`, the guide names Claude Code, Gemini, Codex, OMP, Pi, and Grok as agent CLIs to use it with, and says to always pass `--timeout-ms`. ### Which agents can be resumed Two overlapping lists matter, and they are not the same. **Hibernation-eligible (resumable session).** Agent hibernation only pauses an agent that is one with a resumable session: **Claude, Codex, Gemini, Antigravity, OpenCode, Pi, MiMo Code, Droid, Grok, Devin, or OMP**. The docs name non-resumable terminals explicitly: "Cursor CLI, Hermes, Copilot, Trae, and other non-resumable terminals are left running." Hibernation also requires the agent to be `done`, off-screen, untouched since it finished, idle for at least the configured window (default **30 minutes**, range **1 minute** to **24 hours**), with no mobile session driving it, no unsettled orchestration Dispatch, and no live subagent/teammate roster on the pane. **Session-history scanned.** The Agent Session History panel's view-options menu can toggle these CLIs on or off for the scan: Claude, Codex, Hermes, Pi, OMP, Prime Agent, Cursor, Gemini, Antigravity, Rovo Dev, Copilot, OpenCode, Grok, OpenClaw, Devin, Kimi. Documented resume commands, which both hibernation and manual resume reuse: ``` claude --resume codex resume pi --session prime-agent --resume cursor-agent --resume acli rovodev run --restore ``` Pi resumes from the on-disk session file reported by its hooks (`--session `), **not** from a bare session id; if that file is missing, Resume is unavailable for that row even when a session id exists. Codex sessions also re-export `CODEX_HOME` when the original session set one. ### Where transcripts come from Orca reads each agent's own on-disk session store — Codex's `~/.codex/sessions`, Claude's `~/.claude` history, Cursor's session log, OpenCode's legacy session files or `~/.local/share/opencode/opencode.db`, and so on. There is nothing extra to enable. ## Per-agent specifics ### Claude Code Anthropic's agentic CLI, run as a first-class terminal agent with account-aware session start, usage tracking, and account hot-swapping. - **Setup:** install (`npm i -g @anthropic-ai/claude-code` or Anthropic's docs), log in once from any terminal. Orca picks up `~/.claude` automatically — no extra config. - **Launching:** Orca launches it with the worktree as the working directory and a **status-line hook that emits OSC title events** Orca uses for state dots. - **Usage:** Orca reads local `~/.claude` usage state and shows current usage plus rate-limit proximity in the status bar. - **Hot-swap:** multiple Claude accounts, swappable in one click, matching the Codex flow. Switching works even with live Claude sessions running — Orca holds the in-progress switch behind a guard so you don't trigger overlapping auth refreshes. - **Subagents and teams:** background subagents and Agent Teams teammates can show as expandable child rows under the lead agent in the worktree agent list and Agent Dashboard. **Selecting a child focuses the lead terminal** — children do not own a separate pane. - **Hooks and memory:** per-repo hooks and memory files are surfaced under Agent hooks & memory. Issue #2432 asked for exactly the Agent Teams behaviour now in the picker roster: at the time it was filed, Claude Code agent-teams sub-agents spawned into a hidden tmux session (e.g. `tmux -L claude-swarm-25198 a`) rather than native Orca panes, with no pane per teammate, no sidebar entries, and no notifications, and the workaround was attaching to that tmux session from a floating terminal. As of the 2026-09-09 docs snapshot, `Claude Agent Teams` is listed as a picker entry — **disabled by default** — that launches via `orca claude-teams` "with native panes for each teammate." Upstream closed #2432 as completed on 2026-06-10. ### Codex OpenAI's agentic CLI, described as one of the deepest integrations in the app: "usage, hot-swap, and restart all preserve account identity." - **Setup:** install per OpenAI's docs, log in from any terminal. Orca reads `~/.codex` for accounts and credentials. - **Launching:** Orca launches `codex` with the worktree as `cwd` and routes auth through the currently selected account. - **System default vs extra accounts:** `System default` uses your real `~/.codex` login — the same home a bare `codex` outside Orca would use. Extra accounts Orca manages get their own home under Orca's account data so credentials and rollouts stay isolated. New Codex launches follow the active account; already-running sessions keep the home they started with until restarted. - **Nested Task subagents:** when Codex spawns Task subagents, Orca can show them as child rows under the parent; clicking a child focuses the parent terminal, because subagents do not own a separate pane. - **Continue in a new session:** `Continue in New Session…` from an agent terminal's header or context menu starts a fresh agent session (same or different CLI) and injects a bounded handoff prompt from the prior transcript or captured context. The original session is left alone — **this is not `codex resume`**. - **Restart chip:** relaunches the agent with the same account. To restart with a different one, swap accounts first. - **Windows (WSL):** Orca can run Codex from the host install or from a WSL distro. See [Usage and rate limits](../concepts/usage-and-rate-limits.md) for the isolated-home path and the failure message when Codex isn't installed in the target distro. The `orca-cli` skill guide adds a launch nuance: `worktree create --agent codex` uses Orca's configured launcher and "has no per-call model/effort flags or arbitrary Codex argument forwarding." For a specific model and effort you create the worktree, then launch Codex through `terminal create --command` with `--model` and `-c model_reasoning_effort=...`, wait for TUI readiness, then send the prompt. ### Cursor CLI Cursor's command-line agent, with first-class support: launch from the combobox, full OSC state detection, and a restart chip on exit. - **Setup:** install per Cursor's docs, log in once. Orca auto-detects the CLI on `PATH`. - **Launching:** Orca launches the CLI scoped to the worktree; Cursor's TUI emits the state events Orca needs for agent state dots. - **Model selection:** driven by Cursor's own settings. **Orca doesn't override it** — configure inside the CLI. - Cursor CLI is *not* hibernation-eligible. ### GLM-5.2 GLM-5.2 is not a picker entry — it is a model you configure inside an existing harness, then launch that harness from Orca. The docs are explicit that Orca supplies the isolated worktree, terminal panes, browser tab, review flow, and session management, while "Your Z.ai CodePlan subscription and agent config supply the model access." **Via Claude Code** — Claude Code reads model overrides from `~/.claude/settings.json`. Add or update the `env` block, restart Claude Code sessions in Orca so the new environment is loaded, then run `/status` inside Claude Code to confirm the active model: ```json { "env": { "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]" } } ``` Use the `[1m]` suffix for the 1M context variant, and keep `CLAUDE_CODE_AUTO_COMPACT_WINDOW` set to `1000000` so Claude Code's compaction window matches that context size. If Claude Code says the `[1m]` model does not exist, update Claude Code and try again. For coding tasks Z.ai recommends setting Claude Code effort to `max` with `/effort`; Claude Code's lower effort settings map to GLM-5.2 high effort, while `xhigh`, `max`, and `ultracode` map to GLM-5.2 max effort. **Via an OpenAI-compatible harness** (OpenCode, Cline, Kilo Code, Roo Code, Droid): choose the OpenAI-compatible provider option (or the Z.ai option if the harness has one), set the base URL to `https://api.z.ai/api/coding/paas/v4`, add your Z.ai API key, set the custom model name to `glm-5.2`, set context window size to `1000000` if the harness exposes that field, and disable image support unless the harness specifically documents image support for this provider path. **Via OpenClaw:** if OpenClaw cannot select GLM-5.2 from its provider model list, add the model manually in `~/.openclaw/openclaw.json` under `models.providers.zai.models` (`"id": "glm-5.2"`, `"contextWindow": 1000000`, `"maxTokens": 131072`), set `model.primary` to `"zai/glm-5.2"` with `"fallbacks": ["zai/glm-4.7"]`, add it under `agents.defaults.models`, then restart the gateway with `openclaw gateway restart` and confirm with `openclaw tui`. The docs' summarizing rule: "configure GLM-5.2 wherever the harness stores provider/model settings, then let Orca launch that harness in the right worktree." ### MiniMax The only roster entry whose notes name both usage tracking and rate-limit tracking. Its credential path is a pasted session cookie under `Settings → Integrations → MiniMax` rather than a CLI login — see [Usage and rate limits](../concepts/usage-and-rate-limits.md). ### Grok on Windows Issue #14828 reports that on Windows, while a Grok session runs inside Orca, "a black console window flashes for a fraction of a second and takes foreground," and anything typed into the Orca terminal at that moment goes into the flash instead of Grok. The reporter stresses that it fires continuously during ordinary Grok work, not only on SSH connect/reconnect. A confirming comment on a second Windows machine (Orca 1.4.184, Windows 11 build 10.0.26200, `grok.exe --permission-mode bypassPermissions`) traces it to `%USERPROFILE%\.grok\hooks\orca-status.json`, which registers nine events — `SessionStart`, `UserPromptSubmit`, `Stop`, `StopFailure`, `SessionEnd`, `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `Notification` — all invoking `powershell.exe -NoProfile -ExecutionPolicy Bypass -EncodedCommand ` with no `-WindowStyle Hidden` and no `conhost.exe --headless`. A maintainer replied "thanks for reporting. looking into it," and related issues (#10488, #14543, #14589, #14815) are named as the same Win32 class. Upstream closed #14828, #10488, #14543 and #14815 as completed between 2026-08-17 and 2026-08-22 (PR #14589 was closed unmerged). A fresh report of the same Win32 class landed on #14828 on 2026-08-23, after closure — treat this as addressed but historically recurring. ### Antigravity on Windows Issue #2434 reports Antigravity CLI not responding to navigation keys (ESC, arrows) inside the Orca terminal on Windows v1.4.12, while working normally in PowerShell/CMD outside Orca. A maintainer cut `v1.4.20-rc.0` with a trial fix that "disables xterm's Kitty-enhanced keyboard protocol for local Windows terminals, while leaving macOS/Linux and SSH terminals unchanged," and asked for a retest. The raw file ends with the reporter supplying version details but no confirmation either way, and upstream closed #2434 as completed on 2026-06-29 via merged PR #7944 (`fix(grok): clipboard, native chat, hooks, sessions, ConPTY KKP`). ## How to Use Pick an agent from the combobox in any worktree; Orca spawns the CLI scoped to that worktree. From the CLI: ``` orca worktree create --name child-task --agent codex --prompt "Investigate the flaky login test" --json orca terminal create --worktree active --command "codex" --json ``` `worktree create --agent` makes a **new checkout** with the agent in the first terminal. For a fresh agent in the *current* checkout, use `terminal create --worktree active --command ""`. Do not do both for the same agent — `--agent` already owns the first terminal. `Settings → Agents` lists detected CLIs you can enable or disable, so launch menus only show the CLIs you want. ## Related entities - [Orca CLI reference](orca-cli-reference.md) - [Settings reference](settings-reference.md) Related concepts: [Usage and rate limits](../concepts/usage-and-rate-limits.md), [Notifications and inbox](../concepts/notifications-and-inbox.md), [Orchestration](../concepts/orchestration.md), [Skills and MCP](../concepts/skills-and-mcp.md). ## Sources `raw/web_community-supported-agents-orca-docs.md`, `raw/web_community-claude-code-in-orca-orca-docs.md`, `raw/web_community-codex-in-orca-orca-docs.md`, `raw/web_community-cursor-cli-in-orca-orca-docs.md`, `raw/web_community-how-to-use-glm-5-2-in-orca-ade-orca-docs.md`, `raw/web_community-agent-hibernation-orca-docs.md`, `raw/web_community-agent-session-history-orca-docs.md`, `raw/web_community-agents-sessions-orca-docs.md`, `raw/github_doc-skill-guides-orca-cli-md.md`, `raw/github_issue-bug-windows-grok-agent-hooks-flash-a-visible-console-and-ste.md`, `raw/github_issue-other-claude-code-agent-teams-spawn-hidden-tmux-sessions-ins.md`, `raw/github_issue-bug-antigravity-cli-does-not-respond-to-navigation-keys-in-o.md`, `raw/web_community-settings-reference-orca-docs.md`, `raw/web_community-orca-cli-reference-orca-docs.md`. --- title: "Activity Log" type: log --- # Activity Log Append-only record of all wiki changes. ## 2026-09-09 — initial build - **Source/Trigger**: New wiki. Gathered via `source-pipeline/specs/orca.json`. - **Sources captured**: 166 immutable records — 57 pages from `onorca.dev/docs`, 24 repository documents, 25 release bodies (17 desktop stable, `v1.4.182`–`v1.4.199`, plus 4 release candidates and 4 mobile-Android tags), and 60 closed issues with substantive discussion. All fetched deterministically (httpx + BeautifulSoup, `gh api`) with provenance frontmatter. No model-generated text entered `raw/`. - **Gather note worth keeping**: the user documentation is **not in the repository**. `docs/reference/` there is engineering-internal (EDR posture, xterm patch regeneration, spinner rendering); the 57 user-facing pages live on the docs site. An initial spec built from the repo alone would have produced a wiki about the wrong material while appearing complete, and was discarded. - **Pages created**: 23 concepts, 3 entities, 2 summaries, 2 syntheses, plus index and the documentation catalog. - **Terminology corrections made during the build** — each was asserted in the build brief and refuted by the sources: - **The terminal is xterm.js-based, not Ghostty-based.** Issue #12099 pins `xterm.js @6.0.1-beta.287` + WebGL. Ghostty appears only as a config import (`Settings → Terminal → Import from Ghostty`) and as "Ghostty-style" / "Ghostty-class" marketing copy. - **"ADE" — a correction that was itself wrong, then reversed.** The build initially asserted that no source expands the acronym. That was an artifact of the gatherer: `fetch_web_urls` strips `