Orca: Parallel Agent Worktrees Without Merge Conflicts

Orca solves a specific problem: how do you run multiple coding agents (Codex, ClaudeCode, OpenCode, Pi) in parallel on the same repository without them stepping on each other’s changes? The answer is Git worktrees, not queues or locks.

Most multi-agent systems use task queues or sequential execution. Orca treats each agent as a separate filesystem context. Every agent gets its own worktree, a Git feature that lets you check out multiple branches simultaneously in different directories. The orchestration layer tracks which agent owns which worktree, and the mobile companion app syncs state across all of them.

This is infrastructure, not a wrapper around an LLM API.

How Worktree Isolation Works

Git worktrees let you maintain multiple working directories from a single repository. Orca maps each agent instance to a dedicated worktree:

# Orca creates a worktree per agent
git worktree add ../orca-worktree-codex-1 main
git worktree add ../orca-worktree-claude-1 main
git worktree add ../orca-worktree-opencode-1 main

Each agent operates in its own directory. File writes are isolated. There’s no shared state at the filesystem level. When an agent modifies src/api/handler.ts, it’s writing to its own copy of the file in its own worktree.

The orchestration layer maintains a registry:

Agent ID
Worktree path
Current branch
Task assignment
Status (idle, running, blocked, merging)

When you assign a task to an agent, Orca:

Allocates or reuses a worktree
Checks out the target branch in that worktree
Launches the agent process with the worktree path as the working directory
Monitors file changes via filesystem watchers
Tracks Git operations (commits, branch switches) via hooks

Merge Conflict Handling

The hard part is consolidation. When two agents modify overlapping files, Orca needs to merge their changes back into the main branch without manual intervention.

Orca uses a three-phase merge strategy:

Phase 1: Detect Overlap

Before merging, Orca diffs each worktree’s changes against the current main branch. It builds a conflict matrix:

Agent	Files Modified	Overlaps With
Codex-1	`api/handler.ts`	Claude-1
Claude-1	`api/handler.ts`, `db/schema.ts`	Codex-1
OpenCode-1	`ui/components.tsx`	None

Phase 2: Sequential Merge

Non-overlapping changes merge first. OpenCode-1’s changes go straight to main. For overlapping changes, Orca uses a priority queue based on:

Task dependency graph (if available)
Agent completion time (first-done wins by default)
User-defined priority

Phase 3: Conflict Resolution

When a merge conflict occurs, Orca:

Pauses the merge
Notifies the user via the mobile app
Presents a three-way diff (base, agent A, agent B)
Waits for manual resolution or applies a conflict strategy (accept theirs, accept ours, or invoke an LLM-based merge agent)

The mobile app is critical here. You get a push notification when a conflict blocks progress. You can review the diff on your phone and either resolve it inline or defer to desktop.

State Synchronization

The mobile companion app is not just a viewer. It’s a control plane. The desktop app runs a local WebSocket server. The mobile app connects over your local network (or via a relay for remote access).

State sync happens in both directions:

Desktop to Mobile:

Worktree status updates (agent started, file changed, commit created)
Task queue state
Conflict notifications
Build/test results

Mobile to Desktop:

Task assignments (start agent X on feature Y)
Conflict resolution decisions
Agent pause/resume commands
Follow-up prompts to running agents

The protocol is JSON over WebSocket. Each message includes a worktree ID, so the mobile app can display per-agent state.

{
  "type": "worktree_update",
  "worktree_id": "codex-1",
  "agent": "codex",
  "status": "running",
  "current_file": "src/api/handler.ts",
  "lines_changed": 42,
  "last_commit": "abc123"
}

Failure Modes

Worktree isolation prevents some failure modes but introduces others.

Prevented:

Concurrent file writes causing corruption
Agents overwriting each other’s uncommitted changes
Race conditions in shared state

Introduced:

Disk space consumption (each worktree is a full checkout)
Merge conflict accumulation if agents run too long without consolidation
Worktree cleanup failures (orphaned directories if the desktop app crashes)
Mobile app losing sync if the WebSocket connection drops

Orca mitigates disk space by lazy-loading worktrees. It only creates a new worktree when an agent starts. Idle worktrees are pruned after a configurable timeout (default 1 hour).

For merge conflicts, Orca enforces a consolidation policy. By default, agents must merge back to main every 10 commits or 30 minutes, whichever comes first. This keeps the conflict surface small.

Worktree cleanup runs on startup. Orca scans for orphaned worktree directories and removes them if they’re not referenced in the registry.

Observability

Orca exposes agent activity through:

A desktop UI showing all active worktrees in a grid
Per-worktree logs (stdout/stderr from the agent process)
Git operation history (commits, merges, branch switches)
File change timeline (which files were modified when)

The mobile app surfaces this as a timeline view. You can see what each agent did in chronological order, filter by agent or file, and jump to specific commits.

There’s no distributed tracing or structured logging yet. Observability is file-based. Each worktree writes logs to ~/.orca/logs/<worktree-id>/. The desktop app tails these files and streams them to the UI.

Deployment Shape

Orca is a desktop app (Electron) with a mobile companion (React Native). The desktop app is the orchestrator. The mobile app is a remote control.

You can also run Orca on a VPS. The desktop app runs headless. You connect via the mobile app or a web UI (experimental). This is useful for long-running agent tasks that outlive your laptop’s uptime.

The VPS deployment uses the same worktree model. The difference is persistence. On desktop, worktrees live in ~/.orca/worktrees/. On VPS, they live in /var/lib/orca/worktrees/ and survive reboots.

Orca does not provide multi-user support. One Orca instance serves one user. If you want team collaboration, you run multiple Orca instances and coordinate via Git (push/pull to a shared remote).

Security Boundaries

Each agent runs as a subprocess of the Orca desktop app. There’s no sandboxing. Agents have full filesystem access within their worktree and can execute arbitrary shell commands.

This is a deliberate trade-off. Coding agents need to run build tools, package managers, and test suites. Sandboxing would break most workflows.

The risk is that a malicious or buggy agent can:

Read files outside its worktree
Modify system files
Exfiltrate credentials from environment variables
Spawn background processes that outlive the agent task

Orca does not prevent this. The security model is: trust your agents or run Orca in a VM.

The mobile app uses TLS for remote connections (when not on the local network). The WebSocket server generates a self-signed certificate on first run. You can replace it with a real cert if you expose Orca to the internet.

Technical Verdict

Use Orca when:

You want to run multiple coding agents in parallel on the same codebase
You’re comfortable with Git worktrees and manual merge conflict resolution
You need a mobile interface to monitor and steer agents remotely
You’re okay with agents having full filesystem access

Avoid Orca when:

You need sandboxed agent execution
You want fully automated merge conflict resolution
You’re working on a team and need multi-user orchestration
Disk space is constrained (worktrees consume 2-5x the repo size)

Orca’s core insight is that filesystem isolation is simpler than distributed state management. Worktrees are a proven Git feature. The orchestration layer is thin. The failure modes are predictable. For solo developers running agent fleets, this is a practical pattern.

Agentic AI, minus the noise.