Claude Fleet Traffic Shaper

August 10, 2026 · View on GitHub

Priority-aware traffic shaping for a fleet of concurrent Claude Code sessions.

Status: specification and prior-art research. No implementation yet.

The problem

Run six to eight Claude Code sessions in parallel against one account and they behave like six to eight independent greedy clients. Each one asks for everything it wants the moment it wants it. Nothing in the system knows the other seven exist.

Most of the time this is fine. At random intervals the aggregate offered load crosses an account-level ceiling and something gives — 429 rate_limit_error, or more often 529 overloaded_error — and the session that eats it is whichever one happened to be mid-request. That is uncorrelated with what the operator cares about. The session in the foreground, the one being watched, is exactly as likely to stall as the background documentation sweep that nobody would miss for ten minutes.

The sessions do recover on their own after a few seconds, without intervention. So this is not an outage. It is a scheduling failure: the pain is distributed at random instead of being distributed on purpose.

The idea

Put a load balancer's brain in front of the fleet. One local process, the only thing in the system with a global view, that:

knows every session and what it is for,
assigns each one a priority — manually, or automatically from the repo and the opening prompt,
and shapes the aggregate to fit under the ceiling, spending the slack on the high-priority sessions first.

The design goal is that low-priority work gets slower, and nothing fails. Below a concurrency threshold the shaper does nothing at all; above it, it degrades in stages, and at every stage the visible effect on a deprioritised session is latency, not an error.

Does this already exist?

No — but two adjacent halves of it do, and one project is close enough to be worth trialling before writing a line of code. Full landscape with dates, stars and licences in docs/prior-art.md. Short version:

Category	Examples	Why it isn't this
Route around the limit	teamclaude, maxpool, neurolink, sub2api	Rotates across multiple accounts. Needs accounts you don't have; doesn't arbitrate.
Send less	ClaudeSlim (repo now 404)	Compresses payloads. Orthogonal — helps quota, not concurrency.
Batch task queues	claude-queue, CrowdControl, overstory	Priorities exist, but over headless tasks they launch. Cannot touch a session you already have open.
General LLM gateways	LiteLLM, Kong AI Gateway, Envoy AI Gateway	Have the primitives (priority queue, token buckets, tiered quotas). Know nothing about Claude Code sessions, and WFQ is still an open feature request.
Closest match	HiveMind	Transparent proxy with admission control, AIMD backpressure and a priority queue. But priority attaches to tasks submitted through its MCP interface, not to sessions arriving through the proxy. 3★, early.

The gap is specific and small: nothing binds a priority to an interactive Claude Code session and schedules between sessions on that basis. Everything else needed already exists in one project or another.

Anthropic hasn't shipped it either — maxConcurrentRequests and maxParallelAgents are open feature requests (#68502, #15487), with a cluster of bug reports describing exactly this failure mode.

What the client already gives you for free

Before building anything, note that Claude Code 2.1.226 already ships per-session concurrency caps — CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS, CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY — and an ANTHROPIC_CUSTOM_HEADERS hook that is the natural way to tag a session's traffic. These were read out of the shipped binary, not the docs. See docs/claude-code-client-surface.md.

Capping subagent fan-out per session is a one-line mitigation that addresses a real share of the problem with no proxy at all. Try it first.

Layout

docs/
  spec.md                        the design — architecture, priority model,
                                 degradation ladder, the constraints that shape it
  prior-art.md                   what exists, verified 2026-08-10
  claude-code-client-surface.md  env vars and headers extracted from the binary

Licence

MIT.