Skip to content

CLAUDE.md

Latest commit

 

History

History
161 lines (128 loc) · 6.78 KB

CLAUDE.md

File metadata and controls

161 lines (128 loc) · 6.78 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Development Commands

npm run dev          # Start local development server (http://localhost:8787)
npm run deploy       # Deploy to Cloudflare Workers
npm run cf-typegen   # Generate TypeScript types after wrangler config changes

⚠️ Important: Always run npm run cf-typegen after making changes to wrangler.jsonc. This regenerates the TypeScript types and updates worker-configuration.d.ts to match your bindings and configuration.

Wrangler CLI Commands

npx wrangler dev                    # Start local development (same as npm run dev)
npx wrangler dev --remote          # Use remote Cloudflare resources
npx wrangler deploy                 # Deploy to production (same as npm run deploy)
npx wrangler login                  # Authenticate with Cloudflare
npx wrangler versions upload        # Upload new version with preview URL

Tech Stack & Architecture

This is a Cloudflare Workers Container project that integrates Claude Code with GitHub for automated issue processing. It combines:

  • TypeScript Worker (src/index.ts) - Main request router and GitHub integration
  • Node.js Container (container_src/src/main.ts) - Containerized Claude Code environment running on port 8080
  • Durable Objects - Two DO classes: GitHubAppConfigDO for encrypted credential storage and MyContainer for container management

Key Architecture Points

Request Flow:

  1. Worker receives requests and routes based on path
  2. GitHub webhooks trigger issue processing in Claude Code containers
  3. Container routes (/container, /lb, /singleton, /error) for testing and load balancing
  4. Setup routes (/claude-setup, /gh-setup/*) handle API key configuration and GitHub app OAuth

Container Management:

  • Extends cf-containers library's Container class
  • Default port 8080, 45-second sleep timeout
  • Lifecycle hooks: onStart(), onStop(), onError()
  • Load balancing support across multiple container instances
  • Contains Claude Code SDK (@anthropic-ai/claude-code) and GitHub API client (@octokit/rest)

GitHub Integration:

  • Uses GitHub App Manifests for one-click app creation
  • Each deployment gets isolated GitHub app with dynamic webhook URLs
  • OAuth flow: /gh-setup → GitHub → /gh-setup/callback → /gh-setup/install
  • Webhook processing: /webhooks/github handles push, pull_request, issues, installation events
  • Encrypted credential storage using AES-256-GCM in Durable Objects

Configuration Files

  • wrangler.jsonc - Workers configuration with container bindings and Durable Objects
  • Dockerfile - Multi-stage build with Node.js, Python, Git, and Claude Code CLI
  • worker-configuration.d.ts - Auto-generated types (run npm run cf-typegen after config changes)
  • .dev.vars - Local environment variables (not committed to git)
  • container_src/package.json - Container dependencies including Claude Code SDK

Key Wrangler Configuration Patterns

{
  "compatibility_date": "2025-05-23",  // Controls API behavior and features
  "nodejs_compat": true,               // Enable Node.js API compatibility
  "vars": {                           // Environment variables
    "ENVIRONMENT": "development"
  },
  "durable_objects": {                // Durable Object bindings
    "bindings": [
      { "name": "MY_CONTAINER", "class_name": "MyContainer" },
      { "name": "GITHUB_APP_CONFIG", "class_name": "GitHubAppConfigDO" }
    ]
  }
}

After modifying bindings or vars in wrangler.jsonc:

  1. Run npm run cf-typegen to update TypeScript types
  2. Check that worker-configuration.d.ts reflects your changes
  3. Update your Env interface in TypeScript code if needed

Development Patterns

Key Endpoints:

  • /claude-setup - Configure Claude API key
  • /gh-setup - GitHub app creation and setup
  • /gh-status - Check configuration status
  • /webhooks/github - GitHub webhook processor
  • /container/* - Basic container functionality
  • /lb/* - Load balancing across 3 containers
  • /singleton/* - Single container instance
  • /error/* - Test container error handling

Environment Variables:

  • Container receives issue context and GitHub credentials from Worker
  • Configure base environment in wrangler.jsonc vars section
  • Sensitive data (API keys, tokens) stored encrypted in Durable Objects

Cloudflare Workers Best Practices

Worker Code Structure

export interface Env {
  MY_CONTAINER: DurableObjectNamespace;
  GITHUB_APP_CONFIG: DurableObjectNamespace;
  // Add other bindings here
  ENVIRONMENT?: string;
}

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
    // Worker logic here
    return new Response("Hello World");
  },
} satisfies ExportedHandler<Env>;

Resource Bindings

  • Durable Objects: Access via env.MY_CONTAINER.get(id)
  • Environment Variables: Access via env.VARIABLE_NAME
  • KV/D1/R2: Configure in wrangler.jsonc, access via env bindings

Development Tips

  • Use console.log() for debugging - visible in wrangler dev and deployed logs
  • Workers must start within 400ms - keep imports and initialization lightweight
  • Use .dev.vars for local secrets (never commit this file)
  • Test with --remote flag to use actual Cloudflare resources during development

Current Implementation Status

✅ Completed:

  • GitHub App Manifest setup and OAuth flow
  • Secure credential storage in Durable Objects with AES-256-GCM encryption
  • Basic webhook processing infrastructure with signature verification
  • Container enhancement with Claude Code SDK and GitHub API integration
  • Issue detection and routing to Claude Code containers

🔧 In Progress:

  • End-to-end issue processing with Claude Code analysis and solutions
  • Pull request creation from Claude's code modifications
  • Enhanced error handling and progress monitoring

Important: Containers are a Beta feature - API may change. The cf-containers library version is pinned to 0.0.7.

Project Architecture Summary

This project creates an automated GitHub issue processor powered by Claude Code:

  1. Setup Phase: Configure Claude API key and GitHub app via web interface
  2. Issue Processing: GitHub webhooks trigger containerized Claude Code analysis
  3. Solution Implementation: Claude Code analyzes repositories and implements solutions
  4. Result Delivery: Solutions are delivered as GitHub comments or pull requests

Key Integration Points:

  • src/handlers/github_webhook.ts - Main webhook entry point
  • src/handlers/github_webhooks/issues.ts - Issue-specific processing
  • container_src/src/main.ts - Claude Code execution environment
  • Durable Objects for persistent, encrypted storage of credentials and state