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                              # first-time setup
orc start-session --provider=claude   # start orchestrating

That's it — the coordinator picks up tasks from your backlog and dispatches them to workers automatically.

How it works

After orc start-session starts, you're in a conversation with the master agent in your terminal. You can now start planning the work with the master and ask it to create tasks to the backlog. Discuss scope, break work into units, and the master 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