Headless Mode Explained: Running Claude Code Without a Terminal
Every Claude Code session you run at a terminal is interactive: you type a request, Claude Code responds, maybe asks to run a tool, and you approve or deny it in real time.
That model breaks down the moment nobody is sitting at the terminal to approve anything - inside a script, a scheduled job, or a CI pipeline.
Headless mode is how Claude Code handles that case: it runs as a single non-interactive command that takes a prompt, does the work, and exits, without ever opening the interactive REPL.
Understanding headless mode is the prerequisite for everything else in this section that touches CI - an automated review bot, a GitHub Actions job, anything that runs Claude Code without a person watching.
Summary
- Core Idea: headless mode invokes Claude Code as a single scripted command that runs a prompt to completion and exits, instead of opening an interactive terminal session.
- Why It Matters: scripts, cron jobs, and CI pipelines have no human present to type follow-up messages or approve tool calls one at a time - headless mode is the only invocation shape that works in that context.
- Key Concepts: interactive session, headless invocation, print mode, output format, non-interactive permissions.
- When to Use: any automation where Claude Code needs to run without a person watching - CI jobs, scheduled tasks, batch scripts, or a review bot triggered by a GitHub event.
- Limitations / Trade-offs: without a human to approve actions in real time, headless invocations need their permitted tools and scope decided in advance, which means less room for mid-task judgment calls than an interactive session allows.
- Related Topics: the
ghCLI, GitHub Actions triggers, automated code review, CI secrets management.
Foundations
An interactive Claude Code session is a conversation. You send a message, Claude Code replies, maybe requests to run a tool, you approve it, and the back-and-forth continues until you're satisfied.
Headless mode replaces that conversation with a single instruction. You give Claude Code one prompt describing the whole task, and it runs everything needed to complete that task without pausing to ask you anything further.
The output is text (or a structured format like JSON), returned once the run finishes, rather than a live stream of messages you respond to as they arrive.
A useful comparison: an interactive session is like sitting down with a colleague and talking through a task together. Headless mode is like handing that colleague a written brief and getting a finished report back, with no conversation in between.
# Interactive: opens a live session, waits for your input.
claude
# Headless: runs one prompt to completion, then exits.
claude -p "Summarize the open pull requests in this repository." --output-format textBoth invocations use the same underlying Claude Code capability - the same models, the same tool access model. What differs is entirely the shape of the invocation: one waits for you, one does not.
Mechanics & Interactions
Because headless mode has no human present to approve tool calls as they come up, its permission model has to be decided before the run starts, not negotiated during it.
In an interactive session, a tool call you haven't pre-approved typically pauses and asks. In a headless run, there's nobody there to answer that prompt - so a headless invocation needs its allowed tools, working directory, and any relevant scopes configured up front, otherwise the run either fails or gets stuck waiting on an approval that will never come.
This is why headless invocations are usually paired with an explicit permission or tool-allowlist configuration passed alongside the prompt, rather than relying on the interactive approval flow.
The output format matters more in headless mode too. An interactive session's output is meant for a person reading a terminal in real time. A headless run's output often feeds into something else - a script that parses it, a CI step that posts it as a PR comment, a log a pipeline archives. That's why headless invocations commonly specify an explicit output format (plain text, JSON, or a structured transcript) rather than relying on whatever the default human-facing formatting looks like.
# Headless mode invoked with structured output, so a script can parse the result
# programmatically instead of scraping human-readable text.
claude -p "Review the diff on PR #482 and summarize any risks." \
--output-format json > review-result.jsonThe commentary that matters here: --output-format json exists specifically because headless mode's consumer is usually another program, not a person - the same request phrased for an interactive session would just print readable prose.
Advanced Considerations & Applications
Headless mode is the mechanism that makes every CI-based use of Claude Code possible, because a GitHub Actions job is, by definition, running with nobody watching a terminal.
A GitHub Actions job that runs Claude Code headlessly needs three things wired together: a trigger (such as on: pull_request), a secret holding an API key so the job can authenticate, and the headless invocation itself with its flags and permitted tools configured. Each of those is covered in more depth elsewhere in this section.
Headless mode also changes the failure mode developers need to think about. An interactive session that hits an ambiguous situation can ask you a clarifying question. A headless run has no one to ask - so a well-designed headless prompt needs to specify enough constraints and context up front that ambiguity is unlikely, or needs to fail gracefully (exit with a clear error) rather than guess.
| Aspect | Interactive Session | Headless Mode |
|---|---|---|
| Who approves tool calls | You, in real time | Pre-configured allowlist, decided before the run |
| Output shape | Human-readable, streamed | Text or structured (JSON), returned at completion |
| Handles ambiguity by | Asking a follow-up question | Failing clearly, or acting on the best available instruction |
| Typical trigger | You, typing a request | A script, a schedule, or a CI event |
This is also where headless mode's security posture matters most. Since a headless run's tool access is decided up front rather than approved interactively, the permissions and secrets granted to a CI job effectively become the boundary of what that headless invocation can do - there's no human safety net catching an overly broad grant in the moment, the way there would be in an interactive session.
Common Misconceptions
- "Headless mode is a separate, lesser version of Claude Code." It's the same underlying capability - the same models, the same tools - invoked differently; nothing about the model itself changes.
- "Headless mode can't ask for clarification, so it must be less capable." It's not less capable, it's differently constrained - the trade-off is intentional, because the whole point is running without a person available to answer follow-up questions.
- "Any Claude Code command works fine headlessly without changes." A command that relies on interactive tool-call approval will stall or fail in headless mode unless its permissions are configured for non-interactive use up front.
- "Headless mode only matters for CI." CI is the most common use, but scheduled scripts, batch jobs, and one-off automation scripts on a local machine use headless mode too, for the same reason: nobody watching in real time.
FAQs
What's the simplest way to run Claude Code headlessly?
Pass a prompt with the print flag and let it run to completion, e.g. claude -p "your instruction here" - the session runs once and exits, without opening the interactive REPL.
Does headless mode use a different Claude model than interactive sessions?
No - model choice is independent of interactive versus headless invocation; either mode can use any model in the current lineup.
Why do headless runs need permissions configured up front?
Because there's no person present to approve a tool call in the moment the way there is in an interactive session - without a pre-configured allowlist, a headless run either fails or stalls waiting on an approval nobody will give.
What output formats does headless mode support?
Commonly plain text and structured JSON; JSON is preferred when the output feeds into another program, such as a CI step that parses the result to post a comment.
Can headless mode ask me a clarifying question mid-run?
No - that's the core trade-off of the mode; a headless prompt needs to carry enough context and constraints up front, since there's no one available to answer a follow-up.
Is headless mode only usable inside GitHub Actions?
No - it works from any script or shell context, including a local terminal; GitHub Actions is simply the most common CI use case for it in this section.
What happens if a headless run tries to use a tool it wasn't granted?
It's blocked or the run fails, since there's no interactive approval flow to fall back on - this is why the permitted tool set has to be decided before the run starts.
Is there a security risk specific to headless mode?
Yes - because permissions are granted up front rather than approved case-by-case, whatever a headless invocation is allowed to do becomes the actual boundary of what it can do, with no human catching an overly broad grant mid-run.
Can I test a headless invocation locally before putting it in CI?
Yes - running the same claude -p "..." command from a local terminal is a reliable way to validate a prompt and its output format before wiring it into a GitHub Actions job.
Does headless mode still have access to the same tools as an interactive session?
It has access to whatever tools are explicitly permitted for that invocation - potentially the same set as an interactive session, or a narrower, deliberately scoped-down set, depending on how it's configured.
Related
- How Claude Code Fits Into Your GitHub Pull Request Workflow - where headless mode fits among the PR touchpoints.
- Running Claude Code as an Automated Code Review Bot in CI - the primary real-world application of headless mode in this section.
- Setting Up a GitHub Actions Job That Runs Claude Code - wiring headless invocations into a working CI job.
- GitHub Integration Basics - a hands-on first headless invocation.
Stack versions: Written against the Claude model lineup current as of ~June 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (the default), and Claude Haiku 4.5. Model names, pricing, and product features move quickly - verify current specifics at platform.claude.com/docs before relying on them.