Claude Code headless mode is a way to run Claude Code without the usual interactive chat window. Instead of typing back and forth in a terminal, you give Claude one request up front, it runs the whole thing on its own, and it prints the result. The core form is claude -p "your request here" -- the -p stands for print. Because it takes an instruction and hands back an answer with nothing else to click, you can drop it inside a script, a scheduled job, or an automated pipeline. In plain terms: it is Claude Code you can wire into other software.

What headless mode actually is

Normally Claude Code opens a live session. You type, it responds, you type again, and the conversation stays open. Headless mode strips that away. You pass your request once with the -p (or --print) flag, Claude works through it start to finish, and it returns the final result. No back-and-forth, no window to sit in front of. That single change is what makes it possible for a machine, rather than a person, to run Claude Code.

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

Ask a one-off question and get the answer back. Click to copy.

Why business operators should care

You do not need to write code to see the point. Anything you would normally open Claude Code and ask by hand, headless mode lets you schedule or trigger automatically. A file that needs summarizing every morning, a report that needs checking before it goes out, a folder of documents that needs sorting -- headless mode is the piece that lets those happen on their own, on a timer or when something else kicks them off.

The three things that make it scriptable

headless capabilities
1One-shot requestsPass your instruction with -p and Claude runs it without a chat window.Core
2Choice of outputReturn plain text, structured JSON, or a live stream of JSON events.Formats
3Reads piped inputFeed in a file or the output of another command, and pipe the result onward.Pipes

The three features that let headless mode slot into scripts and pipelines.

Output formats you can ask for

By default, headless mode returns plain text -- the same words you would read on screen. When another program needs to use the answer, you can ask for it in a more structured shape with the --output-format flag:

claude
# plain words, the default › claude -p "Summarize this project" # structured JSON: result plus session info › claude -p "Summarize this project" --output-format json # streaming JSON, event by event as it runs › claude -p "Explain recursion" --output-format stream-json

The three output formats: text, json, and stream-json.

Plain text is for reading. json wraps the answer with details like a session ID so other software can track and reuse it. stream-json sends results piece by piece as they are produced, which is handy when you want to show progress in real time.

A real example: a scheduled file check

Say every night a build log lands in a folder, and someone on your team usually skims it for the cause of any failure. With headless mode you feed that file straight into Claude and save the explanation, all in one line a scheduler can run for you:

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

Reading left to right: the file goes in, Claude explains the root cause, and the explanation is written to a new file. Because headless mode reads piped input, you can hand it the contents of a file or the output of any other command, and pipe its answer onward to the next step. Put that line on a nightly schedule and the check runs itself, no one sitting at a keyboard.

Note: Headless mode is the foundation the rest of the automation options build on. When Claude Code runs inside a CI pipeline or a GitHub Action, it is running headless underneath. Learn this one idea and the rest follow.

Where headless mode fits with the rest

Headless mode is the plain command-line entry point. For fuller programmatic control -- inside a Python or TypeScript program, with structured results and tool-approval controls -- the same engine is available as the Agent SDK. And when you want Claude to run automatically on every pull request, GitHub Actions wraps headless mode for you. Same core, different levels of packaging.

Step 1Headless commandRun claude -p from a terminal or a shell script. The starting point.
Step 2Scheduled or CIPut that command on a schedule or in a build pipeline so it runs on its own.
Step 3SDK for depthReach for the Agent SDK when you need to embed Claude inside your own program.