Parallel Agents with Orca Worktrees

An Orca worktree is the on-disk git worktree Orca gives each task so agents do not step on the same files. From the CLI you create one with orca worktree create and choose the first-terminal agent with --agent. Parallel here means several worktrees, not several chats on one checkout.

This note only covers creation, agent selection, and collision points from Worktrees and the CLI reference. No prices or reviews. Uncertain flags stay out.

How do you run worktree create?

One-line answer: Pick a repo, give a name, run orca worktree create. Add --json when a script will parse the result.

Documented examples — replace <repoId> with a value from orca repo list --json:

orca worktree list --repo id:<repoId> --json
orca worktree ps --json
orca worktree create --repo id:<repoId> --name fix-login --json
orca worktree current --json

Most commands accept selectors instead of long IDs: active, path:/abs/path, branch:feature-name, issue:123. Use explicit selectors in scripts that may run outside the target worktree.

In the UI, submitting Create Worktree closes the dialog immediately; git fetch and git worktree add continue in the background. The sidebar shows a progress row; failures get Retry. CLI-created worktrees are labeled in the sidebar filter.

When create runs from inside an Orca-managed worktree, Orca may record a child. Pass --parent-worktree active to be explicit, or --no-parent when the work is independent.

Start-from can be the repo base ref (usually origin/main), another local branch, a commit SHA, or a remote branch. Set the base with orca repo set-base-ref before creating many worktrees.

Delete removes the directory and the branch (with confirmation). If git keeps a local branch because of unmerged commits, Orca can offer a review step such as Review N Branches.

How do you pick an agent?

One-line answer: On create, --agent launches the first-terminal agent and --prompt sends the first task. In the UI, the Agent selector can set a default, including Blank Terminal.

orca worktree create --name child-task --agent codex --prompt "Investigate the flaky login test" --json
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

Documented flags:

  • --agent: launches that agent in the first terminal. Blank Terminal in the UI is an ordinary shell.
  • --prompt: sends initial work to that agent.
  • --setup run|skip|inherit: repo setup hooks. inherit follows repo policy.

Orca does not sell a model. You plug in agent CLIs you already pay for — Claude Code, Codex, OpenCode, Grok, Cursor CLI, and others listed on the site. Accounts: desktop Add account, or on a headless host orca account add (Claude by default; Codex with --agent codex).

For tracked multi-agent work, the docs prefer Orchestration over ad-hoc terminal send. Progress checkpoints: orca worktree set --worktree active --comment "..." --json.

What collides when you run in parallel?

One-line answer: Source files are isolated per worktree; gitignored paths, shared directories, the same remote branch, and parent/child links still overlap.

The documented model: each worktree has its own branch, files on disk, and agent terminals. That is why “three agents on the same bug, pick the winner” is safe for source.

What still collides:

  • Clean checkout: a new worktree is missing gitignored deps, caches, and local secrets. Share rebuildable trees such as node_modules via worktree.sharedDirectories in orca.yaml (symlink/share). Copy per-worktree files such as .env with a root .worktreeinclude. Already-shared paths are not copied again. Tracked or missing paths are skipped.
  • Same remote / PR: two worktrees pushing one branch collide in git. Use distinct names and an explicit start-from.
  • Parent/child: inferred children nest in the sidebar only; they do not rewrite git history. Independent work: --no-parent.
  • Host: remote runtimes want server-side selectors such as id:<serverId>:<id> or path:. The local cwd may not exist on the host.
  • Terminal handles: runtime-scoped. After restart, reacquire with orca terminal list --json.

Worktrees you add with git worktree add stay hidden until you Show them under Non-Orca worktrees. Plain git (status, rebase) is picked up on the next render.

The review surface is the diff against start-from. Lifecycle: Create → Work → Review → Ship → Archive/Delete. One owner integrating and testing is the safer pattern.

Sources