What is claude -p?

claude -p runs Claude Code in print mode: it takes a prompt, runs the agentic loop, prints the result, and exits. There is no interactive session, no terminal UI, and no waiting for you to type the next message. That single change is what turns Claude Code from a tool you sit in front of into a command you can put inside a script, a pipe, or a CI job.

The -p is short for --print, and the official headless documentation describes it as the way to run Claude Code programmatically. The mental model worth holding onto is that claude -p is a Unix filter: text goes in, an answer comes out, and the exit code tells you whether it worked. Everything else in this post follows from that.

The short answer

Use plain claude when you want a conversation: an interactive session where you review each step and decide what happens next. Use claude -p when you want an outcome, such as a summary, a review, a fix, or a piece of structured data, produced by a command that runs to completion on its own and then gets out of the way.

Interactive mode is for exploration. Print mode is for automation. Most teams start in the first and reach for the second the moment they want Claude Code to run without a human watching the terminal.

How print mode works

In interactive mode, Claude Code opens a full terminal experience, prompts you before it uses a tool, and waits for /exit. In print mode, none of that applies. The session runs headless, prints its final answer to standard output, and returns control to your shell.

Three consequences matter in practice:

• It reads standard input. Anything you pipe in becomes context for the prompt. This is what makes claude -p composable with the rest of the command line.
• It does not stop to ask. Because there is no interactive prompt, tool permissions have to be settled up front rather than approved one at a time (covered below).
• It exits when done. The command finishes, which means you can check its exit status, capture its output, and chain it into the next step.

The simplest possible invocation is a direct question:

bash claude -p "What does auth.py do?"

The more interesting shape is as a filter, where the input arrives on stdin:

bash cat build-error.txt | claude -p "explain the root cause of this failure" git diff main | claude -p "report any typos introduced in this diff"

Here the file or the diff is the material, and the prompt is the instruction for what to do with it.

Controlling the output

By default, print mode emits plain text, which is ideal for reading or piping into another command. When a script needs to consume the result rather than a person reading it, switch the output format.

• --output-format text: the default; just the answer.
• --output-format json: a structured object that also carries the session_id, the result, and total_cost_usd, so you can log spend or resume later.
• --output-format stream-json: newline-delimited JSON emitted as the run progresses, for when you want to react to events in real time.

Extracting the cost of a run, for example, is a one-liner:

bash claude -p "Summarize the open issues" --output-format json | jq '.total_cost_usd'

For output that has to satisfy a contract, --json-schema validates the result against a JSON Schema before it is returned, which is the difference between hoping the model returned the right shape and knowing it did.

Settling permissions up front

The one thing print mode cannot do is stop and ask you whether it is allowed to run a command or edit a file. Since there is no one at the keyboard, you decide the tool policy before the run starts, not during it.

• --allowedTools "Bash,Read,Edit": the allowlist of tools that run without a prompt.
• --disallowedTools: the matching blocklist.
• --permission-mode: the broader posture. It ranges from plan (explore without touching source), through acceptEdits (auto-approve file writes), to bypassPermissions (skip checks entirely).

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

bypassPermissions deserves a word of caution. Because print mode already skips the workspace trust prompt, a headless run with permissions bypassed will do whatever the prompt leads it to do, with no further confirmation. That is exactly what you want inside a controlled, sandboxed job and exactly what you do not want pointed at a directory you have not vetted. Grant the narrowest set of tools the task needs. This is the same discipline that makes a good MCP server safe: authority is granted deliberately at the boundary, not assumed.

Sessions and continuation

A headless run is stateless by default, but it does not have to be. Capture the session ID from JSON output and you can resume the same context in a later invocation:

bash session_id=$(claude -p "Review this codebase for security issues" --output-format json | jq -r '.session_id') claude -p "Now focus specifically on the database queries" --resume "$session_id"

--continue resumes the most recent session in the current directory without needing the ID, and --fork-session branches from an existing session so the original history is left untouched. Other useful controls include --model to pick the model, --max-turns to cap how many agentic iterations a run may take, and --append-system-prompt to add task-specific instructions on top of the default behavior.

Interactive mode versus print mode

As with any such table, these are the tendencies, not hard walls. The two modes optimize for different jobs. One serves a person thinking through a problem; the other serves a machine running a task.

Where teams use it

Print mode is the seam where Claude Code connects to the rest of a system. Common uses include:

• Continuous integration: review a pull request, triage a failing build, or flag risky changes as a step in the pipeline.

bash gh pr diff "$1" | claude -p --append-system-prompt "You are a security engineer. Review this diff for vulnerabilities." --output-format json

• Git hooks: run a quick check on staged changes before a commit lands.
• Log and error analysis: pipe a stack trace or a log file in and get a root-cause summary out.
• Batch work: loop over many files or records, invoking claude -p per item and collecting the results.
• Scripted glue: any place a shell script could use a step of judgment rather than a fixed rule.

This is also where claude -p sits next to the Claude Agent SDK. The SDK and the CLI share the same agentic loop and the same tools; the CLI is the lightweight way to reach that loop from a shell script or a CI job, while the SDK is the route when you are building a production application that needs callbacks, custom tools, and tighter control. For a one-off automation, the CLI is usually all you need. Either way, the underlying idea is the same as any agentic workflow: fixed structure around the edges, model judgment in the middle.

How XY Space thinks about it

claude -p is a small flag with a large implication: it makes an AI coding agent into a component you can compose. That is the same lens XY Space brings to the systems it builds. The value is rarely a model answering a question in a chat window; it is a model wired into a workflow, invoked by other software, with its inputs, permissions, and outputs all defined at the boundary.

The discipline that matters in headless mode is the discipline that matters everywhere: grant the narrowest permissions, capture structured output you can log and check, and keep a person in the loop at the steps where a mistake is expensive. Print mode makes automation easy, which is exactly why the guardrails around it have to be deliberate. Get that right and claude -p becomes a durable building block. If you want help wiring an agent into your own systems, talk to us.

Sources

• Run Claude Code programmatically (headless)
• Claude Code CLI reference
• Claude Agent SDK overview