An intelligent GitHub code review bot built for Val Town that automatically analyzes pull requests using Claude AI and posts detailed review comments.

• Automatic PR Analysis: Responds to GitHub pull request webhooks instantly
• AI-Powered Reviews: Uses Anthropic's Claude Haiku 4.5 for intelligent code analysis and typo detection
• Secure Integration: Webhook signature verification for security
• Smart File Filtering: Reviews code files and markdown files for typos, skips other documentation and config files
• Detailed Feedback: Provides structured reviews with inline comments on specific lines, including GitHub suggestions for one-click fixes
• Easy Setup: Simple configuration with environment variables
• Debug Tools: Built-in endpoints to test API connections and troubleshoot issues

1. Fork/Copy this project to your Val Town account
2. Set environment variables (see setup section below)
3. Configure GitHub webhook in your repository
4. Create a test PR and watch the magic happen!

When someone opens a pull request, the bot will:

1. 🔄 Post an initial "review in progress" comment
2. 📁 Fetch and analyze changed code files and markdown files (up to 8 files)
3. 🧠 Generate a comprehensive review using Claude Haiku 4.5
4. 💬 Post a structured review with:
   • Summary comment on the PR
   • Inline comments on specific lines with issues
   • GitHub suggestions for one-click fixes (typos, simple errors)
   • For markdown files: typos, grammar issues, and formatting problems
   • For code files: bugs, security concerns, and performance issues
   • Actionable suggestions and improvements

GitHub Token: Create a fine-grained personal access token at https://github.com/settings/personal-access-tokens/new with:

• Repository access: Select the specific repository you want to review
• Permissions > Repository permissions:
  • Metadata: Read-only (required)
  • Contents: Read-only (required to fetch file contents)
  • Pull requests: Read and write (required to post review comments)

Anthropic API Key: Get your API key from Anthropic Console

In Val Town, set these environment variables:

• GITHUB_TOKEN: Your GitHub personal access token
• ANTHROPIC_API_KEY: Your Anthropic API key
• WEBHOOK_SECRET: A random secret string (generate with: openssl rand -hex 32)

Your webhook URL will be: https://[your-username]--[val-id].web.val.run/webhook

You can find this URL by:

1. Opening your index.ts val in Val Town
2. Looking at the URL in your browser
3. Adding /webhook to the end

Example: If your val URL is https://alice--abc123.web.val.run, your webhook URL is https://alice--abc123.web.val.run/webhook

Before setting up the webhook, test your API connections:

1. Open your debug val: https://[your-username]--[debug-val-id].web.val.run
2. Check that all environment variables show "✅ Set"
3. Test GitHub API: Visit /test-github endpoint
4. Test Claude API: Visit /test-claude endpoint

All tests should return "success": true.

In your GitHub repository:

1. Go to Settings > Webhooks > Add webhook
2. Set Payload URL: Your Val Town webhook URL (from step 3)
3. Set Content type: application/json
4. Set Secret: Same value as your WEBHOOK_SECRET environment variable
5. Select Let me select individual events → Check Pull requests
6. Ensure Active is checked
7. Click Add webhook

Create a test pull request in your repository. The bot should:

1. Post an initial "review in progress" comment
2. Analyze the changed files
3. Post a detailed review comment within 30-60 seconds

The bot automatically reviews pull requests when they are opened or reopened. It will:

1. Fetch the changed files from the PR
2. Analyze the code using Claude Haiku 4.5
3. Post a summary comment on the PR
4. Post inline comments on specific lines with issues and suggestions

The bot provides two types of feedback:

1. Summary Comment: Posted on the PR with an overall assessment
2. Inline Comments: Posted on specific lines where issues are found, with actionable suggestions
3. GitHub Suggestions: For simple fixes (typos, formatting), provides one-click suggestions that can be applied directly

This makes it easy to see exactly where problems occur and apply fixes with minimal effort.

├── index.ts              # Main webhook handler (HTTP endpoint)
├── github.ts             # GitHub API integration and PR processing
├── claude.ts             # Claude AI integration for code analysis
├── utils.ts              # Utility functions (webhook verification, file filtering)
├── debug.ts              # Debug endpoints for testing API connections
├── test.ts               # Webhook signature verification tests
├── webhook-test.ts       # Mock webhook payload testing
├── example-env.md        # Environment variable setup guide
└── README.md            # This file

• Webhook Handler (index.ts): Receives GitHub webhooks, verifies signatures, and triggers reviews
• GitHub Integration (github.ts): Fetches PR data, file contents, and posts review comments
• AI Analysis (claude.ts): Generates intelligent code reviews using Claude Haiku 4.5
• Security (utils.ts): HMAC-SHA256 webhook signature verification
• Debug Tools (debug.ts): Test API connections and troubleshoot configuration issues

1. Check that your webhook URL is correct in GitHub settings
2. Verify all environment variables are set in Val Town
3. Check the webhook delivery logs in GitHub (Settings > Webhooks > Recent Deliveries)
4. Look at the Val Town logs for error messages

• Ensure your GitHub token has the correct permissions
• Verify the token hasn't expired
• Check that the repository is accessible with your token

• The bot analyzes up to 10 files per PR to stay within API limits
• Code files are reviewed for quality, security, and best practices
• Markdown files (.md, .mdx) are reviewed for typos, grammar, and formatting
• Very large files are truncated to prevent token limit issues

• Ensure the WEBHOOK_SECRET in Val Town matches the secret in GitHub
• Check that the webhook is configured to send JSON payloads

The bot automatically reviews these file types:

• JavaScript/TypeScript: .js, .ts, .jsx, .tsx
• Python: .py
• Java: .java
• C/C++: .c, .cpp, .h
• C#: .cs
• PHP: .php
• Ruby: .rb
• Go: .go
• Rust: .rs
• Swift: .swift
• Kotlin: .kt
• Web: .html, .css, .scss, .vue, .svelte
• Database: .sql
• Documentation: .md, .mdx (focuses on typos, grammar, and formatting)
• And more...

• Small PRs: The bot works best with focused changes (8 files or fewer)
• Clear Descriptions: Add good PR descriptions to help the AI understand context
• Test First: Use the debug endpoints to verify your setup before going live
• Monitor Usage: Keep an eye on your Anthropic API usage for cost management
• Apply Suggestions: Use GitHub's "Apply suggestion" button for one-click fixes

The bot uses GitHub's suggestion syntax for simple fixes:

• Typos and Grammar: Spelling corrections in markdown files
• Code Fixes: Simple syntax errors, missing punctuation, variable name corrections
• Formatting: Indentation, spacing, and style improvements

When you see a suggestion, you can apply it with one click using GitHub's "Apply suggestion" button!

• Modify the file type filters in utils.ts
• Adjust the Claude prompt in claude.ts for your team's coding standards
• Add custom rules or checks specific to your project
• Integrate with other tools (Slack notifications, JIRA, etc.)

Edit claude.ts to customize the AI review criteria:

// Add your team's specific guidelines
const customGuidelines = `
Additional review criteria:
- Check for proper error handling
- Verify database query optimization
- Ensure proper logging practices
`;

The bot truncates large files to 2000 characters. Adjust in claude.ts:

// Increase or decrease based on your needs
${file.content.substring(0, 2000)}

• File Limit: Reviews up to 8 files per PR (to stay within API token limits)
• File Size: Large files are truncated to 2000 characters for analysis
• File Types: Reviews code files for quality/security and markdown files for typos/grammar
• Dependencies: Requires internet access to GitHub and Anthropic APIs
• Rate Limits: Subject to GitHub and Anthropic API rate limits

These limitations help ensure fast, reliable reviews while managing API costs and complexity.