Headless Mode: Claude Code Without a Terminal

deployment

Headless Mode: Claude Code Without a Terminal

Run Claude Code as a service. Cron jobs, webhooks, async tasks. The patterns that turn Claude into infrastructure.

Claude Code · Hidden Feature #003 · Infrastructure Pattern

Claude Code without a human.

The -p flag turns Claude Code into a Unix tool you can pipe, chain, and schedule. No terminal interaction. Structured JSON output. Runs inside CI/CD without a TTY. This is how Claude becomes infrastructure.

claude -p

the flag

JSON output

schema-constrained

CI/CD ready

no TTY required

Core flags

Everything that makes headless mode powerful

Pass these flags to claude -p to control output format, tool access, and session continuity.

Key insight

Pipeline patterns

Real commands you can copy-paste today

Five patterns that cover 90% of headless use cases. Click a tab to see the command.

Monitor logs in real time

Pipe your log tail directly into Claude. It reads the stream, detects anomalies, and messages you on Slack via MCP.

Deployment patterns

4 ways to run Claude as infrastructure

From simple cron jobs to horizontally-scaled queue workers.

Cron job

Schedule Claude to run at a fixed cadence. No human needs to be present. Works with crontab, launchd, or any job scheduler.

• →Always redirect stdout and stderr to a log file
• →Use --allowedTools to lock down what Claude can touch
• →Test with CLAUDE_SKIP_AUTH=1 locally before scheduling

Webhook handler

Trigger Claude via HTTP webhook: Stripe events, GitHub push hooks, Zapier, or any POST from an external service.

• →Validate webhook signatures before invoking Claude
• →Wrap exec in try/catch; Claude can exit non-zero on errors
• →Keep prompts short; pipe heavy context via stdin instead

Queue worker

Pull jobs from a queue (Redis, SQS, BullMQ) and run Claude per job. Scales horizontally. Handles retries automatically.

• →Set timeout; Claude on large repos can take 60-120s
• →Use job.data.projectPath to scope Claude to the right repo
• →Store structured JSON output directly in the job result

Scheduled task (launchd / systemd)

Run Claude as a persistent background service or scheduled OS-level task. More reliable than cron for mission-critical jobs.

• →launchd is more reliable than cron: it survives reboots and sleeps
• →Use StandardOutPath/ErrorPath to capture all output
• →Test with launchctl start before enabling the schedule

Output parsing

Reading what Claude returns

How to capture stdout, parse JSON, stream responses, and handle exit codes in shell scripts.

bash - capture, parse, stream, exit codes

Exit codes

Error handling

Make headless runs production-safe

Claude can fail: rate limits, context overflow, tool errors. Wrap your calls defensively.

bash - retry wrapper with Slack alerting

Retry with backoff

Rate limits and transient failures need exponential back-off. Start at 5s, double each attempt.

Capture stderr

Claude writes tool errors to stderr. Redirect 2>&1 or you'll miss them in logs.

Set timeouts

Large repos can take 90-120s. Always set a timeout so stuck jobs don't block queues.

Alert on failure

Use Claude itself to send a Slack alert when a headless run fails. No extra tooling needed.

State persistence

Keeping context across separate runs

Claude's context window doesn't survive process boundaries. Use --continue, --resume, or manual state files.

bash - continue, resume, and manual state

Rule of thumb

Production examples

3 real workflows you can deploy today

Copy, adapt, and ship. Each example is running in production at agencies using Claude Code.

Nightly code health report

Runs at 2am every night. Scans the whole repo, builds a quality report, and posts it to Slack before the team starts work.

PR auto-review bot

Triggers on every PR open via GitHub webhook. Posts a structured review comment within 60 seconds. Blocks merge on critical issues.

i18n auto-translator pipeline

Triggered whenever a PR adds new English strings. Detects missing translations, produces accurate i18n output, and opens a follow-up PR.

Bottom line

claude -p is the bridge between an interactive coding assistant and a piece of infrastructure. Once you start thinking of Claude as a CLI tool, something you pipe into, schedule, and chain, the automation surface area becomes enormous. Cron jobs, webhook handlers, queue workers, CI gates: all of them become AI-native with one flag.

Want this running in your stack?

ManasFlow builds AI automation systems for production teams.

Claude Code in GitHub Actions

Production Claude Code: Scale & Reliability