Most people only use Claude Code as an interactive chat in the terminal. But add one flag and it becomes a normal command-line tool: you give it a prompt, it does the work, prints the result and exits. That’s Claude Code headless mode, and it’s how you wire Claude into shell scripts, git hooks, scheduled jobs and CI pipelines. This guide covers the flags that matter and the permission settings that keep an unattended run safe.
The basics: claude -p
Add -p (or --print) to run Claude Code non-interactively:
claude -p "What does the auth module do?"
It prints the answer and exits with status 0 on success and non-zero on failure, so your scripts can branch on it like any other command. Headless runs also read standard input, which makes them easy to drop into a pipe:
cat build-error.txt | claude -p 'concisely explain the root cause of this build error' > output.txt
Piped input is capped at 10MB. For anything bigger, write it to a file and mention the path in your prompt instead.
Getting structured output
Plain text is fine for a human, but scripts want something they can parse. --output-format takes three values:
text: the default, just the answerjson: one JSON object with the answer inresult, plus the session ID, usage and an estimated cost intotal_cost_usdstream-json: newline-delimited JSON events as they happen, for live progress
claude -p "Summarize this project" --output-format json | jq -r '.result'
If you need the answer in a fixed shape, add --json-schema with a JSON Schema. The result then appears in a structured_output field:
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'
If Claude declines or the run fails, structured_output is simply missing, so check it exists before you use it.
Permissions: the part to get right
Nobody is around to answer permission prompts in a headless run. In current versions, a claude -p run starts in Manual mode when nothing else sets a mode, and any call that would need approval is denied. That’s a safe default, but it means you have to grant what the job needs. There are two ways.
List the tools to auto-approve with --allowedTools. It uses the same rule syntax as your settings file, so you can be precise:
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 * matters. Bash(git diff *) allows any command starting with git diff, while Bash(git diff*) would also match git diff-index.
Or set a baseline for the whole run with --permission-mode. acceptEdits lets Claude write files without asking, dontAsk denies everything that would otherwise prompt (good for locked-down CI), and auto has a classifier review each action. For a scheduled job, add --permission-prompts none so Claude is told nobody can approve anything and doesn’t keep retrying.
If you haven’t set up rules before, Claude Code permission modes explains how modes and allow rules fit together, and Claude Code hooks shows how to hard-block dangerous commands whatever the model decides.
Bare mode for repeatable CI runs
By default, claude -p loads everything an interactive session would: your CLAUDE.md, hooks, skills, plugins, MCP servers and auto memory, from both the project and ~/.claude. That’s handy on your own machine, but in CI it means a run can behave differently depending on what’s lying around. It also means a repository’s own .claude/settings.json hooks and .mcp.json servers run, with no trust prompt.
--bare skips all of that auto-discovery, starts faster and gives you the same result on every machine:
claude --bare -p "Summarize README.md" --allowedTools "Read"
Bare mode doesn’t use your subscription login, so set ANTHROPIC_API_KEY in the environment first. Anything you do want loaded, you pass explicitly: --append-system-prompt for instructions, --settings, --mcp-config, --agents or --plugin-dir. Hooks don’t run in bare mode at all, so don’t use it for a job that depends on them. Anthropic’s docs say bare mode is the recommended mode for scripts and will become the default for -p in a future release.
A reusable review script
--append-system-prompt adds instructions on top of Claude Code’s normal behaviour. Combined with a pipe, it makes a tidy one-file reviewer. Save this as review.sh:
gh pr diff "$1" | claude -p \
--append-system-prompt "You are a security engineer. Review for vulnerabilities." \
--output-format json
Run bash review.sh 123 and it reviews pull request 123, printing JSON with the review in result. Because the diff is piped in, Claude doesn’t need Bash permission to fetch it. For a reviewer with its own tools and instructions, Claude Code subagents goes a step further.
Multi-step jobs: continue and resume
Each claude -p call is a fresh conversation unless you say otherwise. --continue picks up the most recent one; --resume takes a specific session ID, which you can grab from the JSON output:
session_id=$(claude -p "Start a review" --output-format json | jq -r '.session_id')
claude -p "Continue that review" --resume "$session_id"
Running it in GitHub Actions
For GitHub, you don’t have to script this yourself. The official anthropics/claude-code-action@v1 runs Claude Code inside a workflow. Without a prompt input it waits for someone to mention @claude in an issue or pull request; with a prompt it runs automatically on whatever event triggers the workflow, including a cron schedule. Pass CLI flags through the claude_args input:
- uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
prompt: "Generate a summary of yesterday's commits and open issues"
claude_args: |
--max-turns 5
--allowedTools "mcp__github__list_commits,mcp__github__list_issues"
The quickest setup is to run /install-github-app inside Claude Code in your repository. It installs the GitHub App, stores the secret and opens a pull request with the workflow file. Store your key as a repository secret, never in the workflow itself, and use --max-turns plus a workflow timeout so a confused run can’t burn through your budget.
Quick reference
-p: run once and exit--output-format json/stream-json: machine-readable output--json-schema: force a fixed output shape--allowedTools/--permission-mode: grant exactly what the job needs--bare: skip local config for repeatable CI runs--continue/--resume: chain several calls into one conversation

Leave a Reply
You must be logged in to post a comment.