Portal by Spotify cut my Claude Code token usage by 90%

What happened

A Spotify principal product manager published a post on September 3, 2026, showing how he reduced his Claude Code token consumption by 90 percent by routing I/O-heavy work through Portal by Spotify, Spotify's internal developer platform built on Backstage. The approach requires no new infrastructure, no dedicated platform team, and no long-running servers — just two declarative agent configurations and a Claude Code plugin called shunt.

This piece explains the mechanism behind the routing, how the two AiKA modes are configured, and what the shunt plugin's three-layer enforcement architecture actually does. It is written for engineers who use Claude Code daily and are starting to feel the cost of feeding a frontier model thousands of tokens of work it is overqualified to handle.

Dimitri Mazmanov, writing on the Spotify Engineering blog, described a token-routing pattern he built using AiKA Modes inside Portal by Spotify. The core observation is that most of what Claude Code does during a typical session is I/O: reading several large files to answer a question about one method, generating test files that follow existing patterns, updating documentation. None of that work requires frontier-model reasoning. By offloading those tasks to Gemini 2.5 Flash running inside two Portal modes — bulk-reader and code-writer — Mazmanov measured mean token savings of around 90 percent on bulk file reads across four scenarios tested against a Java monorepo.

How it works

Gartner data cited in the post adds urgency to the finding. By 2028, AI coding costs are projected to surpass the average developer's salary. A quarter of engineering leaders already spend between $200 and $500 per developer per month on tokens, and some report bills exceeding $2,000 per developer per month. Mazmanov's framing is that the seat license for Claude Code is not the painful number — the token bill is, and most of those tokens are being consumed by work that a cheaper model handles just as well.

Portal by Spotify treats an AiKA Mode as a declarative agent that runs on an ephemeral runtime, comparable to AWS Lambda for agents. Each mode definition specifies a name, visibility, a model, a temperature, tags, and a system prompt. Both modes in this setup use Gemini 2.5 Flash at temperature 0.2. The bulk-reader mode instructs the worker model to output structured bullets only, with no prose or greetings, leading every bullet with an exact name, type, or line number. The code-writer mode tells the worker to match existing conventions exactly and output only code, with no markdown fences or explanations.

Why it matters

Routing enforcement happens in three layers. The shunt Claude Code plugin registers two PreToolUse hooks that fire before every tool call. The check-file-size hook intercepts every Read call and blocks it if the file exceeds a configurable line threshold — the default is 350 lines, configurable via the SHUNT_MIN_LINES environment variable. The check-bash-read hook catches cat, head, tail, less, and more on large files, while allowing piped commands such as cat file | grep to pass through because those are already targeted reads. Two bash scripts, bulk-read and code-write, handle the actual Portal CLI invocations, wrapping files in XML tags for clear boundaries and stripping markdown fences from output before writing results to disk. A pair of Claude Code skill files tell Claude when and how to call the scripts, but the hooks enforce the redirect even if Claude ignores the skill description.

The 90 percent reduction is significant not because of the percentage itself but because of what it reveals about frontier model usage patterns. Claude Code, when left unrouted, reads entire large files to answer questions that require only a fraction of that context. It also generates code output as expensive output tokens rather than delegating generation to a cheaper model and writing the result directly to disk. The shunt plugin restructures both of those patterns: Claude never sees the contents of files above the line threshold, and it never sees generated code that went straight to disk via code-write.

The modes are reusable across every project that can shell out to the Portal CLI, and both bulk-reader and code-writer are already public in AiKA, so any engineer with access to a Portal instance can use them without creating their own mode definitions. Delegation is also one-shot and ephemeral: nothing is stored server-side, so re-sending the same files for a follow-up question does not accumulate state on the Portal backend, and the file contents never enter Claude's context window regardless of how many times they are sent to the worker.

Who is affected

Engineers who use Claude Code against large codebases — particularly monorepos with many files above 350 lines — are the direct beneficiaries. The Java monorepo Mazmanov tested against is a realistic proxy for the kind of codebase that generates the highest token bills. Teams where multiple developers share a Claude Code subscription will see per-seat savings compound, and the engineering leaders Gartner reports spending $2,000 or more per developer per month are exactly the population for whom this routing pattern pays back quickly.

There are real constraints. Delegation does not work for editing tasks because the worker model's summaries do not include reliable line numbers. If Claude needs to make changes based on what the worker found, it still has to read the specific section directly via a targeted read, which the hooks allow. Debugging, architectural decisions, and safety-critical code are explicitly excluded from the routing rules in the skill files. And each delegation adds a network round-trip — responses take 10 to 30 seconds, and Portal caps a single mode invocation at 30 seconds, so very large generations need to be split into smaller calls.

What to watch next

The shunt plugin and both modes are available in the spotify/portal-ai-plugins GitHub repository. Installation requires three commands against a Portal instance with the AiKA plugin enabled: adding the marketplace, installing the portal plugin, and installing shunt. After running /portal:setup in a Claude Code session to authenticate against a Portal instance, the routing activates automatically. Engineers who want to customize the worker — different model, different system prompt, additional MCP tools — can fork either public mode in Portal, and the forked version takes precedence automatically without any change to the plugin configuration.

The broader question the post raises is how far the declarative mode pattern extends. Mazmanov notes that a doc-writer mode, a reviewer mode for code-review summaries, and a translator mode for internationalization are all straightforward additions, each requiring only a mode definition and a skill file. The separation of concerns — the plugin decides when to delegate, the mode decides how to respond — means adding a new delegation type does not require touching the routing logic. Whether that composability holds at scale, and how the 10-to-30-second per-delegation latency accumulates across a full working session, are the two questions worth tracking as more teams adopt the pattern.