Orcha

GitHub issue-to-agent orchestrator using Claude Code instances.

Orcha monitors GitHub issues for a trigger label and automatically spawns Claude Code agents to work on them. It handles the full lifecycle: approval workflows, agent execution, question/answer interactions, and PR creation.

Architecture

┌─────────────────┐     ┌──────────────┐     ┌─────────────────┐
│  GitHub Webhook │────▶│  Orchestrator │────▶│  Agent Runner   │
└─────────────────┘     │  (queue/state)│     │  (Claude Code)  │
                        └──────────────┘     └─────────────────┘
                               │                      │
                               ▼                      ▼
                        ┌──────────────┐     ┌─────────────────┐
                        │  GitHub API  │◀────│ Workspace Mgr   │
                        │  (comments,  │     │ (branches, PRs) │
                        │   PRs)       │     └─────────────────┘
                        └──────────────┘

Features

• Automatic agent spawning when issues are labeled with agent-work
• Approval workflow for non-trusted users
• Concurrent agent management with configurable limits
• Session persistence for sleep/resume capabilities
• Question handling - agents can ask questions via GitHub comments
• Automatic PR creation when work is complete
• Token usage tracking with cost estimation
• Docker deployment with persistent storage

Prerequisites

• Node.js 20+
• A GitHub App with the following permissions:
  • Issues: Read & Write
  • Pull Requests: Read & Write
  • Contents: Read & Write
• Anthropic API key for Claude Code
• Claude Code CLI installed (npm install -g @anthropic-ai/claude-code)

Installation

Local Development

# Clone the repository
git clone https://github.com/your-org/orcha.git
cd orcha

# Install dependencies
npm install

# Copy environment template
cp .env.example .env

# Edit .env with your credentials
# See Configuration section below

# Run database migrations
npm run migrate

# Start development server
npm run dev

Docker Deployment

# Copy environment template
cp .env.example .env

# Edit .env with your credentials

# Build and start
docker-compose up -d

# View logs
docker-compose logs -f

Configuration

Create a .env file with the following variables:

# GitHub App Configuration
GITHUB_APP_ID=123456
GITHUB_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----"
GITHUB_WEBHOOK_SECRET=your-webhook-secret

# Anthropic API Key
ANTHROPIC_API_KEY=sk-ant-...

# Server
PORT=3000
HOST=0.0.0.0

# Database (SQLite)
DATABASE_PATH=./data/orcha.db

# Workspace directory for cloned repos
WORKSPACE_DIR=./workspaces

# Authorization
# Users who can trigger agents directly (comma-separated)
APPROVED_USERS=alice,bob
# Users who can /approve, /stop, /restart (comma-separated)
MAINTAINERS=alice

# Agent Configuration
MAX_CONCURRENT_AGENTS=3
AGENT_TIMEOUT_MINUTES=60

# Label that triggers agent work
TRIGGER_LABEL=agent-work

GitHub App Setup

1. Create a new GitHub App at https://github.com/settings/apps/new
2. Configure the following:
   • Webhook URL: https://your-server.com/webhook/github
   • Webhook Secret: Generate a secure secret
   • Permissions:
     • Issues: Read & Write
     • Pull Requests: Read & Write
     • Contents: Read & Write
   • Subscribe to events:
     • Issues
     • Issue comment
3. Generate and download a private key
4. Install the app on your repositories

Usage

Triggering an Agent

1. Create an issue describing the work to be done
2. Add the agent-work label (or your configured trigger label)
3. If you're an approved user, the agent starts immediately
4. If not, a maintainer must comment /approve

Commands

Comment these on any tracked issue:

Command	Description	Who can use
/approve	Approve and start the agent	Maintainers
/reject	Reject the request	Maintainers
/stop	Stop the running agent	Maintainers, Approved Users
/restart	Start a fresh agent session	Maintainers, Approved Users

Agent Lifecycle

CREATED → WAITING_APPROVAL (if not approved user)
        → APPROVED (if approved user)

WAITING_APPROVAL → APPROVED (on /approve)
                 → REJECTED (on /reject)

APPROVED → INITIALIZING → RUNNING

RUNNING → WAITING (agent asks question)
        → COMPLETING (agent done)
        → FAILED (error)

WAITING → RUNNING (comment reply received)

COMPLETING → COMPLETED (PR created)

Any state → STOPPED (on /stop)
COMPLETED/FAILED/STOPPED → INITIALIZING (on /restart)

Agent Questions

When an agent needs clarification, it posts a comment on the issue. Reply to that comment to provide your answer, and the agent will resume.

API Endpoints

Endpoint	Method	Description
/health	GET	Health check
/webhook/github	POST	GitHub webhook receiver

Project Structure

orcha/
├── src/
│   ├── index.ts              # Entry point
│   ├── app.ts                # Fastify server
│   ├── config/               # Configuration
│   ├── database/             # SQLite + repositories
│   ├── webhook/              # GitHub webhook handling
│   ├── orchestrator/         # Job queue + state machine
│   ├── agent/                # Claude Code runner
│   ├── github/               # GitHub API client
│   └── workspace/            # Git operations
├── migrations/               # Database migrations
├── Dockerfile
└── docker-compose.yml

Development

# Run in development mode with hot reload
npm run dev

# Type check
npm run typecheck

# Lint
npm run lint

# Build for production
npm run build

# Start production server
npm start

Database

Orcha uses SQLite for simplicity. The database is created automatically on first run.

To reset the database:

rm -rf ./data/orcha.db
npm run migrate

Troubleshooting

Agent not starting

1. Check that the trigger label matches TRIGGER_LABEL
2. Verify the user is in APPROVED_USERS or a maintainer approved
3. Check server logs for errors

Webhook not receiving events

1. Verify the webhook URL is accessible from GitHub
2. Check that GITHUB_WEBHOOK_SECRET matches the app configuration
3. Ensure the app is installed on the repository

Agent timing out

Increase AGENT_TIMEOUT_MINUTES or break the task into smaller issues.

License

MIT