Skip to main content
Tips

practitioner tip

Run Claude Code as an Autonomous Headless Agent

AIErudit angle: Scaling AI delivery means running agents unattended — in CI, scripts, or cron — with hard guardrails on what they can touch and spend. This tip shows how the -p flag turns Claude Code into a reasoning headless agent, and how --allowedTools, --max-turns, and --max-budget-usd keep autonomous runs safe and bounded. It's the pattern behind scheduled log reviews, health checks, and overnight triage.

headless-modeautomationclaude-codetips
Tip visual

Published: Mar 5, 2026 Updated: 2026-06-16

Original: https://wmedia.es/en/tips/claude-code-headless-mode-autonomous-agent

Claude Code isn't just an interactive assistant. With the -p (print) flag, it becomes a headless agent you can launch from scripts, CI/CD pipelines, or — here's where it gets interesting — from a cron job.

The difference from a regular script is that Claude doesn't execute fixed steps: it reasons about the current context and decides what to do. Combined with --allowedTools to control its permissions, you get a fully autonomous AI agent that works while you sleep.

TL;DR claude -p "prompt" --allowedTools "Read" "Bash(curl *)" turns Claude into an autonomous agent you can schedule with cron. It's not a static script — it's an agent that reasons and makes decisions. Headless is one of the four ways to send Claude Code to the background — the full map compares claude -p with Agent View, /loop and Routines, and tells you which one fits each case. Before reaching for system cron, check if a Desktop or Cloud scheduled task fits — the Cloud one (now called Routine) covers 90% of what you'd use cron for today. For the full picture of all 6 autonomous primitives, see the map.

Example — cron job that reviews staging logs every night:

# crontab -e
0 3 * * * cd /home/deploy/app && claude -p "Review logs/staging.log from the last 24h. \
  If you find errors, create a GitHub issue with the stack trace. \
  If clean, post a summary to Slack via curl." \
  --allowedTools "Read" "Bash(curl *)" "Bash(gh issue create *)" \
  --max-turns 10 \
  --max-budget-usd 0.50 \
  --output-format json >> /var/log/claude-review.log 2>&1

How it works

1. Basic usage

# Direct prompt
claude -p "explain this function"

# Stdin piping
cat error.log | claude -p "explain these errors and suggest fixes"

# Continue a previous session
claude -c -p "check for type errors in the last changes"

The -p flag disables the interactive interface. Claude processes the prompt, executes the necessary actions, and returns the result to stdout.

2. Control permissions

# Read-only — risk-free analysis
claude -p "audit this codebase" --allowedTools "Read" "Glob" "Grep"

# Read + HTTP — can notify but not modify
claude -p "check health" --allowedTools "Read" "Bash(curl *)"

# Everything allowed (be careful)
claude -p "fix all lint errors" --dangerously-skip-permissions

--allowedTools is the key to safe automation. It defines exactly which tools Claude can use, with pattern matching for specific commands.

3. Limit cost and execution

claude -p "complex analysis" \
  --max-turns 15 \
  --max-budget-usd 1.00

--max-turns limits how many actions Claude can take. --max-budget-usd caps spending. Both are essential for unattended execution. Anthropic announced that from June 15, 2026 that spend would move to a separate monthly Agent SDK credit, but it cancelled the change; for now it still comes out of your subscription limits.

4. Output format for scripts

# JSON for programmatic parsing
claude -p "list all TODO comments" --output-format json

# Streaming JSON for real-time processing
claude -p "analyze" --output-format stream-json

Reference

FlagWhat it doesExample
-p / --printEnables headless modeclaude -p "query"
--allowedToolsPermitted tools--allowedTools "Read" "Bash(curl *)"
--max-turnsAction limit--max-turns 10
--max-budget-usdSpending cap--max-budget-usd 0.50
--output-formatOutput format--output-format json
--dangerously-skip-permissionsSkip all permissionsUse with caution

Official docs: Run Claude Code programmatically

Related: Computer use — when the terminal is not enough · Notify when Claude finishes · Map of the 4 ways to send Claude to background · The Agent SDK credit that was announced and cancelled