Add Claude Code GitHub Workflow

[How1337ItIs]

🤖 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 Integration

Overall Assessment

This PR introduces two well-structured GitHub Actions workflows for Claude Code integration. The implementation is clean and follows GitHub Actions best practices. However, there are some important considerations for this specific repository.

---

Strengths

1. Clean Workflow Structure

   • Both workflows follow standard GitHub Actions conventions
   • Proper permission scoping (read-only where possible)
   • Good use of conditional triggers to avoid unnecessary runs

2. Security-Conscious Design

   • OAuth token stored as a GitHub secret
   • Minimal required permissions granted
   • Scoped tool access in claude-code-review.yml using --allowed-tools

3. Well-Documented

   • PR description clearly explains functionality and security model
   • Inline comments explain optional configurations
   • References to official documentation

4. Comprehensive Event Coverage (claude.yml)

   • Handles issue comments, PR review comments, PR reviews, and issues
   • Smart conditional logic to only run when @claude is mentioned

---

Concerns and Recommendations

1. Missing Write Permissions for Code Review Workflow

Issue: The claude-code-review.yml workflow needs pull-requests: write permission to post comments.

Current (.github/workflows/claude-code-review.yml:22-26):
permissions:
contents: read
pull-requests: read # Should be write
issues: read
id-token: write

Recommendation: Change to pull-requests: write

Without this, the gh pr comment command will fail with a permission error.

---

2. Cost and Resource Considerations

Issue: Running automated Claude reviews on every PR (opened, synchronize) could:

• Consume significant API quota (this bot appears to have frequent development)
• Create noise if reviewing trivial changes
• Delay CI feedback if runs take time

Recommendation: Consider one of these approaches:

Option A: Add a label trigger (review only when requested)
on:
pull_request:
types: [opened, synchronize, labeled]
jobs:
claude-review:
if: contains(github.event.pull_request.labels.*.name, claude-review)

Option B: Use path filters (review only critical code changes)
on:
pull_request:
types: [opened, synchronize]
paths:
- src//*.ts
- src/index.ts
- src/config.ts
- src/rpc/
- src/timing/**
- src/time/**

Option C: Enable the commented author filter for external contributors only

---

3. Integration with Repository Testing Requirements

Issue: The CLAUDE.md documentation emphasizes that npm run test:post-integration must pass before commits, but the review workflow does not check this.

Recommendation: Update the review prompt to include bot-specific critical checks:

• Nonce management violations
• Time unit mixing (seconds vs milliseconds)
• Pre-signed transaction cache invalidation
• Hot path performance (T-3s to T-0s)
• References to CLAUDE.md guidelines and post-mortems

---

4. Missing Write Permissions in Main Workflow

Issue: The claude.yml workflow may need expanded permissions if Claude needs to create commits/branches (mentioned in PR description).

Current (.github/workflows/claude.yml:21-26):
permissions:
contents: read
pull-requests: read
issues: read
id-token: write
actions: read

Recommendation: Based on PR description (creating comments, branches, and commits):
permissions:
contents: write
pull-requests: write
issues: write
id-token: write
actions: read

---

5. Potential for Workflow Conflicts

Issue: Both workflows can trigger on the same event:

• User opens PR → claude-code-review.yml runs automatically
• User comments @claude please review → claude.yml also runs

This could create duplicate reviews or conflicting actions.

Recommendation:

• Keep auto-review workflow disabled by default (using label or author filter)
• OR clearly document that users should NOT use @claude for reviews on PRs

---

Security Assessment

Good:

• OAuth token properly stored in secrets
• Limited tool access (gh commands only in review workflow)
• Read-only checkout (fetch-depth: 1)

Considerations:

1. This repository contains private keys in operation (PRIVATE_KEY env var)

   • Ensure CLAUDE_CODE_OAUTH_TOKEN secret has appropriate access controls
   • Consider restricting workflow to specific branches

2. RPC endpoints are sensitive (RPCS_HTTP, RPCS_WS, RPCS_BROADCAST)

   • Claude should not expose these in comments
   • Add note in prompt: Do not include sensitive env vars in review comments

3. Write access allows code modifications

   • Monitor the Actions history regularly

---

Test Coverage

Missing: No tests for the workflows themselves.

Recommendation: After merging, manually test:

1. claude-code-review.yml: Open a test PR and verify comment appears
2. claude.yml: Comment @claude help on an issue and verify response
3. Check GitHub Actions logs for any permission errors

---

Documentation Needs

Per CLAUDE.md documentation maintenance guidelines, this change requires updates:

1. Update CLAUDE.md: Add section on GitHub Actions integration
2. Update docs/DOCUMENTATION_MAINTENANCE.md: Add CI/CD changes to checklist

---

Checklist for Merge

Before merging, address:

• Fix pull-requests: write permission in claude-code-review.yml
• Consider adding label/path filter to avoid running on every PR
• Update review prompt to include bot-specific critical checks
• Verify CLAUDE_CODE_OAUTH_TOKEN secret is configured
• Update CLAUDE.md with GitHub Actions integration section
• Test workflows after merge (create test PR/issue)
• Document in changelog (docs/DOCUMENTATION_CHANGE_LOG.md)

---

Bot-Specific Notes

Given this is a high-performance NFT minting bot with critical timing requirements:

1. Hot Path Protection: Ensure Claude reviews never suggest changes that add latency to T-3s to T-0s execution path
2. Time Units: Reviews should catch any mixing of seconds/milliseconds
3. Nonce Management: Any changes to nonce fetching/refresh logic need extra scrutiny
4. Gas Calculations: Changes to Battering Ram Mode (50x gas) should reference post-mortems

The automated review can be a valuable safety net for catching violations of these critical patterns.

---

Approval Recommendation

Approve with changes: The workflows are well-designed, but need permission fixes and configuration tuning for this repository specific needs.

Priority: Fix the pull-requests: write permission issue before merging, or the review workflow will fail silently.