orc

An AI workflow engine that turns product visions into code.

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.

✨ Highlights

• 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 confined mode with explicit tool allow-lists. Opt in to yolo when 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.

📦 Installation

pip install qorc

# or, with uv:
uv add qorc

Requires Python 3.13+.

🚀 Quick start

cd your-project/
orc bootstrap          # scaffold .orc/ config directory
$EDITOR .env           # fill in credentials (see below)
orc run                # let the orchestra play

That's it. orc will plan tasks, write code, review changes, and merge passing work into your dev branch.

Key commands

🏗️ How it works

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-branch in .orc/config.yaml. Tip: namespace all orc branches with orc-branch-prefix (e.g. orc → .orc/feat/0001-foo).

🗂️ Project layout after bootstrap

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.

⚙️ Configuration

Credentials (.env)

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)

Environment variables

Config file (.orc/config.yaml)

🎻 Squad profiles

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

Permission modes

QA review threshold

Controls which severity of issues causes QA to reject work back to coders:

The planner count must always be 1. Scale throughput by adding coders and QA reviewers.

📱 Telegram notifications

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…

🤝 Contributing

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

📜 License

Apache 2.0