Headless Mode & the Agent SDK
Claude Code isn't only interactive. You can run it headless (non-interactive, scriptable) and you can build your own agents on the same underlying harness with the Agent SDK.
- How to run a single prompt non-interactively and capture its output
- Why an unattended run needs a deliberate permission posture, not the interactive default
- When you have outgrown a one-shot call and should reach for the Agent SDK instead
- The three modes side by side, so you pick deliberately rather than by habit
Headless mode
Run a single prompt non-interactively and capture the output — perfect for scripts, pre-commit hooks, and CI:
Review the staged diff from a script
claude -p "Review the staged diff and list any bugs as a Markdown checklist"
Pipe input in, get a result out. Combine with permissions set to a safe, non-interactive posture so it never hangs waiting for approval — and lock it down so an automated run can't touch secrets (see Hardening Autonomous Runs).
- One prompt, one answer, exit. Everything a headless run needs is a flag, because there is no UI to ask you anything.
- An interactive session asks you; a CI job has nobody to ask. Set explicit allow rules for the tools the task genuinely needs, and make sure an unanswerable prompt ends the run instead of stalling it.
- Cap the turns and the spend so a loop that goes wrong costs minutes and cents rather than hours and dollars.
- A script that parses prose is a script that breaks. Request JSON — or a schema — so the result is machine-readable by construction.
- Secrets, network, and write access are the three things an unattended run should have least of. See Hardening Autonomous Runs.
The exact flags for each step — and the traps in them — are in The claude CLI: Flags That Change Outcomes. A classic use of all of it together: a CI job that has Claude review every pull request — see the PR-review walkthrough.
The Agent SDK
The Claude Agent SDK (Python and TypeScript) lets you build production agents on the same loop that powers Claude Code — tool use, file/shell access, permissions, context management — but wired into your application.
Reach for it when you've outgrown a single API call or a hand-rolled loop and want a batteries-included agent runtime. For the spectrum of options — single call → workflow → custom agent → managed — see Building Agents on the API.
Headless/SDK vs interactive
| Mode | For |
|---|---|
| Interactive Claude Code | Day-to-day dev with a human in the loop |
Headless (claude -p) | Scripts, pre-commit, CI one-offs |
| Agent SDK | Production agents embedded in your software |
Check yourself
Check yourself
0/2- Headless is the same harness with the human removed — so everything the human would have decided becomes configuration.
- Narrow the permissions, bound the turns and spend, and ask for structured output. All four are flags, not conventions.
- Graduate to the Agent SDK when you want the loop inside your own application rather than a CLI call from a script.
- An unattended run is a security posture as much as a feature: harden what it can reach before you schedule it.
Next
- Agent SDK Permissions: the Six-Step Order — the first thing to get right once the loop is inside your own app
- The claude CLI: Flags That Change Outcomes — the five-flag contract for an unattended run
- GitHub Action that Reviews Every PR (walkthrough)
- Building Agents on the API
- Hardening Autonomous Runs