claude-batch-toolkit

A four-part add-on for claude-code that sends slow work to Anthropic's batch endpoint instead of the real-time one, so it bills at half price. Built by S2 (s2-streamstore), 158★ / 7 forks / 1 open issue, Shell + Python, README says MIT though GitHub detects no licence file. Created 2026-02-09, last pushed 2026-03-09 — six months untouched at the time of reading, which shows up in the numbers below.

This is the first page here that buys a provider pricing mode as a harness feature. The lever itself is documented in the sibling spoke: claude-message-batches-api in ../llm-providers-wiki.

The pitch

Code review, documentation, architecture analysis, refactoring plans and security audits do not need an answer while you wait. Type /batchy Review this codebase for security issues, and Claude Code gathers the context, builds a self-contained prompt, and posts it as a batch job. Typical turnaround is under an hour; the ceiling is 24. You get the result later, at half the token price.

The trade is unusual here. Every other cost lever in this spoke attacks the token count — headroom compresses what the agent reads, pxpipe re-renders context as images, tokenmining routes and compacts, ponytail argues the agent should write less code. This one leaves the tokens alone and sells the latency instead. It is the only entry here whose saving requires no change to what the model is asked or what it produces.

Four parts, and a status line doing scheduler duty

MCP server (claude_batch_mcp.py, run by uv) exposing send_to_batch, batch_status, batch_fetch, batch_list, batch_poll_once. Doubles as a plain CLI.
Skill (skills/batchy/SKILL.md) teaching the harness when to reach for those tools — agent-skills used as the trigger layer over an MCP transport, the same split knowledge-rag and pullmd use.
Status line (statusline.sh), which renders pending/done counts in the Claude Code status bar.
Jobs registry (jobs.json) tracking submitted jobs, states and result paths.

The status line is the design argument. An asynchronous job needs something to notice it finished, and the obvious answer is a daemon. The README refuses that outright: "The status line is the only moving part — no daemons, no background services, no launchd/systemd." Instead, every assistant message triggers statusline.sh, which renders instantly from jobs.json and forks a poll only when jobs are pending and the cache is over 60s old. Its own table claims the poll never blocks the bar, never runs while you are idle, spawns no extra process, and makes zero API calls with nothing pending. So the harness's own message loop is repurposed as a scheduler. Nothing is measured, but the mechanism is legible from the script.

Two backends, one of them half-wired

send_to_batch defaults to backend: "auto" — Anthropic if ANTHROPIC_API_KEY is set, else Vertex AI if all three of VERTEX_PROJECT / VERTEX_LOCATION / VERTEX_GCS_BUCKET are. Both give the same 50% discount. But the README states the gap plainly: the background poller only polls Anthropic, because Vertex needs Google credentials that a curl+jq script cannot carry, so Vertex jobs update only when you run /batchy check. The multi-backend claim is real for submission and not for noticing. The Vertex path uses GCS rather than BigQuery, and says why: no table schema for a one-prompt-at-a-time workload.

What six months of drift did to it

The cost table quotes Claude Opus 4 at $15/$75 standard and $7.50/$37.50 batched, and Sonnet 4 at $3/$15. Against Anthropic's current card (claude-message-batches-api) that is two generations behind: Opus 5 batches at $2.50/$12.50, a third of what this README calls the discounted price, and the Opus 4 row it quotes now applies only to retired models on cloud resellers. CLAUDE_MODEL still defaults to claude-opus-4-6. The 50% ratio holds — that is the durable claim, and it is the vendor's — but every absolute number on the page is wrong in the buyer's favour in one direction and against it in another: the discount is smaller in dollars than advertised because the base price fell.

There is also a naming scar worth recording: the skill was /batch until Claude Code shipped a built-in /batch with different semantics, so it was renamed /batchy, with re-running install.sh migrating existing installs. A third-party command namespace colliding with the vendor's own is the agent-skills trigger-slot scarcity problem showing up in slash commands rather than descriptions (compare attention-is-all-you-have, which measures the same crowding on auto-trigger).

What the installer touches

The installer prints a manifest and asks before touching anything, and uninstall.sh preserves results unless you pass --purge-data. It writes the API key to ~/.claude/env at mode 600, adds a claude-batch entry under mcpServers in ~/.claude.json, and sets statusLine in ~/.claude/settings.json — a write the README flags itself: "This overwrites any existing statusLine." A full manual-install path is documented for people who won't run the script. A declared manifest, a reversible uninstall and a named destructive edit add up to more disclosure than most installers in this corpus offer; compare ai-marketing-claude's curl | bash.

Tier and what's missing

T1 as a primary artifact; the efficacy claims are structural rather than measured. Nothing here is evaluated: no comparison of batched output against a real-time run of the same prompt, no figure for how often a job actually lands under an hour against the 24-hour ceiling, and no accounting of what the 24-hour expiry costs a session that was waiting on the answer. The README also never mentions that batched requests get best-effort caching only — the finding on claude-message-batches-api — which matters here more than for a generic batch user, because Claude Code's whole cost profile rests on a stable cached prefix.

claude-code · agent-skills · model-context-protocol · s2-stream-store · tokenmining · headroom · pxpipe · ponytail · knowledge-rag · anthropic-agent-sdk-billing-pause · claude-message-batches-api