How does anthropics/claude-code-action@v1 choose between @claude interactive mode and automation mode, and what changes between the two?
answer
- one input decides the mode
- no prompt means wait for a mention
- trigger_phrase, default @claude
- comment versus workflow run log
- tools granted through claude_args
basics
~20 sThe action's prompt input decides: without it, Claude waits for the trigger phrase, @claude by default, and replies in a comment; with it, Claude runs on the workflow's event and reports in the workflow run log by default.
solid answer
~50 sIn `anthropics/claude-code-action@v1` there is no mode switch: the `prompt` input decides. **Interactive mode** (no `prompt`) waits for `@claude`, or whatever `trigger_phrase` sets, in an issue or PR comment, a PR review, or the body or title of a newly opened issue, and posts progress and results as a comment it keeps updating. **Automation mode** (`prompt` set, as plain text or a `/skill-name`) runs on any event the workflow listens to, including a `schedule`, and by default reports in the workflow run log; it posts to the PR only when the prompt says so and Claude has a tool that can post. A plain-text prompt has no shell or GitHub API access until you grant it, with `--allowedTools` in `claude_args` or a `permissions.allow` rule in the `settings` input. `claude_args` takes any Claude Code CLI flag, such as `--max-turns` or `--model`.
code
yaml · 7 lines- uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
prompt: "Summarize yesterday's commits and open issues"
claude_args: |
--max-turns 10
--allowedTools "mcp__github__list_commits,mcp__github__list_issues"go deeper
Remember that the prompt input decides the mode: no prompt means Claude waits for @claude, a prompt means it runs on the event.
Explain where each mode reports, how claude_args forwards CLI flags such as --max-turns and --allowedTools, and why a plain-text prompt needs tools granted.
Diagnose silent failures: an inline-comment server never started, findings left in the run log, a skill missing because checkout ran after the action.
Decide which jobs deserve automation mode on every pull request against on-demand mentions, given per-run token cost and the write access each run holds.
## One input decides The Claude Code GitHub Action, `anthropics/claude-code-action@v1`, runs Claude Code as a step in a GitHub Actions workflow. It has two ways of working, and you never name them: the action **detects the mode** from its configuration. The deciding input is `prompt`. | | Interactive mode | Automation mode | | - | - | - | | Selected by | no `prompt` input | a `prompt` input (plain text or a skill) | | Starts when | the trigger phrase appears | the workflow's event fires | | Default output | a comment on the issue or PR | the workflow run log | | Typical use | `@claude fix the failing test` | review every PR, a nightly report | Both modes run the same **checks on who triggered the run** before Claude starts; automation mode does not skip them. ## Interactive mode With no `prompt`, Claude waits for the **trigger phrase**, `@claude` unless the `trigger_phrase` input changes it. It looks for the phrase in an issue or pull request comment, a pull request review, or the body or title of a newly opened issue, and it must appear as a complete word: `/claude` or `@claude-bot` does not count. The workflow's own `if: contains(github.event.comment.body, '@claude')` only saves runner minutes on unrelated comments; the action checks the phrase again itself. Claude answers in a comment on the same issue or PR and updates it as it works, which is why the example workflow grants `pull-requests: write` and `issues: write`. ## Automation mode With `prompt` set, Claude runs as soon as the event fires, on a pull request opening, a push or a `schedule`, with nobody mentioning it. Three things trip people up: - **Output goes to the run log by default.** Claude posts to the issue or PR only when the prompt directs it to and it has a tool that can post. - **A plain-text prompt starts with no shell or GitHub API access.** Grant the tools it needs with `--allowedTools` in `claude_args` or with a `permissions.allow` rule in the `settings` input. A **skill** prompt (`/skill-name` from `.claude/skills/`, or `/plugin-name:skill-name` from a plugin installed with `plugin_marketplaces` and `plugins`) can use the tools its `allowed-tools` frontmatter grants. - **A repository skill needs a checkout.** Run `actions/checkout` before the action so the skill files exist on the runner. ## claude_args and settings `claude_args` passes **any Claude Code CLI argument** to the run; the `settings` input takes Claude Code settings as a JSON string or a file path. Common arguments: 1. `--max-turns` to cap how many turns a run may take, a per-run cost control that pairs with a workflow-level timeout; 2. `--model` to pick a model instead of Claude Code's default; 3. `--allowedTools` (alias `--allowed-tools`), a comma-separated list of tools that run without a prompt; 4. `--mcp-config` to load MCP servers from a file; 5. `--debug` for verbose output. A trap in the shipped review workflow: the `code-review` plugin's skill already names the inline-comment tool in its `allowed-tools`, yet the workflow keeps `claude_args: '--allowedTools "mcp__github_inline_comment__create_inline_comment"'`, because the action **starts the MCP server that posts inline comments only when `--allowedTools` in `claude_args` names it**. Drop that line and the review posts nothing inline. The skill's `--comment` argument is the other half: without it, findings stay in the run log. ## Bounding each run Every run costs GitHub Actions minutes on the runner plus model usage: API tokens with `anthropic_api_key`, or the subscription's usage with `claude_code_oauth_token`. The documented levers are: - `--max-turns` in `claude_args`, so a confused run stops instead of iterating; - a workflow-level timeout for runaway jobs, and GitHub's concurrency controls to limit parallel runs; - specific `@claude` requests and issue templates, so Claude needs fewer turns; - a concise `CLAUDE.md`, because Claude reads it on every run. ## Upgrading from @beta The mode detection replaced explicit configuration in the beta. To move a workflow from `anthropics/claude-code-action@beta`: 1. change `@beta` to `@v1` in the `uses` line; 2. remove the `mode` input; 3. rename `direct_prompt` to `prompt`; 4. move CLI options such as `max_turns` and `model` into `claude_args`; `custom_instructions` has no same-name flag and becomes `--append-system-prompt`. When you read an unfamiliar v1 workflow, then, look for `prompt` first: its presence alone tells you whether Claude waits for a mention or acts on every matching event.
- A review workflow runs the code-review skill with --comment, but no inline comments ever appear on the pull request. What is missing?Most likely the `claude_args` line `--allowedTools "mcp__github_inline_comment__create_inline_comment"`. The action starts the MCP server that posts inline comments only when `--allowedTools` in `claude_args` names it, even though the skill's own `allowed-tools` frontmatter lists the same tool. Without the server, Claude has no tool to post with.
- A scheduled automation run reports it cannot run git commands or read issues. Why, and what do you change?A plain-text prompt in automation mode starts with no shell or GitHub API access. Grant exactly what the job needs: `--allowedTools` in `claude_args`, such as two GitHub MCP list tools, or a `permissions.allow` rule in the `settings` input. Alternatively invoke a skill, whose `allowed-tools` frontmatter grants its tools.
- What changes when you migrate a workflow from anthropics/claude-code-action@beta to @v1?Switch `@beta` to `@v1`, delete the `mode` input because v1 detects the mode, rename `direct_prompt` to `prompt`, and move CLI options such as `max_turns` and `model` into `claude_args`. `custom_instructions` has no same-name flag and becomes `--append-system-prompt`.
- In v1 you set a mode input to pick interactive or automation
- Automation mode always posts its result as a PR comment
- A plain-text automation prompt can run any shell command by default
- Automation mode skips the checks on who triggered the run
- claude_args accepts only --model and --max-turns