getting-started.md

Getting Started with orch

This guide will take you from zero to your first working agent run in about 5 minutes.

Prerequisites

Before installing orch, ensure you have:

1. Go 1.22+ - For building orch from source (or use pre-built binaries)
2. tmux or zellij - Terminal multiplexer for agent sessions
3. An LLM CLI - At least one of:
   • Claude Code (claude)
   • OpenCode (opencode)
   • Codex (codex)
   • Gemini CLI (gemini)
4. Git - For worktree management

Quick prerequisite check

# Verify Go
go version

# Verify tmux
tmux -V

# Verify your LLM CLI (example with claude)
claude --version

Installation

Option 1: Download pre-built binary (recommended)

# macOS (Apple Silicon)
curl -L https://github.com/proboscis/orch/releases/latest/download/orch-darwin-arm64 -o orch
chmod +x orch
sudo mv orch /usr/local/bin/

# macOS (Intel)
curl -L https://github.com/proboscis/orch/releases/latest/download/orch-darwin-amd64 -o orch
chmod +x orch
sudo mv orch /usr/local/bin/

# Linux (x86_64)
curl -L https://github.com/proboscis/orch/releases/latest/download/orch-linux-amd64 -o orch
chmod +x orch
sudo mv orch /usr/local/bin/

Option 2: Install from source

go install github.com/proboscis/orch/cmd/orch@latest

Verify installation

orch --help

Initialize your project

Navigate to your git repository and initialize orch:

cd /path/to/your/repo

# Create the config directory
mkdir -p .orch

# Create a minimal config file
cat > .orch/config.yaml << 'EOF'
agent: claude
base_branch: main
EOF

Setting up the issues directory

orch needs a place to store issues. Configure it in .orch/config.yaml.

Option A: Use a separate issues directory (recommended for teams)

# Create an issues directory
mkdir -p ~/orch-issues/issues

# Tell orch where to find issues
cat >> .orch/config.yaml << 'EOF'
issues:
  path: ~/orch-issues
EOF

Option B: Keep issues in the same repo

# Create issues directory in your repo
mkdir -p issues

# Update config
cat >> .orch/config.yaml << 'EOF'
issues:
  backend: local
  path: ./issues
EOF

Create your first issue

An issue is a markdown file describing a task for the agent:

# Create an issue file
cat > ~/orch-issues/issues/my-first-issue.md << 'EOF'
---
type: issue
id: my-first-issue
title: Add a hello world function
status: open
---

# Add a hello world function

Create a simple function in this repository that prints "Hello, World!".

## Requirements
- Create a new file with appropriate naming for the project
- The function should be callable
- Add a brief comment explaining what it does
EOF

Or use the CLI:

orch issue create my-first-issue --title "Add a hello world function" --edit

Run your first agent

Start an agent to work on the issue:

orch run my-first-issue

This will:

1. Create a new git worktree for isolation
2. Create a new git branch
3. Start a tmux session with your configured agent
4. Send the issue content as the initial prompt

The command returns immediately - the agent runs in the background.

Check status

See what's running:

orch ps

Example output:

ISSUE            STATUS   RUN                 AGENT   UPDATED
my-first-issue   running  20260120-163045     claude  2m ago

Status meanings

Status	What it means
queued	Run created, starting soon
booting	Agent is launching
running	Agent is actively working
waiting	Agent needs your input
pr_open	Agent created a PR
done	Task completed
failed	Something went wrong

Interact with the agent

Attach to the agent's terminal session:

orch attach my-first-issue

This opens the tmux session where you can:

• Watch the agent work in real-time
• Type messages to the agent
• Paste images (if the agent supports it)
• Provide input when the agent asks questions

Detach without stopping the agent: Press Ctrl+B then D

See the result

When the agent finishes (status becomes done or pr_open):

# Check final status
orch ps

# View run details
orch show my-first-issue

# If a PR was created, it will show the URL

Stop a run

If you need to stop the agent:

# Stop all runs for an issue
orch stop my-first-issue

# Stop a specific run
orch stop my-first-issue#20260120-163045

Next steps

• Learn the core concepts (Issue, Run, Event, etc.)
• Set up remote usage for server-based orchestration
• Configure different agents
• Set up backend integrations (GitHub, Linear)
• Explore all CLI commands
• Use SQL queries to analyze your runs

Next Level

Once you're comfortable with the basics, explore these power-user features:

orch-monitor TUI

A visual dashboard for managing issues and runs:

# Install the TUI
uv tool install ./orch-monitor-tui

# Launch it
orch-monitor --new

Features:

• See all issues and runs at a glance
• Start runs with a keypress
• Attach to agents directly from the UI
• Chat with a control agent to manage tasks

See the orch-monitor guide for details.

Control Agent

Use a persistent AI agent to manage your orch workflow through conversation:

# Start or attach to control agent
orch agent

# Force a new session
orch agent --new

Ask it to create issues, start runs, check status—all through natural language.

Daily Workflow Patterns

Learn efficient patterns for working with orch day-to-day:

• Morning routines for checking overnight progress
• How to handle waiting agents
• Running multiple agents in parallel
• Reviewing and merging agent PRs

See the Daily Workflow guide.

View Agent Changes

Quickly see what an agent has changed:

# Show full diff
orch diff my-issue

# Show just the stats
orch diff --stat my-issue

Troubleshooting

Run fails immediately

Enable debug output:

orch run --verbose my-issue
# or
ORCH_DEBUG=1 orch run my-issue

Agent seems stuck

Check if it's waiting for input:

orch ps  # Look for "waiting" status
orch attach my-issue  # Connect and provide input

System state seems corrupted

Run the repair command:

orch repair

Check daemon logs

tail -f .orch/daemon.log