Add Claude Code GitHub Workflow

[jamiew]

🤖 Installing Claude Code GitHub App

This PR adds a GitHub Actions workflow that enables Claude Code integration in our repository.

What is Claude Code?

Claude Code is an AI coding agent that can help with:

• Bug fixes and improvements
• Documentation updates
• Implementing new features
• Code reviews and suggestions
• Writing tests
• And more!

How it works

Once this PR is merged, we'll be able to interact with Claude by mentioning @claude in a pull request or issue comment.
Once the workflow is triggered, Claude will analyze the comment and surrounding context, and execute on the request in a GitHub action.

Important Notes

• This workflow won't take effect until this PR is merged
• @claude mentions won't work until after the merge is complete
• The workflow runs automatically whenever Claude is mentioned in PR or issue comments
• Claude gets access to the entire PR or issue context including files, diffs, and previous comments

Security

• Our Anthropic API key is securely stored as a GitHub Actions secret
• Only users with write access to the repository can trigger the workflow
• All Claude runs are stored in the GitHub Actions run history
• Claude's default tools are limited to reading/writing files and interacting with our repo by creating comments, branches, and commits.
• We can add more allowed tools by adding them to the workflow file like:

allowed_tools: Bash(npm install),Bash(npm run build),Bash(npm run lint),Bash(npm run test)

There's more information in the Claude Code action repo.

After merging this PR, let's try mentioning @claude in a comment on any PR to get started!

[claude]

Code Review: Claude Code GitHub Workflow

Thank you for adding Claude Code integration! This is a well-structured PR that adds AI-powered assistance to the repository. Here's my detailed review:

✅ Strengths

1. Clear Documentation: The PR description thoroughly explains what Claude Code is, how it works, and important security considerations.

2. Proper Permissions: Both workflows correctly set minimal necessary permissions (contents: read, pull-requests: read, issues: read, id-token: write).

3. Secure Tool Restrictions: The code review workflow properly restricts Claude to only safe, read-only gh commands for viewing and commenting on PRs.

4. Comprehensive Triggers: The main workflow (claude.yml) correctly handles multiple event types (issue comments, PR review comments, regular reviews, issue creation).

5. Smart Filtering: The conditional logic properly checks for @claude mentions before running, preventing unnecessary workflow executions.

🔍 Observations & Recommendations

1. Path Filtering Mismatch (.github/workflows/claude-code-review.yml:7-10)

The commented-out path filters reference TypeScript/JavaScript files (*.ts, *.tsx, *.js, *.jsx), but this is a Python project using uv.

Recommendation: Update the example paths to match the Python codebase:

# Optional: Only run on specific file changes
# paths:
#   - "src/**/*.py"
#   - "tests/**/*.py"
#   - "pyproject.toml"

2. Shallow Fetch May Limit Context (.github/workflows/claude-code-review.yml:32)

fetch-depth: 1 only fetches the latest commit. For code reviews, Claude might benefit from seeing commit history.

Recommendation: Consider increasing to fetch-depth: 0 or at least fetch-depth: 10 to provide more context for reviews. The main claude.yml already uses shallow fetch appropriately.

3. Missing Integration with Existing CI (.github/workflows/claude-code-review.yml)

The code review workflow runs independently but doesn't reference the project's quality gates defined in CLAUDE.md (mypy, pytest).

Recommendation: Consider enhancing the prompt to reference CI results:

prompt: |
  REPO: ${{ github.repository }}
  PR NUMBER: ${{ github.event.pull_request.number }}
  
  Please review this pull request and provide feedback on:
  - Code quality and best practices
  - Potential bugs or issues
  - Performance considerations
  - Security concerns
  - Test coverage
  - Compliance with quality gates (mypy, pytest must pass per CLAUDE.md)
  
  Check CI results and remind the author if quality gates haven't passed.
  Use the repository's CLAUDE.md for guidance on style and conventions.
  
  Use \`gh pr comment\` with your Bash tool to leave your review as a comment on the PR.

4. Additional Actions Permission (.github/workflows/claude.yml:39-41)

The main workflow includes actions: read permission twice (line 26 and 39-41), though the second one is properly explained as optional.

Note: This is fine and explicit, just worth noting the duplication is intentional for documentation purposes.

5. No Tool Restrictions in Main Workflow (.github/workflows/claude.yml:49)

The main claude.yml workflow has claude_args commented out, meaning Claude would have access to default tools (Read, Write, Edit, Bash, etc.).

Security Consideration: This is mentioned in the PR description but worth emphasizing: After merging, users with write access can trigger Claude to modify files. This is powerful but requires trust in Claude's guardrails and user discretion.

Recommendation: Monitor early interactions closely and consider uncommenting/customizing claude_args if you want more restrictions on what Claude can do when invoked via @claude mentions.

🧪 Test Coverage

Not applicable - These are workflow configurations that will be tested in practice once merged.

🔒 Security Assessment

Overall: Good

✅ Strengths:

• OAuth token properly stored as GitHub secret
• Minimal permissions granted
• Code review workflow restricts tools to safe gh commands only
• Only users with write access can trigger workflows
• All runs logged in GitHub Actions history

⚠️ Awareness Required:

• Main workflow allows file modifications when merged (by design)
• Claude Code is a third-party service (Anthropic) - API calls include repo context
• Consider organizational policies on AI-powered code modifications

📋 Alignment with CLAUDE.md

The PR aligns well with the repository's conventions:

• The prompt references CLAUDE.md directly for style guidance ✅
• Mentions quality gates (though could be more explicit) ⚠️
• The workflow will help enforce commit message format and testing requirements ✅

🎯 Final Verdict

Approval Recommended ✅

This is a solid implementation with good security practices and clear documentation. The suggested improvements above are optional enhancements, not blockers. The PR is ready to merge as-is, with the minor path filter comment being the only "fix" needed (and it's already commented out).

Post-merge suggestions:

1. Test @claude mentions with simple requests first
2. Update path filters after testing if you want to limit scope
3. Monitor Claude's tool usage patterns
4. Consider adding project-specific allowed_tools based on common workflows

Great work adding this capability! 🚀