Claude Code headless and in CI. The -p flag, JSON output and Claude in GitHub Actions

How to run Claude Code without a chat, from a script or a pipeline. The -p flag, output formats, allowed tools, --bare mode and the official GitHub Actions integration.

Part of the guideClaude Code, the complete guide. From installation to your own skills and plugins

In this article
  1. What headless mode in Claude Code is
  2. Output formats
  3. Permissions when nobody clicks approve
  4. Claude Code in GitHub Actions
  5. When it makes sense for a small business

In short

The -p flag runs Claude Code without a chat window, so you can put it in a script, a scheduled job or a pipeline. Output comes as text, JSON or a JSON stream, and the --allowedTools flag lists the tools Claude may use without asking. For GitHub Actions there is the official anthropics/claude-code-action, and the easiest way to install it is the /install-github-app command.

The nightly build broke, and in the morning someone has to read a long log to find one cause. The same log can go through Claude Code with one line in a script, and in the morning the explanation is waiting in a file. That is Claude Code in headless mode.

This post is mostly for developers and people who look after servers or CI. It is part of our Claude Code guide. The flags come from the Anthropic docs on running Claude Code programmatically and on GitHub Actions, as of 10 November 2026.

What headless mode in Claude Code is

The -p flag, long form --print, runs Claude Code without an interactive session. Claude gets the prompt, works, prints the result and exits. The exit code is 0 on success and non zero on failure, so your script can branch on it.

bash
claude -p "What does the auth module in this project do?"
cat build-error.txt | claude -p "explain the root cause of this build error briefly" > explanation.txt

-p also reads standard input, so it behaves like any other tool in a pipe. You can continue a conversation with --continue, or with --resume and a session ID.

Output formats

You choose the format with --output-format.

FormatWhat you get
textJust the answer text, the default
jsonThe answer in a result field, plus session ID and metadata
stream-jsonEvents as separate JSON lines, as they happen

When the output needs a fixed shape, add --json-schema with a JSON Schema. The data then lands in the structured_output field. If Claude declines or stops early, that field is missing, so your script has to check for it first.

bash
claude -p "Extract the main function names from auth.py" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}' \
  | jq '.structured_output'

Permissions when nobody clicks approve

In -p mode nobody is there to answer a permission prompt. Since version 2.1.302 such a run starts in Manual mode, so a call that needs approval is denied. You allow tools with --allowedTools, using the same syntax as permission rules.

bash
claude -p "Look at my staged changes and create an appropriate commit" \
  --allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)"

The space before the asterisk matters. Bash(git diff *) matches commands that start with git diff, while without the space it would also match git diff-index. Instead of listing tools you can set a mode with --permission-mode. acceptEdits lets Claude change files, dontAsk denies anything that would need a prompt, and auto hands the review to a classifier. Rules are covered in our post on Claude Code permissions.

For CI the docs recommend --bare. Claude Code then skips hooks, skills, plugins, MCP servers, auto memory and CLAUDE.md, so the result does not depend on what happens to be on that machine. With the Anthropic API you then need a key in ANTHROPIC_API_KEY, because subscription login is not used in this mode.

There is one more reason to care. Without --bare, a -p run executes the hooks in .claude/settings.json and connects the servers in .mcp.json, even in a folder you never trusted. With someone else's repository, always use --bare or read its .claude folder first. Two more flags limit spend. --max-turns caps the number of agent turns, and --max-budget-usd stops the run once estimated API spend reaches the amount you set.

Claude Code in GitHub Actions

The official action is anthropics/claude-code-action. The easiest setup is the /install-github-app command, run in Claude Code inside the repository folder. It works only with repositories on github.com, needs the GitHub CLI installed and logged in, and needs admin access to the repository.

The command installs the Claude GitHub App, saves a secret and prepares a pull request with the workflow file. The secret is either ANTHROPIC_API_KEY with an API key or CLAUDE_CODE_OAUTH_TOKEN from a subscription. You create the token with claude setup-token, and the docs say it works on Pro, Max, Ultra, Team and Enterprise plans.

After merging, write @claude in an issue or pull request comment. The workflow looks roughly like this.

yaml
name: Claude Code
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
jobs:
  claude:
    if: contains(github.event.comment.body, '@claude')
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: write
      id-token: write
      actions: read
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

With a prompt input in the workflow, the action runs without a mention, for example on a cron schedule. CLI flags such as --max-turns or --allowedTools go into the claude_args input. Only users with write access to the repository can trigger Claude, and bots are rejected unless you list them.

Without --bare, claude -p also loads the project hooks and the MCP servers from .mcp.json, even in a folder nobody has trusted. That is why we start CI jobs with --bare.

When it makes sense for a small business

A business with one website and one contractor usually does not need any of this. Headless mode pays off where code lives in a repository and someone reviews changes regularly. Good first jobs are explaining nightly build failures, reviewing pull requests and a weekly summary of commits, all with read only tools.

Start with one claude -p command with --bare and read only tools, and add write permissions only once the output proves useful. If you want to know which processes in your business could be automated like this, ask for our free AI audit.

Documentation for this topic

What would you like to change in your business?

Leave your number. We will talk about your process and see whether we can help. The first call is free.

When is the best time to call?
Controller: Oleksandr Bondarenko (BondSoft)Privacy PolicyTerms of Service
Legal details

The data controller is Oleksandr Bondarenko, trading as Oleksandr Bondarenko Software Solutions (BondSoft), ul. Jana Heweliusza 11, 80-890 Gdańsk, Poland, NIP 5833576264, e-mail: office@bondsoft.pl.

We process your data solely to contact you about your enquiry and to present an offer — on the basis of your consent (Art. 6(1)(a) GDPR and Art. 398 of the Polish Electronic Communications Law) and our legitimate interest in handling the enquiry (Art. 6(1)(f) GDPR).

Providing the data is voluntary but necessary for us to reply. You may withdraw your consent at any time by writing to office@bondsoft.pl — this does not affect the lawfulness of processing before the withdrawal.

You have the right to access your data, rectify it, erase it, restrict its processing, transfer it, and lodge a complaint with the President of the Polish Personal Data Protection Office.

Full information: Privacy Policy.

Send us an email

The service this text is about

Automation and AI / OCR

Automation of document re-typing, OCR and checking rules, and your data stays with you.