Orchestrator for managing multiple LLM CLIs (Claude, Codex, Gemini, OpenCode) using a unified vocabulary of Issue, Run, and Event.
orch runs AI coding agents non-interactively in the background, creating isolated git worktrees for each task. Check status with orch ps, interact when needed with orch attach.
Beta support scope: single machine. The current beta covers running orch on one machine (daemon, worker, and agents all local — zero process management needed). Multi-host / cluster mode (remote masters,
ORCH_REMOTE,--on <target>) works and is used in development, but it is outside the supported beta scope until the multi-host milestone lands.
Paste this into your coding agent (Claude Code, Codex, OpenCode, …):
Fetch https://github.com/proboscis/orch/releases/latest/download/agent-install.md and follow it exactly: install the orch binary, install the orch skill into this agent, then walk me through my first orch run interactively.
The agent installs the binary, installs the orch skill into its own skills directory (so every future session knows orch), and then runs the first tutorial together with you. Manual setup is below.
Prerequisites: a git repository with an origin remote, tmux (or zellij),
and at least one agent CLI installed and logged in (claude, codex,
opencode, or gemini). Full checklist:
Prerequisites.
# Install (recommended) — installs to ~/.local/bin. If `orch` is not found
# afterwards, open a new shell (or source your shell rc) first.
curl -sSL https://raw.githubusercontent.com/proboscis/orch/main/install.sh | bash
# Or with Go — pin the tag: @latest resolves to the last non-beta release
go install github.com/proboscis/orch/cmd/orch@v1.7.0-beta
# One-time, inside your git repo (needs an `origin` remote — orch derives
# project identity from its URL):
mkdir -p .orch && printf 'agent: claude\nbase_branch: main\n' > .orch/config.yaml
orch daemon repo register "$(pwd)" # map project identity -> this checkout
# (daemon and worker start automatically on demand — no manual process management)
# Create an issue — the body is the worker agent's ONLY context, so write a
# complete brief (goal, constraints, acceptance criteria) in your editor.
# --edit opens $EDITOR (falls back to vim); non-interactive: --body "..."
orch issue create my-task --title "Add hello world function" --edit
# Run an agent
orch run my-task --no-pr
# Check status
orch ps
# Interact when needed
orch attach my-task--no-pr keeps this first exercise local when origin does not point to a
real GitHub repository. Drop the flag once a real GitHub remote exists and
gh is authenticated so the agent can push and open a pull request.
Read the full Getting Started guide — 日本語版のローカル入門は ローカルクイックスタート。
| Guide | Description |
|---|---|
| Getting Started | Install → First issue → First run → See it work |
| Agent Install Runbook | One-liner setup executed by your own AI agent (binary + skill + guided first run) |
| ローカルクイックスタート (日本語) | 1 台のマシンで試す最短経路(クラスタ設定なし) |
| Remote Usage | Multi-host mode — works, outside the supported beta scope |
| Daily Workflow | Morning routine, parallel runs, reviewing PRs |
| orch-monitor TUI | Visual dashboard for managing issues and runs |
| Core Concepts | Issue, Run, Event, Status, Worktree explained |
| Configuration | All config options with examples |
| Architecture Decision Records | ADR-0001: issue hex IDs · ADR-0002: worker autostart · ADR-0003: loopback-default listen · ADR-0004: store writes through daemon |
| Backend | Description |
|---|---|
| File | Local markdown files (default) |
| GitHub | GitHub Issues integration |
| Agent | Description |
|---|---|
| Claude | Anthropic's Claude Code |
| OpenCode | Multi-provider open-source agent |
| Codex | OpenAI's Codex |
| Gemini | Google's Gemini |
| Custom | Bring your own agent |
| Reference | Description |
|---|---|
| Commands | Full CLI reference |
| Events | Event types and format |
| Statuses | Status state machine |
| SQL Queries | Query examples and schema |
- Issue: A task specification (markdown file or external ticket)
- Run: One execution attempt for an issue (isolated worktree + branch)
- Event: Append-only log entry tracking run progress
- Status: Current state derived from events (running, waiting, done, etc.)
User runs: orch run my-issue
→ Creates worktree + branch
→ Starts agent in a terminal multiplexer (tmux or zellij)
→ Returns immediately (non-blocking)
User checks: orch ps
→ Shows all runs with status
User interacts: orch attach my-issue
→ Connects to the terminal multiplexer session
→ Detach with Ctrl+B D (tmux) or Ctrl+O D (zellij)
| Status | Meaning | User Action |
|---|---|---|
queued |
Run created, agent not started yet | Wait (transitions quickly) |
booting |
Agent is starting up | Wait |
running |
Agent is working | Wait, or attach to watch |
waiting |
Agent needs input | orch attach to help |
pr_open |
PR created | Review the PR |
done |
Completed | Celebrate! |
failed |
Error occurred | Check logs, retry |
See the Development Guide for:
- Versioning philosophy (Semver)
- Trunk-based development workflow
- Branch naming conventions
- PR guidelines
git tag v0.1.0
git push --tagsSee GitHub Releases for binaries.
License: TBD. During the beta, orch is provided for evaluation purposes only — no license is granted yet, and redistribution is not permitted. A license will be chosen before general availability.