An agent orchestrator — lets AI coding agents spawn and manage parallel workers.
Each worker runs in its own git worktree and tmux window. No shared state, no conflicts.
Note: This is a hobby / personal project. Contributions and feedback welcome, but expect rough edges.
Orca is a CLI tool designed to be used by AI coding agents, not humans directly. You talk to your agent, and it uses Orca behind the scenes to break work into pieces, farm them out to parallel workers, and create swarms of agents working simultaneously.
The primary use case is with OpenClaw as the L0 orchestrator — you delegate tasks from any OpenClaw channel (Slack, WhatsApp, Telegram, Matrix, Discord, etc.) and OpenClaw uses Orca to spawn workers, monitor progress, and report back results. You can also use it with Claude Code, Codex, or Cursor as workers — they must run inside a tmux session so Orca can auto-detect their pane for notification delivery.
Each worker gets its own git worktree (isolated code sandbox) and tmux window (isolated terminal). A background daemon monitors all workers, auto-handles simple prompts, escalates blockers, and notifies the orchestrator when work is done. Workers can also be orchestrators themselves, spawning sub-workers up to 3 levels deep.
Full setup guide: SETUP.md — install, configure, and wire up your agents.
Multi-backend E2E check (spawn, steer,
orca logs,ghissue): E2E.md and./scripts/e2e-test.sh.
- Git (2.20+) — Orca uses worktrees and stash; auto-initializes non-repo directories (see SPEC.md)
- Rust toolchain (1.85+)
- tmux (3.0+)
- At least one AI coding agent: Claude Code, Codex, Cursor, or Droid
The repo is private: github.com/nansen-ai/orca. Pick one path depending on how Git talks to GitHub on this machine.
| HTTPS + GitHub auth (token or CLI) | SSH (Deploy key or user key on GitHub) | |
|---|---|---|
| Use when | Sandboxes, OpenClaw, CI, or GITHUB_TOKEN / gh auth |
Mac/Linux with git@github.com:… already working |
| Install | cargo install --git https://github.com/nansen-ai/orca --branch main --locked --force |
cargo install --git git@github.com:nansen-ai/orca.git --branch main --locked --force |
HTTPS: configure Git before running Cargo — e.g. export GITHUB_TOKEN=… (PAT with repo), or gh auth login then gh auth setup-git, or your org’s credential helper.
SSH: ensure ssh -T git@github.com succeeds and this repo is allowed for that key.
cargo installputs the binary in~/.cargo/bin/. Addexport PATH="$HOME/.cargo/bin:$PATH"to your shell profile if needed.
Pre-built binaries may also be on Releases.
The skill is what teaches your AI agent how to use Orca. Install it globally so every agent (Claude Code, Codex, Cursor, etc.) can discover it:
npx skills add nansen-ai/orca --skill orca -g -y(Requires GitHub access to the repo; set GITHUB_TOKEN or configure gh/Git credentials if npx cannot clone.)
Or install manually — use HTTPS or SSH to match how you authenticate (git clone only one of these):
# HTTPS (token / gh / credential helper)
git clone https://github.com/nansen-ai/orca.git /tmp/orca
# or SSH
# git clone git@github.com:nansen-ai/orca.git /tmp/orca
mkdir -p ~/.agents/skills
cp -r /tmp/orca/skills/orca ~/.agents/skills/orcaHooks let Orca detect when workers finish. Safe to run multiple times — merges without overwriting:
orca hooks installorca --help # shows all commands
orca daemon status # daemon info
orca list # should say "No workers."This is the most commonly missed step. Installing the binary and skill is not enough — you need to mention Orca in your project's agent instruction file so agents know to delegate work to parallel workers.
Add an "Orca" section to the appropriate file in your repo:
| Agent | File to edit |
|---|---|
| Claude Code | CLAUDE.md in your project root |
| Codex / Cursor / Generic | AGENTS.md in your project root |
| OpenClaw | TOOLS.md in your project root |
For OpenClaw (TOOLS.md) — OpenClaw is the L0 orchestrator. It must explicitly use Orca instead of ACP for coding-agent requests:
## AI Coding Agents
ALWAYS use the `orca` skill (`orca spawn`) to spawn coding agents.
Never run them directly via exec -- use orca workers so the user can attach to sessions.
- Do not use ACP for coding-agent requests
- Default CLI: Claude Code (-b cc), Codex (-b cx), Cursor (-b cu)
- Spawn pattern: `orca spawn "<task>" -b cc -d ~/path/to/repo --orchestrator openclaw --session-id <current-session-id> --spawned-by openclaw`
- After spawning, wait silently -- orca daemon notifies when done. Don't poll with `orca list` loops.
- Use `orca logs <name>`, `orca steer <name> "<msg>"`, `orca kill <name>` when doneFor Claude Code / Codex / Cursor (CLAUDE.md or AGENTS.md) — these agents run as workers inside tmux. They identify themselves by their worker name (ORCA_WORKER_NAME env var):
## Orca (Parallel Agent Orchestration)
This project has Orca installed for parallel task execution. When facing tasks
that can be broken into independent pieces, use `orca spawn` to delegate work
to parallel workers instead of doing everything sequentially.
You must be running inside a tmux session. Check ORCA_WORKER_NAME for your
worker name and pass it as --spawned-by.
- `orca spawn "<task>" -b cc -d . --orchestrator cc --spawned-by "$ORCA_WORKER_NAME"` to spawn workers
- `orca list` to check status, `orca logs <name>` to review output
- `orca kill <name>` to clean up finished workers
- After spawning, stop and wait -- the daemon notifies you when workers finishBonus: manual takeover. Because every worker runs in a real tmux window, you can attach to any worker's pane and take over manually at any time — inspect state, fix something by hand, or continue where the agent left off.
orca spawncreates a git worktree, opens a tmux window, and launches the AI agent- A background daemon watches all worker panes via tmux
- When a worker finishes, the daemon notifies the orchestrator
- When a worker is stuck on a prompt, the daemon auto-handles it or escalates
- The orchestrator reviews, steers, or kills and spawns fresh
For the full design — lifecycle, notifications, isolation, stuck-worker handling — see SPEC.md.
- Claude Code —
-b ccor-b claude(binary:claude) - Codex —
-b cxor-b codex(binary:codex) - Cursor —
-b cuor-b cursor(binary:agent/cursor agent) - Droid (Factory.ai) —
-b dror-b droid(binary:droid; requiresFACTORY_API_KEY). For fewer permission prompts, set~/.factory/settings.jsonsessionDefaultSettingsto Auto + High autonomy (see SETUP.md and araa47/dotfileshome/harnesses/).
- Claude Code —
--orchestrator cc— message to tmux pane - Codex —
--orchestrator cx— message to tmux pane - Cursor —
--orchestrator cu— message to tmux pane (sent 3x) - Droid —
--orchestrator dr— message to tmux pane - OpenClaw —
--orchestrator openclaw— notification viaopenclaw system event - None —
--orchestrator none— no notification, check withorca list
Orca handles the mechanics — spawning, isolation, monitoring, notifications. It does not decide how to split work, what roles agents play, or what workflow to follow.
- Your prompt drives the strategy. "Build a payment system, split it into parallel tasks" produces different results than "fix this one bug."
- Optional workflow skills like
sprint-teamcan help structure work with roles (Researcher, Architect, Coder, Validator). But they're optional — the agent can figure out the split from your prompt alone.
Divide and conquer — Break a task into pieces, spawn one worker per piece, review results.
Parallel exploration — Try multiple approaches simultaneously, pick the best.
Fresh context — Kill a finished worker, spawn a new one for the next step. Clean context windows lead to better results.
Iterative refinement — Steer a running worker with corrections instead of starting over.
Hierarchical delegation — A worker becomes an orchestrator, spawning its own sub-workers.
Full command reference lives in skills/orca/SKILL.md — the same file AI agents read.
| Command | Description |
|---|---|
orca spawn "task" |
Spawn a new worker with a task |
orca list |
Show all workers and their status |
orca logs <name> |
View a worker's terminal output |
orca steer <name> "msg" |
Send a follow-up message to a worker |
orca kill <name> |
Kill a worker and clean up its worktree |
orca gc |
Clean up all finished/dead workers |
orca doctor |
Check backend authentication before spawning |
orca hooks install |
Install lifecycle hooks for Claude Code & Codex |
| Type | Examples | Action |
|---|---|---|
| Auto-handled | Workspace trust, permission prompts, y/n, Codex model-switch prompts | Daemon answers automatically |
| Confirmed blockers | Rate-limit keywords, stale output (pane content frozen) | Daemon samples repeatedly, marks blocked, and notifies with orca logs, orca steer, and orca kill --reason commands. Auth issues are caught pre-spawn by orca doctor. |
Orca never kills worker panes — the orchestrator decides what to do. By default Orca requires 6 consecutive confirmations, sampled every 20 seconds, before notifying. Tune with ORCA_BLOCKER_CONFIRM_COUNT and ORCA_BLOCKER_CONFIRM_INTERVAL_SECS.
| Environment Variable | Default | Description |
|---|---|---|
ORCA_MAX_DEPTH |
3 |
Maximum nesting depth for sub-workers |
ORCA_MAX_WORKERS |
10 |
Maximum running workers per orchestrator |
ORCA_HOME |
~/.orca |
Base directory for state, logs, and events |
ORCA_BLOCKER_CONFIRM_INTERVAL_SECS |
20 |
Seconds between blocker confirmations |
ORCA_BLOCKER_CONFIRM_COUNT |
6 |
Consecutive confirmations before a blocker notification |
ORCA_BLOCKER_STALE_SECS |
120 |
Seconds of unchanged pane output before stale-output detection |
| Document | Description |
|---|---|
| SPEC.md | Human-readable design spec — how Orca works, use cases, lifecycle |
| ARCHITECTURE.md | Technical architecture — module graph, data flow, runtime state |
| skills/orca/SKILL.md | CLI reference — what agents read to learn Orca |
| skills/sprint-team/SKILL.md | Optional sprint workflow with structured roles |
| CHANGELOG.md | Version history |
If you have direnv installed, run direnv allow — it installs rustup, rustfmt, clippy, and cargo-nextest automatically. Otherwise see CONTRIBUTING.md for manual setup.
cargo build # debug build
cargo nextest run # run tests in parallel (preferred)
cargo test # run tests without nextest
cargo fmt # format code
cargo clippy # lintSee CONTRIBUTING.md for full guidelines.
This project is largely vibe-coded. There are no guarantees of correctness, stability, or backwards compatibility. It works for the author's use cases, but it may not work for yours. Please read the code and understand what it does before relying on it for anything important.