CLAUDE.md

Commands

bun test                # Run tests
bun run typecheck       # TypeScript type checking
bun run format          # Format with prettier
bun run format:check    # Check formatting

What This Is

A GitHub Action that lets Claude respond to @claude mentions on issues/PRs (tag mode) or run tasks via prompt input (agent mode). Mode is auto-detected: if prompt is provided, it's agent mode; if triggered by a comment/issue event with @claude, it's tag mode. See src/modes/detector.ts.

How It Runs

Single entrypoint: src/entrypoints/run.ts orchestrates everything — prepare (auth, permissions, trigger check, branch/comment creation), install Claude Code CLI, execute Claude via base-action/ functions (imported directly, not subprocess), then cleanup (update tracking comment, write step summary). SSH signing cleanup and token revocation are separate always() steps in action.yml.

base-action/ is also published standalone as @anthropic-ai/claude-code-base-action. Don't break its public API. It reads config from INPUT_-prefixed env vars (set by action.yml), not from action inputs directly.

Key Concepts

Auth priority: github_token input (user-provided) > GitHub App OIDC token (default). The claude_code_oauth_token and anthropic_api_key are for the Claude API, not GitHub. Token setup lives in src/github/token.ts.

Mode lifecycle: detectMode() in src/modes/detector.ts picks the mode name ("tag" or "agent"). Trigger checking and prepare dispatch are inlined in run.ts: tag mode calls prepareTagMode() from src/modes/tag/, agent mode calls prepareAgentMode() from src/modes/agent/.

Prompt construction: Tag mode's prepareTagMode() builds the prompt by fetching GitHub data (src/github/data/fetcher.ts), formatting it as markdown (src/github/data/formatter.ts), and writing it to a temp file via createPrompt(). Agent mode writes the user's prompt directly. The prompt includes issue/PR body, comments, diff, and CI status. This is the most important part of the action — it's what Claude sees.

Things That Will Bite You

• Strict TypeScript: noUnusedLocals and noUnusedParameters are enabled. Typecheck will fail on unused variables.
• Discriminated unions for GitHub context: GitHubContext is a union type — call isEntityContext(context) before accessing entity-specific fields like context.issue or context.pullRequest.
• Token lifecycle matters: The GitHub App token is obtained early and revoked in a separate always() step in action.yml. If you move token revocation into run.ts, it won't run if the process crashes. Same for SSH signing cleanup.
• Error phase attribution: The catch block in run.ts uses prepareCompleted to distinguish prepare failures from execution failures. The tracking comment shows different messages for each.
• action.yml outputs reference step IDs: Outputs like execution_file, branch_name, github_token reference steps.run.outputs.*. If you rename the step ID, update the outputs section too.
• Integration testing happens in a separate repo (install-test), not here. The tests in this repo are unit tests.

Code Conventions

• Runtime is Bun, not Node. Use bun test, not jest.
• moduleResolution: "bundler" — imports don't need .js extensions.
• GitHub API calls should use retry logic (src/utils/retry.ts).
• MCP servers are auto-installed at runtime to ~/.claude/mcp/github-{type}-server/.

Claude Code Action

A general-purpose Claude Code action for GitHub PRs and issues that can answer questions and implement code changes. This action intelligently detects when to activate based on your workflow context—whether responding to @claude mentions, issue assignments, or executing automation tasks with explicit prompts. It supports multiple authentication methods including Anthropic direct API, Amazon Bedrock, Google Vertex AI, and Microsoft Foundry.

Features

• 🎯 Intelligent Mode Detection: Automatically selects the appropriate execution mode based on your workflow context—no configuration needed
• 🤖 Interactive Code Assistant: Claude can answer questions about code, architecture, and programming
• 🔍 Code Review: Analyzes PR changes and suggests improvements
• ✨ Code Implementation: Can implement simple fixes, refactoring, and even new features
• 💬 PR/Issue Integration: Works seamlessly with GitHub comments and PR reviews
• 🛠️ Flexible Tool Access: Access to GitHub APIs and file operations (additional tools can be enabled via configuration)
• 📋 Progress Tracking: Visual progress indicators with checkboxes that dynamically update as Claude completes tasks
• 📊 Structured Outputs: Get validated JSON results that automatically become GitHub Action outputs for complex automations
• 🏃 Runs on Your Infrastructure: The action executes entirely on your own GitHub runner (Anthropic API calls go to your chosen provider)
• ⚙️ Simplified Configuration: Unified prompt and claude_args inputs provide clean, powerful configuration aligned with Claude Code SDK

📦 Upgrading from v0.x?

See our Migration Guide for step-by-step instructions on updating your workflows to v1.0. The new version simplifies configuration while maintaining compatibility with most existing setups.

Quickstart

The easiest way to set up this action is through Claude Code in the terminal. Just open claude and run /install-github-app.

This command will guide you through setting up the GitHub app and required secrets.

Note:

• You must be a repository admin to install the GitHub app and add secrets
• This quickstart method is only available for direct Anthropic API users. For AWS Bedrock, Google Vertex AI, or Microsoft Foundry setup, see docs/cloud-providers.md.

📚 Solutions & Use Cases

Looking for specific automation patterns? Check our Solutions Guide for complete working examples including:

• 🔍 Automatic PR Code Review - Full review automation
• 📂 Path-Specific Reviews - Trigger on critical file changes
• 👥 External Contributor Reviews - Special handling for new contributors
• 📝 Custom Review Checklists - Enforce team standards
• 🔄 Scheduled Maintenance - Automated repository health checks
• 🏷️ Issue Triage & Labeling - Automatic categorization
• 📖 Documentation Sync - Keep docs updated with code changes
• 🔒 Security-Focused Reviews - OWASP-aligned security analysis
• 📊 DIY Progress Tracking - Create tracking comments in automation mode

Each solution includes complete working examples, configuration details, and expected outcomes.

Documentation

• Solutions Guide - 🎯 Ready-to-use automation patterns
• Migration Guide - ⭐ Upgrading from v0.x to v1.0
• Setup Guide - Manual setup, custom GitHub apps, and security best practices
• Usage Guide - Basic usage, workflow configuration, and input parameters
• Custom Automations - Examples of automated workflows and custom prompts
• Configuration - MCP servers, permissions, environment variables, and advanced settings
• Experimental Features - Execution modes and network restrictions
• Cloud Providers - AWS Bedrock, Google Vertex AI, and Microsoft Foundry setup
• Capabilities & Limitations - What Claude can and cannot do
• Security - Access control, permissions, and commit signing
• FAQ - Common questions and troubleshooting

📚 FAQ

Having issues or questions? Check out our Frequently Asked Questions for solutions to common problems and detailed explanations of Claude's capabilities and limitations.

License

This project is licensed under the MIT License—see the LICENSE file for details.