Headless Task

A headless task is when you execute requests to the Claude Code CLI without entering interactive mode. You run headless queries/tasks using the -p flag (print mode).

claude -p "refactor the auth module to use OAuth2"
claude -p --permission-mode plan "analyze the codebase and create a migration plan"
# Limit how many steps the agent can take
claude -p --max-turns 10 "run the test suite and fix any failures"
# Pipe output to a file
claude -p "generate API documentation" > docs/api.md
# Pass input via stdin
cat error.log | claude -p "diagnose this error"
# Use a specific model
claude -p --model claude-opus-4-6 "review this codebase for security issues"

Use cases:

CI/CD pipeline — auto-fix lint errors on commit
Scripted automation — batch file processing
Cron jobs — nightly code analysis
Piping data — feed logs/files directly via stdin

You can use --allowedTools and --disallowedTools to apply permissions for that specific headless task:

# Allow specific tools for this run only
claude -p "run the tests" --allowedTools "Bash(npm run test:*)" "Read"
# Deny specific tools for this run
claude -p "analyze the codebase" --disallowedTools "Bash(rm:*)" "Write"