Claude Code Headless Mode

Build and run claude commands for work that should be executed through Claude Code itself.

Reference	Read it when
references/flags-and-permissions.md	The command needs more than -p — permission modes, tool scoping, output formats, flag inventory, installation
references/examples.md	You want a worked command for a specific shape of task (read-only analysis, safe edit run, JSON report, resume, MCP, sandboxed unattended run)

Requires the claude CLI installed and authenticated on the target machine.

Core rules

• claude --help on the target machine is the compatibility floor. CLI flags and permission-rule syntax move faster than docs and copied examples, and they differ between builds. Verify any uncommon flag there before emitting it.
• Do not add --model unless the user asked for an override or the workflow must pin a model for reproducibility. The user's configured model is the right default.
• Prefer --append-system-prompt over --system-prompt unless replacing Claude Code's default behavior is the point.
• Choose the least-permissive mode that still fits the task. acceptEdits is the usual starting point for coding automation. For a truly unattended run, reach for explicit permission rules or dontAsk first; bypassPermissions is only for an already-isolated environment.

Check what the task needs

Before execution, confirm the CLI is available and authenticated. Consult claude --help for flags needed by this command; use version or diagnostic commands when compatibility or installation is in doubt. A request for a command example does not authorize running that task.

Basic shape

claude -p "summarize the repository architecture"
claude -p "review the auth layer for risks" --output-format json

Everything else is a matter of scoping tools and permissions around that — see the references.

When to pause

Pause for missing credentials, unavailable required capabilities, or a permission expansion. If an equivalent supported command stays within the request, use it without adding an approval step.

What to return

For execution requests, run the authorized command and inspect its result and relevant artifacts; do not stop at printing a command or treat exit code zero as proof that the requested work is complete. Continue bounded follow-up within the existing scope when work remains. For command-only requests, return the command without executing it.

Report the command, outcome, relevant checks, and any permission or validation gaps. Include a resume command only when the workflow is meant to continue later.