Imported from jochst/dotfiles (.hermes/skills/setup-orca/SKILL.md). Install upstream with npx skills add jochst/dotfiles --skill setup-orca. Copyright stays with the author.

Setup Orca for Multi-Agent Local Development

This skill turns a fresh Orca install into a productive multi-agent command deck. It covers: install verification, CLI registration, repo onboarding, worktree conventions, agent setup, feature configuration (browser, orchestration, MCP, notifications, hibernation), and a quick smoke test.

On Linux, use orca-ide wherever this file says orca.

Support files

• references/quick-setup.md — one-page printable checklist.
• references/orca-config-surgery.md — how to safely edit ~/.config/orca/profiles/local-default/orca-data.json when the UI is closed and a setting has no CLI command.
• references/orca-uninstall-reinstall.md — how to preserve work, fully remove Orca, and recover from GPU/Wayland bus crashes.
• references/orca-docs-notes.md — doc URL notes and source coverage for this skill.
• scripts/setup.sh — runnable installer for core and optional Orca skills.
• scripts/verify-orca-setup.sh — health check for install, worktrees, skills, agent defaults, and notifications. Run with bash ~/.hermes/skills/setup-orca/scripts/verify-orca-setup.sh.

Run the script first, then walk the checklist for the manual GUI steps. For setup tasks, provide both a runnable script and a one-page checklist so the user can choose automation or a manual walkthrough.

Before you start

Confirm requirements:

• Orca desktop app installed (macOS, Windows, or Linux).
• At least one CLI agent installed (Claude Code, Codex, Cursor CLI, OpenCode, Hermes, etc.) and already authenticated at least once outside Orca.
• Git repos already cloned locally and ready to add to Orca.

Phase 1: Verify the install and register the CLI

1. Open the Orca app.
2. Open Settings → General → Orca CLI and click Install CLI / Register CLI.
3. Verify in a terminal:

command -v orca || command -v orca-ide
orca-ide status --json

If orca is not found, restart the terminal or shell after registering. On Linux, confirm the orca-ide symlink is available.

.orca/ metadata should be gitignored

Orca stores worktree metadata and runtime state inside an .orca/ directory under the managed repo. This directory should be added to the repo's .gitignore so it is never committed:

echo '.orca/' >> .gitignore
git add .gitignore
git commit -m "Ignore Orca metadata directory"

The .orca/ folder contains generated state, not source code. If you see it as an untracked directory in git status, commit the ignore rule rather than the directory itself.

Pitfall: orca-ide serve crashes when the daemon is already running

If orca-ide serve exits immediately, the runtime socket is likely already bound. Always check status first instead of blindly starting a new server:

orca-ide status --json

If the runtime is already reachable, use it directly. Only run orca-ide serve when status reports the runtime as unreachable. If the app window is closed but the daemon is running, the CLI will still work; you do not need to reopen the UI to create worktrees, install skills, or fix config.

Phase 2: Add repos and set base refs

Add a repo

• In the sidebar, click Add Repo and point it at a local checkout.
• Orca reads the default branch and sets it as the base ref (usually origin/main).

Verify and tune base refs

orca repo list --json
orca repo show --repo id:<repoId> --json

If the default branch is wrong, fix it per repo:

orca repo set-base-ref --repo id:<repoId> --ref origin/main --json

Use Settings → Git → Default base ref resolver if you want Orca to default to origin/main or origin/master automatically.

Multi-repo folder groups

If several related repos live under one parent folder, add the parent folder and let Orca group them as a project group. Create folder workspaces from the group header when a task spans repos but its git source should be one specific repo underneath.

Phase 3: Configure agents

Open Settings → Agents.

Enable only the agents you actually use

Toggle on/off each detected agent so the launch combobox stays short. Recommended initial shortlist for a multi-agent setup:

• Claude Code
• Codex
• Cursor CLI
• OpenCode
• Hermes (if installed)

Tune launch permissions

Orca prefills each agent's dangerous permission flag (--dangerously-skip-permissions, --dangerously-bypass-approvals-and-sandbox, --yolo, etc.). These are the right defaults for disposable worktrees.

• Keep Settings → Agents → Agent Permissions set to Yolo for fast agentic work.
• Switch to Manual only if you want per-tool approval prompts for a specific agent.
• If you override one agent's launch arguments or environment, Orca stops migrating that agent on global permission changes. Leave the global setting alone if you want consistency.

Add a custom agent

If a CLI agent isn't in the shipped list:

1. Click Add custom agent.
2. Fill in name, binary path or command, and default arguments.
3. Add a startup hook if it needs one (e.g., source .envrc).

Custom agents get the launch combobox, restart chip, and working-directory scoping; state dots only work if the CLI emits OSC title sequences like working/idle.

Phase 4: Install agent skills

Orca skills are distributed packages an agent can install into its skill directory. Install the baseline multi-agent set and any extras needed:

# Core multi-agent kit (always install)
npx skills add https://github.com/stablyai/orca --skill orca-cli
npx skills add https://github.com/stablyai/orca --skill orchestration
npx skills add https://github.com/stablyai/orca --skill computer-use

# Optional extras
npx skills add https://github.com/stablyai/orca --skill orca-linear   # if using Linear
npx skills add https://github.com/stablyai/orca --skill orca-emulator # if driving iOS Simulator

Verify:

npx skills list
# or inspect the global agent skills directory directly
ls ~/.agents/skills 2>/dev/null

Note: On this setup, Orca uses the global ~/.agents/skills directory (managed by the npx skills CLI). The ~/.orca/skills directory is not used.

Phase 5: Tune worktree behavior

Naming and defaults

• Settings → General → Default new-worktree name: choose a custom prefix or keep the marine creatures.
• When creating a worktree, use the Advanced drawer to set an explicit branch name when the task name doesn't match the desired branch name.

Setup hooks

Open Settings → Repository → Hooks for each repo and add auto-run commands on worktree create. For Python projects using uv, use:

uv sync
if [ -f "$ORCA_ROOT_PATH/.env" ]; then cp "$ORCA_ROOT_PATH/.env" "$ORCA_WORKSPACE_NAME/.env"; fi

For Node projects, use pnpm install instead of uv sync.

Use --setup run to force hooks, --setup skip to bypass them, and --setup inherit to follow the repo policy.

Worktree lifecycle conventions

• Start independent work from origin/main or the repo base ref.
• Use --parent-worktree active only when the task genuinely depends on another in-flight worktree.
• Delete stale worktrees and their branches from the sidebar once a task is abandoned or merged.
• Pin long-running worktrees so they stay at the top of the project group.

Branch-per-agent mapping

If your GitHub repo has agent-specific default branches (e.g., claude-default-branch, codex-default-branch, grok-default-branch), create a dedicated home worktree for each agent so future worktrees can branch from the agent's default rather than from master:

for agent in claude codex grok; do
  orca-ide worktree create \
    --name "$agent-default" \
    --base-branch "refs/remotes/origin/$agent-default-branch" \
    --no-parent \
    --json
done

Verify with orca-ide worktree list --json.

Note: Orca may prepend the repo's configured gitUsername (e.g., jochst/) to the local branch it creates, so the local branch may be jochst/claude-default while the worktree base is origin/claude-default-branch. If you want the local branch to be exactly claude-default, you must rename it manually in the worktree and refresh Orca's metadata.

Phase 6: Configure orchestration

Use orca orchestration for tracked multi-agent work with completion, dependencies, and decision gates.

Quick orchestration checklist

1. Ensure orchestration skill is installed (Phase 4).
2. Confirm agent availability:

orca status --json
orca worktree ps --json
orca terminal list --json

3. For a simple fan-out:

orca orchestration run \
  --spec "Split the task across available agents and collect results" \
  --max-concurrent 3 \
  --worktree active \
  --json

4. Monitor progress:

orca orchestration task-list --json
orca orchestration task-list --ready --json

When to use each pattern

• orca terminal send for one-off prompts to an agent you are watching.
• orca orchestration dispatch --inject for tracked work that must report worker_done.
• orca orchestration run for full coordinator-loop fan-out.
• orca worktree create --no-parent --agent <agent> --prompt "..." for a full handoff that stops monitoring the original agent.

Phase 7: Configure browser and Design Mode

Open Settings → Browser.

• Create browser-use profiles if agents need to test as multiple users or keep separate login sessions.
• Enable Design Mode in the browser toolbar for pointer-to-code UI workflows. It captures the clicked element's DOM, computed styles, screenshot, and source location, dropping them into the active agent terminal.
• If testing web apps locally, forward ports automatically from the Ports tab on SSH worktrees, or open the browser to http://localhost:<port> for local worktrees.

Phase 8: Configure MCP servers and integrations

Open Settings → Integrations.

MCP servers

Under MCP, add MCP servers that expose tools your agents need. Agents that speak MCP will see those tools in their CLI. Example: a database MCP server, a web-search MCP server, or an internal company API MCP server.

GitHub / Linear / Jira

• GitHub: OAuth with the provider your repos use. Enables PR creation, checks, issue triage, and Actions logs inline.
• Linear: add a Linear API token for Linear ticket context.
• Jira: add Atlassian site URL, email, and API token.

Link worktrees to issues/PRs when creating them so the review surface stays attached to the task.

Phase 9: Notifications, hibernation, and config surgery

Notifications

Open Settings → Notifications and tune for your workflow:

• Agent-finished: system + sound + chip is recommended so you can queue agents and walk away.
• PR check failures: recommended for CI-driven workflows.
• Pick a custom sound if you need agent pings to stand out from other apps.

If the UI is closed, you can also enable them directly in the profile data file:

# See references/orca-config-surgery.md

Hibernation

Open Settings → Experimental → Agent hibernation:

• Turn it on if you keep many worktrees open and want idle background agents paused.
• Default idle window: 30 minutes. Adjust shorter for memory savings, longer for fewer resumes.
• Only resumable agents hibernate (Claude, Codex, Gemini, Antigravity, OpenCode, Droid, Grok). Non-resumable agents (Cursor CLI, Hermes, Pi, Copilot, etc.) stay running.

Config surgery (when the UI is closed)

Some settings have no CLI command. When the Orca window is closed, it is safe to edit the JSON profile file directly with a backup:

cp ~/.config/orca/profiles/local-default/orca-data.json \
   ~/.config/orca/profiles/local-default/orca-data.json.bak.$(date +%Y%m%d_%H%M%S)
# edit with Python/jq

Typical reasons: malformed setup hook, enabling notifications, correcting a base branch. See references/orca-config-surgery.md for the exact paths and safe edits.

After editing, verify the runtime still sees the new state:

orca-ide status --json

Phase 10: Terminal and appearance tuning

Terminal

Open Settings → Terminal:

• Pick a font with good box-drawing (e.g., JetBrains Mono, Fira Code, SF Mono, Cascadia Code).
• Import Ghostty or Warp theme if you have a favorite.
• Set padding and cursor style to taste.

Appearance

• Choose a theme, accent color, and density.
• Toggle editor minimap and status bar items to reduce visual noise.

Quick Commands

Open Settings → Quick Commands and save common commands per project or globally, e.g.:

• pnpm test
• pnpm lint
• pytest -x
• cargo check

Phase 11: Test the full loop

Run this end-to-end smoke test to confirm everything works together.

1. Verify Orca and CLI

orca status --json
orca worktree ps --json
orca terminal list --json

2. Create a throwaway worktree and race two agents

orca worktree create --name orca-smoke-claude --no-parent --agent claude --prompt "Write a tiny hello-world function in this repo's language and test it." --json
orca worktree create --name orca-smoke-codex --no-parent --agent codex --prompt "Write a tiny hello-world function in this repo's language and test it." --json

Watch the sidebar status dots. Once idle, open each worktree's diff and pick a winner.

3. Test browser + Design Mode

orca tab create --url https://example.com --json
orca snapshot --json
orca design-mode  # if available, or click the Design Mode toolbar button in the Orca UI

4. Test orchestration

orca orchestration run --spec "Ask the active agent to summarize the current directory structure" --max-concurrent 1 --worktree active --json
orca orchestration task-list --json

5. Test computer-use

orca computer permissions --json
orca computer list-apps --json

Grant any missing Accessibility / Screen Recording permissions, then retry.

Phase 12: Clean up the smoke test

Delete the smoke worktrees and their branches:

orca worktree rm --worktree name:orca-smoke-claude --force --json
orca worktree rm --worktree name:orca-smoke-codex --force --json

Common first-run issues

Recommended defaults checklist

Use this as a quick reference once setup is complete.

• Orca CLI registered and orca status --json returns cleanly.
• All active repos added and base refs set to origin/main (or correct default).
• Agents enabled: Claude Code, Codex, Cursor CLI, OpenCode, Hermes (or your chosen subset).
• Agent permissions set to Yolo for disposable worktrees.
• Skills installed: orca-cli, orchestration, computer-use, plus optional orca-linear / orca-emulator.
• Repo setup hooks configured (install, env, etc.).
• Browser profiles created for multi-identity testing.
• GitHub / Linear / Jira integrations connected as needed.
• MCP servers registered as needed.
• Notifications tuned (agent-finished + PR check failures recommended).
• Hibernation enabled for many-worktree workflows.
• Terminal font and theme set.
• Smoke test completed and throwaway worktrees deleted.

Next steps after setup

• See orca-cli for daily worktree/terminal/browser commands.
• See orchestration for structured multi-agent coordination.
• See computer-use for desktop app control.
• See Orca docs for advanced recipes: first-session, recipes.