bullswarm

bullswarm brings the quota meters of every coding-agent CLI on your machine into Claude Code and, when Claude spawns a subagent, hands the job to whichever of those CLIs has the most unspent subscription quota instead of running it as a Claude subagent. Where quota-meter watches your own Claude windows, bullswarm watches all of them: Claude Code, Codex, Grok, OpenCode, Command Code, or several accounts of one.

It is the Claude Mod half of the bullswarm CLI. That CLI sends one coding task, or a graph of dependent tasks, to whichever installed agent CLI has surplus quota, and judges the result by what was written rather than by the exit code. The mod is its read-only view inside Claude Code plus the routing of Claude’s own subagents.

What it does

• Routes Agent calls. A general-purpose, Explore or Plan subagent goes out through bullswarm run on the analyze lane, read-only and in one attempt, to the pool with the most surplus, and Claude gets the verified output back as the tool result with a routing note.
• Annotates Bash results. When Claude itself runs bullswarm run or bullswarm workflow goal, the verdict is appended to the tool result in plain words, with the run’s checked answer when it had one. A workflow watch or workflow wait result gets a note when the run is waiting at a gate or a loop is out of rounds.
• The strip above the prompt: a header line (runs, dispatches in flight, route off when routing is off) with a [w] button for the pane, then one row per ongoing workflow run and one per standalone dispatch. A digit in front of a row opens that run from an empty prompt. The strip option picks runs (default), full (pool meter rows too) or off.
• The runs pane, docked beside the transcript: the run overview, a step page per workflow step or standalone task with an overview and detail toggle (the latest turns, the full turn-and-tool transcript, the result, task facts and cost rows), and a usage page with every meter window of every pool as a bar with reset time and pace, plus the model rungs per lane or provider. Read-only, with a compact layout under 20 rows.
• /bullswarm with pools, runs, pane, open <step> [run], on, off, refresh and routed. Bare /bullswarm <task> still belongs to the CLI’s packaged skill. A tool, mcp__bullswarm__route, lets the model flip the same routing switch when you ask it to.
• Pool display names. An account pool such as claude-code:acme shows as claude-code:a; a label set with bullswarm pools label or the poolAliases option in /config overrides it.

Install

Needs Claude Code 2.1.287 or later (the README names no minimum of its own), plus the bullswarm CLI on PATH (Node.js 22.12 or later) and at least one agent CLI besides Claude Code for routing to have anywhere to go.

npm i -g bullswarm
bullswarm setup

bullswarm setup detects your installed agent CLIs, shows their quota state and writes the routing configuration. Then the mod:

claude plugin marketplace add Bulls-Work/bullswarm
claude plugin install bullswarm@bullswarm

The CLI’s own route, bullswarm integrate install --agents claude --yes, links the mod folder into ~/.claude/skills/ instead, where it auto-loads as bullswarm@skills-dir. Use one or the other: an installed marketplace copy wins over the link, and Claude Code says so at startup. The strip appears once the CLI reports at least one pool. /bullswarm prints the pools and the routing state, [w] or /bullswarm pane opens the pane, and /bullswarm off keeps every subagent in-session.

How it works

The mod makes no network calls of its own and never reads another CLI’s files. Every figure comes from the bullswarm CLI as a child process through $.process.run: bullswarm pools --json for the meters, workflow runs --json and assignments --json for the runs and the in-flight ledger, and the workflow tui, runs show and action show readers while the pane is open. It re-reads every 2 minutes, every 20 seconds while something is in flight.

prompt.context appends a block named bullswarm to the turn: each pool’s surplus, whether routing is on, how many calls were routed, and one line per ongoing run (id, status, progress, the steps running, the goal cut at 80 characters). It is a handful of lines and only changes when a pool moves by a bucket or a run starts or ends; the author gives no token figure. It is skipped when the CLI reports no pools, and when BULLSWARM_DEPTH is set, which marks a Claude session that is itself a bullswarm delegate.

Routing happens in tool.call on Agent, not by swapping models: engine.create only adds $.bullswarm, an API other plugins can call. A general-purpose, Explore or Plan subagent type maps to the analyze lane, which is read-only; any other type stays in-session. So does a call without a text prompt, a forked, background or isolated agent, and any call while no enabled, unquarantined pool other than claude-code exists. When a call qualifies, the mod runs bullswarm run --lane analyze --add-dir <cwd> --json --no-retry --timeout 540 --prompt <prompt> and waits: one attempt, because the process budget of $.process.run holds one, and a failed run already falls back to a subagent. Until 28 September 2026 a general-purpose subagent went to the build lane and could write files; that is gone. If the verdict is ok and names an output file, the mod reads it with $.fs.read and returns it as the Agent tool’s completed result: agent type bullswarm:<pool>, the delegate’s model, wall time and token counts as the CLI measured them, plus a context line telling Claude the call was routed, to judge the output as evidence, and what the worker left not done. ok: false, an unreadable file or a CLI error fall through to the normal Claude subagent, with a notice on the tool call saying why.

The Bash hook reads the command text of every Bash call to match bullswarm run, bullswarm workflow goal, workflow watch and workflow wait; other commands pass untouched. A matching command runs normally, then the mod parses the JSON verdict from its stdout and appends a note: for run, read the output file because a clean exit code is not proof, or inspect a failure without retrying blindly, with the checked answer when the run had an answer schema; for workflow goal, that the run is detached and bullswarm workflow watch <id> --until trouble follows it, or which gate it parked at and the continue command that moves it.

/bullswarm on and off, and the mcp__bullswarm__route tool, flip a switch persisted in $.store under bullswarm.autoRoute, the only thing the mod stores. multi-core also brings other providers into a Claude Code session, by a different route.

Limitations

• No minimum Claude Code version is declared and this site has not run it. The plugin has stayed at version 0.1.0 through 25 commits since 17 September 2026 while the CLI moved from 0.32 to 0.38; a marketplace install picks up changes only with claude plugin update.
• Routed subagents are read-only. A task that needs a file written stays with Claude, or runs through the CLI’s own bullswarm run on the build lane.
• The CLI’s content gate wants 80 or more characters of substance, so a delegate that answers in one short line is rejected and the call falls back to an in-session subagent: you spend the delegate’s quota and then Claude’s.
• By default the strip shows runs, not meters. Set strip to full for the pool rows in the band, or read them in the pane.
• Terminal only. The strip and pane draw nothing on the mobile surface.