Orca as mission control for my coding agents

After OmniRoute consolidated where my agents’ API traffic goes, the next bottleneck was managing the agents themselves. Claude Code here, OpenCode there, the odd Codex trial — each in its own terminal window, parked on some branch, holding half the context of a task I handed it yesterday. Multiply three agents by four repos and the folder-and-tabs approach collapses.

Orca is the desktop app I use to keep that straight. Its model is simple: every task gets a workspace. I’ve been running it on the Mac mini for the last couple of months, and this post is the inventory of how it actually gets used, reconstructed (with some embarrassment) from Orca’s own session index, because my memory server turned out to have nothing on it.

Worktrees are the unit of work

Register a repo once and Orca watches it. Ask for a task and it creates a real git worktree under ~/orca/workspaces/<repo>/<task> on its own branch. This week’s example from the xhs-1688-bridge repo:

/Users/weidai/orca/workspaces/xhs-1688-bridge/w12-suppliers-reports
branch: refs/heads/weidai/w12-suppliers-reports

The main checkout stays on main, untouched. The worktree gets its own terminals, browser tabs and agent sessions. Each workspace card also carries the coordination state I used to keep in my head or in a notes file: a status (todo / in-progress / in-review / completed), a one-line comment (“fix implemented; running integration tests”), and links to the PR, issue, Linear ticket or Jira key it serves.

This is git worktree under the hood (I can cd into these paths from any plain shell), but Orca adds the bookkeeping raw worktrees never had.

Launching agents

Each worktree can spawn any of the agent CLIs it knows: claude, codex, opencode, gemini, grok, droid, and more (the session indexer on my machine tracks 25 agent types; I’ve exercised two). Launch with a model and reasoning effort pinned:

orca worktree create --name fix-login --no-parent --agent codex \
  --model gpt-6-astra --effort high --prompt "reproduce and fix #42" --json

Per the agent’s settings it opens as a chat or a CLI terminal, and the launch receipt says which. Managed accounts are per agent type, so a launch can be pinned to a specific login instead of whatever the shell had.

The honest usage count, from orca search --index-status: 37 Claude Code sessions, 34 OpenCode. Claude Code in Orca terminals is my daily driver; OpenCode is the second opinion.

The CLI is the real interface

orca agent-context reports 321 commands. The CLI is why I think of Orca as a control plane rather than a nicer terminal grid: agents drive it directly, same as I do.

• Handoffs. An agent that finishes its slice can spawn the next worktree and hand over a written brief, then end there. The brief carries the context, so nothing gets copy-pasted between windows.
• Orchestration. A coordinator can run workers of a different agent: my Claude session dispatching a Codex worker for review, with ask/reply message flow, task DAGs and decision gates, instead of me relaying messages between two terminals.
• Terminal I/O. terminal read --screen returns what a TUI actually shows (Claude Code repaints constantly, so plain scrollback reads as stacked fragments), terminal wait --for tui-idle blocks until an agent stops thinking, and terminal send nudges it along.
• Full-text session search. Every agent conversation on the host, indexed: 13,222 messages at the moment I wrote this. “Which session touched that function?” is one quoted phrase away, which is how I audited my own usage for this post.

Browser and ports

Each worktree has an embedded browser scoped to it (snapshot, click, fill, screenshot, all scriptable from the CLI), plus port discovery: orca ports --json finds the dev servers listening on the machine and attributes them to the workspace that started them, so neither I nor an agent has to run lsof and guess.

Scheduled prompts

Automations are prompts on a schedule (hourly, daily, weekdays, 5-field cron, or RRULE), run by a chosen provider, either in a fresh worktree per run or against an existing workspace, with an optional shell --precheck gate that skips the run when its exit code says so. My install has none wired yet; the first candidate is a weekly triage prompt on the repo with the most issue traffic.

Phone as a second screen

The desktop app is only one client of the runtime. orca serve --mobile-pairing starts the same runtime headlessly and prints a pairing code; pair the phone (the orca://pair link scheme handles the handshake) and the phone becomes a window onto the same state: worktree cards, live PTYs, unread dots. Since the runtime keeps the terminals alive, what I read on the phone mid-commute is the session I left running on the desk, including where the agent is stuck and a text box to unblock it.

I can already reach the Mac mini’s full desktop from the iPhone through my self-hosted HopToDesk web client when I need the whole machine. Most of the time I only want to check on an agent, and for that pairing wins: it’s lighter, faster, and it shows exactly the slice I care about.

Potholes

Every one of these I hit for real:

1. Terminal handles are runtime-scoped. Restart Orca and old handles report terminal_handle_stale. Re-list, continue with the replacement, and don’t send to both.
2. terminal read is not the screen. It’s scrollback with escape sequences stripped, so anything repainting (shells, progress bars, agent TUIs) reads as stacked fragments. Use read --screen whenever the answer depends on what the terminal actually shows.
3. Permission menus eat prompts. Sending text+Enter while an agent shows a permission or trust menu is refused with agent_prompt_blocked. Answer the menu by sending the text and the Enter as separate commands.
4. Every worktree is a full checkout. node_modules per task adds up fast; the repo setup script (--setup run) automates the install but doesn’t shrink the disk bill.
5. Session search is opt-in per host. It’s a toggle under Settings → Agent Session History, with no CLI way to enable it. Turn it on early, because it only indexes what comes after.
6. The board only tells the truth if you feed it. Comments and statuses don’t update themselves; an agent that finishes without setting --workspace-status in-review leaves the card lying.

My setup today

Plus one saved SSH target, waiting for the day I want worktrees on a second machine.

The shift Orca pushed me through: agents stopped being things I watch in terminal windows, and became workers with mailboxes, status cards and searchable transcripts. I’m the dispatcher who reads the board now. The Mac mini is turning into an agent server, and the phone into its remote control.

← Back to all posts