Skip to content
AgentAtlas

Claude Code headless mode: claude -p, --output-format json, --bare and CI flags

How do I run Claude Code non-interactively with claude -p in scripts and CI?

Add -p (or --print) to any claude command to run it once without the interactive interface, for example claude -p "What does the auth module do?". Use --output-format json or stream-json for machine-readable output, --allowedTools or --permission-mode to avoid prompts, and --bare in CI so the run skips local hooks, plugins, MCP servers, auto memory and CLAUDE.md.

Compare: headless mode for scripts and CI in every AI coding agent →

Basic usage

The -p flag runs Claude Code in non-interactive mode. It reads stdin, so you can pipe data in and redirect the answer out. Claude Code exits with code 0 on success and a non-zero code when the run fails.

Ask a question

claude -p "What does the auth module do?"

Pipe a log in and write the answer to a file

cat build-error.txt | claude -p 'concisely explain the root cause of this build error' > output.txt

Piped stdin is capped at 10MB. For bigger inputs, write the content to a file and reference the path in your prompt.

Start faster and reproducibly with --bare

--bare skips auto-discovery of hooks, skills, custom commands, subagents, installed plugins, MCP servers, auto memory and CLAUDE.md. The docs recommend it for scripted and SDK calls and say it will become the default for -p in a future release.

Bare mode never reads OAuth credentials or the system keychain. Set ANTHROPIC_API_KEY first, or supply an apiKeyHelper in the --settings JSON.

Bare mode run

claude --bare -p "Summarize README.md" --allowedTools "Read"
  • --append-system-prompt or --append-system-prompt-file: add to the system prompt
  • --settings <file-or-json>: load settings
  • --mcp-config <file-or-json>: load MCP servers
  • --agents <file-or-json>: load custom agents
  • --plugin-dir <path>: load a plugin

Get structured output

  • text (default): plain text
  • json: result, session ID and metadata, including total_cost_usd
  • stream-json: newline-delimited JSON events

JSON output, extract the text with jq

claude -p "Summarize this project" --output-format json | jq -r '.result'

Force a JSON Schema (result lands in structured_output)

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'

Stream tokens as they arrive

claude -p "Explain recursion" --output-format stream-json --verbose --include-partial-messages

Approve tools without prompts

--allowedTools uses permission rule syntax. A trailing space and * means prefix match, so Bash(git diff *) allows any command starting with git diff.

Run tests and fix failures

claude -p "Run the test suite and fix any failures" \
  --allowedTools "Bash,Read,Edit"

Commit with scoped git permissions

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 *)"

Or set a baseline with --permission-mode: auto (a classifier reviews most actions), dontAsk (deny anything that would prompt, good for locked-down CI) or acceptEdits (write files without prompting). Add --permission-prompts none for unattended jobs (v2.1.259 or later).

Unattended auto mode run

claude -p "Update the dependency pins and run the tests" --permission-mode auto --permission-prompts none

Continue a conversation

Continue the most recent conversation

claude -p "Review this codebase for performance issues"
claude -p "Now focus on the database queries" --continue

Resume a specific session by ID

session_id=$(claude -p "Start a review" --output-format json | jq -r '.session_id')
claude -p "Continue that review" --resume "$session_id"

Use it in a build script

package.json typo linter

{
  "scripts": {
    "lint:claude": "git diff main | claude -p \"you are a typo linter. for each typo in this diff, report filename:line on one line and the issue on the next. return nothing else.\""
  }
}

Run it with npm run lint:claude. For full programmatic control in Python or TypeScript, use the Agent SDK packages.

Sources

More Claude Code guides

Reviewed Oct 18, 2026. Settings change often; the linked vendor docs are the source of truth.

Built an MCP server? Get it listed everywhere →

Shipping an Android app? Google Play needs 12 testers for 14 days first. Get them with Tester Exchange →