[{"data":1,"prerenderedAt":53},["ShallowReactive",2],{"blog-claude-code-headless-mode":3,"blog-related-claude-code-headless-mode":36},{"slug":4,"title":5,"description":6,"category":7,"categoryId":8,"keyword":9,"date":10,"minutes":11,"body":12,"html":13,"headings":14},"claude-code-headless-mode","Claude Code in headless mode: scripts, cron and CI","Run Claude Code without the interface using claude -p: pipe input, get JSON, pre-approve tools safely, resume sessions, and wire it into cron or CI.","Agents & automation","agents-automation","claude code headless mode","2026-11-17",5,"Headless mode is `claude -p \"your prompt\"`: Claude Code runs one task without the interactive interface, prints the result and exits. That makes it a normal command-line tool you can pipe, put in a script, run from cron or call in CI. Anthropic now documents it as the CLI face of the Agent SDK, but the flag you type is still `-p` (short for `--print`).\n\n## How do you run Claude Code non-interactively?\n\n```sh\nclaude -p \"What does the auth module do?\"\n```\n\nClaude Code prints the answer and exits with code 0 on success and non-zero when the run fails, so a script can branch on it. Failures inside the run, such as missing authentication, are printed as the result on stdout.\n\nInput can come from a pipe, which is the most useful trick:\n\n```sh\ncat build-error.txt | claude -p 'concisely explain the root cause of this build error' > output.txt\ngit diff main | claude -p \"list typos in this diff, one per line as file:line\"\n```\n\nPiped input is capped at 10 MB. For anything larger, write it to a file and refer to the path in the prompt. A bonus of piping a diff: Claude does not need Bash permission to read it.\n\n## Which output format should you use?\n\n`--output-format` takes three values:\n\n| Value | You get |\n| --- | --- |\n| `text` (default) | Plain text |\n| `json` | One JSON object with the result, session ID, usage and cost |\n| `stream-json` | Newline-delimited JSON events as they happen |\n\n```sh\nclaude -p \"Summarize this project\" --output-format json | jq -r '.result'\n```\n\nFor machine-readable answers, add `--json-schema` with a JSON Schema. The validated output lands in the `structured_output` field:\n\n```sh\nclaude -p \"Extract the main function names from auth.py\" \\\n  --output-format json \\\n  --json-schema '{\"type\":\"object\",\"properties\":{\"functions\":{\"type\":\"array\",\"items\":{\"type\":\"string\"}}},\"required\":[\"functions\"]}' \\\n  | jq '.structured_output'\n```\n\nIf a run ends without valid structured output (Claude declined, say), that field is simply absent, so check for it before using it. For live tokens, use `--output-format stream-json --verbose --include-partial-messages`. The JSON result also reports `total_cost_usd`, a client-side estimate that can differ from your bill; [what your usage would cost at API prices](\u002Fblog\u002Fclaude-code-token-costs) explains how to read such figures.\n\n## How do you let it use tools without a human?\n\nNobody can click \"allow\" in a script, so decide up front. There are two levers.\n\n**Allow specific tools** with `--allowedTools`, using permission-rule syntax:\n\n```sh\nclaude -p \"Look at my staged changes and create an appropriate commit\" \\\n  --allowedTools \"Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)\"\n```\n\nThe space before `*` matters: `Bash(git diff *)` matches any command starting with `git diff`, while `Bash(git diff*)` would also match `git diff-index`. Prefer narrow rules like these over a bare `Bash`.\n\n**Set a baseline** with `--permission-mode`: `acceptEdits` lets file edits through, `dontAsk` denies anything that would prompt (good for locked-down CI), and `auto` has a classifier review actions. The [permission modes explained](\u002Fblog\u002Fclaude-code-permission-modes) article covers the differences. Avoid `--dangerously-skip-permissions` outside a sandbox with no network.\n\nFor jobs where nobody is around, `--permission-prompts none` makes anything that would prompt get denied automatically, and Claude is told not to retry it. Add `--max-budget-usd` to cap what a run may spend, and for tighter control a [hook](\u002Fblog\u002Fclaude-code-hooks) can refuse specific commands.\n\n## How do you continue a conversation?\n\n```sh\nclaude -p \"Review this codebase for performance issues\"\nclaude -p \"Now focus on the database queries\" --continue\n\n# or keep the ID to resume exactly that session\nsid=$(claude -p \"Start a review\" --output-format json | jq -r '.session_id')\nclaude -p \"Continue that review\" --resume \"$sid\"\n```\n\nSessions are saved like any other, so you can open them later in a normal terminal with `claude --resume`. If you do not want the run saved, `--no-session-persistence` turns it off.\n\n## What changes in CI and cron?\n\nThree things to decide.\n\n**What the run loads.** Without `--bare`, `claude -p` discovers hooks, skills, plugins, MCP servers, auto memory and `CLAUDE.md` the way an interactive session does, including the project's `.claude\u002Fsettings.json` and `.mcp.json`, with no trust dialog and no per-server approval. That is convenient on your laptop and surprising on a build machine. `--bare` skips all of it for a consistent run; you then pass what you need with `--append-system-prompt`, `--settings`, `--mcp-config`, `--agents` or `--plugin-dir`. Bare mode never reads your login: it needs `ANTHROPIC_API_KEY` or an `apiKeyHelper`. Mind that hooks passed through `--settings` still do not run in bare mode.\n\n**How it authenticates.** An unattended machine cannot do a browser login. `claude setup-token` creates a long-lived token for a Claude subscription; check the Claude Code docs for where the CI job reads it. Remember that subscription use counts toward your plan's limits: see [Claude Code usage limits](\u002Fblog\u002Fclaude-code-usage-limits).\n\n**How it ends.** If you stop a run with SIGTERM, Claude Code exits with code 143 and leaves the turn unfinished. Send SIGINT first if you want the turn to end cleanly. After the main turn, a run can also wait up to ten minutes for background work it started, such as background subagents.\n\nA minimal cron entry that writes a daily summary:\n\n```sh\n# crontab -e\n0 8 * * 1-5 cd ~\u002Fcode\u002Fapp && git log --since=yesterday --oneline | claude -p \"summarize these commits for a standup, 5 bullets max\" --allowedTools \"Read\" >> ~\u002Fstandup.md\n```\n\nFor repositories on GitHub or GitLab, Anthropic publishes ready-made integrations (GitHub Actions and GitLab CI\u002FCD) built on the same `-p` interface, so you rarely have to write the workflow file from scratch. For recurring work that should live outside your machine, see [scheduled Claude Code routines](\u002Fblog\u002Fscheduled-claude-code-routines).\n\n## What can't you do in headless mode?\n\nTerminal-only commands such as `\u002Flogin` are unavailable. Your own skills and slash commands work if you put `\u002Fskill-name` in the prompt. A few built-ins accept an argument, for example `\u002Fmodel sonnet`. Nobody is there to answer a question, so tasks that need your judgment in the middle belong in an interactive session, not in `-p`.\n\n## In Relais\n\nRelais is a desktop app, not a CI tool, so it does not replace a script on a build server. Where it overlaps is the repeating part: its \"Repeat\" feature resends a prompt at set times, in the same session or a fresh one each time, and sessions it runs are normal Claude Code sessions in `~\u002F.claude\u002Fprojects`, so `claude --resume` opens them. More on the [features page](\u002Ffeatures).","\u003Cp>Headless mode is \u003Ccode>claude -p &quot;your prompt&quot;\u003C\u002Fcode>: Claude Code runs one task without the interactive interface, prints the result and exits. That makes it a normal command-line tool you can pipe, put in a script, run from cron or call in CI. Anthropic now documents it as the CLI face of the Agent SDK, but the flag you type is still \u003Ccode>-p\u003C\u002Fcode> (short for \u003Ccode>--print\u003C\u002Fcode>).\u003C\u002Fp>\n\u003Ch2 id=\"how-do-you-run-claude-code-non-interactively\">\u003Ca class=\"anchor\" href=\"#how-do-you-run-claude-code-non-interactively\" aria-label=\"Link to this section\">#\u003C\u002Fa>How do you run Claude Code non-interactively?\u003C\u002Fh2>\n\u003Cpre class=\"code\" data-lang=\"sh\">\u003Ccode>claude -p &quot;What does the auth module do?&quot;\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>Claude Code prints the answer and exits with code 0 on success and non-zero when the run fails, so a script can branch on it. Failures inside the run, such as missing authentication, are printed as the result on stdout.\u003C\u002Fp>\n\u003Cp>Input can come from a pipe, which is the most useful trick:\u003C\u002Fp>\n\u003Cpre class=\"code\" data-lang=\"sh\">\u003Ccode>cat build-error.txt | claude -p 'concisely explain the root cause of this build error' &gt; output.txt\ngit diff main | claude -p &quot;list typos in this diff, one per line as file:line&quot;\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>Piped input is capped at 10 MB. For anything larger, write it to a file and refer to the path in the prompt. A bonus of piping a diff: Claude does not need Bash permission to read it.\u003C\u002Fp>\n\u003Ch2 id=\"which-output-format-should-you-use\">\u003Ca class=\"anchor\" href=\"#which-output-format-should-you-use\" aria-label=\"Link to this section\">#\u003C\u002Fa>Which output format should you use?\u003C\u002Fh2>\n\u003Cp>\u003Ccode>--output-format\u003C\u002Fcode> takes three values:\u003C\u002Fp>\n\u003Cdiv class=\"table-wrap\">\u003Ctable>\u003Cthead>\u003Ctr>\u003Cth>Value\u003C\u002Fth>\u003Cth>You get\u003C\u002Fth>\u003C\u002Ftr>\u003C\u002Fthead>\u003Ctbody>\u003Ctr>\u003Ctd>\u003Ccode>text\u003C\u002Fcode> (default)\u003C\u002Ftd>\u003Ctd>Plain text\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd>\u003Ccode>json\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>One JSON object with the result, session ID, usage and cost\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd>\u003Ccode>stream-json\u003C\u002Fcode>\u003C\u002Ftd>\u003Ctd>Newline-delimited JSON events as they happen\u003C\u002Ftd>\u003C\u002Ftr>\u003C\u002Ftbody>\u003C\u002Ftable>\u003C\u002Fdiv>\n\u003Cpre class=\"code\" data-lang=\"sh\">\u003Ccode>claude -p &quot;Summarize this project&quot; --output-format json | jq -r '.result'\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>For machine-readable answers, add \u003Ccode>--json-schema\u003C\u002Fcode> with a JSON Schema. The validated output lands in the \u003Ccode>structured_output\u003C\u002Fcode> field:\u003C\u002Fp>\n\u003Cpre class=\"code\" data-lang=\"sh\">\u003Ccode>claude -p &quot;Extract the main function names from auth.py&quot; \\\n  --output-format json \\\n  --json-schema '{&quot;type&quot;:&quot;object&quot;,&quot;properties&quot;:{&quot;functions&quot;:{&quot;type&quot;:&quot;array&quot;,&quot;items&quot;:{&quot;type&quot;:&quot;string&quot;}}},&quot;required&quot;:[&quot;functions&quot;]}' \\\n  | jq '.structured_output'\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>If a run ends without valid structured output (Claude declined, say), that field is simply absent, so check for it before using it. For live tokens, use \u003Ccode>--output-format stream-json --verbose --include-partial-messages\u003C\u002Fcode>. The JSON result also reports \u003Ccode>total_cost_usd\u003C\u002Fcode>, a client-side estimate that can differ from your bill; \u003Ca href=\"\u002Fblog\u002Fclaude-code-token-costs\">what your usage would cost at API prices\u003C\u002Fa> explains how to read such figures.\u003C\u002Fp>\n\u003Ch2 id=\"how-do-you-let-it-use-tools-without-a-human\">\u003Ca class=\"anchor\" href=\"#how-do-you-let-it-use-tools-without-a-human\" aria-label=\"Link to this section\">#\u003C\u002Fa>How do you let it use tools without a human?\u003C\u002Fh2>\n\u003Cp>Nobody can click &quot;allow&quot; in a script, so decide up front. There are two levers.\u003C\u002Fp>\n\u003Cp>\u003Cstrong>Allow specific tools\u003C\u002Fstrong> with \u003Ccode>--allowedTools\u003C\u002Fcode>, using permission-rule syntax:\u003C\u002Fp>\n\u003Cpre class=\"code\" data-lang=\"sh\">\u003Ccode>claude -p &quot;Look at my staged changes and create an appropriate commit&quot; \\\n  --allowedTools &quot;Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)&quot;\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>The space before \u003Ccode>*\u003C\u002Fcode> matters: \u003Ccode>Bash(git diff *)\u003C\u002Fcode> matches any command starting with \u003Ccode>git diff\u003C\u002Fcode>, while \u003Ccode>Bash(git diff*)\u003C\u002Fcode> would also match \u003Ccode>git diff-index\u003C\u002Fcode>. Prefer narrow rules like these over a bare \u003Ccode>Bash\u003C\u002Fcode>.\u003C\u002Fp>\n\u003Cp>\u003Cstrong>Set a baseline\u003C\u002Fstrong> with \u003Ccode>--permission-mode\u003C\u002Fcode>: \u003Ccode>acceptEdits\u003C\u002Fcode> lets file edits through, \u003Ccode>dontAsk\u003C\u002Fcode> denies anything that would prompt (good for locked-down CI), and \u003Ccode>auto\u003C\u002Fcode> has a classifier review actions. The \u003Ca href=\"\u002Fblog\u002Fclaude-code-permission-modes\">permission modes explained\u003C\u002Fa> article covers the differences. Avoid \u003Ccode>--dangerously-skip-permissions\u003C\u002Fcode> outside a sandbox with no network.\u003C\u002Fp>\n\u003Cp>For jobs where nobody is around, \u003Ccode>--permission-prompts none\u003C\u002Fcode> makes anything that would prompt get denied automatically, and Claude is told not to retry it. Add \u003Ccode>--max-budget-usd\u003C\u002Fcode> to cap what a run may spend, and for tighter control a \u003Ca href=\"\u002Fblog\u002Fclaude-code-hooks\">hook\u003C\u002Fa> can refuse specific commands.\u003C\u002Fp>\n\u003Ch2 id=\"how-do-you-continue-a-conversation\">\u003Ca class=\"anchor\" href=\"#how-do-you-continue-a-conversation\" aria-label=\"Link to this section\">#\u003C\u002Fa>How do you continue a conversation?\u003C\u002Fh2>\n\u003Cpre class=\"code\" data-lang=\"sh\">\u003Ccode>claude -p &quot;Review this codebase for performance issues&quot;\nclaude -p &quot;Now focus on the database queries&quot; --continue\n\n# or keep the ID to resume exactly that session\nsid=$(claude -p &quot;Start a review&quot; --output-format json | jq -r '.session_id')\nclaude -p &quot;Continue that review&quot; --resume &quot;$sid&quot;\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>Sessions are saved like any other, so you can open them later in a normal terminal with \u003Ccode>claude --resume\u003C\u002Fcode>. If you do not want the run saved, \u003Ccode>--no-session-persistence\u003C\u002Fcode> turns it off.\u003C\u002Fp>\n\u003Ch2 id=\"what-changes-in-ci-and-cron\">\u003Ca class=\"anchor\" href=\"#what-changes-in-ci-and-cron\" aria-label=\"Link to this section\">#\u003C\u002Fa>What changes in CI and cron?\u003C\u002Fh2>\n\u003Cp>Three things to decide.\u003C\u002Fp>\n\u003Cp>\u003Cstrong>What the run loads.\u003C\u002Fstrong> Without \u003Ccode>--bare\u003C\u002Fcode>, \u003Ccode>claude -p\u003C\u002Fcode> discovers hooks, skills, plugins, MCP servers, auto memory and \u003Ccode>CLAUDE.md\u003C\u002Fcode> the way an interactive session does, including the project&#39;s \u003Ccode>.claude\u002Fsettings.json\u003C\u002Fcode> and \u003Ccode>.mcp.json\u003C\u002Fcode>, with no trust dialog and no per-server approval. That is convenient on your laptop and surprising on a build machine. \u003Ccode>--bare\u003C\u002Fcode> skips all of it for a consistent run; you then pass what you need with \u003Ccode>--append-system-prompt\u003C\u002Fcode>, \u003Ccode>--settings\u003C\u002Fcode>, \u003Ccode>--mcp-config\u003C\u002Fcode>, \u003Ccode>--agents\u003C\u002Fcode> or \u003Ccode>--plugin-dir\u003C\u002Fcode>. Bare mode never reads your login: it needs \u003Ccode>ANTHROPIC_API_KEY\u003C\u002Fcode> or an \u003Ccode>apiKeyHelper\u003C\u002Fcode>. Mind that hooks passed through \u003Ccode>--settings\u003C\u002Fcode> still do not run in bare mode.\u003C\u002Fp>\n\u003Cp>\u003Cstrong>How it authenticates.\u003C\u002Fstrong> An unattended machine cannot do a browser login. \u003Ccode>claude setup-token\u003C\u002Fcode> creates a long-lived token for a Claude subscription; check the Claude Code docs for where the CI job reads it. Remember that subscription use counts toward your plan&#39;s limits: see \u003Ca href=\"\u002Fblog\u002Fclaude-code-usage-limits\">Claude Code usage limits\u003C\u002Fa>.\u003C\u002Fp>\n\u003Cp>\u003Cstrong>How it ends.\u003C\u002Fstrong> If you stop a run with SIGTERM, Claude Code exits with code 143 and leaves the turn unfinished. Send SIGINT first if you want the turn to end cleanly. After the main turn, a run can also wait up to ten minutes for background work it started, such as background subagents.\u003C\u002Fp>\n\u003Cp>A minimal cron entry that writes a daily summary:\u003C\u002Fp>\n\u003Cpre class=\"code\" data-lang=\"sh\">\u003Ccode># crontab -e\n0 8 * * 1-5 cd ~\u002Fcode\u002Fapp &amp;&amp; git log --since=yesterday --oneline | claude -p &quot;summarize these commits for a standup, 5 bullets max&quot; --allowedTools &quot;Read&quot; &gt;&gt; ~\u002Fstandup.md\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>For repositories on GitHub or GitLab, Anthropic publishes ready-made integrations (GitHub Actions and GitLab CI\u002FCD) built on the same \u003Ccode>-p\u003C\u002Fcode> interface, so you rarely have to write the workflow file from scratch. For recurring work that should live outside your machine, see \u003Ca href=\"\u002Fblog\u002Fscheduled-claude-code-routines\">scheduled Claude Code routines\u003C\u002Fa>.\u003C\u002Fp>\n\u003Ch2 id=\"what-can-39-t-you-do-in-headless-mode\">\u003Ca class=\"anchor\" href=\"#what-can-39-t-you-do-in-headless-mode\" aria-label=\"Link to this section\">#\u003C\u002Fa>What can&#39;t you do in headless mode?\u003C\u002Fh2>\n\u003Cp>Terminal-only commands such as \u003Ccode>\u002Flogin\u003C\u002Fcode> are unavailable. Your own skills and slash commands work if you put \u003Ccode>\u002Fskill-name\u003C\u002Fcode> in the prompt. A few built-ins accept an argument, for example \u003Ccode>\u002Fmodel sonnet\u003C\u002Fcode>. Nobody is there to answer a question, so tasks that need your judgment in the middle belong in an interactive session, not in \u003Ccode>-p\u003C\u002Fcode>.\u003C\u002Fp>\n\u003Ch2 id=\"in-relais\">\u003Ca class=\"anchor\" href=\"#in-relais\" aria-label=\"Link to this section\">#\u003C\u002Fa>In Relais\u003C\u002Fh2>\n\u003Cp>Relais is a desktop app, not a CI tool, so it does not replace a script on a build server. Where it overlaps is the repeating part: its &quot;Repeat&quot; feature resends a prompt at set times, in the same session or a fresh one each time, and sessions it runs are normal Claude Code sessions in \u003Ccode>~\u002F.claude\u002Fprojects\u003C\u002Fcode>, so \u003Ccode>claude --resume\u003C\u002Fcode> opens them. More on the \u003Ca href=\"\u002Ffeatures\">features page\u003C\u002Fa>.\u003C\u002Fp>\n",[15,18,21,24,27,30,33],{"id":16,"text":17},"how-do-you-run-claude-code-non-interactively","How do you run Claude Code non-interactively?",{"id":19,"text":20},"which-output-format-should-you-use","Which output format should you use?",{"id":22,"text":23},"how-do-you-let-it-use-tools-without-a-human","How do you let it use tools without a human?",{"id":25,"text":26},"how-do-you-continue-a-conversation","How do you continue a conversation?",{"id":28,"text":29},"what-changes-in-ci-and-cron","What changes in CI and cron?",{"id":31,"text":32},"what-can-39-t-you-do-in-headless-mode","What can&#39;t you do in headless mode?",{"id":34,"text":35},"in-relais","In Relais",[37,43,48],{"slug":38,"title":39,"description":40,"category":7,"categoryId":8,"keyword":41,"date":10,"minutes":42},"ai-agents-with-a-browser","AI agents that use a browser: what works and what breaks","What AI agents with a browser do well (testing, reading, forms), where they fail (logins, CAPTCHAs, dialogs), and how to give one a browser safely.","ai agents with a browser",6,{"slug":44,"title":45,"description":46,"category":7,"categoryId":8,"keyword":47,"date":10,"minutes":11},"ai-agents-as-a-company","Running a group of AI agents like a small company","How to organize AI agents like a small company: roles, a manager, a shared task board, approvals and routines, and the mistakes that make teams drift.","ai agents as a company",{"slug":49,"title":50,"description":51,"category":7,"categoryId":8,"keyword":52,"date":10,"minutes":11},"scheduled-claude-code-routines","Scheduled Claude Code tasks: recurring routines on autopilot","Four ways to run Claude Code on a schedule: \u002Floop, cloud scheduled tasks (routines), Desktop tasks and plain cron. What each needs, and which to pick.","scheduled claude code tasks",1794931098788]