Gabriel Koerich Orchestrator

Install

brew tap gabrielkoerich/homebrew-tap
brew install orch

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

Agent CLIs

Install at least one agent CLI:

brew install --cask claude-code   # Claude (if available)
brew install --cask codex         # Codex (if available)
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 run <id>      # run a specific task
orch service start      # start background service

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 service start                   # service picks it up automatically

Bare clones live at ~/.orch/projects/<owner>/<repo>.git. Agents always work in worktrees — never in the main clone. Worktrees are under ~/.orch/worktrees/<project>/<branch>/.

GitHub Authentication

The orchestrator requires GitHub authentication to create issues, post comments, and manage PRs. Three auth methods are supported:

Option 1: Personal Access Token (Recommended for individuals)

Create a token at GitHub Settings → Developer settings → Personal access tokens.

# Set as environment variable (add to ~/.zshrc or ~/.bashrc)
export GH_TOKEN="ghp_xxxxxxxxxxxxxxxxxxxx"

# Or configure in ~/.orch/config.yml
gh:
  auth:
    token: "ghp_xxxxxxxxxxxxxxxxxxxx"

Option 2: GitHub App (Recommended for organizations)

GitHub Apps provide better audit trails and scoped permissions for automation:

1. Create a GitHub App in your organization settings
2. Generate a private key and download the .pem file
3. Install the app on your repositories
4. Configure in ~/.orch/config.yml:

github:
  token_mode: github_app
  app_id: "123456"
  private_key_path: "/path/to/app-private-key.pem"

The orchestrator automatically exchanges the App credentials for installation tokens and refreshes them before expiry.

Option 3: gh CLI (Default fallback)

The simplest setup — orch calls gh auth token automatically when no env var or config token is set:

gh auth login

That's it. No extra config needed. To disable this fallback:

# ~/.orch/config.yml
gh:
  allow_gh_fallback: false

Note: The gh CLI fallback is not recommended for service environments (launchd/systemd) as it requires an interactive login session. Use GH_TOKEN via ~/.private or a GitHub App instead.

Security: Service Deployments (Homebrew / launchd)

When orch runs as a background service (brew services start orch), it does not inherit your shell environment. The service process starts with a minimal environment, so you must pass the token through one of these channels:

Option A — ~/.private file (recommended for local installs):

# Create ~/.private with mode 600
echo 'export GH_TOKEN="ghp_xxxxxxxxxxxxxxxxxxxx"' >> ~/.private
chmod 600 ~/.private

The service sources ~/.private if it exists.

Option B — launchd EnvironmentVariables in the plist (for system-wide installs):

<key>EnvironmentVariables</key>
<dict>
  <key>GH_TOKEN</key>
  <string>ghp_xxxxxxxxxxxxxxxxxxxx</string>
</dict>

Edit your plist with sudo launchctl edit <label> or update it via the Homebrew formula.

Option C — GitHub App (recommended for teams and CI):

Use mode: github_app in ~/.orch/config.yml — no long-lived token is stored; the service generates short-lived JWTs and installation tokens automatically.

Security guarantee: Orch never embeds GH_TOKEN in runner scripts on disk. Tokens are injected into the tmux session environment at spawn time (via tmux set-environment) and live only in process memory, not in ~/.orch/state/ artifacts.

Files

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

Per-project config lives at {project_path}/.orch.yml (for GitHub repo and job definitions).

Source files:

How It Works

1. Add a task via orch task add (or via a GitHub issue / scheduled job).
2. Route the task — the LLM router chooses executor + builds a specialized profile and selects skills.
3. Run the task — the chosen executor runs in agentic mode inside a tmux session in the task worktree (PROJECT_DIR) with controlled tool access.
4. Output — the agent writes results to ~/.orch/state/{repo}/tasks/{id}/attempts/{n}/output.json; task metadata is updated in the SQLite store (~/.orch/orch.db).
5. Review — if enabled, a different agent reviews the PR and posts a GitHub review comment.
6. Delegation — if the agent returns delegations, child tasks are created and the parent is blocked until children finish.
7. Error handling — if the agent fails or returns blocked, the error is commented on the GitHub issue with a needs_review label.