Interactive vs Headless

Claude Code runs in two fundamentally different modes, and choosing the right one is a real architectural decision.

• Interactive: a conversational session. You type, Claude responds, you steer, it asks for approvals. A human is in the loop.
• Headless (non-interactive): a single scripted invocation that runs to completion with no human present. Built for pipelines and automation.

Same engine, very different control model. This lesson shows when each one wins.

You switch into headless mode with -p (also written --print). It runs the prompt once, prints the result, and exits. No back-and-forth, no TTY required.

This is the required form for CI/CD pipelines: there is no human to answer prompts inside a build job, so an interactive session would simply hang.

Interactive output is for humans to read. Headless output is for machines to parse. Use --output-format json so a downstream step can act on the result programmatically.

Pair it with a JSON Schema so the structure is guaranteed and your pipeline never breaks on free-form prose.

The deepest difference is who steers.

• Interactive: the human course-corrects mid-task, approves edits, and resolves ambiguity by being asked.
• Headless: no one is there to ask. The prompt must be self-contained, the success criteria explicit, and ambiguous input handled by the prompt itself, not by a follow-up question.

If your task genuinely needs a human judgment call partway through, headless is the wrong choice.

Plan mode belongs to the interactive world. You use it for large changes, multiple possible approaches, or architectural decisions: Claude explores and proposes a plan, then waits for your approval before editing.

That approval gate is a human checkpoint. It has no meaning in a headless run, where there is no one to approve. For single-file fixes or a clear stack trace, you skip plan mode and execute directly anyway.

A classic headless use case: an automated code review on every pull request. The job runs -p, emits JSON, and a script turns findings into comments or a gate.

Crucially, run this review in an isolated session so it is not biased by any generation context. Fresh-instance review beats same-session self-review, where the author keeps its own reasoning and won't challenge itself.

A headless reviewer that cries wolf gets muted. Give it explicit criteria instead of vague instructions: "flag a comment only when it contradicts the code" beats "be more precise".

When re-running on a later push, include the prior results and report only new or unfixed issues, so the same noise isn't repeated on every commit.

Don't confuse a headless blocking check with the Message Batches API. They solve different problems.

• Headless -p in CI: synchronous, returns now, gates a merge.
• Batch API: 50% cheaper, up to a 24h window, no latency SLA, and no multi-turn tool calling.

Use Batch for non-blocking overnight jobs like reports or audits, never for a pre-merge or time-sensitive check that must answer immediately.

Interactive work is conversational and resumable. --resume <name> continues a named session; fork_session branches from a shared point to try alternatives.

One caution: resumed tool results can be stale if the codebase changed since. Sometimes a fresh session seeded with a structured summary is better than resuming an out-of-date one.

Both modes read the same project configuration, so a well-set-up repo behaves consistently whether a human or a pipeline invokes it.

• ./CLAUDE.md (project-level, shared via VCS) carries standards into every run.
• .claude/skills/ and commands give reusable, scoped behaviors.

Note: user-level ~/.claude/CLAUDE.md is personal and NOT shared via VCS, so your CI runner won't have it. Put anything the headless job depends on in the project scope.

When picking a mode, ask:

• Is a human present to approve and steer? Yes -> interactive. No -> headless.
• Does a script need to parse the result? Yes -> headless with --output-format json.
• Is it a blocking, time-sensitive check? Use synchronous headless, not Batch.
• Large or architectural change needing approval first? Interactive plan mode.
• Automated PR review? Headless, isolated session, explicit criteria.

Match the mode to who is in the loop and what consumes the output.

Apply what you've learned to a realistic pipeline decision.

Key takeaways:

• Interactive = conversational, human-in-the-loop; supports plan mode approvals and resumable/forkable sessions.
• Headless = -p/--print, runs once and exits; required for CI/CD where no human is present.
• Add --output-format json (plus a schema) for machine-parseable results.
• Automated review should run in an isolated session with explicit criteria, reporting only new/unfixed issues.
• Both modes share project-scope config (./CLAUDE.md, .claude/), but not personal ~/.claude config.
• Headless blocking checks are NOT the Batch API: Batch is cheaper but has no latency SLA and no multi-turn tool calling.