[Feature] Automated GitHub Issue Orchestrator for Claude Code

[spejman]

Problem Statement

Currently, working on GitHub issues with Claude Code requires manual intervention for each issue. This creates bottlenecks when multiple issues are ready for automated processing, and requires constant monitoring to know when Claude Code needs input or has completed work. There's no automated way to track progress across multiple issues or get notified about status changes.

User Value

• Automated issue processing: Issues labeled "ready-for-claude" are automatically picked up and processed without manual intervention
• Parallel processing: Multiple issues can be worked on simultaneously with configurable concurrency
• Real-time notifications: Get Telegram alerts when Claude starts, finishes, encounters errors, or needs input - including relevant output
• Persistent state tracking: Processing continues correctly even after system restarts
• Hands-free operation: Once configured, the system runs autonomously via cron, processing issues as they become available

Definition of Done

• Implementation complete with edge cases handled
• Unit tests added (>80% coverage)
• Integration tests for main flows
• Documentation updated
• Code review approved
• CI/CD passes
• Manual testing complete
• Cron job setup documented
• Configuration template provided

Manual Testing Checklist

• Basic flow:
  • Create test issue with "ready-for-claude" label
  • Verify script picks it up within 5 minutes
  • Confirm label changes to "claude-working"
  • Verify branch creation (issue-ISSUE_NUMBER)
  • Confirm Telegram notifications received
• Edge case testing:
  • Multiple issues with "ready-for-claude" label
  • Claude Code requiring user input (verify notification)
  • Claude Code encountering errors (verify notification with output)
  • System restart during processing (verify resume)
  • Issue already has "claude-working" label (should skip)
• Error handling:
  • Invalid GitHub token
  • Invalid Telegram credentials
  • Network failures
  • Claude Code not installed
• Integration:
  • Verify with real GitHub repository
  • Test with actual Telegram bot
  • Confirm branch creation and commits

Potential Solutions

Option 1: Python-based Orchestrator

• Description: Async Python script using aiohttp for GitHub API, asyncio for process management, and python-telegram-bot for notifications
• Pros:
  • Excellent async support for concurrent Claude processes
  • Rich ecosystem for GitHub/Telegram integration
  • Easy JSON state management
  • Good process monitoring capabilities
• Cons:
  • Requires Python runtime and dependencies
  • More complex deployment
• Files to modify:
  • Create: scripts/issue-orchestrator/issue-orchestrator.py
  • Create: scripts/issue-orchestrator/config.json
  • Create: scripts/issue-orchestrator/requirements.txt
  • Create: scripts/issue-orchestrator/setup.sh
  • Create: scripts/issue-orchestrator/README.md

Option 2: Node.js/TypeScript Solution

• Description: TypeScript application using Octokit for GitHub, child_process for Claude, and node-telegram-bot-api
• Pros:
  • Same runtime as Claude Code (Node.js)
  • TypeScript for type safety
  • Native JSON handling
• Cons:
  • Node.js async subprocess handling is more complex
  • Less mature process monitoring tools
• Files to modify:
  • Create: scripts/issue-orchestrator/issue-orchestrator.ts
  • Create: scripts/issue-orchestrator/config.json
  • Create: scripts/issue-orchestrator/package.json
  • Create: scripts/issue-orchestrator/tsconfig.json

Option 3: Bash Script with CLI Tools

• Description: Shell script using gh CLI, direct Claude invocation, and curl for Telegram
• Pros:
  • Minimal dependencies
  • Simple deployment
  • Direct CLI integration
• Cons:
  • Limited concurrent processing control
  • Complex state management in bash
  • Poor error handling
  • Difficult output parsing
• Files to modify:
  • Create: scripts/issue-orchestrator/issue-orchestrator.sh
  • Create: scripts/issue-orchestrator/config.env

Recommended Approach

Option 1 (Python-based Orchestrator) is recommended because:

• Superior async/concurrent processing crucial for managing multiple Claude instances
• Robust process monitoring to detect when Claude needs input
• Clean state management with JSON files
• Excellent error handling and logging
• Easy to parse Claude's JSON output and detect various states
• Well-maintained libraries for GitHub and Telegram integration

Technical Notes

Core Components:

1. Main Orchestrator (scripts/issue-orchestrator/issue-orchestrator.py):

   • Cron-triggered entry point (*/5 * * * *)
   • Fetches issues with "ready-for-claude" label via GitHub API
   • Manages concurrent Claude Code processes
   • Tracks state in processing-state.json
   • Sends Telegram notifications

2. Configuration (scripts/issue-orchestrator/config.json):

   {
     "github": {
       "token": "ghp_...",
       "repo": "owner/repo",
       "max_concurrent": 3
     },
     "telegram": {
       "bot_token": "...",
       "chat_id": "..."
     },
     "claude": {
       "timeout_seconds": 3600,
       "check_interval": 5
     }
   }

3. State Management (scripts/issue-orchestrator/processing-state.json):

   • Tracks: issue_number, status, session_id, branch, start_time
   • Persists across restarts
   • Prevents duplicate processing

4. Process Monitoring:

   • Launch: claude --dangerously-skip-permissions --no-interactive --output-format json "/start-working-on-issue ISSUE_NUMBER"
   • Monitor stdout/stderr for completion or input needed
   • Track session IDs for potential resume
   • Capture output for Telegram notifications

5. GitHub Integration:

   • Label management: "ready-for-claude" → "claude-working"
   • Branch creation: issue-ISSUE_NUMBER
   • Auto-detect repo from git remote if not configured

6. Telegram Notifications:

   • Start: "🚀 Started issue #X: [title]"
   • Complete: "✅ Completed issue #X [duration]"
   • Need input: "⏳ Issue #X needs input: [last output lines]"
   • Error: "❌ Error on issue #X: [error details + output]"

Dependencies:

• Python 3.8+
• aiohttp for GitHub API
• python-telegram-bot or aiogram for Telegram
• gh CLI (for branch operations)
• Claude Code CLI installed and configured

Deployment:

# Setup
cd scripts/issue-orchestrator
pip install -r requirements.txt
cp config.example.json config.json
# Edit config.json with credentials

# Add to crontab
*/5 * * * * cd /path/to/repo/scripts/issue-orchestrator && python issue-orchestrator.py >> orchestrator.log 2>&1

Directory Structure:

scripts/
└── issue-orchestrator/
    ├── issue-orchestrator.py      # Main orchestrator script
    ├── config.json                 # Configuration (gitignored)
    ├── config.example.json         # Configuration template
    ├── requirements.txt            # Python dependencies
    ├── processing-state.json       # State tracking (gitignored)
    ├── orchestrator.log           # Execution logs (gitignored)
    ├── setup.sh                   # Setup script
    └── README.md                  # Documentation