How to run Claude Code headlessly

Claude Code can run non-interactively for bounded jobs such as repository analysis, release-note drafting, test triage, and code changes that will be reviewed through Git.

Headless execution means there is no person answering prompts during the run. It does not mean unlimited autonomy, persistent memory, or automatic safety. The command still runs on a host, under credentials and permissions that you control.

Start with a bounded command

Claude Code supports non-interactive execution through its print mode. A minimal pattern is:

claude --print "Inspect the failing tests in packages/api. Explain the likely cause. Do not edit files."

Check Anthropic's Claude Code documentation before scripting flags, output formats, or permission settings because the interface evolves.

Begin read-only. Once the job reliably produces useful output, allow a narrowly scoped write task in a disposable branch or worktree.

Define the output contract

An automation should produce something another system can evaluate. Ask for structured output when a machine will consume the result, or write a stable Markdown artifact when a person will review it.

A useful task definition includes:

• the repository path and allowed files,
• the objective and acceptance criteria,
• commands the agent may run,
• actions it must not take,
• a time or iteration limit,
• the required final artifact.

For a code change, the artifact should normally be a diff plus test results, not only a prose answer.

Run each job in an isolated worktree

Do not point concurrent jobs at the same checkout. Create one worktree and branch per task:

git fetch origin
git worktree add ../app-agent-142 -b agent/issue-142 origin/main
cd ../app-agent-142
claude --print "Fix issue 142 using the acceptance criteria in the issue. Run the focused tests."

The worktree prevents agents from mixing file changes, indexes, generated output, and package locks. Use separate ports and databases when jobs run services.

Treat permissions as part of the program

Non-interactive jobs cannot pause for every ambiguous decision. Configure permissions so the safe path is also the available path.

Avoid broad production credentials. Prefer a repository token that can push only the task branch, read-only access to logs, and short-lived credentials for external tools. Keep deployment, merge, and destructive database operations behind separate approval gates.

Decide where the process should run

For CI jobs, use the CI runner and its normal timeout, artifacts, and credential controls. For a scheduled job, use a service or computer with process supervision. For long exploratory work, a persistent remote computer can keep the repository and tools available after the laptop disconnects.

Matrix OS can host Claude Code on a persistent cloud computer with browser and terminal access. The remote host removes the laptop from the runtime path, but Git checkpoints, logs, timeouts, and recovery procedures still matter.

Keep context in durable artifacts

Do not depend on an earlier conversation being available. Store task context in the issue, repository instructions, plan, or input file. Store progress in commits, notes, and test output.

If a job must resume, give it the original goal plus the durable artifacts from the previous run. This is easier to audit than relying on hidden conversational memory.

Use headless Claude Code in CI carefully

A safe first CI use is review-only: summarize a diff, identify missing tests, or compare changes with repository guidance. Keep the result advisory until the team understands false positives and cost.

If the job writes code, run it in a separate workflow with a bot branch. Do not let generated changes bypass the same tests and human review required for human-authored code.

This article focuses on non-interactive automation. For remote runtime setup, see How to run Claude Code in the cloud; for unattended work, see How to run Claude Code overnight safely.

FAQs

Does headless Claude Code keep running after a laptop closes?

Only if the command runs somewhere other than the sleeping laptop. Headless describes the interface, not the location or uptime of the host.

Is headless mode the same as a background agent?

Not necessarily. A headless CLI process is something you operate. A managed background agent usually includes a provider-owned runtime, task lifecycle, and review interface.

Can headless Claude Code modify code?

Yes, when its configured permissions allow it. Use an isolated branch and require normal tests and review before merging.