fix: rewrite branch.test.ts to match actual implementation

- Remove tests for non-existent cleanupBranch function
- Fix types: use Octokits instead of Octokit, ParsedGitHubContext instead of EntityContext
- Fix assertions: test actual BranchInfo return type (baseBranch, claudeBranch, currentBranch)
- Add comprehensive test coverage for:
  - Issue branch creation (default/custom base branch, commit signing)
  - PR branch handling (open/closed/merged states)
  - Error handling (branch not found, repository fetch failures)
  - Branch naming (kubernetes-compatible, custom prefixes)
- Use proper Bun test mocking patterns instead of Jest
- Match function signatures and behavior from actual setupBranch implementation

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-authored-by: kashyap murali <km-anthropic@users.noreply.github.com>

README.md

@@ -31,8 +31,25 @@ This command will guide you through setting up the GitHub app and required secre
 - 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 or Google Vertex AI setup, see [docs/cloud-providers.md](./docs/cloud-providers.md).
 
+## 📚 Solutions & Use Cases
+
+Looking for specific automation patterns? Check our **[Solutions Guide](./docs/solutions.md)** 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](./docs/solutions.md)** - **🎯 Ready-to-use automation patterns**
 - **[Migration Guide](./docs/migration-guide.md)** - **⭐ Upgrading from v0.x to v1.0**
 - [Setup Guide](./docs/setup.md) - Manual setup, custom GitHub apps, and security best practices
 - [Usage Guide](./docs/usage.md) - Basic usage, workflow configuration, and input parameters

action.yml

@@ -162,7 +162,7 @@ runs:
         # Install Claude Code if no custom executable is provided
         if [ -z "${{ inputs.path_to_claude_code_executable }}" ]; then
           echo "Installing Claude Code..."
-          curl -fsSL https://claude.ai/install.sh | bash -s 1.0.96
+          curl -fsSL https://claude.ai/install.sh | bash -s 1.0.103
           echo "$HOME/.local/bin" >> "$GITHUB_PATH"
         else
           echo "Using custom Claude Code executable: ${{ inputs.path_to_claude_code_executable }}"

base-action/action.yml

@@ -99,7 +99,7 @@ runs:
       run: |
         if [ -z "${{ inputs.path_to_claude_code_executable }}" ]; then
           echo "Installing Claude Code..."
-          curl -fsSL https://claude.ai/install.sh | bash -s 1.0.96
+          curl -fsSL https://claude.ai/install.sh | bash -s 1.0.103
         else
           echo "Using custom Claude Code executable: ${{ inputs.path_to_claude_code_executable }}"
           # Add the directory containing the custom executable to PATH

docs/custom-automations.md

@@ -2,6 +2,15 @@
 
 These examples show how to configure Claude to act automatically based on GitHub events. When you provide a `prompt` input, the action automatically runs in agent mode without requiring manual @mentions. Without a `prompt`, it runs in interactive mode, responding to @claude mentions.
 
+## Mode Detection & Tracking Comments
+
+The action automatically detects which mode to use based on your configuration:
+
+- **Interactive Mode** (no `prompt` input): Responds to @claude mentions, creates tracking comments with progress indicators
+- **Automation Mode** (with `prompt` input): Executes immediately, **does not create tracking comments**
+
+> **Note**: In v1, automation mode intentionally does not create tracking comments by default to reduce noise in automated workflows. If you need progress tracking, use the `track_progress: true` input parameter.
+
 ## Supported GitHub Events
 
 This action supports the following GitHub events ([learn more GitHub event triggers](https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows)):

docs/migration-guide.md

@@ -74,13 +74,75 @@ The following inputs have been deprecated and replaced:
 ```yaml
 - uses: anthropics/claude-code-action@v1
   with:
-    prompt: "Review this PR for security issues"
+    prompt: |
+      REPO: ${{ github.repository }}
+      PR NUMBER: ${{ github.event.pull_request.number }}
+
+      Review this PR for security issues
     anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
     claude_args: |
       --model claude-4-0-sonnet-20250805
       --allowedTools Edit,Read,Write
 ```
 
+> **⚠️ Important**: For PR reviews, always include the repository and PR context in your prompt. This ensures Claude knows which PR to review.
+
+### Automation with Progress Tracking (New in v1.0)
+
+**Missing the tracking comments from v0.x agent mode?** The new `track_progress` input brings them back!
+
+In v1.0, automation mode (with `prompt` input) doesn't create tracking comments by default to reduce noise. However, if you need progress visibility, you can use the `track_progress` feature:
+
+**Before (v0.x with tracking):**
+
+```yaml
+- uses: anthropics/claude-code-action@beta
+  with:
+    mode: "agent"
+    direct_prompt: "Review this PR for security issues"
+    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+```
+
+**After (v1.0 with tracking):**
+
+```yaml
+- uses: anthropics/claude-code-action@v1
+  with:
+    track_progress: true # Forces tag mode with tracking comments
+    prompt: |
+      REPO: ${{ github.repository }}
+      PR NUMBER: ${{ github.event.pull_request.number }}
+
+      Review this PR for security issues
+    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+```
+
+#### Benefits of `track_progress`
+
+1. **Preserves GitHub Context**: Automatically includes all PR/issue details, comments, and attachments
+2. **Brings Back Tracking Comments**: Creates progress indicators just like v0.x agent mode
+3. **Works with Custom Prompts**: Your `prompt` is injected as custom instructions while maintaining context
+
+#### Supported Events for `track_progress`
+
+The `track_progress` input only works with these GitHub events:
+
+**Pull Request Events:**
+
+- `opened` - New PR created
+- `synchronize` - PR updated with new commits
+- `ready_for_review` - Draft PR marked as ready
+- `reopened` - Previously closed PR reopened
+
+**Issue Events:**
+
+- `opened` - New issue created
+- `edited` - Issue title or body modified
+- `labeled` - Label added to issue
+- `assigned` - Issue assigned to user
+
+> **Note**: Using `track_progress: true` with unsupported events will cause an error.
+
 ### Custom Template with Variables
 
 **Before (v0.x):**
@@ -100,10 +162,16 @@ The following inputs have been deprecated and replaced:
 - uses: anthropics/claude-code-action@v1
   with:
     prompt: |
-      Analyze PR #${{ github.event.pull_request.number }} in ${{ github.repository }}
+      REPO: ${{ github.repository }}
-      Focus on security vulnerabilities in the changed files
+      PR NUMBER: ${{ github.event.pull_request.number }}
+
+      Analyze this pull request focusing on security vulnerabilities in the changed files.
+
+      Note: The PR branch is already checked out in the current working directory.
 ```
 
+> **💡 Tip**: While you can access GitHub context variables in your prompt, it's recommended to use the standard `REPO:` and `PR NUMBER:` format for consistency.
+
 ### Environment Variables
 
 **Before (v0.x):**
@@ -244,6 +312,7 @@ You can also pass MCP configuration from a file:
 - [ ] Convert `disallowed_tools` to `claude_args` with `--disallowedTools`
 - [ ] Move `claude_env` to `settings` JSON format
 - [ ] Move `mcp_config` to `claude_args` with `--mcp-config`
+- [ ] **Optional**: Add `track_progress: true` if you need tracking comments in automation mode
 - [ ] Test workflow in a non-production environment
 
 ## Getting Help

docs/solutions.md

@@ -0,0 +1,591 @@
+# Solutions & Use Cases
+
+This guide provides complete, ready-to-use solutions for common automation scenarios with Claude Code Action. Each solution includes working examples, configuration details, and expected outcomes.
+
+## 📋 Table of Contents
+
+- [Automatic PR Code Review](#automatic-pr-code-review)
+- [Review Only Specific File Paths](#review-only-specific-file-paths)
+- [Review PRs from External Contributors](#review-prs-from-external-contributors)
+- [Custom PR Review Checklist](#custom-pr-review-checklist)
+- [Scheduled Repository Maintenance](#scheduled-repository-maintenance)
+- [Issue Auto-Triage and Labeling](#issue-auto-triage-and-labeling)
+- [Documentation Sync on API Changes](#documentation-sync-on-api-changes)
+- [Security-Focused PR Reviews](#security-focused-pr-reviews)
+
+---
+
+## Automatic PR Code Review
+
+**When to use:** Automatically review every PR opened or updated in your repository.
+
+### Basic Example (No Tracking)
+
+```yaml
+name: Claude Auto Review
+on:
+  pull_request:
+    types: [opened, synchronize]
+
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - uses: anthropics/claude-code-action@v1
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          prompt: |
+            REPO: ${{ github.repository }}
+            PR NUMBER: ${{ github.event.pull_request.number }}
+
+            Please review this pull request with a focus on:
+            - Code quality and best practices
+            - Potential bugs or issues
+            - Security implications
+            - Performance considerations
+
+            Note: The PR branch is already checked out in the current working directory.
+
+            Use `gh pr comment` for top-level feedback.
+            Use `mcp__github_inline_comment__create_inline_comment` to highlight specific code issues.
+            Only post GitHub comments - don't submit review text as messages.
+
+          claude_args: |
+            --allowedTools "mcp__github_inline_comment__create_inline_comment,Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*)"
+```
+
+**Key Configuration:**
+
+- Triggers on `opened` and `synchronize` (new commits)
+- Always include `REPO` and `PR NUMBER` for context
+- Specify tools for commenting and reviewing
+- PR branch is pre-checked out
+
+**Expected Output:** Claude posts review comments directly to the PR with inline annotations where appropriate.
+
+### Enhanced Example (With Progress Tracking)
+
+Want visual progress tracking for PR reviews? Use `track_progress: true` to get tracking comments like in v0.x:
+
+```yaml
+name: Claude Auto Review with Tracking
+on:
+  pull_request:
+    types: [opened, synchronize, ready_for_review, reopened]
+
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - uses: anthropics/claude-code-action@v1
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          track_progress: true # ✨ Enables tracking comments
+          prompt: |
+            REPO: ${{ github.repository }}
+            PR NUMBER: ${{ github.event.pull_request.number }}
+
+            Please review this pull request with a focus on:
+            - Code quality and best practices
+            - Potential bugs or issues
+            - Security implications
+            - Performance considerations
+
+            Provide detailed feedback using inline comments for specific issues.
+
+          claude_args: |
+            --allowedTools "mcp__github_inline_comment__create_inline_comment,Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*)"
+```
+
+**Benefits of Progress Tracking:**
+
+- **Visual Progress Indicators**: Shows "In progress" status with checkboxes
+- **Preserves Full Context**: Automatically includes all PR details, comments, and attachments
+- **Migration-Friendly**: Perfect for teams moving from v0.x who miss tracking comments
+- **Works with Custom Prompts**: Your prompt becomes custom instructions while maintaining GitHub context
+
+**Expected Output:**
+
+1. Claude creates a tracking comment: "Claude Code is reviewing this pull request..."
+2. Updates the comment with progress checkboxes as it works
+3. Posts detailed review feedback with inline annotations
+4. Updates tracking comment to "Completed" when done
+
+---
+
+## Review Only Specific File Paths
+
+**When to use:** Review PRs only when specific critical files change.
+
+**Complete Example:**
+
+```yaml
+name: Review Critical Files
+on:
+  pull_request:
+    types: [opened, synchronize]
+    paths:
+      - "src/auth/**"
+      - "src/api/**"
+      - "config/security.yml"
+
+jobs:
+  security-review:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - uses: anthropics/claude-code-action@v1
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          prompt: |
+            REPO: ${{ github.repository }}
+            PR NUMBER: ${{ github.event.pull_request.number }}
+
+            This PR modifies critical authentication or API files.
+
+            Please provide a security-focused review with emphasis on:
+            - Authentication and authorization flows
+            - Input validation and sanitization
+            - SQL injection or XSS vulnerabilities
+            - API security best practices
+
+            Note: The PR branch is already checked out.
+
+            Post detailed security findings as PR comments.
+
+          claude_args: |
+            --allowedTools "mcp__github_inline_comment__create_inline_comment,Bash(gh pr comment:*)"
+```
+
+**Key Configuration:**
+
+- `paths:` filter triggers only for specific file changes
+- Custom prompt emphasizes security for sensitive areas
+- Useful for compliance or security reviews
+
+**Expected Output:** Security-focused review when critical files are modified.
+
+---
+
+## Review PRs from External Contributors
+
+**When to use:** Apply stricter review criteria for external or new contributors.
+
+**Complete Example:**
+
+```yaml
+name: External Contributor Review
+on:
+  pull_request:
+    types: [opened, synchronize]
+
+jobs:
+  external-review:
+    if: github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - uses: anthropics/claude-code-action@v1
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          prompt: |
+            REPO: ${{ github.repository }}
+            PR NUMBER: ${{ github.event.pull_request.number }}
+            CONTRIBUTOR: ${{ github.event.pull_request.user.login }}
+
+            This is a first-time contribution from @${{ github.event.pull_request.user.login }}.
+
+            Please provide a comprehensive review focusing on:
+            - Compliance with project coding standards
+            - Proper test coverage (unit and integration)
+            - Documentation for new features
+            - Potential breaking changes
+            - License header requirements
+
+            Be welcoming but thorough in your review. Use inline comments for code-specific feedback.
+
+          claude_args: |
+            --allowedTools "mcp__github_inline_comment__create_inline_comment,Bash(gh pr comment:*),Bash(gh pr view:*)"
+```
+
+**Key Configuration:**
+
+- `if:` condition targets specific contributor types
+- Includes contributor username in context
+- Emphasis on onboarding and standards
+
+**Expected Output:** Detailed review helping new contributors understand project standards.
+
+---
+
+## Custom PR Review Checklist
+
+**When to use:** Enforce specific review criteria for your team's workflow.
+
+**Complete Example:**
+
+```yaml
+name: PR Review Checklist
+on:
+  pull_request:
+    types: [opened, synchronize]
+
+jobs:
+  checklist-review:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - uses: anthropics/claude-code-action@v1
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          prompt: |
+            REPO: ${{ github.repository }}
+            PR NUMBER: ${{ github.event.pull_request.number }}
+
+            Review this PR against our team checklist:
+
+            ## Code Quality
+            - [ ] Code follows our style guide
+            - [ ] No commented-out code
+            - [ ] Meaningful variable names
+            - [ ] DRY principle followed
+
+            ## Testing
+            - [ ] Unit tests for new functions
+            - [ ] Integration tests for new endpoints
+            - [ ] Edge cases covered
+            - [ ] Test coverage > 80%
+
+            ## Documentation
+            - [ ] README updated if needed
+            - [ ] API docs updated
+            - [ ] Inline comments for complex logic
+            - [ ] CHANGELOG.md updated
+
+            ## Security
+            - [ ] No hardcoded credentials
+            - [ ] Input validation implemented
+            - [ ] Proper error handling
+            - [ ] No sensitive data in logs
+
+            For each item, check if it's satisfied and comment on any that need attention.
+            Post a summary comment with checklist results.
+
+          claude_args: |
+            --allowedTools "mcp__github_inline_comment__create_inline_comment,Bash(gh pr comment:*)"
+```
+
+**Key Configuration:**
+
+- Structured checklist in prompt
+- Systematic review approach
+- Team-specific criteria
+
+**Expected Output:** Systematic review with checklist results and specific feedback.
+
+---
+
+## Scheduled Repository Maintenance
+
+**When to use:** Regular automated maintenance tasks.
+
+**Complete Example:**
+
+```yaml
+name: Weekly Maintenance
+on:
+  schedule:
+    - cron: "0 0 * * 0" # Every Sunday at midnight
+  workflow_dispatch: # Manual trigger option
+
+jobs:
+  maintenance:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      issues: write
+      pull-requests: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: anthropics/claude-code-action@v1
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          prompt: |
+            REPO: ${{ github.repository }}
+
+            Perform weekly repository maintenance:
+
+            1. Check for outdated dependencies in package.json
+            2. Scan for security vulnerabilities using `npm audit`
+            3. Review open issues older than 90 days
+            4. Check for TODO comments in recent commits
+            5. Verify README.md examples still work
+
+            Create a single issue summarizing any findings.
+            If critical security issues are found, also comment on open PRs.
+
+          claude_args: |
+            --allowedTools "Read,Bash(npm:*),Bash(gh issue:*),Bash(git:*)"
+```
+
+**Key Configuration:**
+
+- `schedule:` for automated runs
+- `workflow_dispatch:` for manual triggering
+- Comprehensive tool permissions for analysis
+
+**Expected Output:** Weekly maintenance report as GitHub issue.
+
+---
+
+## Issue Auto-Triage and Labeling
+
+**When to use:** Automatically categorize and prioritize new issues.
+
+**Complete Example:**
+
+```yaml
+name: Issue Triage
+on:
+  issues:
+    types: [opened]
+
+jobs:
+  triage:
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+      id-token: write
+    steps:
+      - uses: anthropics/claude-code-action@v1
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          prompt: |
+            REPO: ${{ github.repository }}
+            ISSUE NUMBER: ${{ github.event.issue.number }}
+            TITLE: ${{ github.event.issue.title }}
+            BODY: ${{ github.event.issue.body }}
+            AUTHOR: ${{ github.event.issue.user.login }}
+
+            Analyze this new issue and:
+            1. Determine if it's a bug report, feature request, or question
+            2. Assess priority (critical, high, medium, low)
+            3. Suggest appropriate labels
+            4. Check if it duplicates existing issues
+
+            Based on your analysis, add the appropriate labels using:
+            `gh issue edit [number] --add-label "label1,label2"`
+
+            If it appears to be a duplicate, post a comment mentioning the original issue.
+
+          claude_args: |
+            --allowedTools "Bash(gh issue:*),Bash(gh search:*)"
+```
+
+**Key Configuration:**
+
+- Triggered on new issues
+- Issue context in prompt
+- Label management capabilities
+
+**Expected Output:** Automatically labeled and categorized issues.
+
+---
+
+## Documentation Sync on API Changes
+
+**When to use:** Keep docs up-to-date when API code changes.
+
+**Complete Example:**
+
+```yaml
+name: Sync API Documentation
+on:
+  pull_request:
+    types: [opened, synchronize]
+    paths:
+      - "src/api/**/*.ts"
+      - "src/routes/**/*.ts"
+
+jobs:
+  doc-sync:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.head.ref }}
+          fetch-depth: 0
+
+      - uses: anthropics/claude-code-action@v1
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          prompt: |
+            REPO: ${{ github.repository }}
+            PR NUMBER: ${{ github.event.pull_request.number }}
+
+            This PR modifies API endpoints. Please:
+
+            1. Review the API changes in src/api and src/routes
+            2. Update API.md to document any new or changed endpoints
+            3. Ensure OpenAPI spec is updated if needed
+            4. Update example requests/responses
+
+            Use standard REST API documentation format.
+            Commit any documentation updates to this PR branch.
+
+          claude_args: |
+            --allowedTools "Read,Write,Edit,Bash(git:*)"
+```
+
+**Key Configuration:**
+
+- Path-specific trigger
+- Write permissions for doc updates
+- Git tools for committing
+
+**Expected Output:** API documentation automatically updated with code changes.
+
+---
+
+## Security-Focused PR Reviews
+
+**When to use:** Deep security analysis for sensitive repositories.
+
+**Complete Example:**
+
+```yaml
+name: Security Review
+on:
+  pull_request:
+    types: [opened, synchronize]
+
+jobs:
+  security:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+      security-events: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - uses: anthropics/claude-code-action@v1
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          # Optional: Add track_progress: true for visual progress tracking during security reviews
+          # track_progress: true
+          prompt: |
+            REPO: ${{ github.repository }}
+            PR NUMBER: ${{ github.event.pull_request.number }}
+
+            Perform a comprehensive security review:
+
+            ## OWASP Top 10 Analysis
+            - SQL Injection vulnerabilities
+            - Cross-Site Scripting (XSS)
+            - Broken Authentication
+            - Sensitive Data Exposure
+            - XML External Entities (XXE)
+            - Broken Access Control
+            - Security Misconfiguration
+            - Cross-Site Request Forgery (CSRF)
+            - Using Components with Known Vulnerabilities
+            - Insufficient Logging & Monitoring
+
+            ## Additional Security Checks
+            - Hardcoded secrets or credentials
+            - Insecure cryptographic practices
+            - Unsafe deserialization
+            - Server-Side Request Forgery (SSRF)
+            - Race conditions or TOCTOU issues
+
+            Rate severity as: CRITICAL, HIGH, MEDIUM, LOW, or NONE.
+            Post detailed findings with recommendations.
+
+          claude_args: |
+            --allowedTools "mcp__github_inline_comment__create_inline_comment,Bash(gh pr comment:*),Bash(gh pr diff:*)"
+```
+
+**Key Configuration:**
+
+- Security-focused prompt structure
+- OWASP alignment
+- Severity rating system
+
+**Expected Output:** Detailed security analysis with prioritized findings.
+
+---
+
+## Tips for All Solutions
+
+### Always Include GitHub Context
+
+```yaml
+prompt: |
+  REPO: ${{ github.repository }}
+  PR NUMBER: ${{ github.event.pull_request.number }}
+  [Your specific instructions]
+```
+
+### Common Tool Permissions
+
+- **PR Comments**: `Bash(gh pr comment:*)`
+- **Inline Comments**: `mcp__github_inline_comment__create_inline_comment`
+- **File Operations**: `Read,Write,Edit`
+- **Git Operations**: `Bash(git:*)`
+
+### Best Practices
+
+- Be specific in your prompts
+- Include expected output format
+- Set clear success criteria
+- Provide context about the repository
+- Use inline comments for code-specific feedback

docs/usage.md

@@ -52,6 +52,7 @@ jobs:
 | `anthropic_api_key`            | Anthropic API key (required for direct API, not needed for Bedrock/Vertex)                                           | No\*     | -         |
 | `claude_code_oauth_token`      | Claude Code OAuth token (alternative to anthropic_api_key)                                                           | No\*     | -         |
 | `prompt`                       | Instructions for Claude. Can be a direct prompt or custom template for automation workflows                          | No       | -         |
+| `track_progress`               | Force tag mode with tracking comments. Only works with specific PR/issue events. Preserves GitHub context            | No       | `false`   |
 | `claude_args`                  | Additional arguments to pass directly to Claude CLI (e.g., `--max-turns 10 --model claude-4-0-sonnet-20250805`)      | No       | ""        |
 | `base_branch`                  | The base branch to use for creating new branches (e.g., 'main', 'develop')                                           | No       | -         |
 | `use_sticky_comment`           | Use just one comment to deliver PR comments (only applies for pull_request event workflows)                          | No       | `false`   |
@@ -139,7 +140,11 @@ For a comprehensive guide on migrating from v0.x to v1.0, including step-by-step
 ```yaml
 - uses: anthropics/claude-code-action@v1
   with:
-    prompt: "Update the API documentation"
+    prompt: |
+      REPO: ${{ github.repository }}
+      PR NUMBER: ${{ github.event.pull_request.number }}
+
+      Update the API documentation to reflect changes in this PR
     anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
     claude_args: |
       --model claude-4-0-sonnet-20250805

examples/auto-fix-ci-signed/auto-fix-ci-signed.yml

@@ -1,97 +0,0 @@
-name: Auto Fix CI Failures (Signed Commits)
-
-on:
-  workflow_run:
-    workflows: ["CI"]
-    types:
-      - completed
-
-permissions:
-  contents: write
-  pull-requests: write
-  actions: read
-  issues: write
-  id-token: write # Required for OIDC token exchange
-
-jobs:
-  auto-fix-signed:
-    if: |
-      github.event.workflow_run.conclusion == 'failure' &&
-      github.event.workflow_run.pull_requests[0] &&
-      !startsWith(github.event.workflow_run.head_branch, 'claude-auto-fix-ci-signed-')
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-        with:
-          ref: ${{ github.event.workflow_run.head_branch }}
-          fetch-depth: 0
-          token: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Generate fix branch name
-        id: branch
-        run: |
-          BRANCH_NAME="claude-auto-fix-ci-signed-${{ github.event.workflow_run.head_branch }}-${{ github.run_id }}"
-          echo "branch_name=$BRANCH_NAME" >> $GITHUB_OUTPUT
-          # Don't create branch locally - MCP tools will create it via API
-          echo "Generated branch name: $BRANCH_NAME (will be created by MCP tools)"
-
-      - name: Get CI failure details
-        id: failure_details
-        uses: actions/github-script@v7
-        with:
-          script: |
-            const run = await github.rest.actions.getWorkflowRun({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              run_id: ${{ github.event.workflow_run.id }}
-            });
-
-            const jobs = await github.rest.actions.listJobsForWorkflowRun({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              run_id: ${{ github.event.workflow_run.id }}
-            });
-
-            const failedJobs = jobs.data.jobs.filter(job => job.conclusion === 'failure');
-
-            let errorLogs = [];
-            for (const job of failedJobs) {
-              const logs = await github.rest.actions.downloadJobLogsForWorkflowRun({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                job_id: job.id
-              });
-              errorLogs.push({
-                jobName: job.name,
-                logs: logs.data
-              });
-            }
-
-            return {
-              runUrl: run.data.html_url,
-              failedJobs: failedJobs.map(j => j.name),
-              errorLogs: errorLogs
-            };
-
-      - name: Fix CI failures with Claude (Signed Commits)
-        id: claude
-        uses: anthropics/claude-code-action@v1-dev
-        env:
-          CLAUDE_BRANCH: ${{ steps.branch.outputs.branch_name }}
-          BASE_BRANCH: ${{ github.event.workflow_run.head_branch }}
-        with:
-          prompt: |
-            /fix-ci-signed 
-            Failed CI Run: ${{ fromJSON(steps.failure_details.outputs.result).runUrl }}
-            Failed Jobs: ${{ join(fromJSON(steps.failure_details.outputs.result).failedJobs, ', ') }}
-            PR Number: ${{ github.event.workflow_run.pull_requests[0].number }}
-            Branch Name: ${{ steps.branch.outputs.branch_name }}
-            Base Branch: ${{ github.event.workflow_run.head_branch }}
-            Repository: ${{ github.repository }}
-
-            Error logs:
-            ${{ toJSON(fromJSON(steps.failure_details.outputs.result).errorLogs) }}
-          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
-          use_commit_signing: true
-          claude_args: "--allowedTools 'Edit,MultiEdit,Write,Read,Glob,Grep,LS,Bash(bun:*),Bash(npm:*),Bash(npx:*),Bash(gh:*),mcp__github_file_ops__commit_files,mcp__github_file_ops__delete_files'"

examples/auto-fix-ci-signed/commands/fix-ci-signed.md

@@ -1,148 +0,0 @@
----
-description: Analyze and fix CI failures with signed commits using MCP tools
-allowed_tools: Edit,MultiEdit,Write,Read,Glob,Grep,LS,Bash(bun:*),Bash(npm:*),Bash(npx:*),Bash(gh:*),mcp__github_file_ops__commit_files,mcp__github_file_ops__delete_files
----
-
-# Fix CI Failures with Signed Commits
-
-You are tasked with analyzing CI failure logs and fixing the issues using MCP tools for signed commits. Follow these steps:
-
-## Context Provided
-
-$ARGUMENTS
-
-## Important Context Information
-
-Look for these key pieces of information in the arguments:
-
-- **Failed CI Run URL**: Link to the failed CI run
-- **Failed Jobs**: List of jobs that failed
-- **PR Number**: The PR number to comment on
-- **Branch Name**: The fix branch you're working on
-- **Base Branch**: The original PR branch
-- **Error logs**: Detailed logs from failed jobs
-
-## CRITICAL: Use MCP Tools for Git Operations
-
-**IMPORTANT**: You MUST use MCP tools for all git operations to ensure commits are properly signed. DO NOT use `git` commands directly via Bash.
-
-- Use `mcp__github_file_ops__commit_files` to commit and push changes
-- Use `mcp__github_file_ops__delete_files` to delete files
-
-## Step 1: Analyze the Failure
-
-Parse the provided CI failure information to understand:
-
-- Which jobs failed and why
-- The specific error messages and stack traces
-- Whether failures are test-related, build-related, or linting issues
-
-## Step 2: Search and Understand the Codebase
-
-Use MCP search tools to locate the failing code:
-
-- Use `mcp_github_file_ops_server__search_files` or `mcp_github_file_ops_server__file_search` to find failing test names or functions
-- Use `mcp_github_file_ops_server__read_file` to read source files mentioned in error messages
-- Review related configuration files (package.json, tsconfig.json, etc.)
-
-## Step 3: Apply Targeted Fixes
-
-Make minimal, focused changes:
-
-- **For test failures**: Determine if the test or implementation needs fixing
-- **For type errors**: Fix type definitions or correct the code logic
-- **For linting issues**: Apply formatting using the project's tools
-- **For build errors**: Resolve dependency or configuration issues
-- **For missing imports**: Add the necessary imports or install packages
-
-Requirements:
-
-- Only fix the actual CI failures, avoid unrelated changes
-- Follow existing code patterns and conventions
-- Ensure changes are production-ready, not temporary hacks
-- Preserve existing functionality while fixing issues
-
-## Step 4: Verify Fixes Locally
-
-Run available verification commands using Bash:
-
-- Execute the failing tests locally to confirm they pass
-- Run the project's lint command (check package.json for scripts)
-- Run type checking if available
-- Execute any build commands to ensure compilation succeeds
-
-## Step 5: Commit and Push Changes Using MCP
-
-**CRITICAL**: You MUST use MCP tools for committing and pushing:
-
-1. Prepare all your file changes (using Edit/MultiEdit/Write tools as needed)
-2. **Use `mcp__github_file_ops__commit_files` to commit and push all changes**
-   - Pass the file paths you've edited in the `files` array
-   - Set `message` to describe the specific fixes (e.g., "Fix CI failures: remove syntax errors and format code")
-   - The MCP tool will automatically create the branch specified in "Branch Name:" from the context and push signed commits
-
-**IMPORTANT**: The MCP tool will create the branch from the context automatically. The branch name from "Branch Name:" in the context will be used.
-
-Example usage:
-
-```
-mcp__github_file_ops__commit_files with:
-- files: ["src/utils/retry.ts", "src/other/file.ts"]  // List of file paths you edited
-- message: "Fix CI failures: [describe specific fixes]"
-```
-
-Note: The branch will be created from the Base Branch specified in the context.
-
-## Step 6: Create PR Comment (REQUIRED - DO NOT SKIP)
-
-**CRITICAL: You MUST create a PR comment after pushing. This step is MANDATORY.**
-
-After successfully pushing the fixes, you MUST create a comment on the original PR to notify about the auto-fix. DO NOT end the task without completing this step.
-
-1. Extract the PR number from the context provided in arguments (look for "PR Number:" in the context)
-2. **MANDATORY**: Execute the gh CLI command below to create the comment
-3. Verify the comment was created successfully
-
-**YOU MUST RUN THIS COMMAND** (replace placeholders with actual values from context):
-
-```bash
-gh pr comment PR_NUMBER --body "## 🤖 CI Auto-Fix Available (Signed Commits)
-
-Claude has analyzed the CI failures and prepared fixes with signed commits.
-
-[**→ Create pull request to fix CI**](https://github.com/OWNER/REPO/compare/BASE_BRANCH...FIX_BRANCH?quick_pull=1)
-
-_This fix was generated automatically based on the [failed CI run](FAILED_CI_RUN_URL)._"
-```
-
-**IMPORTANT REPLACEMENTS YOU MUST MAKE:**
-
-- Replace `PR_NUMBER` with the actual PR number from "PR Number:" in context
-- Replace `OWNER/REPO` with the repository from "Repository:" in context
-- Replace `BASE_BRANCH` with the branch from "Base Branch:" in context
-- Replace `FIX_BRANCH` with the branch from "Branch Name:" in context
-- Replace `FAILED_CI_RUN_URL` with the URL from "Failed CI Run:" in context
-
-**DO NOT SKIP THIS STEP. The task is NOT complete until the PR comment is created.**
-
-## Step 7: Final Verification
-
-**BEFORE CONSIDERING THE TASK COMPLETE**, verify you have:
-
-1. ✅ Fixed all CI failures
-2. ✅ Committed the changes using `mcp_github_file_ops_server__push_files`
-3. ✅ Verified the branch was pushed successfully
-4. ✅ **CREATED THE PR COMMENT using `gh pr comment` command from Step 6**
-
-If you have NOT created the PR comment, go back to Step 6 and execute the command.
-
-## Important Guidelines
-
-- Always use MCP tools for git operations to ensure proper commit signing
-- Focus exclusively on fixing the reported CI failures
-- Maintain code quality and follow the project's established patterns
-- If a fix requires significant refactoring, document why it's necessary
-- When multiple solutions exist, choose the simplest one that maintains code quality
-- **THE TASK IS NOT COMPLETE WITHOUT THE PR COMMENT**
-
-Begin by analyzing the failure details provided above.

examples/auto-fix-ci/commands/fix-ci.md

@@ -1,127 +0,0 @@
----
-description: Analyze and fix CI failures by examining logs and making targeted fixes
-allowed_tools: Edit,MultiEdit,Write,Read,Glob,Grep,LS,Bash(git:*),Bash(bun:*),Bash(npm:*),Bash(npx:*),Bash(gh:*)
----
-
-# Fix CI Failures
-
-You are tasked with analyzing CI failure logs and fixing the issues. Follow these steps:
-
-## Context Provided
-
-$ARGUMENTS
-
-## Important Context Information
-
-Look for these key pieces of information in the arguments:
-
-- **Failed CI Run URL**: Link to the failed CI run
-- **Failed Jobs**: List of jobs that failed
-- **PR Number**: The PR number to comment on
-- **Branch Name**: The fix branch you're working on
-- **Base Branch**: The original PR branch
-- **Error logs**: Detailed logs from failed jobs
-
-## Step 1: Analyze the Failure
-
-Parse the provided CI failure information to understand:
-
-- Which jobs failed and why
-- The specific error messages and stack traces
-- Whether failures are test-related, build-related, or linting issues
-
-## Step 2: Search and Understand the Codebase
-
-Use search tools to locate the failing code:
-
-- Search for the failing test names or functions
-- Find the source files mentioned in error messages
-- Review related configuration files (package.json, tsconfig.json, etc.)
-
-## Step 3: Apply Targeted Fixes
-
-Make minimal, focused changes:
-
-- **For test failures**: Determine if the test or implementation needs fixing
-- **For type errors**: Fix type definitions or correct the code logic
-- **For linting issues**: Apply formatting using the project's tools
-- **For build errors**: Resolve dependency or configuration issues
-- **For missing imports**: Add the necessary imports or install packages
-
-Requirements:
-
-- Only fix the actual CI failures, avoid unrelated changes
-- Follow existing code patterns and conventions
-- Ensure changes are production-ready, not temporary hacks
-- Preserve existing functionality while fixing issues
-
-## Step 4: Verify Fixes Locally
-
-Run available verification commands:
-
-- Execute the failing tests locally to confirm they pass
-- Run the project's lint command (check package.json for scripts)
-- Run type checking if available
-- Execute any build commands to ensure compilation succeeds
-
-## Step 5: Commit and Push Changes
-
-After applying ALL fixes:
-
-1. Stage all modified files with `git add -A`
-2. Commit with: `git commit -m "Fix CI failures: [describe specific fixes]"`
-3. Document which CI jobs/tests were addressed
-4. **CRITICAL**: Push the branch with `git push origin HEAD` - You MUST push the branch after committing
-
-## Step 6: Create PR Comment (REQUIRED - DO NOT SKIP)
-
-**CRITICAL: You MUST create a PR comment after pushing. This step is MANDATORY.**
-
-After successfully pushing the fixes, you MUST create a comment on the original PR to notify about the auto-fix. DO NOT end the task without completing this step.
-
-1. Extract the PR number from the context provided in arguments (look for "PR Number:" in the context)
-2. **MANDATORY**: Execute the gh CLI command below to create the comment
-3. Verify the comment was created successfully
-
-**YOU MUST RUN THIS COMMAND** (replace placeholders with actual values from context):
-
-```bash
-gh pr comment PR_NUMBER --body "## 🤖 CI Auto-Fix Available
-
-Claude has analyzed the CI failures and prepared fixes.
-
-[**→ Create pull request to fix CI**](https://github.com/OWNER/REPO/compare/BASE_BRANCH...FIX_BRANCH?quick_pull=1)
-
-_This fix was generated automatically based on the [failed CI run](FAILED_CI_RUN_URL)._"
-```
-
-**IMPORTANT REPLACEMENTS YOU MUST MAKE:**
-
-- Replace `PR_NUMBER` with the actual PR number from "PR Number:" in context
-- Replace `OWNER/REPO` with the repository from "Repository:" in context
-- Replace `BASE_BRANCH` with the branch from "Base Branch:" in context
-- Replace `FIX_BRANCH` with the branch from "Branch Name:" in context
-- Replace `FAILED_CI_RUN_URL` with the URL from "Failed CI Run:" in context
-
-**DO NOT SKIP THIS STEP. The task is NOT complete until the PR comment is created.**
-
-## Step 7: Final Verification
-
-**BEFORE CONSIDERING THE TASK COMPLETE**, verify you have:
-
-1. ✅ Fixed all CI failures
-2. ✅ Committed the changes
-3. ✅ Pushed the branch with `git push origin HEAD`
-4. ✅ **CREATED THE PR COMMENT using `gh pr comment` command from Step 6**
-
-If you have NOT created the PR comment, go back to Step 6 and execute the command.
-
-## Important Guidelines
-
-- Focus exclusively on fixing the reported CI failures
-- Maintain code quality and follow the project's established patterns
-- If a fix requires significant refactoring, document why it's necessary
-- When multiple solutions exist, choose the simplest one that maintains code quality
-- **THE TASK IS NOT COMPLETE WITHOUT THE PR COMMENT**
-
-Begin by analyzing the failure details provided above.

examples/ci-failure-auto-fix.yml

@@ -80,7 +80,7 @@ jobs:
 
       - name: Fix CI failures with Claude
         id: claude
-        uses: anthropics/claude-code-action@v1-dev
+        uses: anthropics/claude-code-action@v1
         with:
           prompt: |
             /fix-ci 

examples/claude-args-example.yml

@@ -1,30 +0,0 @@
-name: Claude Args Example
-
-on:
-  workflow_dispatch:
-    inputs:
-      prompt:
-        description: "Prompt for Claude"
-        required: true
-        type: string
-
-jobs:
-  claude-with-custom-args:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Run Claude with custom arguments
-        uses: anthropics/claude-code-action@v1-dev
-        with:
-          prompt: ${{ github.event.inputs.prompt }}
-          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
-
-          # claude_args provides direct CLI argument control
-          # This allows full customization of Claude's behavior
-          claude_args: |
-            --max-turns 15
-            --model claude-opus-4-1-20250805
-            --allowedTools Edit,Read,Write,Bash
-            --disallowedTools WebSearch
-            --system-prompt "You are a senior engineer focused on code quality"

examples/claude-auto-review.yml

@@ -1,48 +0,0 @@
-name: Claude PR Auto Review
-
-on:
-  pull_request:
-    types: [opened, synchronize]
-
-jobs:
-  auto-review:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      pull-requests: read
-      id-token: write
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 1
-
-      - name: Automatic PR Review
-        uses: anthropics/claude-code-action@v1-dev
-        with:
-          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
-          prompt: |
-            REPO: ${{ github.repository }}
-            PR NUMBER: ${{ github.event.pull_request.number }}
-
-            Please review this pull request.
-
-            Note: The PR branch is already checked out in the current working directory.
-
-            Focus on:
-            - Code quality and best practices
-            - Potential bugs or issues
-            - Performance considerations
-            - Security implications
-            - Test coverage
-            - Documentation updates if needed
-            - Verify that README.md and docs are updated for any new features or config changes
-
-            Provide constructive feedback with specific suggestions for improvement.
-            Use `gh pr comment:*` for top-level comments.
-            Use `mcp__github_inline_comment__create_inline_comment` to highlight specific areas of concern.
-            Only your GitHub comments that you post will be seen, so don't submit your review as a normal message, just as comments.
-            If the PR has already been reviewed, or there are no noteworthy changes, don't post anything.
-
-          claude_args: |
-            --allowedTools "mcp__github_inline_comment__create_inline_comment,Bash(gh pr comment:*), Bash(gh pr diff:*), Bash(gh pr view:*)"

examples/claude-modes.yml

@@ -1,54 +0,0 @@
-name: Claude Automatic Mode Detection Examples
-
-on:
-  # Events for interactive mode (responds to @claude mentions)
-  issue_comment:
-    types: [created]
-  issues:
-    types: [opened, labeled]
-  pull_request:
-    types: [opened]
-  # Events for automation mode (runs with explicit prompt)
-  workflow_dispatch:
-  schedule:
-    - cron: "0 0 * * 0" # Weekly on Sunday
-
-jobs:
-  # Interactive Mode - Activated automatically when no prompt is provided
-  interactive-mode-example:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write
-      pull-requests: write
-      issues: write
-      id-token: write
-    steps:
-      - uses: anthropics/claude-code-action@v1-dev
-        with:
-          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
-          # Interactive mode (auto-detected when no prompt):
-          # - Scans for @claude mentions in comments, issues, and PRs
-          # - Only acts when trigger phrase is found
-          # - Creates tracking comments with progress checkboxes
-          # - Perfect for: Interactive Q&A, on-demand code changes
-
-  # Automation Mode - Activated automatically when prompt is provided
-  automation-mode-scheduled-task:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write
-      pull-requests: write
-      issues: write
-      id-token: write
-    steps:
-      - uses: anthropics/claude-code-action@v1-dev
-        with:
-          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
-          prompt: |
-            Check for outdated dependencies and security vulnerabilities.
-            Create an issue if any critical problems are found.
-          # Automation mode (auto-detected when prompt provided):
-          # - Works with any GitHub event
-          # - Executes immediately without waiting for @claude mentions
-          # - No tracking comments created
-          # - Perfect for: scheduled maintenance, automated reviews, CI/CD tasks

examples/claude.yml

@@ -32,14 +32,10 @@ jobs:
 
       - name: Run Claude Code
         id: claude
-        uses: anthropics/claude-code-action@v1-dev
+        uses: anthropics/claude-code-action@v1
         with:
           anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
 
-          # This is an optional setting that allows Claude to read CI results on PRs
-          additional_permissions: |
-            actions: read
-
           # Optional: Customize the trigger phrase (default: @claude)
           # trigger_phrase: "/claude"
 

examples/issue-deduplication.yml

@@ -20,7 +20,7 @@ jobs:
           fetch-depth: 1
 
       - name: Check for duplicate issues
-        uses: anthropics/claude-code-action@v1-dev
+        uses: anthropics/claude-code-action@v1
         with:
           prompt: |
             Analyze this new issue and check if it's a duplicate of existing issues in the repository.

examples/issue-triage.yml

@@ -10,6 +10,7 @@ jobs:
     permissions:
       contents: read
       issues: write
+      id-token: write
 
     steps:
       - name: Checkout repository
@@ -18,7 +19,7 @@ jobs:
           fetch-depth: 0
 
       - name: Triage issue with Claude
-        uses: anthropics/claude-code-action@v1-dev
+        uses: anthropics/claude-code-action@v1
         with:
           prompt: |
             You're an issue triage assistant for GitHub issues. Your task is to analyze the issue and select appropriate labels from the provided list.

examples/manual-code-analysis.yml

@@ -28,10 +28,13 @@ jobs:
           fetch-depth: 2 # Need at least 2 commits to analyze the latest
 
       - name: Run Claude Analysis
-        uses: anthropics/claude-code-action@v1-dev
+        uses: anthropics/claude-code-action@v1
         with:
           anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
           prompt: |
+            REPO: ${{ github.repository }}
+            BRANCH: ${{ github.ref_name }}
+
             Analyze the latest commit in this repository.
 
             ${{ github.event.inputs.analysis_type == 'summarize-commit' && 'Task: Provide a clear, concise summary of what changed in the latest commit. Include the commit message, files changed, and the purpose of the changes.' || '' }}

examples/pr-review-comprehensive.yml

@@ -0,0 +1,74 @@
+name: PR Review with Progress Tracking
+
+# This example demonstrates how to use the track_progress feature to get
+# visual progress tracking for PR reviews, similar to v0.x agent mode.
+
+on:
+  pull_request:
+    types: [opened, synchronize, ready_for_review, reopened]
+
+jobs:
+  review-with-tracking:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+      id-token: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: PR Review with Progress Tracking
+        uses: anthropics/claude-code-action@v1
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+
+          # Enable progress tracking
+          track_progress: true
+
+          # Your custom review instructions
+          prompt: |
+            REPO: ${{ github.repository }}
+            PR NUMBER: ${{ github.event.pull_request.number }}
+
+            Perform a comprehensive code review with the following focus areas:
+
+            1. **Code Quality**
+               - Clean code principles and best practices
+               - Proper error handling and edge cases
+               - Code readability and maintainability
+
+            2. **Security**
+               - Check for potential security vulnerabilities
+               - Validate input sanitization
+               - Review authentication/authorization logic
+
+            3. **Performance**
+               - Identify potential performance bottlenecks
+               - Review database queries for efficiency
+               - Check for memory leaks or resource issues
+
+            4. **Testing**
+               - Verify adequate test coverage
+               - Review test quality and edge cases
+               - Check for missing test scenarios
+
+            5. **Documentation**
+               - Ensure code is properly documented
+               - Verify README updates for new features
+               - Check API documentation accuracy
+
+            Provide detailed feedback using inline comments for specific issues.
+            Use top-level comments for general observations or praise.
+
+          # Tools for comprehensive PR review
+          claude_args: |
+            --allowedTools "mcp__github_inline_comment__create_inline_comment,Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*)"
+
+# When track_progress is enabled:
+# - Creates a tracking comment with progress checkboxes
+# - Includes all PR context (comments, attachments, images)
+# - Updates progress as the review proceeds
+# - Marks as completed when done

examples/pr-review-filtered-authors.yml

@@ -23,7 +23,7 @@ jobs:
           fetch-depth: 1
 
       - name: Review PR from Specific Author
-        uses: anthropics/claude-code-action@v1-dev
+        uses: anthropics/claude-code-action@v1
         with:
           anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
           prompt: |

examples/pr-review-filtered-paths.yml

@@ -24,7 +24,7 @@ jobs:
           fetch-depth: 1
 
       - name: Claude Code Review
-        uses: anthropics/claude-code-action@v1-dev
+        uses: anthropics/claude-code-action@v1
         with:
           anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
           prompt: |

src/github/operations/__tests__/branch.test.ts

@@ -0,0 +1,178 @@
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { mock } from "bun:test";
+import { setupBranch, type BranchInfo } from "../branch";
+import type { Octokits } from "../../api/client";
+import type { FetchDataResult } from "../../data/fetcher";
+import type { ParsedGitHubContext } from "../../context";
+import type { GitHubPullRequest, GitHubIssue } from "../../types";
+
+// Mock process.exit to prevent tests from actually exiting
+const mockExit = mock(() => {});
+const originalExit = process.exit;
+
+describe("setupBranch", () => {
+  let mockOctokits: Octokits;
+  let mockContext: ParsedGitHubContext;
+  let mockGithubData: FetchDataResult;
+
+  beforeEach(() => {
+    // Replace process.exit temporarily
+    (process as any).exit = mockExit;
+    mockExit.mockClear();
+
+    // Simple mock objects
+    mockOctokits = {
+      rest: {
+        repos: {
+          get: mock(() => Promise.resolve({ data: { default_branch: "main" } })),
+        },
+        git: {
+          getRef: mock(() => Promise.resolve({ 
+            data: { object: { sha: "abc123def456" } } 
+          })),
+        },
+      },
+      graphql: mock(() => Promise.resolve({})),
+    } as any;
+
+    mockContext = {
+      repository: {
+        owner: "test-owner",
+        repo: "test-repo",
+        full_name: "test-owner/test-repo",
+      },
+      isPR: false,
+      entityNumber: 123,
+      inputs: {
+        branchPrefix: "claude/",
+        useCommitSigning: false,
+      },
+    } as ParsedGitHubContext;
+
+    // Default mock data for issues
+    mockGithubData = {
+      contextData: {
+        title: "Test Issue",
+        body: "Test issue body",
+        state: "OPEN",
+      } as GitHubIssue,
+      comments: [],
+      changedFiles: [],
+      changedFilesWithSHA: [],
+      reviewData: null,
+    };
+  });
+
+  afterEach(() => {
+    // Restore original process.exit
+    process.exit = originalExit;
+  });
+
+  describe("Issue branch creation", () => {
+    test("should create new branch for issue using default branch as source", async () => {
+      const result = await setupBranch(mockOctokits, mockGithubData, mockContext);
+
+      expect(result.baseBranch).toBe("main");
+      expect(result.claudeBranch).toMatch(/^claude\/issue-123-\d{8}-\d{4}$/);
+      expect(result.currentBranch).toMatch(/^claude\/issue-123-\d{8}-\d{4}$/);
+    });
+
+    test("should use provided base branch as source", async () => {
+      mockContext.inputs.baseBranch = "develop";
+      
+      const result = await setupBranch(mockOctokits, mockGithubData, mockContext);
+
+      expect(result.baseBranch).toBe("develop");
+      expect(result.claudeBranch).toMatch(/^claude\/issue-123-\d{8}-\d{4}$/);
+    });
+
+    test("should handle commit signing mode", async () => {
+      mockContext.inputs.useCommitSigning = true;
+
+      const result = await setupBranch(mockOctokits, mockGithubData, mockContext);
+
+      expect(result.baseBranch).toBe("main");
+      expect(result.currentBranch).toBe("main"); // Should stay on source branch
+      expect(result.claudeBranch).toMatch(/^claude\/issue-123-\d{8}-\d{4}$/);
+    });
+  });
+
+  describe("PR branch handling", () => {
+    beforeEach(() => {
+      mockContext.isPR = true;
+      mockGithubData.contextData = {
+        title: "Test PR",
+        body: "Test PR body",
+        state: "OPEN",
+        baseRefName: "main",
+        headRefName: "feature/test",
+        commits: { totalCount: 5 },
+      } as GitHubPullRequest;
+    });
+
+    test("should checkout existing PR branch for open PR", async () => {
+      const result = await setupBranch(mockOctokits, mockGithubData, mockContext);
+
+      expect(result.baseBranch).toBe("main");
+      expect(result.currentBranch).toBe("feature/test");
+      expect(result.claudeBranch).toBeUndefined(); // No claude branch for open PRs
+    });
+
+    test("should create new branch for closed PR", async () => {
+      const closedPR = mockGithubData.contextData as GitHubPullRequest;
+      closedPR.state = "CLOSED";
+
+      const result = await setupBranch(mockOctokits, mockGithubData, mockContext);
+
+      expect(result.baseBranch).toBe("main");
+      expect(result.claudeBranch).toMatch(/^claude\/pr-123-\d{8}-\d{4}$/);
+      expect(result.currentBranch).toMatch(/^claude\/pr-123-\d{8}-\d{4}$/);
+    });
+
+    test("should create new branch for merged PR", async () => {
+      const mergedPR = mockGithubData.contextData as GitHubPullRequest;
+      mergedPR.state = "MERGED";
+
+      const result = await setupBranch(mockOctokits, mockGithubData, mockContext);
+
+      expect(result.baseBranch).toBe("main");
+      expect(result.claudeBranch).toMatch(/^claude\/pr-123-\d{8}-\d{4}$/);
+    });
+  });
+
+  describe("Error handling", () => {
+    test("should exit with code 1 when source branch doesn't exist", async () => {
+      mockOctokits.rest.git.getRef = mock(() => Promise.reject(new Error("Branch not found")));
+
+      await setupBranch(mockOctokits, mockGithubData, mockContext);
+
+      expect(mockExit).toHaveBeenCalledWith(1);
+    });
+
+    test("should exit with code 1 when repository fetch fails", async () => {
+      mockOctokits.rest.repos.get = mock(() => Promise.reject(new Error("Repository not found")));
+
+      await setupBranch(mockOctokits, mockGithubData, mockContext);
+
+      expect(mockExit).toHaveBeenCalledWith(1);
+    });
+  });
+
+  describe("Branch naming", () => {
+    test("should generate kubernetes-compatible branch names", async () => {
+      const result = await setupBranch(mockOctokits, mockGithubData, mockContext);
+
+      // Branch name should be lowercase, use hyphens, and include timestamp
+      expect(result.claudeBranch).toMatch(/^claude\/issue-123-\d{8}-\d{4}$/);
+      expect(result.claudeBranch?.length).toBeLessThanOrEqual(50);
+    });
+
+    test("should use custom branch prefix", async () => {
+      mockContext.inputs.branchPrefix = "ai/";
+
+      const result = await setupBranch(mockOctokits, mockGithubData, mockContext);
+
+      expect(result.claudeBranch).toMatch(/^ai\/issue-123-\d{8}-\d{4}$/);
+    });
+  });
+});

src/mcp/install-mcp-server.ts

@@ -63,6 +63,9 @@ export async function prepareMcpConfig(
   try {
     const allowedToolsList = allowedTools || [];
 
+    // Detect if we're in agent mode (explicit prompt provided)
+    const isAgentMode = !!context.inputs?.prompt;
+
     const hasGitHubMcpTools = allowedToolsList.some((tool) =>
       tool.startsWith("mcp__github__"),
     );
@@ -71,11 +74,24 @@ export async function prepareMcpConfig(
       tool.startsWith("mcp__github_inline_comment__"),
     );
 
+    const hasGitHubCommentTools = allowedToolsList.some((tool) =>
+      tool.startsWith("mcp__github_comment__"),
+    );
+
+    const hasGitHubCITools = allowedToolsList.some((tool) =>
+      tool.startsWith("mcp__github_ci__"),
+    );
+
     const baseMcpConfig: { mcpServers: Record<string, unknown> } = {
       mcpServers: {},
     };
 
-    // Always include comment server for updating Claude comments
+    // Include comment server:
+    // - Always in tag mode (for updating Claude comments)
+    // - Only with explicit tools in agent mode
+    const shouldIncludeCommentServer = !isAgentMode || hasGitHubCommentTools;
+
+    if (shouldIncludeCommentServer) {
       baseMcpConfig.mcpServers.github_comment = {
         command: "bun",
         args: [
@@ -91,6 +107,7 @@ export async function prepareMcpConfig(
           GITHUB_API_URL: GITHUB_API_URL,
         },
       };
+    }
 
     // Include file ops server when commit signing is enabled
     if (context.inputs.useCommitSigning) {
@@ -136,10 +153,17 @@ export async function prepareMcpConfig(
       };
     }
 
-    // CI server is included when we have a workflow token and context is a PR
+    // CI server is included when:
+    // - In tag mode: when we have a workflow token and context is a PR
+    // - In agent mode: same conditions PLUS explicit CI tools in allowedTools
     const hasWorkflowToken = !!process.env.DEFAULT_WORKFLOW_TOKEN;
+    const shouldIncludeCIServer =
+      (!isAgentMode || hasGitHubCITools) &&
+      isEntityContext(context) &&
+      context.isPR &&
+      hasWorkflowToken;
 
-    if (isEntityContext(context) && context.isPR && hasWorkflowToken) {
+    if (shouldIncludeCIServer) {
       // Verify the token actually has actions:read permission
       const actuallyHasPermission = await checkActionsReadPermission(
         process.env.DEFAULT_WORKFLOW_TOKEN || "",

src/modes/detector.ts

@@ -44,6 +44,10 @@ export function detectMode(context: GitHubContext): AutoDetectedMode {
 
   // Issue events
   if (isEntityContext(context) && isIssuesEvent(context)) {
+    // If prompt is provided, use agent mode (same as PR events)
+    if (context.inputs.prompt) {
+      return "agent";
+    }
     // Check for @claude mentions or labels/assignees
     if (checkContainsTrigger(context)) {
       return "tag";

test/modes/agent.test.ts

@@ -161,9 +161,11 @@ describe("Agent Mode", () => {
 
     // Note: We can't easily test file creation in this unit test,
     // but we can verify the method completes without errors
-    // Agent mode now includes MCP config even with empty user args
+    // With our conditional MCP logic, agent mode with no allowed tools
+    // should not include any MCP config
     const callArgs = setOutputSpy.mock.calls[0];
     expect(callArgs[0]).toBe("claude_args");
-    expect(callArgs[1]).toContain("--mcp-config");
+    // Should be empty or just whitespace when no MCP servers are included
+    expect(callArgs[1]).not.toContain("--mcp-config");
   });
 });

tests/modes/detector.test.ts

@@ -113,6 +113,33 @@ describe("detectMode with enhanced routing", () => {
 
       expect(detectMode(context)).toBe("agent");
     });
+
+    it("should use agent mode for issues with explicit prompt", () => {
+      const context: GitHubContext = {
+        ...baseContext,
+        eventName: "issues",
+        eventAction: "opened",
+        payload: { issue: { number: 1, body: "Test issue" } } as any,
+        entityNumber: 1,
+        isPR: false,
+        inputs: { ...baseContext.inputs, prompt: "Analyze this issue" },
+      };
+
+      expect(detectMode(context)).toBe("agent");
+    });
+
+    it("should use tag mode for issues with @claude mention and no prompt", () => {
+      const context: GitHubContext = {
+        ...baseContext,
+        eventName: "issues",
+        eventAction: "opened",
+        payload: { issue: { number: 1, body: "@claude help" } } as any,
+        entityNumber: 1,
+        isPR: false,
+      };
+
+      expect(detectMode(context)).toBe("tag");
+    });
   });
 
   describe("Comment Events (unchanged behavior)", () => {