Runs a batch of Claude Code agent calls the way you’d run a batch job: describe the work in a file, let code decide what runs and in what order, and get back a report of what happened and what it cost.
Why a runner instead of an orchestrating agent
Asking one agent to fan itself out over fifty files works until it doesn’t — it forgets a file,
decides ten is enough, or reports success for a unit that quietly failed. claude-batch-runner
keeps that control flow in code: the spec is validated before anything runs, so an unknown field
or a bad tier name fails at parse rather than forty units in. A worker that dies comes back as a
FLAGGED row with its error, not a silent hole, and the rest of the batch keeps going.
Escalation and verification
Cheap work runs on a cheap tier; only units matching an escalation condition written as
<field> <op> <number> — confidence < 0.6, checked against the worker’s own structured output —
redo on a stronger advisor. The condition is parsed before the batch runs, so a typo costs nothing
instead of failing after unit 39. An optional verify pass grades output against a rubric, gets one
bounded chance to fix a failure, and never auto-passes.
Quick start
1python -m claude_batch_runner --spec campaign.json --dry-run
--dry-run validates the spec and counts units — from a worklist of one JSON object or bare
string per line — without dispatching anything or spending a token.
Requirements
Python 3.11+, standard library only beyond the claude CLI it shells out to, one process per
unit of work. That CLI must already be on PATH and authenticated — the runner uses whatever
authentication it already has and never reads or sets credentials of its own.
Documentation
claude-batch-runner’s documentation lives in its repository, next to the code it describes — the README is the manual.