Write a vision document. Run orc run. Walk away.
orc reads your high-level feature descriptions, breaks them into tasks, spawns AI coder agents, reviews the results, and merges passing work — all on a separate dev branch so you can keep working on main.
- Board-driven workflow — a YAML kanban board is the single source of truth; the orchestrator drives a plan → code → review → merge pipeline.
- Parallel coders — scale from 1 coder to many, each in its own git worktree, with configurable tool permissions.
- Git-native — every decision is a commit. The full audit trail lives in your repo.
- Sandboxed by default — agents run in
confinedmode with explicit tool allow-lists. Opt in toyolowhen you trust the environment. - Backend-agnostic — uses OpenAI-compatible LLM APIs (Gemini, OpenAI, GitHub Models).
- Telegram integration — optional real-time notifications and human-in-the-loop unblocking.
pip install qorc
# or, with uv:
uv add qorcRequires Python 3.13+.
cd your-project/
orc bootstrap # scaffold .orc/ config directory
$EDITOR .env # fill in credentials (see below)
orc run # let the orchestra playThat's it. orc will plan tasks, write code, review changes, and merge passing work into your dev branch.
| Command | What it does |
|---|---|
orc bootstrap |
Scaffold the .orc/ directory with roles, squads, and vision templates |
orc run |
Run the dispatch loop (plan → code → review → merge) |
orc run --maxloops 0 |
Loop until all visions are implemented |
orc run --squad broad |
Use a custom squad profile |
orc status |
Print current board state |
orc merge |
Rebase dev on main and fast-forward merge |
orc is a workflow engine. On every cycle it reads the board (.orc/work/board.yaml) and drives a pipeline:
pending visions → plan (single LLM call → creates tasks)
open task, no branch → coder (full agentic loop in git worktree)
coder done → review (run tests + single LLM review)
review approved → merge (git merge, LLM for conflicts)
review rejected → coder (retry with feedback)
Only the coder is a full agent with creative autonomy. Planning, review, and merge are orchestrator operations — deterministic steps with targeted LLM calls. This eliminates the infinite-loop and instruction-reading failure modes of a multi-agent system.
Board tools are called in-process by the ToolExecutor. Each coder agent works in its own git worktree with role-appropriate tool permissions.
Work happens on a dev branch. You keep working on main. When you're ready, orc merge brings everything together (with automatic conflict resolution by a coder agent if needed).
Tip: configure the integration branch name via
orc-dev-branchin.orc/config.yaml. Tip: namespace all orc branches withorc-branch-prefix(e.g.orc→.orc/feat/0001-foo).
your-project/
.orc/
agents/ ← coder instructions (override bundled defaults)
squads/
default.yaml ← squad profile (coder count, model, permissions)
config.yaml ← project settings
justfile ← convenience recipes
vision/ ← your feature descriptions go here
work/
board.yaml ← kanban board (managed by orc)
.env.example ← credential template
Existing files are never overwritten unless --force is passed.
Copy .env.example → .env and fill in:
GEMINI_API_TOKEN=... # Gemini API key (default provider)
# OPENAI_API_KEY=... # OpenAI API key (optional)
# GH_TOKEN=... # GitHub Models token (optional)| Variable | Default | Description |
|---|---|---|
GEMINI_API_TOKEN |
— | Gemini API key. Required when using the default gemini provider. |
OPENAI_API_KEY |
— | OpenAI API key. Required when using the openai provider. |
GH_TOKEN |
— | GitHub token. Required when using the github provider. |
COLONY_TELEGRAM_TOKEN |
— | Telegram bot token for notifications. |
COLONY_TELEGRAM_CHAT_ID |
— | Telegram chat ID. Required when token is set. |
ORC_DIR |
.orc/ |
Override config directory path. |
ORC_LOG_LEVEL |
INFO |
DEBUG · INFO · WARNING · ERROR |
ORC_LOG_FORMAT |
console |
console or json |
ORC_LOG_FILE |
.orc/logs/orc.log |
Log file path. Empty string disables file logging. |
| Key | Default | Description |
|---|---|---|
orc-dev-branch |
dev |
Integration branch name. |
orc-branch-prefix |
(empty) | Optional prefix for orc-owned branches. |
orc-worktree-base |
.orc/worktrees |
Base directory for git worktrees. |
Squads define the composition and permissions of your agent team. They live in .orc/squads/{name}.yaml.
name: broad
description: High-throughput squad for large projects.
permissions:
mode: confined # "confined" (default) or "yolo"
allow_tools:
- "shell(just:*)"
deny_tools:
- "shell(git push:*)"
composition:
- role: planner
count: 1
model: claude-sonnet-4.6
- role: coder
count: 4
model: claude-sonnet-4.6
permissions:
allow_tools:
- "shell(npm:*)"
- "shell(cargo:*)"
- role: qa
count: 2
model: claude-sonnet-4.6
review-threshold: HIGH
timeout_minutes: 180| Mode | Behaviour |
|---|---|
confined |
Agents may only use board tools, read, write, shell(git:*), plus explicit allow_tools. Default. |
yolo |
Unrestricted tool access. Use for trusted environments or debugging. |
Controls which severity of issues causes QA to reject work back to coders:
| Threshold | Rejects on |
|---|---|
CRITICAL |
Critical failures only (most lenient) |
HIGH |
High-severity and above |
MID |
Medium-severity and above |
LOW |
Any issue (strictest, default) |
The planner count must always be
1. Scale throughput by adding coders and QA reviewers.
Optionally monitor your agents in real time via Telegram. Set up a bot through @BotFather, add it to a group, and configure COLONY_TELEGRAM_TOKEN + COLONY_TELEGRAM_CHAT_ID.
Agents post structured status updates:
[coder-1](done) 2026-03-01T12:45:00Z: Implemented task 0002.
[qa-1](passed) 2026-03-01T13:00:00Z: No issues found.
[coder-2](blocked) 2026-03-01T14:00:00Z: Need clarification on auth flow…
See CONTRIBUTING.md for the development workflow, commit conventions, and test-first policy.
git clone https://github.com/PietroPasotti/orc.git && cd orc
just install # deps + git hooks
just test # run the suite