Run Claude Code Without Watching: The -p Flag for CI, Scripts, and GitHub Actions

TL;DR: claude -p "your task" --allowedTools Bash,Read,Edit runs Claude Code non-interactively — add it to any CI pipeline, shell script, or scheduled job in minutes.

-p (short for --print) is Claude Code's scripting mode: it processes one prompt, runs the full agent loop (reads files, edits code, runs tests), then exits with a zero or non-zero status code. No interactive shell, no permission prompts, no human needed.

The minimal CI step

# GitHub Actions — official action handles auth plumbing for you
- uses: anthropics/claude-code-action@v1
  with:
    prompt: "Review this PR for security issues and comment on the diff"
    allowed_tools: "Read,Bash"
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

Or bare shell in any CI runner:

claude -p "Run the test suite and fix any failures" \
  --allowedTools "Bash,Read,Edit" \
  --max-turns 15 \
  --output-format json | jq .result

Four flags that matter

Flag	What it does
--allowedTools	Comma-list of tools Claude can use without prompting
--max-turns	Hard stop after N agent turns — safety cap for unattended runs
--output-format json	Return JSON with result, cost_usd, turns — machine-parseable
--bare	Strip local config; ensures identical behavior on every machine

Rate-limit guardrail

CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION=50 caps WebSearch calls per -p invocation. The default is 200 — useful to lower it when Claude Code runs autonomously so a runaway search loop doesn't burn your quota.

Background agents are awaited

Background /fork subagents spawned during a -p run complete before the process exits (capped at 10 minutes by default, tunable with CLAUDE_CODE_MAX_BACKGROUND_WAIT_MINUTES). Their output is included in the JSON result.

Start with a narrow --allowedTools list and widen as you see what the agent needs. It's much easier to add a tool than to clean up a CI run that modified unexpected files.

Sources: Run Claude Code programmatically (official docs) · CLI reference · anthropics/claude-code-action