# Orca agent orchestrator is fucking awesome!

> Orca, the free open-source app for running many agents in parallel: its features, my control room where HAL coordinates Claude Code and Grok, and the limits.

- URL: https://stocasticparrot.ai/en/tools/orca-agent-orchestrator/
- Author: Danilo Giudice
- Published: 2026-11-14

![The character, with the parrot on his right shoulder, points at HAL, the little pixel robot with the red eye; threads run from HAL to a swarm of small pixel agents, the orange Claude Code mascots and the grey ones with the Grok symbol; the Orca logo is in the top right corner](https://stocasticparrot.ai/en/tools/orca-agent-orchestrator/img/01-apertura-regia.jpg)

Like many of you, I’m living the hyperproductivity paradox: twenty different sessions, each with its own terminal, all needing me to step in, and a flood of notifications every hour. Some call it AI frying; all I know is I was losing my mind.

As I write, the page I use to follow my agents counts 19 of them across 15 projects, between Claude Code and Grok. Almost all of them are idle: they’re done, or they’re waiting for me.

**The spoiler:** if you make it to the end, you’ll know what Orca does, how I put an agent on top of it that coordinates the others (with the rules I wrote for it), and which limits I found, including the ones I still fix by hand.

## What Orca is

[Orca](https://orca.dev) is a desktop app for running several agents in parallel: Claude Code, Codex, Grok and 24 others listed by name on its site, plus “any other command-line agent.” It’s made by Stably AI, a San Francisco startup backed by Y Combinator. It’s free and open source, under the MIT license, and it runs on macOS, Windows, and Linux. The really cool thing is that it’s practically complete, but above all it’s a box: I can finally do everything inside Orca, it even has its own built-in browser, and I can switch between agents or tasks really comfortably.

Everything rests on the worktree.

In practice, it’s a second folder of the same project, on another branch (the line of changes you’re working on), that shares its history with the first one. If one agent redoes the site’s home page and another fixes the sign-up form, each one works in its own folder and doesn’t touch the other’s files; at the end you merge the two branches. Orca gives each task a tab, and each tab [its own worktree](https://orca.dev/docs/model/worktrees).

**The features, one by one**

- **Tabs and worktrees.** Each task lives in a tab with its own worktree, and tabs are grouped by project.
- **Agents in chat or in a terminal.** You start an agent in a new tab or an existing one, with a prompt, a model, and a starting effort.
- **The command line.** Orca has a command, `orca`, that does from the terminal what you do with the mouse: it lists the tabs, reads what an agent’s terminal shows, types into it, opens the browser. It’s the part I use the most, because the agents can use it too.
- **Orchestration.** A coordinator agent opens a *run* (a workspace with its own mailbox), creates tasks, and starts *workers*, that is, other supervised agents. A worker with a doubt sends it to the coordinator with `ask` and stops; the coordinator answers with `reply`; when the job is done, the worker sends `worker_done`, even if it failed. *Decision gates* block a task until someone answers a question. [The documentation](https://orca.dev/docs/cli/orchestration) marks it as experimental.
- **A browser per tab,** with [Design Mode](https://orca.dev/docs/browser/design-mode): you click an element on the page, and Orca sends the agent its HTML, its CSS, and a cropped screenshot.
- **Change review** line by line: your comments go back to the agent in a single prompt.
- **Scheduled automations, a phone app, and remote servers,** the last two still in beta.

I use the first four every day, plus the browser to look at the images the agents produce. The mobile app is incredible: it gives me the FULL terminal, with all the same features as Orca, but on my iPhone.

A note on privacy. Orca collects pseudonymous usage data (version, operating system, agent type, token counts) and, [according to its documentation](https://orca.dev/docs/telemetry), leaves out files, prompts, agent responses, and terminal output. You can turn it off in Settings → Privacy or with `DO_NOT_TRACK=1`.

## How I use it: a control room on top of Orca

Orca shows me the tabs, one by one. With fifteen projects open (an app, a couple of sites, video, social, and this brand), I needed to see at a glance who’s working, who’s waiting for me, and who’s about to fill up their context. So on November 11 I built a control room, all local. Let’s go through it piece by piece.

**The Engine and the page**

The Engine is a script that runs in an Orca terminal. Every 3 seconds it asks Orca for tabs and terminals, reads the files where Claude Code keeps sessions, background jobs, and subagents, and writes everything into a state file. That file feeds a page, open in Orca’s browser: one box per project and, for each agent, its state (working, waiting for you, done, error, idle), the model, how much context it has used, and which subagents it has running. It has two views, a map and an “office,” and from there I can write directly to an agent.

![The Map view of the control room: on the left three agents, HAL, Zen, and a Stocastic Parrot session, each with its context tokens, model, and cache timer; in the middle the folders they are touching; on the right the Regia, Etna Now, and Stocastic Parrot projects, linked by colored lines](https://stocasticparrot.ai/en/tools/orca-agent-orchestrator/img/regia-mappa.jpg "The Map view: who is working, on which folders, and for which project (the interface is in Italian)")

![The Office view of the control room: at the top HAL and Sam with their chats; below, one room for each group of projects; on the right HAL’s room, the counter with an agent that is waiting, and the lounge with the idle agents on the sofas](https://stocasticparrot.ai/en/tools/orca-agent-orchestrator/img/regia-ufficio.jpg "The Office view: one room per group of projects, the counter of who is waiting for me, and the idle agents in the lounge")

**HAL, the orchestrator**

HAL is a Claude Code in another terminal of the control room. It has a one-page CLAUDE.md that tells it how to read the state file and how to talk to the others: first it reads what the agent’s screen shows with `orca terminal read`, then it writes to it with `orca terminal send`. I talk to HAL, and HAL passes my instructions on to the agents, one at a time, always quoting my words.

The rules that matter are few: no push, merge, deploy, or deletion without a yes from me that names the thing, every time. No answering the other agents’ permission requests on my behalf. No identical message sent to several agents at once.

**Sam, the devops**

In the same tab runs Sam, a Grok agent that works as HAL’s devops: it starts servers, runs builds and tests, reads the logs.

**Workers, with ask and reply**

For long jobs with steps to approve, I use orchestration. An agent that edits a video, for example, runs as a worker: when it has some clips ready, it sends them to HAL with `ask` and ends its turn. HAL looks at them and answers with `reply`, or passes the question on to me. While it waits, the worker doesn’t use any tokens, and Orca wakes it up when the answer arrives.

**Handoff and /clear between 60 and 80%**

Every session has a context window: how many tokens the model rereads at each response. When it fills up, Claude Code summarizes it on its own and loses details you don’t get to choose (I wrote about it in [“Auto-compaction is a colossal piece of crap”](https://stocasticparrot.ai/en/explainers/auto-compaction/)).

The thing that really changed the game for me is this: HAL keeps an eye on every agent’s context. Between 60 and 80% it waits for a quiet moment (agent idle, no pending question, no subagent at work, no deploy halfway through), has it write a handoff, sends `/clear`, and has it reload the file. The handoff is a text file with the task, my decisions in my own words, the state, the useful files, and the next steps: it’s what the agent rereads after the `/clear` to pick up where it left off.

**Always in auto mode**

All the agents run in [auto mode](https://code.claude.com/docs/en/permission-modes), never with permissions bypassed. In auto mode, reads and edits in the working folder go through on their own; every other action goes to a classifier, a separate model that lets it through or blocks it ([Anthropic explains how it works](https://www.anthropic.com/engineering/claude-code-auto-mode)).

In my install, Orca launched Claude Code with `--dangerously-skip-permissions`, that is, with no checks at all. In Claude Code’s settings I turned that mode off (`"disableBypassPermissionsMode": "disable"`), and since then sessions start in auto mode anyway. If an agent ends up in another mode, HAL sends it shift+tab until the status line says “auto mode on” again.

**The summaries**

Every half hour, at minutes 17 and 47, HAL sends me a summary: who’s working, who’s waiting for me, who it has refreshed. They’re Claude Code crons, that is, reminders scheduled inside the session, and they survive `/clear`: before creating one, HAL checks it isn’t already there, so as not to end up with two. But on my phone I only get a notification for the things that need me: a login, a payment, a confirmation.

## The limits I ran into

- **The classifier blocks the orchestrator.** When HAL gives an agent a task that didn’t come from a request of mine, the classifier blocks it as “unauthorized communication,” even within a delegation I gave it myself. It also blocks deploys requested with a generic “yes to everything,” and the ones HAL orders another agent to do. In those cases HAL prepares the sentence for me to copy or the command for me to run, and the manual step remains, but always in its session; frankly, I don’t know whether this can be considered a bad thing, it’s one more layer of protection anyway.
- **Terminal IDs change.** To write to an agent you need the ID of its terminal in Orca, and I’ve seen it change several times. HAL rereads them from the state file every time, and some agents end up “orphaned”: they work, but the control room can no longer find their terminal. One ID per agent solves the problem; I’m implementing it.
- **Part of the setup goes through internal commands.** Orca’s command line has no commands to create or rename project groups: I made them with internal calls of the app, which need to be rechecked after every update.

## If you want to try it

1. Download Orca from [orca.dev](https://orca.dev) and register the `orca` command in Settings → General → Orca CLI.
2. In Settings → Agents, choose Auto permissions for new sessions. According to [the documentation](https://orca.dev/docs/settings), Auto applies to Claude, Agent Teams, and Codex; for the other agents, choose Manual. Then, in Claude Code’s settings, turn off bypass mode, so that no session starts without checks.
3. One group per project, one tab per line of work. I keep in Orca only the tabs being worked on: I remove the idle ones, and the files stay on disk.
4. If you don’t want telemetry, turn it off in Settings → Privacy.
5. Before opening the fourth agent, write the orchestrator’s CLAUDE.md: how it reads the state, how it writes to the others (it looks at the screen first), what it can’t do without your yes, and when it does the handoff.