Getting Started

Install

brew tap gabrielkoerich/homebrew-tap
brew install orch

On Linux, install the prebuilt binary with cargo-binstall, or build from source with cargo:

cargo binstall orch-cli      # prebuilt x86_64 binary
cargo install orch-cli       # from source, needs libssl-dev and pkg-config
orch service install         # systemd user unit for `orch serve`

orch service start|stop|restart|status drives it through systemctl --user. A user service stops at logout unless lingering is on (loginctl enable-linger $USER).

The Homebrew formula targets macOS on Apple silicon and installs gh and tmux. On Linux, install gh and tmux yourself.

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

The grok CLI must be on PATH. Orch discovers it by the binary name grok.

Quick Start

orch init
orch plan PLAN.md

orch init finds the agent CLIs on PATH and whether each is logged in, and checks gh auth. It asks for one repository, writes a config that lists only non-default values, and starts the service.

--repo OWNER/REPO skips the question. From a git checkout, origin is the default.

orch task add always targets the current project (resolved from CWD). To create tasks for another project, cd into it first. 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 simplest setup is gh auth login — orch picks up the token automatically. No extra config needed.

Tokens are resolved in this order (first match wins):

GH_TOKEN environment variable
GITHUB_TOKEN environment variable
gh.auth.token in ~/.orch/config.yml
gh auth token CLI

Security: Service Deployments (Homebrew / launchd)

When orch runs as a background service (launchd on macOS, the systemd user unit on Linux), 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

At startup orch loads the export KEY=VALUE lines of ~/.private into its environment, if the file 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.

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):

File	Description
`config.yml`	Global runtime configuration
`orch.db`	SQLite task database (internal tasks, metrics, KV store)
`projects/`	Bare clones added via `orch project add`
`worktrees/`	Agent worktrees (`<project>/<branch>/`)
`state/`	Runtime state (logs, prompts, per-task artifacts)

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

Source files:

File	Description
`prompts/agent_system.md`	System prompt (workflow, rules, output format)
`prompts/agent_message.md`	Task message (task details, context, memory)
`prompts/route.md`	Routing + profile generation prompt
`prompts/review_system.md`	Review agent system prompt
`prompts/review_task.md`	Review task prompt (diff, commits, criteria)

How It Works

Add a task via orch task add (or via a GitHub issue / scheduled job).
Route the task: the router picks an agent and the agent's model for the task's complexity. router.mode is round_robin by default. In llm mode the router also builds a profile.
Run the task — the chosen executor runs in agentic mode inside a tmux session in the task worktree (PROJECT_DIR) with controlled tool access.
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).
Review: a different agent reviews the PR when one is available (the authoring agent reviews otherwise) and posts an ## Automated Review comment, or an App review in review.mode: app. An approved task waits in approved until CI passes and orch merges the PR.
Delegation — if the agent returns delegations, child tasks are created and the parent is blocked until children finish.
Error handling: a failed run puts the agent or model in cooldown and routes the task again. After workflow.max_attempts attempts (default 5) the task is blocked.