Getting Started - Orchestrator

Install

brew tap gabrielkoerich/tap
brew install orchestrator

All dependencies (yq, jq, just, python3, rg, fd) are installed automatically.

Agent CLIs

Install at least one:

brew install --cask claude-code   # Claude
brew install --cask codex         # Codex
brew install opencode             # OpenCode

Optional: gh for GitHub sync, bats for tests.

Quick Start

Option A: Existing local repo

cd ~/projects/my-app
orch init               # configure project (optional GitHub setup)
orch task add "title"   # add a task
orch task next          # route + run next task
orch start              # start background server

Option B: Any GitHub repo

orch project add owner/repo          # bare clone + import issues
orch task add "title" -p owner/repo  # add a task to that project
orch start                           # serve loop picks it up

Bare clones live at ~/.orchestrator/projects/<owner>/<repo>.git. Agents always work in worktrees — never in the main clone.

orch is a short alias for orchestrator — both work interchangeably.

Files

All runtime state lives in ~/.orchestrator/ (ORCH_HOME):

File	Description
`tasks.yml`	Task database
`jobs.yml`	Scheduled job definitions
`config.yml`	Runtime configuration
`skills.yml`	Approved skill repositories and catalog
`skills/`	Cloned skill repositories (via `skills-sync`)
`contexts/`	Persisted context files per task/profile
`projects/`	Bare clones added via `project add`
`worktrees/`	Agent worktrees (`<project>/<branch>/`)
`.orchestrator/`	Runtime state (pid, logs, locks, output, tool history, prompts)

Source files:

File	Description
`prompts/system.md`	System prompt (output format, workflow, constraints)
`prompts/agent.md`	Execution prompt (task details + enriched context)
`prompts/plan.md`	Planning/decomposition prompt
`prompts/route.md`	Routing + profile generation prompt
`prompts/review.md`	Review agent prompt
`scripts/*.sh`	Orchestration commands
`tests/orchestrator.bats`	Tests (bats framework)

How It Works

Add a task to tasks.yml (or via orchestrator task add).
Route the task with an LLM that chooses executor + builds a specialized profile and selects skills.
Run the task with the chosen executor in agentic mode. The agent runs inside $PROJECT_DIR with full tool access.
Output: the agent writes results to .orchestrator/output-{task_id}.json.
Review: if enabled, a different agent reviews the PR and posts a GitHub review.
Delegation: if the agent returns delegations, child tasks are created and the parent is blocked until children finish.
Error handling: if the agent fails or returns blocked, the error is commented on the GitHub issue with a blocked label.