Headless mode

Everything so far has been a conversation: you type, Claude answers, you type again. Headless mode drops the conversation. You give Claude one instruction, it does the job, it prints the answer, it’s done.

Run claude -p "your instruction here" and Claude does the task and prints the result straight to the terminal — no chat, no back-and-forth. The -p is for print.

claude -p "summarize what this project does in three bullet points"

It thinks, prints three bullets, and you’re back at your prompt. One shot.

That doesn’t sound like much. The power shows up when you stop thinking of Claude as a place you visit and start thinking of it as a command you combine with other commands.

Claude in a pipe

Back in Level 1 the terminal was about chaining small commands. The | symbol (a “pipe”) takes the output of one command and feeds it into the next. Headless Claude plugs right into that chain:

git diff | claude -p "write a clear commit message for these changes"

Read it as a sentence: take the diff, hand it to Claude, ask for a commit message. Claude reads what the pipe fed it and prints a message. A few more that earn their keep:

cat error.log | claude -p "what is the root cause of this crash?"

claude -p "list every TODO comment in this folder and who should own it"

Claude is now just another tool in the pipeline, sitting between programs that have no idea it’s an AI.

Why this is the unlock

In headless mode Claude becomes composable. Anything your terminal can do, you can now wrap a bit of intelligence around.

And because it’s a plain command, it can go anywhere a command goes — inside a shell script, a Makefile, a scheduled job, an automated pipeline. That’s the bridge to the last three lessons of this level. A chat window can’t live inside a script. A command can.

Made for scripts

When you’re piping Claude into other programs, you often want clean, predictable output instead of friendly prose. Two flags help:

• --output-format json — return a structured result a script can read reliably, instead of free text.
• --allowedTools — pre-approve exactly which tools Claude may use, so an unattended run never stops to ask permission (Level 6 still applies — you’re deciding the blast radius up front instead of in the moment).

That last point is the mental shift. In a normal session, Claude pauses and asks before risky moves. Headless, there’s nobody there to answer — so you grant a careful, narrow set of permissions ahead of time and let it run.

What’s next

Headless mode is Claude as one command. The Agent SDK is the next step up: building a whole program around that same engine — your own custom agent, with the harness in your hands.