Headless Mode

Headless mode is Claude Code running without a human at the keyboard. Instead of opening an interactive session and chatting back and forth, you pass a task in via flags and get structured output back, ready to be consumed by another program. The primary entry point is the --print flag (and the equivalent method in the SDK), which runs the task to completion and prints the result rather than dropping you into a conversation.

This unlocks automation. Because headless mode is just a command that takes input and produces output, you can drop Claude Code into the same places you put any other script: a cron job that triages incoming issues every morning, a GitHub Action that drafts a changelog on every release, a build step that updates documentation when the API changes, or a data pipeline that summarizes yesterday's records. The one-off session you would normally run by hand becomes a repeatable step that runs on a schedule or a trigger.

Running unattended raises the stakes on safety and determinism, which is why headless mode pairs so well with hooks and a tight CLAUDE.md. Hooks enforce guardrails when no one is watching, and clear standing context keeps the agent on-task without a human to course-correct. The mark of a builder who has moved past tinkering is that their best Claude Code workflows no longer require them to be present - they have been captured in headless commands that run themselves.