claude-hub/README.md

Claude GitHub Webhook

🚀 Quick Start Guide | 💬 Discord | 📚 Documentation | 📖 Complete Setup | 🔐 Authentication

Deploy Claude Code as a fully autonomous GitHub bot. Create your own bot account, mention it in any issue or PR, and watch AI-powered development happen end-to-end. Claude can implement complete features, review code, merge PRs, wait for CI builds, and run for hours autonomously until tasks are completed. Production-ready microservice with container isolation, automated workflows, and intelligent project management.

What This Does

# In any GitHub issue or PR (using your configured bot account):
@YourBotName implement user authentication with OAuth
@YourBotName review this PR for security vulnerabilities  
@YourBotName fix the failing CI tests and merge when ready
@YourBotName refactor the database layer for better performance

Claude autonomously handles complete development workflows. It analyzes your entire repository, implements features from scratch, conducts thorough code reviews, manages pull requests, monitors CI/CD pipelines, and responds to automated feedback - all without human intervention. No context switching. No manual oversight required. Just seamless autonomous development where you work.

🚀 Quick Start

Follow our 10-minute Quick Start Guide to get Claude responding to your GitHub issues using Cloudflare Tunnel - no domain or complex setup required!

# 1. Clone and configure
git clone https://github.com/claude-did-this/claude-hub.git
cd claude-hub
cp .env.quickstart .env
nano .env  # Add your GitHub token and bot details

# 2. Authenticate Claude (uses your Claude.ai Max subscription)
./scripts/setup/setup-claude-interactive.sh

# 3. Start the service
docker compose up -d

# 4. Create a tunnel (see quickstart guide for details)
cloudflared tunnel --url http://localhost:3002

That's it! Your bot is ready to use. See the complete quickstart guide for detailed instructions and webhook setup.

Autonomous Workflow Capabilities

End-to-End Development 🚀

• Feature Implementation: From requirements to fully tested, production-ready code
• Code Review & Quality: Comprehensive analysis including security, performance, and best practices
• PR Lifecycle Management: Creates branches, commits changes, pushes code, and manages merge process
• CI/CD Monitoring: Actively waits for builds, analyzes test results, and fixes failures
• Automated Code Response: Responds to automated review comments and adapts based on feedback

Intelligent Task Management 🧠

• Multi-hour Operations: Continues working autonomously until complex tasks are 100% complete
• Dependency Resolution: Handles blockers, waits for external processes, and resumes work automatically
• Context Preservation: Maintains project state and progress across long-running operations
• Adaptive Problem Solving: Iterates on solutions based on test results and code review feedback

Key Features

Autonomous Development 🤖

• Complete Feature Implementation: Claude codes entire features from requirements to deployment
• Intelligent PR Management: Automatically creates, reviews, and merges pull requests
• CI/CD Integration: Waits for builds, responds to test failures, and handles automated workflows
• Long-running Tasks: Operates autonomously for hours until complex projects are completed
• Auto-labeling: New issues automatically tagged by content analysis
• Context-aware: Claude understands your entire repository structure and development patterns
• Stateless execution: Each request runs in isolated Docker containers

Claude Orchestration (NEW) 🎭

• Parallel Claude Sessions: Run multiple Claude containers concurrently for complex tasks
• Smart Task Decomposition: Automatically breaks down projects into parallel workstreams
• Dependency Management: Sessions wait for prerequisites before starting
• MCP Integration: Built for the MCP hackathon to showcase super-charged Claude capabilities
• See Claude Orchestration Documentation for details

Performance Architecture ⚡

• Parallel test execution with strategic runner distribution
• Conditional Docker builds (only when code changes)
• Repository caching for sub-second response times
• Advanced build profiling with timing metrics

Enterprise Security 🔒

• Webhook signature verification (HMAC-SHA256)
• AWS IAM role-based authentication
• Pre-commit credential scanning
• Container isolation with minimal permissions
• Fine-grained GitHub token scoping

Bot Account Setup

Current Setup: You need to create your own GitHub bot account:

1. Create a dedicated GitHub account for your bot (e.g., MyProjectBot)
2. Generate a Personal Access Token with repository permissions
3. Configure the bot username in your environment variables
4. Add the bot account as a collaborator to your repositories

Future Release: We plan to release this as a GitHub App that provides a universal bot account, eliminating the need for individual bot setup while maintaining the same functionality for self-hosted instances.

Production Deployment

1. Environment Configuration

# Core settings  
BOT_USERNAME=YourBotName              # GitHub bot account username (create your own bot account)
GITHUB_WEBHOOK_SECRET=<generated>     # Webhook validation
GITHUB_TOKEN=<fine-grained-pat>       # Repository access (from your bot account)

# Claude Authentication - Choose ONE method:

# Option 1: Setup Container (Personal/Development)
# Use existing Claude Max subscription (5x or 20x plans)
# See docs/setup-container-guide.md for setup

# Option 2: Direct API Key (Production/Team)
ANTHROPIC_API_KEY=sk-ant-your-api-key

# Option 3: AWS Bedrock (Enterprise)
AWS_REGION=us-east-1
ANTHROPIC_MODEL=anthropic.claude-3-sonnet-20240229-v1:0
CLAUDE_CODE_USE_BEDROCK=1

# Security
AUTHORIZED_USERS=user1,user2,user3    # Allowed GitHub usernames
CLAUDE_API_AUTH_REQUIRED=1            # Enable API authentication

Authentication Methods

Setup Container (Personal/Development)

Use your existing Claude Max subscription for automation instead of pay-per-use API fees:

# 1. Run interactive authentication setup
./scripts/setup/setup-claude-interactive.sh

# 2. In container: authenticate with your subscription
claude --dangerously-skip-permissions  # Follow authentication flow
exit                                    # Save authentication

# 3. Use captured authentication  
cp -r ${CLAUDE_HUB_DIR:-~/.claude-hub}/* ~/.claude/

Prerequisites: Claude Max subscription (5x or 20x plans). Claude Pro does not include Claude Code access.
Details: Setup Container Guide

Direct API Key (Production/Team)

ANTHROPIC_API_KEY=sk-ant-your-api-key-here

Best for: Production environments, team usage, guaranteed stability.
Details: Authentication Guide

AWS Bedrock (Enterprise)

AWS_REGION=us-east-1
ANTHROPIC_MODEL=anthropic.claude-3-sonnet-20240229-v1:0
CLAUDE_CODE_USE_BEDROCK=1

Best for: Enterprise deployments, AWS integration, compliance requirements.
Details: Authentication Guide

2. GitHub Webhook Setup

1. Navigate to Repository → Settings → Webhooks
2. Add webhook:
   • Payload URL: https://your-domain.com/api/webhooks/github
   • Content type: application/json
   • Secret: Your GITHUB_WEBHOOK_SECRET
   • Events: Select "Send me everything"

3. AWS Authentication Options

# Option 1: IAM Instance Profile (EC2)
# Automatically uses instance metadata

# Option 2: ECS Task Role
# Automatically uses container credentials

# Option 3: AWS Profile
./scripts/aws/setup-aws-profiles.sh

# Option 4: Static Credentials (not recommended)
AWS_ACCESS_KEY_ID=xxx
AWS_SECRET_ACCESS_KEY=xxx

Advanced Usage

Direct API Access

Integrate Claude without GitHub webhooks:

curl -X POST http://localhost:3002/api/claude \
  -H "Content-Type: application/json" \
  -d '{
    "repoFullName": "owner/repo",
    "command": "Analyze security vulnerabilities",
    "authToken": "your-token",
    "useContainer": true
  }'

CLI Tool

# Basic usage
./cli/claude-webhook myrepo "Review the authentication flow"

# PR review
./cli/claude-webhook owner/repo "Review this PR" -p -b feature-branch

# Specific issue
./cli/claude-webhook myrepo "Fix this bug" -i 42

Container Execution Modes

Different operations use tailored security profiles for autonomous execution:

• Auto-tagging: Minimal permissions (Read + GitHub tools only)
• PR Reviews: Standard permissions (full tool access with automated merge capabilities)
• Feature Development: Full development permissions (code editing, testing, CI monitoring)
• Long-running Tasks: Extended container lifetime with checkpoint/resume functionality
• Custom Commands: Configurable via --allowedTools flag

Architecture Deep Dive

Autonomous Request Flow

GitHub Event → Webhook Endpoint → Signature Verification
     ↓                                      ↓
Container Spawn ← Command Parser ← Event Processor
     ↓
Claude Analysis → Feature Implementation → Testing & CI
     ↓                     ↓                    ↓
GitHub API ← Code Review ← PR Management ← Build Monitoring
     ↓
Autonomous Merge/Deploy → Task Completion

Autonomous Container Lifecycle

1. Spawn: New Docker container per request with extended lifetime for long tasks
2. Clone: Repository fetched (or cache hit) with full development setup
3. Execute: Claude implements features, runs tests, monitors CI, handles feedback autonomously
4. Iterate: Continuous development cycle until task completion
5. Deploy: Results pushed, PRs merged, tasks marked complete
6. Cleanup: Container destroyed after successful task completion

Security Layers

• Network: Webhook signature validation
• Authentication: GitHub user allowlist
• Authorization: Fine-grained token permissions
• Execution: Container isolation
• Tools: Operation-specific allowlists

Performance Tuning

Repository Caching

REPO_CACHE_DIR=/cache/repos
REPO_CACHE_MAX_AGE_MS=3600000    # 1 hour

Container Optimization

CONTAINER_LIFETIME_MS=7200000     # 2 hour timeout
CLAUDE_CONTAINER_IMAGE=claudecode:latest

CI/CD Pipeline

• Parallel Jest test execution
• Docker layer caching
• Conditional image builds
• Self-hosted runners for heavy operations

Monitoring & Debugging

Health Check

curl http://localhost:3002/health

Logs

docker compose logs -f webhook

Test Suite

npm test                    # All tests
npm run test:unit          # Unit only
npm run test:integration   # Integration only
npm run test:coverage      # With coverage report

Debug Mode

DEBUG=claude:* npm run dev

Documentation

Deep Dive Guides

• Setup Container Authentication - Technical details for subscription-based auth
• Authentication Guide - All authentication methods and troubleshooting
• Complete Workflow - End-to-end technical guide
• Container Setup - Docker configuration details
• AWS Best Practices - IAM and credential management
• GitHub Integration - Webhook events and permissions

Reference

• Scripts Documentation - Utility scripts and commands
• Command Reference - Build and run commands

Contributing

Development Setup

# Install dependencies
npm install

# Setup pre-commit hooks
./scripts/setup/setup-precommit.sh

# Run in dev mode
npm run dev

Code Standards

• Node.js 20+ with async/await patterns
• Jest for testing with >80% coverage target
• ESLint + Prettier for code formatting
• Conventional commits for version management

Security Checklist

• No hardcoded credentials
• All inputs sanitized
• Webhook signatures verified
• Container permissions minimal
• Logs redact sensitive data

Troubleshooting

Common Issues

Webhook not responding

• Verify signature secret matches
• Check GitHub token permissions
• Confirm webhook URL is accessible

Claude timeouts

• Increase CONTAINER_LIFETIME_MS
• Check AWS Bedrock quotas
• Verify network connectivity

Permission denied

• Confirm user in AUTHORIZED_USERS
• Check GitHub token scopes
• Verify AWS IAM permissions

Support

• Report issues: GitHub Issues
• Detailed troubleshooting: Complete Workflow Guide

License

MIT - See the LICENSE file for details.