feat: implement Claude Code GitHub Action v1.0 with auto-detection and slash commands (#421)

* feat: implement Claude Code GitHub Action v1.0 with auto-detection and slash commands Major features: - Mode auto-detection based on GitHub event type - Unified prompt field replacing override_prompt and direct_prompt - Slash command system with pre-built commands - Full backward compatibility with v0.x Key changes: - Add mode detector for automatic mode selection - Implement slash command loader with YAML frontmatter support - Update action.yml with new prompt input - Create pre-built slash commands for common tasks - Update all tests for v1.0 compatibility Breaking changes (with compatibility): - Mode input now optional (auto-detected) - override_prompt deprecated (use prompt) - direct_prompt deprecated (use prompt) * test + formatting fixes * feat: simplify to two modes (tag and agent) for v1.0 BREAKING CHANGES: - Remove review mode entirely - now handled via slash commands in agent mode - Remove all deprecated backward compatibility fields (mode, anthropic_model, override_prompt, direct_prompt) - Simplify mode detection: prompt overrides everything, then @claude mentions trigger tag mode, default is agent mode - Remove slash command resolution from GitHub Action - Claude Code handles natively - Remove variable substitution - prompts passed through as-is Architecture changes: - Only two modes now: tag (for @claude mentions) and agent (everything else) - Agent mode is the default for all events including PRs - Users configure behavior via prompts/slash commands (e.g. /review) - GitHub Action is now a thin wrapper that passes prompts to Claude Code - Mode names changed: 'experimental-review' → removed entirely This aligns with the philosophy that the GitHub Action should do minimal work and delegate to Claude Code for all intelligent behavior. * fix: address PR review comments for v1.0 simplification - Remove duplicate prompt field spread (line 160) - Remove async from generatePrompt since slash commands are handled by Claude Code - Add detailed comment explaining why prompt → agent mode logic - Remove entire slash-commands loader and directories as Claude Code handles natively - Simplify prompt generation to just pass through to Claude Code These changes align with v1.0 philosophy: GitHub Action is a thin wrapper that delegates everything to Claude Code for native handling. * chore: remove unused js-yaml dependencies These were added for slash-command YAML parsing but are no longer needed since we removed slash-command preprocessing entirely * fix: remove experimental-review mode reference from MCP config The inline comment server configuration was checking for deprecated 'mode' field. Since review mode is removed in v1.0, this conditional block is no longer needed. * prettify * feat: add claudeArgs input for direct CLI argument passing - Add claude_args input to both action.yml files - Implement shell-style argument parsing with quote handling - Pass arguments directly to Claude CLI for maximum flexibility - Add comprehensive tests for argument parsing - Log custom arguments for debugging Users can now pass any Claude CLI arguments directly: claude_args: '--max-turns 3 --mcp-config /path/to/config.json' This provides power users full control over Claude's behavior without waiting for specific inputs to be added to the action. * refactor: use industry-standard shell-quote for argument parsing - Replace custom parseShellArgs with battle-tested shell-quote package - Simplify code by removing unnecessary -p filtering (Claude handles it) - Update tests to use shell-quote directly - Add example workflow showing claude_args usage This provides more robust argument parsing while reducing code complexity. * bun format * feat: add claudeArgs input for direct CLI argument passing - Add claude_args input to action.yml for flexible CLI control - Parse arguments with industry-standard shell-quote library - Maintain proper argument order: -p [claudeArgs] [legacy] [BASE_ARGS] - Keep tag mode defaults (needed for functionality) - Agent mode has no defaults (full user control) - Add comprehensive tests for new functionality - Add example workflow showing usage * format * refactor: complete v1.0 simplification by removing all legacy inputs - Remove all backward compatibility for v1.0 simplification - Remove 10 legacy inputs from base-action/action.yml - Remove 9 legacy inputs from main action.yml - Simplify ClaudeOptions type to just timeoutMinutes and claudeArgs - Remove all legacy option handling from prepareRunConfig - Update tests to remove references to deleted fields - Remove obsolete test file github/context.test.ts - Clean up types to remove customInstructions, allowedTools, disallowedTools Users now use claudeArgs exclusively for CLI control. * fix: update MCP server tests after removing additionalPermissions - Change github_ci server logic to check for workflow token presence - Update test names to reflect new behavior - Fix test that was incorrectly setting workflow token * model version update * Update package json * remove deprecated workflow file (tests features we no longer support) * Simplify agent mode and re-add additional_permissions input - Agent mode now only triggers when explicit prompt is provided - Removed automatic triggering for workflow_dispatch/schedule without prompt - Re-added additional_permissions input for requesting GitHub permissions - Fixed TypeScript types for mock context helpers to properly handle partial inputs - Updated documentation to reflect simplified mode behavior * Fix MCP config not being passed to Claude CLI The MCP servers (including github_comment server) were configured but not passed to Claude. This caused the "update_claude_comment" tool to be unavailable. Changes: - Write MCP config to a file at $RUNNER_TEMP/claude-mcp-config.json - Add mcp_config_file output from prepare.ts - Pass MCP config file via --mcp-config flag in claude_args - Use fs/promises writeFile to match codebase conventions * Fix MCP tool availability and shell escaping in tag mode Pass MCP config and allowed tools through claude_args to ensure tools like mcp__github_comment__update_claude_comment are properly available to Claude CLI. Key changes: - Tag mode outputs claude_args with MCP config (as JSON string) and allowed tools - Fixed shell escaping vulnerability when JSON contains single quotes - Agent mode passes through user-provided claude_args unchanged - Re-added mcp_config input for users to provide custom MCP servers - Cleaned up misleading comments and unused file operations - Clarified test workflow is for fork testing Security fix: Properly escape single quotes in MCP config JSON to prevent shell injection vulnerabilities. Co-Authored-By: Claude <noreply@anthropic.com> * bun format * tests, typecheck, format * registry test update * Update agent mode to have github server as a default * Fix agent mode to include GitHub MCP server with proper token * Simplify review workflow - prevent multiple submissions - Rename workflow to avoid conflicts - Remove review submission tools - Keep only essential tools for reading and analyzing PR * Add GitHub MCP server and context prefix to agent mode - Include main GitHub MCP server (Docker-based) by default - Fetch and prefix GitHub context to prompts when in PR/issue context - Users no longer need to manually configure GitHub tools * Delete .github/workflows/claude-auto-review-test.yml * Remove github_comment and inline_comment servers from agent mode defaults - Agent mode now only includes the main GitHub MCP server by default - Users can add additional servers via mcp_config if needed - Reduces unnecessary MCP server overhead * Remove all default MCP servers from agent mode Agent mode now starts with no default servers - users must explicitly configure any MCP servers they need via mcp_config input * Remove GitHub context prefixing and clean up agent mode - Remove automatic GitHub context fetching and prefixing - Remove unused imports (fetcher, formatter, context checks) - Clean up comments - Agent mode now simply passes through the user's prompt as-is * Add GitHub MCP support to agent mode - Parse --allowedTools from claude_args to detect when user wants GitHub MCPs - Wire up github_inline_comment server in prepareMcpConfig for PR contexts - Update agent mode to use prepareMcpConfig instead of manual config - Add comprehensive tests for parseAllowedTools edge cases - Fix TypeScript types to support both entity and automation contexts * Format code with prettier * Fix agent mode test to expect branch values * Fix agent test to handle dynamic branch names from environment * Better fix: Control environment variables in agent test for predictable behavior * minor formatting * Simplify MCP configuration to use multiple --mcp-config flags - Remove MCP config merging logic from prepareMcpConfig - Update agent and tag modes to pass multiple --mcp-config flags - Let Claude handle config merging natively through multiple flags - Fix TypeScript errors in test file This approach is cleaner and relies on Claude's built-in support for multiple --mcp-config flags instead of manual JSON merging. * feat: Copy project subagents to Claude runtime environment Enables custom subagents defined in .claude/agents/ to work in GitHub Actions by: - Checking for project agents in GITHUB_WORKSPACE/.claude/agents/ - Creating ~/.claude/agents/ directory if needed - Copying all .md agent files to Claude's runtime location - Following same pattern as slash commands for consistency Includes comprehensive test coverage for the new functionality. * formatting * Add auto-fix CI workflows with slash command and inline approaches - Add /fix-ci slash command for programmatic CI failure fixing - Create auto-fix-ci.yml workflow using slash command approach - Create auto-fix-ci-inline.yml workflow with full inline prompt - Both workflows automatically analyze CI failures and create fix branches * Add workflow_run event support and auto-fix CI workflows - Add support for workflow_run event type in GitHub context - Create /fix-ci slash command for programmatic CI failure fixing - Add auto-fix-ci.yml workflow using slash command approach - Add auto-fix-ci-inline.yml workflow with full inline prompt - Both workflows automatically analyze CI failures and create fix branches - Fix workflow syntax issues with optional chaining operator * Use proper WorkflowRunEvent type instead of any * bun formatting * Remove auto-fix workflows and commands from v1-dev These files should only exist in km-anthropic fork: - .github/workflows/auto-fix-ci.yml - .github/workflows/auto-fix-ci-inline.yml - slash-commands/fix-ci.md - .claude/commands/fix-ci.md The workflow_run event support remains as it's useful for general automation. * feat: Expose GitHub token as action output for external use This allows workflows to use the Claude App token obtained by the action for posting comments as claude[bot] instead of github-actions[bot]. Changes: - Add github_token output to action.yml - Export token from prepare.ts after authentication - Allows workflows to use the same token Claude uses internally * Debug: Add logging and always output github_token in prepare step * Fix: Add git authentication to agent mode Agent mode now fetches the authenticated user (claude[bot] when using Claude App token) and configures git identity properly, matching the behavior of tag mode. This fixes the issue where commits in agent mode were failing due to missing git identity. * minor bun format * remove unnecessary file * fix: Add branch environment variable support to agent mode for signed commits - Read CLAUDE_BRANCH and BASE_BRANCH env vars in agent mode - Pass correct branch info to MCP file ops server - Enables signed auto-fix workflows to create branches via API * feat: Add auto-fix CI workflow examples - Add auto-fix-ci example with inline git commits - Add auto-fix-ci-signed example with signed commits via MCP - Include corresponding slash commands for both workflows - Examples demonstrate automated CI failure detection and fixing * fix: Fix TypeScript error in agent mode git config - Remove dependency on configureGitAuth which expects ParsedGitHubContext - Implement git configuration directly for automation contexts - Properly handle git authentication for agent mode * fix: Align agent mode git config with existing patterns - Use GITHUB_SERVER_URL from config module consistently - Remove existing headers before setting new ones - Use remote URL with embedded token like git-config.ts does - Match the existing git authentication pattern in the codebase * refactor: Use shared configureGitAuth function in agent mode - Update configureGitAuth to accept GitHubContext instead of ParsedGitHubContext - This allows both tag mode and agent mode to use the same function - Removes code duplication and ensures consistent git configuration * feat: Improve error message for 403 permission errors when committing When the github_file_ops MCP server gets a 403 error, it now shows a cleaner message suggesting to rebase from main/master branch to fix the issue. * docs: Update documentation for v1.0 release (#476) * docs: Update documentation for v1.0 release - Integrate breaking changes naturally without alarming users - Replace deprecated inputs (direct_prompt, custom_instructions, mode) with new unified approach - Update all examples to use prompt and claude_args instead of deprecated inputs - Add migration guides to help users transition from v0.x to v1.0 - Emphasize automatic mode detection as a key feature - Update all workflow examples to @v1 from @beta - Document how claude_args provides direct CLI control - Update FAQ with automatic mode detection explanation - Convert all tool configuration to use claude_args format * fix: Apply prettier formatting to documentation files * fix: Update all Claude model versions to latest and improve documentation accuracy - Update all model references to claude-4-0-sonnet-20250805 (latest Sonnet 4) - Update Bedrock models to anthropic.claude-4-0-sonnet-20250805-v1:0 - Update Vertex models to claude-4-0-sonnet@20250805 - Fix cloud-providers.md to use claude_args instead of deprecated model input - Ensure all examples use @v1 instead of @beta - Keep claude-opus-4-1-20250805 in examples where Opus is demonstrated - Align all documentation with v1.0 patterns consistently * feat: Add dedicated migration guide as requested in PR feedback - Create comprehensive migration-guide.md with step-by-step instructions - Add prominent links to migration guide in README.md - Update usage.md to reference the separate migration guide - Include before/after examples for all common scenarios - Add checklist for systematic migration - Address Ashwin's feedback about having a separate, clearly linked migration guide * feat: Add comprehensive examples for hero use cases - Add dedicated issue deduplication workflow example - Add issue triage example (moved from .github/workflows) - Update all examples to use v1-dev branch consistently - Enable MCP tools in claude-auto-review.yml - Consolidate PR review examples into single comprehensive example Hero use cases now covered: 1. Code reviews (claude-auto-review.yml) 2. Issue triaging (issue-triage.yml) 3. Issue deduplication (issue-deduplication.yml) 4. Auto-fix CI failures (auto-fix-ci/auto-fix-ci.yml) All examples updated to follow v1-dev paradigm with proper prompt and claude_args configuration. * refactor: Remove timeout_minutes parameter from action (#482) This change removes the custom timeout_minutes parameter from the action in favor of using GitHub Actions' native timeout-minutes feature. Changes: - Removed timeout_minutes input from action.yml and base-action/action.yml - Removed all timeout handling logic from base-action/src/run-claude.ts - Updated base-action/src/index.ts to remove timeoutMinutes parameter - Removed timeout-related tests from base-action/test/run-claude.test.ts - Removed timeout_minutes from all example workflow files (19 files) Rationale: - Simplifies the codebase by removing custom timeout logic - Users can use GitHub Actions' native timeout-minutes at the job/step level - Reduces complexity and maintenance burden - Follows GitHub Actions best practices BREAKING CHANGE: The timeout_minutes parameter is no longer supported. Users should use GitHub Actions' native timeout-minutes instead. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-authored-by: Claude <noreply@anthropic.com> * refactor: Remove unused slash commands and agents copying logic Removes experimental file copying features that had no default content: - Removed experimental_slash_commands_dir parameter and related logic - Removed automatic project agents copying from .claude/agents/ - Eliminated flaky error-prone cp operations with stderr suppression - Removed 175 lines of unused code and associated tests These features were infrastructure without default content that used problematic error handling patterns (2>/dev/null || true) which could hide real filesystem errors. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> * docs: Remove references to timeout_minutes parameter The timeout_minutes parameter was removed in commit 986e40a but documentation still referenced it. This updates: - docs/usage.md: Removed timeout_minutes from inputs table - base-action/README.md: Removed from inputs table and example 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> --------- Co-authored-by: km-anthropic <km-anthropic@users.noreply.github.com> Co-authored-by: Claude <noreply@anthropic.com> Co-authored-by: Kashyap Murali <13315300+katchu11@users.noreply.github.com>
2026-01-22 14:24:13 +08:00 · 2025-08-25 12:51:37 -07:00
parent 9c7e1bac94
commit 0630ef383a
68 changed files with 2315 additions and 2387 deletions
--- a/docs/cloud-providers.md
+++ b/docs/cloud-providers.md
@@ -20,23 +20,25 @@ Use provider-specific model names based on your chosen provider:

 ```yaml
 # For direct Anthropic API (default)
- uses: anthropics/claude-code-action@beta
+- uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    # ... other inputs

 # For Amazon Bedrock with OIDC
- uses: anthropics/claude-code-action@beta
+- uses: anthropics/claude-code-action@v1
  with:
-    model: "anthropic.claude-3-7-sonnet-20250219-beta:0" # Cross-region inference
    use_bedrock: "true"
+    claude_args: |
+      --model anthropic.claude-4-0-sonnet-20250805-v1:0
    # ... other inputs

 # For Google Vertex AI with OIDC
- uses: anthropics/claude-code-action@beta
+- uses: anthropics/claude-code-action@v1
  with:
-    model: "claude-3-7-sonnet@20250219"
    use_vertex: "true"
+    claude_args: |
+      --model claude-4-0-sonnet@20250805
    # ... other inputs
 ```

@@ -59,10 +61,11 @@ Both AWS Bedrock and GCP Vertex AI require OIDC authentication.
    app-id: ${{ secrets.APP_ID }}
    private-key: ${{ secrets.APP_PRIVATE_KEY }}

- uses: anthropics/claude-code-action@beta
+- uses: anthropics/claude-code-action@v1
  with:
-    model: "anthropic.claude-3-7-sonnet-20250219-beta:0"
    use_bedrock: "true"
+    claude_args: |
+      --model anthropic.claude-4-0-sonnet-20250805-v1:0
    # ... other inputs

  permissions:
@@ -84,10 +87,11 @@ Both AWS Bedrock and GCP Vertex AI require OIDC authentication.
    app-id: ${{ secrets.APP_ID }}
    private-key: ${{ secrets.APP_PRIVATE_KEY }}

- uses: anthropics/claude-code-action@beta
+- uses: anthropics/claude-code-action@v1
  with:
-    model: "claude-3-7-sonnet@20250219"
    use_vertex: "true"
+    claude_args: |
+      --model claude-4-0-sonnet@20250805
    # ... other inputs

  permissions:
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -160,33 +160,38 @@ jobs:

 ## Custom Environment Variables

-You can pass custom environment variables to Claude Code execution using the `claude_env` input. This is useful for CI/test setups that require specific environment variables:
+You can pass custom environment variables to Claude Code execution using the `settings` input. This is useful for CI/test setups that require specific environment variables:

 ```yaml
- uses: anthropics/claude-code-action@beta
+- uses: anthropics/claude-code-action@v1
  with:
-    claude_env: |
-      NODE_ENV: test
-      CI: true
-      DATABASE_URL: postgres://test:test@localhost:5432/test_db
+    settings: |
+      {
+        "env": {
+          "NODE_ENV": "test",
+          "CI": "true",
+          "DATABASE_URL": "postgres://test:test@localhost:5432/test_db"
+        }
+      }
    # ... other inputs
 ```

-The `claude_env` input accepts YAML format where each line defines a key-value pair. These environment variables will be available to Claude Code during execution, allowing it to run tests, build processes, or other commands that depend on specific environment configurations.
+These environment variables will be available to Claude Code during execution, allowing it to run tests, build processes, or other commands that depend on specific environment configurations.

 ## Limiting Conversation Turns

-You can use the `max_turns` parameter to limit the number of back-and-forth exchanges Claude can have during task execution. This is useful for:
+You can limit the number of back-and-forth exchanges Claude can have during task execution using the `claude_args` input. This is useful for:

 - Controlling costs by preventing runaway conversations
 - Setting time boundaries for automated workflows
 - Ensuring predictable behavior in CI/CD pipelines

 ```yaml
- uses: anthropics/claude-code-action@beta
+- uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
-    max_turns: "5" # Limit to 5 conversation turns
+    claude_args: |
+      --max-turns 5  # Limit to 5 conversation turns
    # ... other inputs
 ```

@@ -200,28 +205,50 @@ By default, Claude only has access to:
 - Comment management (creating/updating comments)
 - Basic GitHub operations

-Claude does **not** have access to execute arbitrary Bash commands by default. If you want Claude to run specific commands (e.g., npm install, npm test), you must explicitly allow them using the `allowed_tools` configuration:
+Claude does **not** have access to execute arbitrary Bash commands by default. If you want Claude to run specific commands (e.g., npm install, npm test), you must explicitly allow them using the `claude_args` configuration:

-**Note**: If your repository has a `.mcp.json` file in the root directory, Claude will automatically detect and use the MCP server tools defined there. However, these tools still need to be explicitly allowed via the `allowed_tools` configuration.
+**Note**: If your repository has a `.mcp.json` file in the root directory, Claude will automatically detect and use the MCP server tools defined there. However, these tools still need to be explicitly allowed.

 ```yaml
- uses: anthropics/claude-code-action@beta
+- uses: anthropics/claude-code-action@v1
  with:
-    allowed_tools: "Bash(npm install),Bash(npm run test),Edit,Replace,NotebookEditCell"
-    disallowed_tools: "TaskOutput,KillTask"
+    claude_args: |
+      --allowedTools "Bash(npm install),Bash(npm run test),Edit,Replace,NotebookEditCell"
+      --disallowedTools "TaskOutput,KillTask"
    # ... other inputs
 ```

-**Note**: The base GitHub tools are always included. Use `allowed_tools` to add additional tools (including specific Bash commands), and `disallowed_tools` to prevent specific tools from being used.
+**Note**: The base GitHub tools are always included. Use `--allowedTools` to add additional tools (including specific Bash commands), and `--disallowedTools` to prevent specific tools from being used.

 ## Custom Model

-Use a specific Claude model:
+Specify a Claude model using `claude_args`:

 ```yaml
- uses: anthropics/claude-code-action@beta
+- uses: anthropics/claude-code-action@v1
  with:
-    # model: "claude-3-5-sonnet-20241022"  # Optional: specify a different model
+    claude_args: |
+      --model claude-4-0-sonnet-20250805
+    # ... other inputs
+```
+
+For provider-specific models:
+
+```yaml
+# AWS Bedrock
+- uses: anthropics/claude-code-action@v1
+  with:
+    use_bedrock: "true"
+    claude_args: |
+      --model anthropic.claude-4-0-sonnet-20250805-v1:0
+    # ... other inputs
+
+# Google Vertex AI
+- uses: anthropics/claude-code-action@v1
+  with:
+    use_vertex: "true"
+    claude_args: |
+      --model claude-4-0-sonnet@20250805
    # ... other inputs
 ```

@@ -232,7 +259,7 @@ You can provide Claude Code settings to customize behavior such as model selecti
 ### Option 1: Settings File

 ```yaml
- uses: anthropics/claude-code-action@beta
+- uses: anthropics/claude-code-action@v1
  with:
    settings: "path/to/settings.json"
    # ... other inputs
@@ -241,7 +268,7 @@ You can provide Claude Code settings to customize behavior such as model selecti
 ### Option 2: Inline Settings

 ```yaml
- uses: anthropics/claude-code-action@beta
+- uses: anthropics/claude-code-action@v1
  with:
    settings: |
      {
@@ -280,6 +307,20 @@ For a complete list of available settings and their descriptions, see the [Claud
 **Notes**:

 - The `enableAllProjectMcpServers` setting is always set to `true` by this action to ensure MCP servers work correctly.
- If both the `model` input parameter and a `model` in settings are provided, the `model` input parameter takes precedence.
- The `allowed_tools` and `disallowed_tools` input parameters take precedence over `permissions` in settings.
- In a future version, we may deprecate individual input parameters in favor of using the settings file for all configuration.
+- The `claude_args` input provides direct access to Claude Code CLI arguments and takes precedence over settings.
+- We recommend using `claude_args` for simple configurations and `settings` for complex configurations with hooks and environment variables.
+
+## Migration from Deprecated Inputs
+
+Many individual input parameters have been consolidated into `claude_args` or `settings`. Here's how to migrate:
+
+| Old Input             | New Approach                                             |
+| --------------------- | -------------------------------------------------------- |
+| `allowed_tools`       | Use `claude_args: "--allowedTools Tool1,Tool2"`          |
+| `disallowed_tools`    | Use `claude_args: "--disallowedTools Tool1,Tool2"`       |
+| `max_turns`           | Use `claude_args: "--max-turns 10"`                      |
+| `model`               | Use `claude_args: "--model claude-4-0-sonnet-20250805"`  |
+| `claude_env`          | Use `settings` with `"env"` object                       |
+| `custom_instructions` | Use `claude_args: "--system-prompt 'Your instructions'"` |
+| `direct_prompt`       | Use `prompt` input instead                               |
+| `override_prompt`     | Use `prompt` with GitHub context variables               |
--- a/docs/custom-automations.md
+++ b/docs/custom-automations.md
@@ -1,6 +1,6 @@
 # Custom Automations

-These examples show how to configure Claude to act automatically based on GitHub events, without requiring manual @mentions.
+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.

 ## Supported GitHub Events

@@ -26,14 +26,15 @@ on:
      - "src/api/**/*.ts"

 steps:
-  - uses: anthropics/claude-code-action@beta
+  - uses: anthropics/claude-code-action@v1
    with:
-      direct_prompt: |
+      prompt: |
        Update the API documentation in README.md to reflect
        the changes made to the API endpoints in this PR.
+      anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
 ```

-When API files are modified, Claude automatically updates your README with the latest endpoint documentation and pushes the changes back to the PR, keeping your docs in sync with your code.
+When API files are modified, the action automatically detects that a `prompt` is provided and runs in agent mode. Claude updates your README with the latest endpoint documentation and pushes the changes back to the PR, keeping your docs in sync with your code.

 ## Author-Specific Code Reviews

@@ -50,28 +51,26 @@ jobs:
      github.event.pull_request.user.login == 'developer1' ||
      github.event.pull_request.user.login == 'external-contributor'
    steps:
-      - uses: anthropics/claude-code-action@beta
+      - uses: anthropics/claude-code-action@v1
        with:
-          direct_prompt: |
+          prompt: |
            Please provide a thorough review of this pull request.
            Pay extra attention to coding standards, security practices,
            and test coverage since this is from an external contributor.
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
 ```

-Perfect for automatically reviewing PRs from new team members, external contributors, or specific developers who need extra guidance.
+Perfect for automatically reviewing PRs from new team members, external contributors, or specific developers who need extra guidance. The action automatically runs in agent mode when a `prompt` is provided.

 ## Custom Prompt Templates

-Use `override_prompt` for complete control over Claude's behavior with variable substitution:
+Use the `prompt` input with GitHub context variables for dynamic automation:

 ```yaml
- uses: anthropics/claude-code-action@beta
+- uses: anthropics/claude-code-action@v1
  with:
-    override_prompt: |
-      Analyze PR #$PR_NUMBER in $REPOSITORY for security vulnerabilities.
-
-      Changed files:
-      $CHANGED_FILES
+    prompt: |
+      Analyze PR #${{ github.event.pull_request.number }} in ${{ github.repository }} for security vulnerabilities.

      Focus on:
      - SQL injection risks
@@ -80,12 +79,35 @@ Use `override_prompt` for complete control over Claude's behavior with variable
      - Exposed secrets or credentials

      Provide severity ratings (Critical/High/Medium/Low) for any issues found.
+    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
 ```

-The `override_prompt` feature supports these variables:
+You can access any GitHub context variable using the standard GitHub Actions syntax:

- `$REPOSITORY`, `$PR_NUMBER`, `$ISSUE_NUMBER`
- `$PR_TITLE`, `$ISSUE_TITLE`, `$PR_BODY`, `$ISSUE_BODY`
- `$PR_COMMENTS`, `$ISSUE_COMMENTS`, `$REVIEW_COMMENTS`
- `$CHANGED_FILES`, `$TRIGGER_COMMENT`, `$TRIGGER_USERNAME`
- `$BRANCH_NAME`, `$BASE_BRANCH`, `$EVENT_TYPE`, `$IS_PR`
+- `${{ github.repository }}` - The repository name
+- `${{ github.event.pull_request.number }}` - PR number
+- `${{ github.event.issue.number }}` - Issue number
+- `${{ github.event.pull_request.title }}` - PR title
+- `${{ github.event.pull_request.body }}` - PR description
+- `${{ github.event.comment.body }}` - Comment text
+- `${{ github.actor }}` - User who triggered the workflow
+- `${{ github.base_ref }}` - Base branch for PRs
+- `${{ github.head_ref }}` - Head branch for PRs
+
+## Advanced Configuration with claude_args
+
+For more control over Claude's behavior, use the `claude_args` input to pass CLI arguments directly:
+
+```yaml
+- uses: anthropics/claude-code-action@v1
+  with:
+    prompt: "Review this PR for performance issues"
+    claude_args: |
+      --max-turns 15
+      --model claude-4-0-sonnet-20250805
+      --allowedTools Edit,Read,Write,Bash
+      --system-prompt "You are a performance optimization expert. Focus on identifying bottlenecks and suggesting improvements."
+    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+```
+
+This provides full access to Claude Code CLI capabilities while maintaining the simplified action interface.
--- a/docs/experimental.md
+++ b/docs/experimental.md
@@ -2,65 +2,66 @@

 **Note:** Experimental features are considered unstable and not supported for production use. They may change or be removed at any time.

-## Execution Modes
+## Automatic Mode Detection

-The action supports three execution modes, each optimized for different use cases:
+The action intelligently detects the appropriate execution mode based on your workflow context, eliminating the need for manual mode configuration.

-### Tag Mode (Default)
+### Interactive Mode (Tag Mode)

-The traditional implementation mode that responds to @claude mentions, issue assignments, or labels.
+Activated when Claude detects @mentions, issue assignments, or labels—without an explicit `prompt`.

- **Triggers**: `@claude` mentions, issue assignment, label application
+- **Triggers**: `@claude` mentions in comments, issue assignment to claude user, label application
 - **Features**: Creates tracking comments with progress checkboxes, full implementation capabilities
- **Use case**: General-purpose code implementation and Q&A
+- **Use case**: Interactive code assistance, Q&A, and implementation requests

 ```yaml
- uses: anthropics/claude-code-action@beta
+- uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
-    # mode: tag is the default
+    # No prompt needed - responds to @claude mentions
 ```

-### Agent Mode
+### Automation Mode (Agent Mode)

-**Note: Agent mode is currently in active development and may undergo breaking changes.**
+Automatically activated when you provide a `prompt` input.

-For automation with workflow_dispatch and scheduled events only.
-
- **Triggers**: Only works with `workflow_dispatch` and `schedule` events - does NOT work with PR/issue events
- **Features**: Perfect for scheduled tasks, works with `override_prompt`
- **Use case**: Maintenance tasks, automated reporting, scheduled checks
+- **Triggers**: Any GitHub event when `prompt` input is provided
+- **Features**: Direct execution without requiring @claude mentions, streamlined for automation
+- **Use case**: Automated PR reviews, scheduled tasks, workflow automation

 ```yaml
- uses: anthropics/claude-code-action@beta
+- uses: anthropics/claude-code-action@v1
  with:
-    mode: agent
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
-    override_prompt: |
+    prompt: |
      Check for outdated dependencies and create an issue if any are found.
+    # Automatically runs in agent mode when prompt is provided
 ```

-### Experimental Review Mode
+### How It Works

-**Warning: This is an experimental feature that may change or be removed at any time.**
+The action uses this logic to determine the mode:

-For automated code reviews on pull requests.
+1. **If `prompt` is provided** → Runs in **agent mode** for automation
+2. **If no `prompt` but @claude is mentioned** → Runs in **tag mode** for interaction
+3. **If neither** → No action is taken

- **Triggers**: Pull request events (`opened`, `synchronize`) or `@claude review` comments
- **Features**: Provides detailed code reviews with inline comments and suggestions
- **Use case**: Automated PR reviews, code quality checks
+This automatic detection ensures your workflows are simpler and more intuitive, without needing to understand or configure different modes.
+
+### Advanced Mode Control
+
+For specialized use cases, you can fine-tune behavior using `claude_args`:

 ```yaml
- uses: anthropics/claude-code-action@beta
+- uses: anthropics/claude-code-action@v1
  with:
-    mode: experimental-review
+    prompt: "Review this PR"
+    claude_args: |
+      --max-turns 20
+      --system-prompt "You are a code review specialist"
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
-    custom_instructions: |
-      Focus on code quality, security, and best practices.
 ```

-See [`examples/claude-modes.yml`](../examples/claude-modes.yml) and [`examples/claude-experimental-review-mode.yml`](../examples/claude-experimental-review-mode.yml) for complete examples of each mode.
-
 ## Network Restrictions

 For enhanced security, you can restrict Claude's network access to specific domains only. This feature is particularly useful for:
@@ -76,7 +77,7 @@ When `experimental_allowed_domains` is set, Claude can only access the domains y
 #### If using Anthropic API or subscription

 ```yaml
- uses: anthropics/claude-code-action@beta
+- uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    # Or: claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
@@ -87,7 +88,7 @@ When `experimental_allowed_domains` is set, Claude can only access the domains y
 #### If using AWS Bedrock

 ```yaml
- uses: anthropics/claude-code-action@beta
+- uses: anthropics/claude-code-action@v1
  with:
    use_bedrock: "true"
    experimental_allowed_domains: |
@@ -98,7 +99,7 @@ When `experimental_allowed_domains` is set, Claude can only access the domains y
 #### If using Google Vertex AI

 ```yaml
- uses: anthropics/claude-code-action@beta
+- uses: anthropics/claude-code-action@v1
  with:
    use_vertex: "true"
    experimental_allowed_domains: |
@@ -111,7 +112,7 @@ When `experimental_allowed_domains` is set, Claude can only access the domains y
 In addition to your provider domains, you may need to include GitHub-related domains. For GitHub.com users, common domains include:

 ```yaml
- uses: anthropics/claude-code-action@beta
+- uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    experimental_allowed_domains: |
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -41,10 +41,11 @@ By default, Claude only uses commit tools for non-destructive changes to the bra
 - Never push to branches other than where it was invoked (either its own branch or the PR branch)
 - Never force push or perform destructive operations

-You can grant additional tools via the `allowed_tools` input if needed:
+You can grant additional tools via the `claude_args` input if needed:

 ```yaml
-allowed_tools: "Bash(git rebase:*)" # Use with caution
+claude_args: |
+  --allowedTools "Bash(git rebase:*)"  # Use with caution
 ```

 ### Why won't Claude create a pull request?
@@ -67,7 +68,7 @@ Yes! Claude can access GitHub Actions workflow runs, job logs, and test results

 2. Configure the action with additional permissions:
   ```yaml
-   - uses: anthropics/claude-code-action@beta
+   - uses: anthropics/claude-code-action@v1
     with:
       additional_permissions: |
         actions: read
@@ -105,30 +106,51 @@ If you need full history, you can configure this in your workflow before calling

 ## Configuration and Tools

-### What's the difference between `direct_prompt` and `custom_instructions`?
+### How does automatic mode detection work?

-These inputs serve different purposes in how Claude responds:
+The action intelligently detects whether to run in interactive mode or automation mode:

- **`direct_prompt`**: Bypasses trigger detection entirely. When provided, Claude executes this exact instruction regardless of comments or mentions. Perfect for automated workflows where you want Claude to perform a specific task on every run (e.g., "Update the API documentation based on changes in this PR").
+- **With `prompt` input**: Runs in automation mode - executes immediately without waiting for @claude mentions
+- **Without `prompt` input**: Runs in interactive mode - waits for @claude mentions in comments

- **`custom_instructions`**: Additional context added to Claude's system prompt while still respecting normal triggers. These instructions modify Claude's behavior but don't replace the triggering comment. Use this to give Claude standing instructions like "You have been granted additional tools for ...".
+This automatic detection eliminates the need to manually configure modes.

 Example:

 ```yaml
-# Using direct_prompt - runs automatically without @claude mention
-direct_prompt: "Review this PR for security vulnerabilities"
+# Automation mode - runs automatically
+prompt: "Review this PR for security vulnerabilities"
+# Interactive mode - waits for @claude mention
+# (no prompt provided)
+```

-# Using custom_instructions - still requires @claude trigger
-custom_instructions: "Focus on performance implications and suggest optimizations"
+### What happened to `direct_prompt` and `custom_instructions`?
+
+**These inputs are deprecated in v1.0:**
+
+- **`direct_prompt`** → Use `prompt` instead
+- **`custom_instructions`** → Use `claude_args` with `--system-prompt`
+
+Migration examples:
+
+```yaml
+# Old (v0.x)
+direct_prompt: "Review this PR"
+custom_instructions: "Focus on security"
+
+# New (v1.0)
+prompt: "Review this PR"
+claude_args: |
+  --system-prompt "Focus on security"
 ```

 ### Why doesn't Claude execute my bash commands?

-The Bash tool is **disabled by default** for security. To enable individual bash commands:
+The Bash tool is **disabled by default** for security. To enable individual bash commands using `claude_args`:

 ```yaml
-allowed_tools: "Bash(npm:*),Bash(git:*)" # Allows only npm and git commands
+claude_args: |
+  --allowedTools "Bash(npm:*),Bash(git:*)"  # Allows only npm and git commands
 ```

 ### Can Claude work across multiple repositories?
@@ -152,7 +174,7 @@ Claude Code Action automatically configures two MCP servers:
 1. **GitHub MCP server**: For GitHub API operations
 2. **File operations server**: For advanced file manipulation

-However, tools from these servers still need to be explicitly allowed via `allowed_tools`.
+However, tools from these servers still need to be explicitly allowed via `claude_args` with `--allowedTools`.

 ## Troubleshooting

@@ -168,7 +190,7 @@ The trigger uses word boundaries, so `@claude` must be a complete word. Variatio

 1. **Always specify permissions explicitly** in your workflow file
 2. **Use GitHub Secrets** for API keys - never hardcode them
-3. **Be specific with `allowed_tools`** - only enable what's necessary
+3. **Be specific with tool permissions** - only enable what's necessary via `claude_args`
 4. **Test in a separate branch** before using on important PRs
 5. **Monitor Claude's token usage** to avoid hitting API limits
 6. **Review Claude's changes** carefully before merging
--- a/docs/migration-guide.md
+++ b/docs/migration-guide.md
@@ -0,0 +1,219 @@
+# Migration Guide: v0.x to v1.0
+
+This guide helps you migrate from Claude Code Action v0.x to v1.0. The new version introduces intelligent mode detection and simplified configuration while maintaining backward compatibility for most use cases.
+
+## Overview of Changes
+
+### 🎯 Key Improvements in v1.0
+
+1. **Automatic Mode Detection** - No more manual `mode` configuration
+2. **Simplified Configuration** - Unified `prompt` and `claude_args` inputs
+3. **Better SDK Alignment** - Closer integration with Claude Code CLI
+
+### ⚠️ Breaking Changes
+
+The following inputs have been deprecated and replaced:
+
+| Deprecated Input      | Replacement                      | Notes                                         |
+| --------------------- | -------------------------------- | --------------------------------------------- |
+| `mode`                | Auto-detected                    | Action automatically chooses based on context |
+| `direct_prompt`       | `prompt`                         | Direct drop-in replacement                    |
+| `override_prompt`     | `prompt`                         | Use GitHub context variables instead          |
+| `custom_instructions` | `claude_args: --system-prompt`   | Move to CLI arguments                         |
+| `max_turns`           | `claude_args: --max-turns`       | Use CLI format                                |
+| `model`               | `claude_args: --model`           | Specify via CLI                               |
+| `allowed_tools`       | `claude_args: --allowedTools`    | Use CLI format                                |
+| `disallowed_tools`    | `claude_args: --disallowedTools` | Use CLI format                                |
+| `claude_env`          | `settings` with env object       | Use settings JSON                             |
+
+## Migration Examples
+
+### Basic Interactive Workflow (@claude mentions)
+
+**Before (v0.x):**
+
+```yaml
+- uses: anthropics/claude-code-action@beta
+  with:
+    mode: "tag"
+    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+    custom_instructions: "Follow our coding standards"
+    max_turns: "10"
+    allowed_tools: "Edit,Read,Write"
+```
+
+**After (v1.0):**
+
+```yaml
+- uses: anthropics/claude-code-action@v1
+  with:
+    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+    claude_args: |
+      --max-turns 10
+      --system-prompt "Follow our coding standards"
+      --allowedTools Edit,Read,Write
+```
+
+### Automation Workflow
+
+**Before (v0.x):**
+
+```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 }}
+    model: "claude-3-5-sonnet-20241022"
+    allowed_tools: "Edit,Read,Write"
+```
+
+**After (v1.0):**
+
+```yaml
+- uses: anthropics/claude-code-action@v1
+  with:
+    prompt: "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
+```
+
+### Custom Template with Variables
+
+**Before (v0.x):**
+
+```yaml
+- uses: anthropics/claude-code-action@beta
+  with:
+    override_prompt: |
+      Analyze PR #$PR_NUMBER in $REPOSITORY
+      Changed files: $CHANGED_FILES
+      Focus on security vulnerabilities
+```
+
+**After (v1.0):**
+
+```yaml
+- uses: anthropics/claude-code-action@v1
+  with:
+    prompt: |
+      Analyze PR #${{ github.event.pull_request.number }} in ${{ github.repository }}
+      Focus on security vulnerabilities in the changed files
+```
+
+### Environment Variables
+
+**Before (v0.x):**
+
+```yaml
+- uses: anthropics/claude-code-action@beta
+  with:
+    claude_env: |
+      NODE_ENV: test
+      CI: true
+```
+
+**After (v1.0):**
+
+```yaml
+- uses: anthropics/claude-code-action@v1
+  with:
+    settings: |
+      {
+        "env": {
+          "NODE_ENV": "test",
+          "CI": "true"
+        }
+      }
+```
+
+## How Mode Detection Works
+
+The action now automatically detects the appropriate mode:
+
+1. **If `prompt` is provided** → Runs in **automation mode**
+
+   - Executes immediately without waiting for @claude mentions
+   - Perfect for scheduled tasks, PR automation, etc.
+
+2. **If no `prompt` but @claude is mentioned** → Runs in **interactive mode**
+
+   - Waits for and responds to @claude mentions
+   - Creates tracking comments with progress
+
+3. **If neither** → No action is taken
+
+## Advanced Configuration with claude_args
+
+The `claude_args` input provides direct access to Claude Code CLI arguments:
+
+```yaml
+claude_args: |
+  --max-turns 15
+  --model claude-4-0-sonnet-20250805
+  --allowedTools Edit,Read,Write,Bash
+  --disallowedTools WebSearch
+  --system-prompt "You are a senior engineer focused on code quality"
+```
+
+### Common claude_args Options
+
+| Option              | Description              | Example                               |
+| ------------------- | ------------------------ | ------------------------------------- |
+| `--max-turns`       | Limit conversation turns | `--max-turns 10`                      |
+| `--model`           | Specify Claude model     | `--model claude-4-0-sonnet-20250805`  |
+| `--allowedTools`    | Enable specific tools    | `--allowedTools Edit,Read,Write`      |
+| `--disallowedTools` | Disable specific tools   | `--disallowedTools WebSearch`         |
+| `--system-prompt`   | Add system instructions  | `--system-prompt "Focus on security"` |
+
+## Provider-Specific Updates
+
+### AWS Bedrock
+
+```yaml
+- uses: anthropics/claude-code-action@v1
+  with:
+    use_bedrock: "true"
+    claude_args: |
+      --model anthropic.claude-4-0-sonnet-20250805-v1:0
+```
+
+### Google Vertex AI
+
+```yaml
+- uses: anthropics/claude-code-action@v1
+  with:
+    use_vertex: "true"
+    claude_args: |
+      --model claude-4-0-sonnet@20250805
+```
+
+## Step-by-Step Migration Checklist
+
+- [ ] Update action version from `@beta` to `@v1`
+- [ ] Remove `mode` input (auto-detected now)
+- [ ] Replace `direct_prompt` with `prompt`
+- [ ] Replace `override_prompt` with `prompt` using GitHub context
+- [ ] Move `custom_instructions` to `claude_args` with `--system-prompt`
+- [ ] Convert `max_turns` to `claude_args` with `--max-turns`
+- [ ] Convert `model` to `claude_args` with `--model`
+- [ ] Convert `allowed_tools` to `claude_args` with `--allowedTools`
+- [ ] Convert `disallowed_tools` to `claude_args` with `--disallowedTools`
+- [ ] Move `claude_env` to `settings` JSON format
+- [ ] Test workflow in a non-production environment
+
+## Getting Help
+
+If you encounter issues during migration:
+
+1. Check the [FAQ](./faq.md) for common questions
+2. Review [example workflows](../examples/) for reference
+3. Open an [issue](https://github.com/anthropics/claude-code-action/issues) for support
+
+## Version Compatibility
+
+- **v0.x workflows** will continue to work but with deprecation warnings
+- **v1.0** is the recommended version for all new workflows
+- Future versions may remove deprecated inputs entirely
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -18,27 +18,26 @@ jobs:
  claude-response:
    runs-on: ubuntu-latest
    steps:
-      - uses: anthropics/claude-code-action@beta
+      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          # Or use OAuth token instead:
          # claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          # Optional: set execution mode (default: tag)
-          # mode: "tag"
+
+          # Optional: provide a prompt for automation workflows
+          # prompt: "Review this PR for security issues"
+
+          # Optional: pass advanced arguments to Claude CLI
+          # claude_args: |
+          #   --max-turns 10
+          #   --model claude-4-0-sonnet-20250805
+
          # Optional: add custom trigger phrase (default: @claude)
          # trigger_phrase: "/claude"
          # Optional: add assignee trigger for issues
          # assignee_trigger: "claude"
          # Optional: add label trigger for issues
          # label_trigger: "claude"
-          # Optional: add custom environment variables (YAML format)
-          # claude_env: |
-          #   NODE_ENV: test
-          #   DEBUG: true
-          #   API_URL: https://api.example.com
-          # Optional: limit the number of conversation turns
-          # max_turns: "5"
          # Optional: grant additional permissions (requires corresponding GitHub token permissions)
          # additional_permissions: |
          #   actions: read
@@ -48,42 +47,127 @@ jobs:

 ## Inputs

-| Input                          | Description                                                                                                                           | Required | Default   |
-| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- | -------- | --------- |
-| `mode`                         | Execution mode: 'tag' (default - triggered by mentions/assignments), 'agent' (for automation), 'experimental-review' (for PR reviews) | No       | `tag`     |
-| `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\*     | -         |
-| `direct_prompt`                | Direct prompt for Claude to execute automatically without needing a trigger (for automated workflows)                                 | No       | -         |
-| `override_prompt`              | Complete replacement of Claude's prompt with custom template (supports variable substitution)                                         | No       | -         |
-| `base_branch`                  | The base branch to use for creating new branches (e.g., 'main', 'develop')                                                            | No       | -         |
-| `max_turns`                    | Maximum number of conversation turns Claude can take (limits back-and-forth exchanges)                                                | No       | -         |
-| `timeout_minutes`              | Timeout in minutes for execution                                                                                                      | No       | `30`      |
-| `use_sticky_comment`           | Use just one comment to deliver PR comments (only applies for pull_request event workflows)                                           | No       | `false`   |
-| `github_token`                 | GitHub token for Claude to operate with. **Only include this if you're connecting a custom GitHub app of your own!**                  | No       | -         |
-| `model`                        | Model to use (provider-specific format required for Bedrock/Vertex)                                                                   | No       | -         |
-| `fallback_model`               | Enable automatic fallback to specified model when primary model is unavailable                                                        | No       | -         |
-| `anthropic_model`              | **DEPRECATED**: Use `model` instead. Kept for backward compatibility.                                                                 | No       | -         |
-| `use_bedrock`                  | Use Amazon Bedrock with OIDC authentication instead of direct Anthropic API                                                           | No       | `false`   |
-| `use_vertex`                   | Use Google Vertex AI with OIDC authentication instead of direct Anthropic API                                                         | No       | `false`   |
-| `allowed_tools`                | Additional tools for Claude to use (the base GitHub tools will always be included)                                                    | No       | ""        |
-| `disallowed_tools`             | Tools that Claude should never use                                                                                                    | No       | ""        |
-| `custom_instructions`          | Additional custom instructions to include in the prompt for Claude                                                                    | No       | ""        |
-| `mcp_config`                   | Additional MCP configuration (JSON string) that merges with the built-in GitHub MCP servers                                           | No       | ""        |
-| `assignee_trigger`             | The assignee username that triggers the action (e.g. @claude). Only used for issue assignment                                         | No       | -         |
-| `label_trigger`                | The label name that triggers the action when applied to an issue (e.g. "claude")                                                      | No       | -         |
-| `trigger_phrase`               | The trigger phrase to look for in comments, issue/PR bodies, and issue titles                                                         | No       | `@claude` |
-| `branch_prefix`                | The prefix to use for Claude branches (defaults to 'claude/', use 'claude-' for dash format)                                          | No       | `claude/` |
-| `claude_env`                   | Custom environment variables to pass to Claude Code execution (YAML format)                                                           | No       | ""        |
-| `settings`                     | Claude Code settings as JSON string or path to settings JSON file                                                                     | No       | ""        |
-| `additional_permissions`       | Additional permissions to enable. Currently supports 'actions: read' for viewing workflow results                                     | No       | ""        |
-| `experimental_allowed_domains` | Restrict network access to these domains only (newline-separated).                                                                    | No       | ""        |
-| `use_commit_signing`           | Enable commit signing using GitHub's commit signature verification. When false, Claude uses standard git commands                     | No       | `false`   |
-| `allowed_bots`                 | Comma-separated list of allowed bot usernames, or '\*' to allow all bots. Empty string (default) allows no bots                       | No       | ""        |
+| Input                          | Description                                                                                                          | Required | Default   |
+| ------------------------------ | -------------------------------------------------------------------------------------------------------------------- | -------- | --------- |
+| `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       | -         |
+| `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`   |
+| `github_token`                 | GitHub token for Claude to operate with. **Only include this if you're connecting a custom GitHub app of your own!** | No       | -         |
+| `use_bedrock`                  | Use Amazon Bedrock with OIDC authentication instead of direct Anthropic API                                          | No       | `false`   |
+| `use_vertex`                   | Use Google Vertex AI with OIDC authentication instead of direct Anthropic API                                        | No       | `false`   |
+| `mcp_config`                   | Additional MCP configuration (JSON string) that merges with the built-in GitHub MCP servers                          | No       | ""        |
+| `assignee_trigger`             | The assignee username that triggers the action (e.g. @claude). Only used for issue assignment                        | No       | -         |
+| `label_trigger`                | The label name that triggers the action when applied to an issue (e.g. "claude")                                     | No       | -         |
+| `trigger_phrase`               | The trigger phrase to look for in comments, issue/PR bodies, and issue titles                                        | No       | `@claude` |
+| `branch_prefix`                | The prefix to use for Claude branches (defaults to 'claude/', use 'claude-' for dash format)                         | No       | `claude/` |
+| `settings`                     | Claude Code settings as JSON string or path to settings JSON file                                                    | No       | ""        |
+| `additional_permissions`       | Additional permissions to enable. Currently supports 'actions: read' for viewing workflow results                    | No       | ""        |
+| `experimental_allowed_domains` | Restrict network access to these domains only (newline-separated).                                                   | No       | ""        |
+| `use_commit_signing`           | Enable commit signing using GitHub's commit signature verification. When false, Claude uses standard git commands    | No       | `false`   |
+| `allowed_bots`                 | Comma-separated list of allowed bot usernames, or '\*' to allow all bots. Empty string (default) allows no bots      | No       | ""        |
+
+### Deprecated Inputs
+
+These inputs are deprecated and will be removed in a future version:
+
+| Input                 | Description                                                                                  | Migration Path                                                 |
+| --------------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| `mode`                | **DEPRECATED**: Mode is now automatically detected based on workflow context                 | Remove this input; the action auto-detects the correct mode    |
+| `direct_prompt`       | **DEPRECATED**: Use `prompt` instead                                                         | Replace with `prompt`                                          |
+| `override_prompt`     | **DEPRECATED**: Use `prompt` with template variables or `claude_args` with `--system-prompt` | Use `prompt` for templates or `claude_args` for system prompts |
+| `custom_instructions` | **DEPRECATED**: Use `claude_args` with `--system-prompt` or include in `prompt`              | Move instructions to `prompt` or use `claude_args`             |
+| `max_turns`           | **DEPRECATED**: Use `claude_args` with `--max-turns` instead                                 | Use `claude_args: "--max-turns 5"`                             |
+| `model`               | **DEPRECATED**: Use `claude_args` with `--model` instead                                     | Use `claude_args: "--model claude-4-0-sonnet-20250805"`        |
+| `fallback_model`      | **DEPRECATED**: Use `claude_args` with fallback configuration                                | Configure fallback in `claude_args` or `settings`              |
+| `allowed_tools`       | **DEPRECATED**: Use `claude_args` with `--allowedTools` instead                              | Use `claude_args: "--allowedTools Edit,Read,Write"`            |
+| `disallowed_tools`    | **DEPRECATED**: Use `claude_args` with `--disallowedTools` instead                           | Use `claude_args: "--disallowedTools WebSearch"`               |
+| `claude_env`          | **DEPRECATED**: Use `settings` with env configuration                                        | Configure environment in `settings` JSON                       |

 \*Required when using direct Anthropic API (default and when not using Bedrock or Vertex)

 > **Note**: This action is currently in beta. Features and APIs may change as we continue to improve the integration.

+## Upgrading from v0.x?
+
+For a comprehensive guide on migrating from v0.x to v1.0, including step-by-step instructions and examples, see our **[Migration Guide](./migration-guide.md)**.
+
+### Quick Migration Examples
+
+#### Interactive Workflows (with @claude mentions)
+
+**Before (v0.x):**
+
+```yaml
+- uses: anthropics/claude-code-action@beta
+  with:
+    mode: "tag"
+    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+    custom_instructions: "Focus on security"
+    max_turns: "10"
+```
+
+**After (v1.0):**
+
+```yaml
+- uses: anthropics/claude-code-action@v1
+  with:
+    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+    claude_args: |
+      --max-turns 10
+      --system-prompt "Focus on security"
+```
+
+#### Automation Workflows
+
+**Before (v0.x):**
+
+```yaml
+- uses: anthropics/claude-code-action@beta
+  with:
+    mode: "agent"
+    direct_prompt: "Update the API documentation"
+    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+    model: "claude-4-0-sonnet-20250805"
+    allowed_tools: "Edit,Read,Write"
+```
+
+**After (v1.0):**
+
+```yaml
+- uses: anthropics/claude-code-action@v1
+  with:
+    prompt: "Update the API documentation"
+    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+    claude_args: |
+      --model claude-4-0-sonnet-20250805
+      --allowedTools Edit,Read,Write
+```
+
+#### Custom Templates
+
+**Before (v0.x):**
+
+```yaml
+- uses: anthropics/claude-code-action@beta
+  with:
+    override_prompt: |
+      Analyze PR #$PR_NUMBER for security issues.
+      Focus on: $CHANGED_FILES
+```
+
+**After (v1.0):**
+
+```yaml
+- uses: anthropics/claude-code-action@v1
+  with:
+    prompt: |
+      Analyze PR #${{ github.event.pull_request.number }} for security issues.
+      Focus on the changed files in this PR.
+```
+
 ## Ways to Tag @claude

 These examples show how to interact with Claude using comments in PRs and issues. By default, Claude will be triggered anytime you mention `@claude`, but you can customize the exact trigger phrase using the `trigger_phrase` input in the workflow.