Headless, Streaming, and Auto-Mode
CoreDistinguish Claude Code's session and operating-mode features · Difficulty 2/5
Explanation
Session Management
Claude Code conversations persist as sessions that can be resumed later, rather than being lost when a terminal closes. /clear resets the conversation context to keep it focused -- useful when accumulated history has stopped being relevant to the current task (a manual antidote to context rot).
The Three Modes
| Mode | What it does | Typical use |
|---|---|---|
| Headless mode | Runs non-interactively (e.g., claude -p "..."), no interactive TUI | Scripting, CI pipelines, automation |
| Streaming mode | Emits output incrementally, including structured stream-JSON | Programmatic consumption of output as it's produced |
| Auto-mode | Reduced-friction autonomous operation -- proceeds with less step-by-step confirmation | Faster iteration, at the cost of reduced human checkpoints |
These three axes are independent: a run can be headless and streaming at once (a CI job consuming stream-JSON output), and auto-mode is an autonomy setting orthogonal to whether the session is interactive.
Auto-mode is powerful precisely because it removes confirmation checkpoints -- which is why it should be paired with settings.json permission rules and hooks, not used unguarded. Removing human-in-the-loop confirmation raises the stakes of any single action Claude takes, so the deterministic controls that would otherwise be backed up by a confirmation prompt need to be enforced structurally instead.
The Best-Practice Loop
Anthropic's operational guidance is to work in a gather context -> make a plan -> act -> verify loop: understand the task and codebase, form a plan, execute it, and use tests/builds as ground-truth verification rather than trusting the model's own claim of success. Tighten this loop over time with custom slash commands and hooks rather than accumulating long, brittle ad-hoc prompts.
Common exam traps
- Confusing headless mode with auto-mode. Headless mode is about *interactivity* (no TUI, suitable for CI/scripting); auto-mode is about *autonomy* (fewer confirmations before acting). An exam item may describe "running in a CI pipeline" (headless) as a distractor for a question actually asking about auto-mode, or vice versa.
- Assuming streaming mode implies headless, or that headless implies auto-mode -- the three are independent settings, not a single spectrum.
- Using auto-mode without corresponding settings.json permission rules/hooks, on the assumption that reduced confirmation is safe by default.
Key Takeaways
- Session management persists conversations as resumable sessions; /clear resets context to stay focused
- Headless mode = non-interactive execution for scripting/CI (e.g., claude -p); streaming mode = incremental/stream-JSON output for programmatic use; auto-mode = reduced-confirmation autonomy
- Headless mode (interactivity) and auto-mode (autonomy) are frequently confused but are independent axes
- Auto-mode should be paired with settings.json permission rules and hooks, not used unguarded
- The best-practice loop is gather context -> plan -> act -> verify, tightened with custom commands/hooks rather than long prompts
Glossary Terms
Shell scripts or commands configured in .claude/settings.json that run at defined lifecycle points: PreToolUse (before tool execution), PostToolUse (after tool execution), Stop (before ending), SubagentStop (when subagent finishes). Used for code quality gates, notifications, logging, and safety checks.
The Claude Code settings file that configures tool permissions, hook scripts, environment variables, and behavioral settings. Project-scoped (.claude/settings.json) checked into version control, or user-scoped (~/.claude/settings.json) for personal preferences. Hooks are defined here.
A Claude Code CLI flag that controls the response format. Values: 'text' (default, plain text), 'json' (structured JSON), 'stream-json' (streaming JSON events). Use with --json-schema to guarantee output matches a specific schema. Critical for CI/CD pipeline integration.
Claude Code CLI flag for non-interactive (headless) execution. Processes the prompt, outputs to stdout, and exits immediately without entering an interactive session. Essential for CI/CD pipeline integration, scripting, and automation workflows.
Related Concepts
settings.json as the Deterministic Control Surface
settings.json (user: ~/.claude/settings.json, project: .claude/settings.json) configures tool permissions, hooks, env vars, model selection, and MCP servers
Built-in vs. Custom Slash Commands
Built-in slash commands include /clear (reset context), /init (bootstrap CLAUDE.md), and /help