# mazmanov-portal-spotify-shunt-claude-code-tokens-2026-09-03

## Veille

Engineering post from **Spotify** published on **September 3, 2026** on engineering.atspotify.com (~1,600 words, nine sections, two YAML manifests, four command-line examples), authored by **Dimitri Mazmanov**, Principal Product Manager. It describes a personal setup designed to move I/O tasks out of the context of **Claude Code**. The premise stated upfront: *« Most of what an AI coding agent does for me isn't thinking. It's I/O »* — reading five files to answer a question about a single method, producing a test modeled on the other twenty in the directory. **(A) The modes.** **Portal by Spotify** exposes *AiKA Modes*, declarative agents on an ephemeral runtime — instructions, model, temperature, **MCP** tools — compared to *« AWS Lambda, but for agents »*; two public modes, `bulk-reader` and `code-writer`, run here on **Gemini 2.5 Flash**. **(B) The routing.** A Claude Code plugin named `shunt` replaces `CLAUDE.md` rules deemed *« advisory, not enforced »* with three layers: `PreToolUse` hooks that block any read beyond **350 lines** (threshold adjustable via `SHUNT_MIN_LINES`), two bash scripts calling the Portal CLI, two skills that provide the invocation syntax. The corpus goes to the secondary model and **never enters Claude's context**. **(C) Measurements and their limits.** On a Java monorepo, four scenarios, the reported average saving is **~90%** on `bulk-read`; the author notes that the `code-write` scenario is *« harder to measure »*, and lists three limitations — non-delegable editing, non-delegable reasoning, **10 to 30 seconds** of latency per call. Extends the budget questions from [[gupta-token-budget-wars-marginal-token-utility-2026-05-28]] and the delegation examined in [[willison-fable-judgement-delegation-subagents-2026-07-03]].

## Titre Article

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

## Date

2026-09-03

## URL

https://engineering.atspotify.com/2026/9/portal-by-spotify-cut-my-claude-code-token-usage-by-90

## Keywords

Portal by Spotify, AiKA Modes, shunt, Claude Code plugin, model routing, secondary model, I/O delegation, Gemini 2.5 Flash, bulk-reader, code-writer, PreToolUse hooks, read blocking, line threshold, SHUNT_MIN_LINES, skills, Portal CLI, ephemeral runtime, declarative agent, MCP, token budget, cost per developer, output tokens, agent context, Java monorepo, delegation latency, plugin marketplace, spotify/portal-ai-plugins, Backstage, AI FinOps

## Authors

Dimitri Mazmanov (Principal Product Manager, Spotify), sur le blog d'ingénierie engineering.atspotify.com.

## Ton

**Profile**: an individual experience report published on a corporate engineering blog, in the first person, doubling as an openly acknowledged promotion of an internal product. Audience: advanced coding-agent users and internal platform owners.

**Style**: the text follows a technical-demonstration progression — quantified problem, solution, numbered-layer architecture, measurements, limitations, usage instructions. The artifacts are given in full: two complete YAML manifests, four command-line invocations, the threshold environment variable, the three installation commands. Implementation details are laid out rather than summarized, including micro-decisions and their rationale — the *« output only the code »* instruction is justified by the markdown fences Claude would otherwise have to parse, the mandatory reference file by the out-of-context code a model would produce without it.

**Epistemic position**: the title displays a quantified result, but the body bounds it itself. An entire section, *« What doesn't work »*, lists what the setup does not do: no delegated editing for lack of reliable line numbers, no delegated reasoning — a *thread-safety* bug missed by the secondary model, caught by Claude —, and a latency overhead that makes delegation counterproductive below the threshold. The measurement itself remains declarative: four scenarios on a Java monorepo, with no published protocol, no absolute volumes, no accounting for the secondary model's cost. The final section explicitly shifts the stakes from the figure to the reusability of the modes, phrased as *« they turn model routing from a systems engineering problem into a configuration problem »*.

## Pense-betes

- **The starting intuition is load-sharing, not prompt optimization.** Reading files and generating repetitive code consumes tokens without requiring reasoning; these tasks go to a cheap model, while the primary model keeps the problems that require judgment.
- **What is saved is not just the price, it is context occupancy.** The corpus that is read is sent to the secondary model and never enters Claude's window; a follow-up query on the same files therefore reloads nothing on the primary side. Same mechanism as the delegation to subagents in [[willison-fable-judgement-delegation-subagents-2026-07-03]].
- **A mode = a declarative agent**: name, description, instructions, model, `visibility`, `resourceLimits`, `tags`. Ephemeral runtime, nothing stored server-side, no API key to manage. Resolution by name, case-insensitive, with precedence personal → team → public: forking a public mode is enough to override it with no configuration.
- **The rules in `CLAUDE.md` did not hold up.** First version of the routing: a block of instructions that Claude read and sometimes followed. Two named flaws — *advisory, not enforced*, and having to be copied into each project. This is the argument that drives the move to hooks, hard gates independent of the model's decision.
- **The threshold is the central tuning parameter.** `check-file-size` blocks `Read` calls beyond 350 lines by default; `check-bash-read` intercepts `cat`, `head`, `tail`, `less`, `more`. Targeted reads (`offset`/`limit`) and piped commands pass through. Below the threshold, delegation latency costs more than it saves.
- **Graceful degradation is the architectural point.** Three layers: the hook blocks, the script executes, the skill explains. If Claude ignores the skill, the hook still blocks — the contract is not entrusted to the model.
- **Two mode instructions do most of the work.** *Output only the code* avoids markdown fences and prose that the primary model would have to re-parse; a mandatory reference file for `code-writer` avoids out-of-context code. Same framing logic as the skills described in [[shihipar-claude-code-lessons-building-skills-2026-06-03]].
- ⚠️ **The headline figure is self-reported and not reproducible as stated**: an average across four scenarios on a Java monorepo, with no protocol, no absolute volumes, no comparison to a primary model used with targeted reads. The author admits that the `code-write` scenario is harder to measure, and the cost of the secondary model is not subtracted.
- **The three claimed limitations frame the scope**: no delegated editing (summary line numbers unreliable), no delegated reasoning (debugging, architecture decisions, and critical code explicitly excluded from routing), 10 to 30 s of latency per round trip, with a 30 s Portal cap that forces large generations to be split.
- **The operational conclusion is about the modes, not the plugin**: reusable across projects, shareable (both modes are public), composable (`doc-writer`, `reviewer`, `translator` cited as possible extensions), and decoupled from routing — changing the working model does not change the plugin. This packaging/execution separation is the one formalized by [[google-agent-plugins-packaging-skills-mcp-2026-08-06]].
- **Installation**: `claude plugin marketplace add spotify/portal-ai-plugins`, then the `portal` (the CLI) and `shunt` (routing) plugins, then `/portal:setup` for authentication against a Portal instance. The setup therefore assumes a Portal instance with the AiKA plugin enabled — it is not transferable as-is outside an organization that runs it.
- **The framing figures come from outside the post and are unsourced**: AI coding costs exceeding the average developer salary by 2028, a quarter of engineering leaders at $200-500 per developer per month, some above $2,000. To be treated as an order of magnitude, worth comparing against the per-team measurements in [[patel-block-buzz-teams-tokens-benchmarks-2026-08-06]].

## RésuméDe400mots

Dimitri Mazmanov, Principal Product Manager at Spotify, published on September 3, 2026 on the company's engineering blog an account of a setup that reportedly cuts his token consumption in Claude Code by 90%. His starting observation: most of what a coding agent does for him is not reasoning but I/O — reading five files to answer a question about a method, generating a test file identical to the twenty neighboring ones. This work is sent to an overqualified frontier model, when a cheap model would handle it just as well.

The solution relies on Portal by Spotify's AiKA Modes: declarative agents run on an ephemeral runtime, defined by instructions, a model, parameters, and MCP tools, with no infrastructure or API keys to manage. The author creates two public modes running on Gemini 2.5 Flash. The first, bulk-reader, reads a batch of files and responds in structured bullet points. The second, code-writer, generates code from a specification and a reference file whose conventions it must reproduce.

Routing is handled by a Claude Code plugin called shunt, after the failure of a first version based on rules written in CLAUDE.md, which the model could ignore and which had to be copied into each project. The plugin stacks three layers. PreToolUse hooks block file reads beyond a configurable line threshold, as well as cat, head, or tail commands on large files; targeted reads pass through. Bash scripts wrap calls to the Portal CLI, build the request, and report back token usage. Skill files tell Claude when and how to call these scripts. The corpus moves to the secondary model without ever entering Claude's context, which also never sees the generated code, written directly to disk.

The measurements are presented as an average saving of about 90% across four scenarios tested against a Java monorepo, with the author acknowledging that the generation scenario is hard to measure. One section details what doesn't work: editing is not delegable for lack of reliable line numbers, nor is reasoning — the secondary model missed a thread-safety bug that Claude spotted immediately — and each delegation costs ten to thirty seconds of latency, which makes it counterproductive on small files.

The author concludes that token savings are only a starting point: the real value of the modes is turning model routing into a configuration problem rather than a systems engineering one.

## GrapheDeConnaissance

- Dimitri Mazmanov —travaille_chez→ Spotify (ORGANISATION, 0.97)
- Dimitri Mazmanov —a_créé→ shunt (TECHNOLOGIE, 0.95)
- Dimitri Mazmanov —affirme_que→ "Most of what an AI coding agent does for me isn't thinking. It's I/O" (CITATION, 0.96)
- Dimitri Mazmanov —affirme_que→ les coûts de codage IA dépasseront le salaire moyen d'un développeur d'ici 2028 (AFFIRMATION, 0.85)
- Dimitri Mazmanov —mesure→ un quart des responsables d'ingénierie dépensent 200-500 $ par développeur et par mois en tokens (MESURE, 0.82)
- Spotify —a_créé→ Portal by Spotify (TECHNOLOGIE, 0.95)
- Portal by Spotify —permet→ AiKA Modes (TECHNOLOGIE, 0.95)
- AiKA Modes —est_instance_de→ agent déclaratif sur runtime éphémère (CONCEPT, 0.92)
- AiKA Modes —utilise→ MCP (TECHNOLOGIE, 0.9)
- AiKA Modes —permet→ routage de modèles (CONCEPT, 0.93)
- routage de modèles —réduit→ consommation de tokens du modèle principal (CONCEPT, 0.92)
- shunt —fait_partie_de→ Claude Code (TECHNOLOGIE, 0.94)
- shunt —utilise→ Portal by Spotify (TECHNOLOGIE, 0.94)
- shunt —utilise→ hooks (TECHNOLOGIE, 0.95)
- shunt —remplace→ règles de routage écrites dans CLAUDE.md (CONCEPT, 0.93)
- Dimitri Mazmanov —affirme_que→ "The rules were advisory, not enforced" (CITATION, 0.93)
- hooks —permet→ blocage des lectures au-delà de 350 lignes par défaut (AFFIRMATION, 0.93)
- bulk-reader —est_instance_de→ AiKA Modes (TECHNOLOGIE, 0.94)
- code-writer —est_instance_de→ AiKA Modes (TECHNOLOGIE, 0.94)
- bulk-reader —utilise→ Gemini 2.5 Flash (TECHNOLOGIE, 0.93)
- code-writer —utilise→ Gemini 2.5 Flash (TECHNOLOGIE, 0.93)
- shunt —mesure→ économie moyenne de ~90 % de tokens sur le scénario bulk-read, monorepo Java, quatre scénarios (MESURE, 0.85)
- shunt —réduit→ occupation de la fenêtre de contexte du modèle principal (CONCEPT, 0.91)
- Dimitri Mazmanov —affirme_que→ le gain sur le scénario code-write est difficile à mesurer en tokens (AFFIRMATION, 0.9)
- routage de modèles —s_oppose_à→ délégation de l'édition de code et du raisonnement (AFFIRMATION, 0.9)
- Gemini 2.5 Flash —s_oppose_à→ détection d'un bug de thread-safety trouvé par Claude Code (AFFIRMATION, 0.86)
- shunt —mesure→ latence de 10 à 30 secondes par délégation, plafond Portal de 30 secondes (MESURE, 0.91)
- Dimitri Mazmanov —recommande→ exclure du routage le débogage, les décisions d'architecture et le code critique (AFFIRMATION, 0.93)
- Dimitri Mazmanov —affirme_que→ "They turn model routing from a systems engineering problem into a configuration problem" (CITATION, 0.93)
- spotify/portal-ai-plugins —publie→ shunt (TECHNOLOGIE, 0.92)

---
Canonical: https://www.thekb.eu/en/fiches/mazmanov-portal-spotify-shunt-claude-code-tokens-2026-09-03/