/headless

description:  >
  Assists in the creation of a headless Claude Code batch script that runs an isolated micro-session per item
  (file, line, task) for ad-hoc automation such as bulk migrations, lint-fix loops, or doc generation.
disable-model-invocation: true
user-invocable: true

Claude Code Headless Batch Setup

Your goal is to help the user assemble a small shell script that drives `claude -p` over many inputs, running one ephemeral micro-session per item. The result usually lives under `.claude/headless/` and pairs a driver script (`*.sh`) with a system prompt file (`*.md`) and potentially an input list file.

**Additional user arguments**: $ARGUMENTS

**Language hint**: Always create all generated script content and comments in English for consistency across the codebase, while continuing to speak to the user in the language of their choice.

**Platform hint**: Instructions and templates assume a Linux host with GNU coreutils. Adapt to the detected user OS.

• macOS — Substitute BSD equivalents for GNU-only utilities.
• Windows — Still use `.sh` files (skip irrelevant `chmod +x`), assuming Git Bash is available at runtime.

Workflow

1. Ensure the user intent is clear. If user arguments are absent or ambiguous, especially regarding the [upcoming decisions](#decisions-to-make), elicit the necessary information via informal conversation with the user. 2. Advise the user on a sensible strategy using the [given background](#background-knowledge) as reference. Push back on choices that are likely to cause token usage escalation, contention, or silent failures. 3. Pick the best suited template and copy it to `.claude/headless/<descriptive-name>.sh` and `chmod +x` it.

• [foreach-file.sh](./templates/foreach-file.sh) — one invocation per file matching a glob argument.
• [foreach-line.sh](./templates/foreach-line.sh) — one invocation per line of stdin (PR numbers, IDs, URLs).
• [foreach-task.sh](./templates/foreach-task.sh) — one invocation per unchecked item in a sibling checklist file.

This is the most powerful driver script, capable of ingesting, tracking and resuming progress on arbitrary items. Use when the user wants to prepare and iterate on hand-curated task list (in this or a separate session).

• [foreach-task-parallel.sh](./templates/foreach-task-parallel.sh) — same as `foreach-task.sh` but

runs `BATCH_SIZE` tasks concurrently per batch. However, tasks with overlapping access scope will race. Check the assumptions block at the top of the script for compatibility before suggesting this option. 4. Copy the matching prompt template to `.claude/headless/<descriptive-name>.md`.

• [foreach-file.md](./templates/foreach-file.md)
• [foreach-line.md](./templates/foreach-line.md)
• [foreach-task.md](./templates/foreach-task.md) (also used for the parallel variant)

For task-based scripts, also create a task file based on [foreach-task.tasks.md](./templates/foreach-task.tasks.md). Tailor all of these files to the user's needs, falling back to interactive feedback as required. 5. Tune the parameters in the script such as `CLAUDE_ARGS` and `BATCH_SIZE` per the decisions below. 6. Review the generated content and flag relevant [pitfalls](#pitfalls) that apply to this setup. 7. Remind the user how to run the script from the current working directory, suggesting a test run on the first items (script can be aborted at any time using `Ctrl+C`).

Decisions to Make

These are the variables that determine the right approach, as well as tweaks to the scripts and prompts.

• **Input shape** — File glob, lines on stdin, fixed custom checkbox-list file (resumable).
• **Per-item task** — Specific, mechanical description. What inputs, what outputs, when to exit without action.
• **Tool surface** — Smaller is cheaper, faster, safer. Whitelist (preferred) or blacklist.

Common shapes: `Read,Grep,Glob` (analysis), `Read,Edit` (single-file rewrite), add `Write` only if needed.

• **Model** — `sonnet` for common tasks; `haiku` for simple tasks, `opus` only when reasoning genuinely demands it.
• **Turn cap** — Set `--max-turns` low (10-20 for mechanical edits, 30-50 for harder tasks).
• **Concurrency** — Sequential by default. Only `foreach-task-parallel.sh` allows parallel execution

when time is the larger constraint over cost control and concurrency conflicts are not an issue.

• **Run target** — Local dev workstation (OAuth works) vs. unattended/CI (needs `ANTHROPIC_API_KEY`).

---

Background Knowledge

Context Isolation

Each `claude -p` invocation is a fresh agent with no memory of the previous one. The advantages: predictable cost, parallel-friendly, clean recovery from individual failures, no context contamination. The trade-off: the agent cannot accumulate cross-item learning. Every item must be self-contained. If the task benefits from cumulative context (exploring a codebase, building up a plan), headless batching is the wrong tool.

Custom System Prompt

A headless run with `--system-prompt-file` is mechanically equivalent to a subagent invocation via the `Agent` tool from the main session. Same isolated context, same custom prompt, same tool restrictions. The difference is only the entry point: a shell driver iterating over items vs. a parent agent dispatching tasks.

The CLI docs make `--system-prompt` and `--system-prompt-file` sound drastic — as if they replace the entire system prompt. They don't. Claude Code's system prompt is segmented and conditional. The injected content only replaces the conversational/persona segments that govern how the agent talks to a user in an interactive session. The structural parts — tool definitions, environment block, harness rules, hook contracts, etc. — remain in place. This is exactly how subagents are configured.

Permissions

Non-interactive `-p` mode cannot display permission dialogs, so the effective tool surface is determined entirely by `permissions.allow