agentic-brownfield-coding

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, 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.

1. 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.

1. Pick the best suited template and copy it to .claude/headless/<descriptive-name>.sh and chmod +x it.
2. [foreach-file.sh](./templates/foreach-file.sh) — one invocation per file matching a glob argument.
3. [foreach-line.sh](./templates/foreach-line.sh) — one invocation per line of stdin (PR numbers, IDs, URLs).
4. [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.

1. Copy the matching prompt template to .claude/headless/<descriptive-name>.md.
2. [foreach-file.md](./templates/foreach-file.md)
3. [foreach-line.md](./templates/foreach-line.md)
4. [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.

1. Tune the parameters in the script such as CLAUDE_ARGS and BATCH_SIZE per the decisions below.
2. Review the generated content and flag relevant [pitfalls](#pitfalls) that apply to this setup.
3. 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 and permissions.deny settings, modified by the command arguments. Permission directives are evaluated in the order deny → ask → allow, where ask equals deny when non-interactive.

The most important general command argument is --permission-mode:

• dontAsk (recommended for unattended runs) — Auto-denies anything not in permissions.allow

or the built-in read-only whitelist for the Bash tool. Error messages explicitly inform agent of this mode.

• acceptEdits — Auto-allows any file edits and common filesystem Bash tool ops (mkdir, mv, cp).
• bypassPermissions (same as --dangerously-skip-permissions) — Skips checks entirely.

Only use under strict isolation (container, worktree, throwaway environment).

• auto uses a security classifier model to decide — not recommended.
• plan exposes read-only tools but also some that control plan mode — not recommended.
• default effectively equivalent to dontAsk but with less explanatory error messages — not recommended.

The arguments --allowedTools and --disallowedTools act exactly as if their content was added to permissions.allow / permissions.deny and also take the same syntax (comma separated). Warning: Listing a bare tool name (e.g. Bash) as allowed will allow every invocation of the tool, except for those listed explicitly as denied. Narrow with patterns like Bash(git:*) when possible.

Also note that --allowedTools must not be confused with --tools: The latter controls which tools are available to the model but has no impact on per-invocation permission. So --tools is an effective way to define a tool whitelist, but each must also be allowed to be invoked successfully.

The interaction between --disallowedTools and --tools is even more nuanced. If a bare tool name is listed in --disallowedTools or the deny settings, it is removed from the available tools. When only certain argument patterns of a tool are denied, the tool in general remains available. So --disallowedTools is an effective way to define a tool blacklist when use of --tools is impractical.

Agent Content Principles

When generating or reviewing content for .md prompt files, you are writing for other AI coding agents. Follow these principles to optimally tailor your instructi