orch

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.

Quick Start

# Install (recommended)
curl -sSL https://raw.githubusercontent.com/proboscis/orch/main/install.sh | bash

# Or with Go
# go install github.com/proboscis/orch/cmd/orch@latest

# Create an issue
mkdir -p issues && cat > issues/my-task.md << 'EOF'
---
type: issue
id: my-task
title: Add hello world function
status: open
---
Add a hello world function to the project.
EOF

# Run an agent
orch run my-task

# Check status
orch ps

# Interact when needed
orch attach my-task

Read the full Getting Started guide

Documentation

Guide	Description
Getting Started	Install → First issue → First run → See it work
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

Backends

Backend	Description
File	Local markdown files (default)
GitHub	GitHub Issues integration
Linear	Linear integration

Agents

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

Reference	Description
Commands	Full CLI reference
Events	Event types and format
Statuses	Status state machine
SQL Queries	Query examples and schema

Key Concepts

• 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, blocked, done, etc.)

User runs: orch run my-issue
  → Creates worktree + branch
  → Starts agent in tmux session
  → Returns immediately (non-blocking)

User checks: orch ps
  → Shows all runs with status

User interacts: orch attach my-issue
  → Connects to tmux session
  → Ctrl+B D to detach

Status Quick Reference

Status	Meaning	User Action
running	Agent is working	Wait, or attach to watch
blocked	Agent needs input	orch attach to help
pr_open	PR created	Review the PR
done	Completed	Celebrate!
failed	Error occurred	Check logs, retry

Contributing

See the Development Guide for:

• Versioning philosophy (Semver)
• Trunk-based development workflow
• Branch naming conventions
• PR guidelines

Releasing

git tag v0.1.0
git push --tags

See GitHub Releases for binaries.

License

MIT