orc-state

Spawn, command, and coordinate.

A provider-agnostic orchestration framework for autonomous coding agents. Dispatches tasks to AI workers, manages their lifecycle, and merges results — all locally in your repo, backed by nothing but files.

• Provider-agnostic — Claude, Codex, Gemini. Same orchestration, any model.
• Cross-provider — mix and match agent providers freely in the same session.
• Zero infrastructure — no servers, no external services. Everything runs locally in your repo.
• Parallel autonomous agents — multiple agents working in isolated worktrees simultaneously.
• Terminal-native — live dashboard, full CLI control, zero context switching.

Quick start

Requires Node.js 24+ and at least one supported provider CLI (Claude, Codex, or Gemini).

npm install -g orc-state
cd my-project
orc init                    # pick providers, install skills/agents/MCP
orc start-session           # start orchestrating

orc init walks you through provider selection and installs the skills, agent definitions, and MCP configuration your providers need. After init, orc start-session reads from your config — no flags required.

orc start-session starts the coordinator in the background and opens a master agent session in your terminal. If a coordinator is already running, it reuses it. You pick the provider for your master session at init time (or override with --provider=<name>).

How it works

You're now in a conversation with the master agent. Start planning the work — discuss scope, break it into units, and ask the master to create tasks. It writes task specs to backlog/*.md.

Once tasks are in the backlog, the coordinator dispatches them to worker agents that execute each task in an isolated git worktree. You can monitor progress, intervene on blockers, and review results — all through the master session.

For deeper work, you can also write task specs directly in backlog/*.md — the coordinator picks them up on the next tick. See Concepts & terminology and Architecture overview for the mental model.

Documentation

• Getting started
• Concepts & terminology
• Architecture overview
• Configuration
• CLI reference
• Memory system
• Writing custom adapters
• Testing
• Contracts & invariants
• Troubleshooting
• Recovery guide

License

MIT