Headless mode is the way to run Claude Code without its interactive terminal UI. Instead of opening a chat session, you pass a prompt directly to the CLI and Claude Code runs the task, prints its output, and exits. This makes it suitable for scripts, CI/CD pipelines, pre-commit checks, and any automation where there is no human at the keyboard.
You enter headless mode with the print flag (claude -p "your prompt"), which tells Claude Code to run once and emit a result rather than start a back-and-forth session. You can pipe data into it (for example feeding it a diff or log via stdin) and capture what it prints. The --output-format flag controls the result format — plain text by default, or json / stream-json for machine-readable output a calling program can parse. Headless mode does not persist between runs, so you trigger it fresh each time. For exact flags and formats, see the official Claude Code docs, since these options evolve.
Headless runs use the same underlying engine as interactive sessions, so they can read your CLAUDE.md, honor your settings.json, and call MCP servers and tools. Because no human is present to approve actions, permissions matter a lot here: you decide up front which tools and edits Claude Code may perform (for example with an allowed-tools list or a non-interactive permission mode) so an automated run does not block waiting for confirmation. Headless mode is also the foundation that the Claude Agent SDK builds on for running Claude Code programmatically.
Why it matters
Headless mode is what turns Claude Code from an interactive assistant into a building block for automation: you can wire it into CI jobs, Git hooks, batch scripts, and larger agent pipelines that run code review, triage, or refactors without anyone watching, which is the foundation for using Claude Code at scale.
Deep dive: What Is Claude Code? A Beginner's Guide
Related terms
See Headless Mode in action across releases — browse the Claude Code changelog.
Get release alerts