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

Dimitri Mazmanov · article · 2026-09-03 source ↗ Reader 🖥️

Agent Harness AI Unit Economics Claude Code Context Engineering Delegated Editing & Document Corruption Hooks Model Routing Token Efficiency

Because most of what a coding agent does is I/O rather than reasoning, routing that I/O-bound work (bulk file reads, pattern-following boilerplate generation) to a cheap worker model — and enforcing that routing deterministically via harness-level hooks rather than relying on advisory instructions the model can ignore — cuts Claude Code's token spend by around 90% on the delegated work while reserving the frontier model for editing, debugging, and anything safety-critical.

practical · mixed — A personal engineering report structured as a how-to: it opens with a narrative problem statement, argues a general thesis (I/O work should be routed off the frontier model), documents a concrete mechanism (Portal AiKA Modes + a three-layer Claude Code plugin called shunt), cites benchmark evidence, and closes with install instructions. The propositions are ultimately in service of 'you should route I/O work to a cheap worker model and enforce it with hooks,' not a claim about what is true in general.

Structure

Part	Role
Opening problem framing: 'most of what an AI coding agent does isn't thinking, it's I/O,' plus industry cost trend data (Gartner 2028 projection, $200-2000/dev/month survey figures).	motivation and stakes
Two modes defined: bulk-reader (read + answer concisely) and code-writer (generate code matching existing patterns, output-only), both declarative Portal AiKA Modes running on Gemini 2.5 Flash.	solution definition
Routing architecture: Layer 1 (PreToolUse hooks that block large reads/cats), Layer 2 (bash scripts wrapping the Portal CLI), Layer 3 (skill files telling Claude when/how to call the scripts) — replacing an earlier, advisory CLAUDE.md-based version.	mechanism / evidence for how enforcement actually works
Benchmark section: four scenarios on a Java monorepo, ~90% mean token savings on bulk-read; code-write savings harder to quantify but qualitatively described.	evidence
'What doesn't work': can't delegate editing (no reliable line numbers), can't delegate reasoning (missed a thread-safety bug), latency adds up (10-30s round trip, 30s cap).	scope boundary / qualification
Generalization: modes are reusable, shareable, composable, and decouple the routing decision (plugin) from the response (mode) — reframed as 'model routing turned from a systems engineering problem into a configuration problem.'	conclusion / broader claim
Try-it-yourself install steps (marketplace plugin install, /portal:setup).	call to action

Key terms

I/O
Coding-agent work whose token cost is dominated by moving and restating text through the model rather than by any decision the model makes — reading files to answer a question, generating boilerplate that follows an existing pattern, updating docs. The category the author claims is safe to hand to a cheaper model.
Mode (AiKA Mode)
A declarative agent definition in Portal by Spotify — instructions, model, parameters like temperature, and attached MCP tools — that runs on an ephemeral, serverless-like runtime and is callable by name from the Portal CLI or API, with no infrastructure or API-key management.
Worker model
The cheaper model (Gemini 2.5 Flash in the author's examples, but configurable) that a Mode actually runs on, doing the delegated I/O work in place of the orchestrating frontier model (Claude).
shunt
The Claude Code plugin (hooks + scripts + skills) that enforces routing of I/O-heavy work to Portal modes, replacing an earlier CLAUDE.md-based advisory version.
Delegation Delegated Editing & Document Corruption
Routing an entire sub-task's execution (reading a set of files and answering about them; generating a file from a spec and reference) to the worker model such that the corpus or generated code never enters Claude's own context — Claude sees only the compact result.

Propositions

explicitMost of what an AI coding agent does for the author isn't thinking — it's I/O: reading multiple files to answer a question about one method, generating boilerplate that follows an existing pattern, updating docs.conf: high
explicitAI coding costs are trending toward exceeding the average developer's salary by 2028 (per a cited Gartner prediction), and a quarter of engineering leaders already spend $200-500 per developer per month on tokens, with some past $2,000.conf: high
explicitA Portal 'Mode' is a declarative agent — instructions, model choice, parameters like temperature, attached MCP tools — that runs on an ephemeral runtime requiring no infrastructure, API keys, or long-running servers, and is callable by name from the Portal CLI/API as public or private.conf: high
explicitDelegating I/O-heavy work (bulk file reads via the bulk-reader mode) to a cheaper worker model (Gemini 2.5 Flash in the author's setup) cut token usage by a mean of around 90% in benchmark testing.conf: high
extendsThe Pulse: a new trend, smart model routing · p2 — Reports a much higher (~90%) savings figure than the 20-30% vendor-claimed general routing savings cited there, but for a narrower, precisely-defined delegation category (I/O-heavy bulk reads and boilerplate) rather than general-purpose per-request model routing.
explicitAn earlier, advisory version of the routing logic — a block of rules in CLAUDE.md instructing Claude to self-route to Portal — worked only partially: Claude could ignore the rules, and every project needed its own copy of them.conf: high
supportsAlex Wang's Post · p7 — A concrete instance of the general claim: an advisory routing rule in CLAUDE.md proved ignorable, which is what motivated moving enforcement into a hook.
explicitPreToolUse hooks that deterministically block Read calls above a configurable line threshold (default 350) and equivalent bash reads (cat/head/tail/less/more on large files) enforce delegation to the bulk-reader mode regardless of whether Claude reads or follows written routing instructions.conf: high
supportsWhen Guardrails Go Wrong · p7 — Recounts, first-hand, exactly the failure mode that proposition names: an advisory, harness/prompt-level routing policy (in CLAUDE.md) that Claude could simply ignore, which is why it was replaced with an enforced PreToolUse hook.
explicitEditing cannot be delegated: the worker model's summaries don't include reliable line numbers, so if Claude needs to make an edit based on the analysis it still has to read the specific section directly.conf: high
explicitReasoning cannot be delegated: the worker model found only surface-level patterns and missed a subtle thread-safety bug that Claude caught in seconds once given the right context, so debugging, architectural decisions, and safety-critical code are explicitly excluded from the routing.conf: high
refinesGitHub - Doorman11991/smallcode: AI coding agent optimized for small LLMs. 87% benchmark with 4B-active model. · p15 — Cuts against the optimistic edge of that claim (that most agentic 'reasoning' in coding is bounded navigation/format/decomposition doable by small models): here the worker model was given a genuine reasoning task without smallcode's heavier scaffolding and missed a subtle thread-safety bug, which is why the piece explicitly excludes reasoning and debugging from delegation rather than trying to scaffold a small model into handling them.
explicitEach delegation is a network round trip (Claude Code to the Portal backend to the worker model and back) typically taking 10-30 seconds, with Portal capping a single invocation at 30 seconds, making delegation counterproductive for reads below the configured line threshold.conf: high
explicitDelegated reads are cheap to repeat because each invocation is ephemeral and stateless (nothing stored server-side) and the underlying file corpus goes to the worker model and never enters Claude's own context — so re-sending the same files on a follow-up question doesn't cost against Claude's context budget.conf: high
explicitThe value of AiKA modes lies in the router/harness layer (mode definitions plus hooks, scripts, and skills), not in the specific worker model chosen — modes are reusable across projects, shareable across a company, composable into new roles (doc-writer, reviewer, translator), and decouple the routing decision (the plugin's job) from the response (the mode's job).conf: high
supportsGitHub - musistudio/claude-code-router: Use Claude Code as the foundation for coding infrastructure, allowing you to decide how to interact with the model while enjoying updates from Anthropic. · p11 — Another instance of the 'harness, not model, is the durable value' thesis: Portal's mode/hook/script/skill stack is reusable and shareable while the worker model itself is an interchangeable parameter ('pick whichever works for you').
implicitThe router/harness layer, not the choice of worker model, is what makes the pattern reusable, shareable, and composable across projects and teams.conf: medium
implicitThe frontier model doing routine I/O work is 'wildly overqualified' for that work — there is a large capability-cost mismatch when the most expensive model in the stack performs routine reads and boilerplate generation.conf: medium
supportsThe Pulse: a new trend, smart model routing · p8 — Independently arrives at the same diagnosis — that frontier models are routinely used on work that doesn't require them — from one practitioner's own Claude Code usage rather than from an industry-wide survey.
implicitThe token/cost problem in AI coding agents is primarily a task-classification and enforcement problem (correctly deciding what's I/O vs. reasoning, and making that decision stick against a model that can ignore instructions) rather than a raw model-capability or model-cost problem.conf: medium
explicitModes resolved by name with 'own > team > public' precedence let an individual or team override a shared default (e.g. forking bulk-reader) without any central coordination or configuration change on the caller's side.conf: high

Arguments

Coding-agent token spend can be cut by roughly 90% on I/O-heavy tasks without sacrificing output quality where it matters. strength: medium

Explicit premises:

Reading files to answer a question and generating pattern-following boilerplate are I/O tasks, not reasoning tasks.
A cheaper worker model (Gemini 2.5 Flash) given a tightly scoped, output-only prompt can perform these I/O tasks adequately.
Benchmarking across four scenarios on a Java monorepo showed a mean ~90% token savings on the bulk-read scenario.

Implicit premises:

The four benchmark scenarios and the one Java monorepo generalize to other codebases and task mixes.
The worker model's output being 'adequate' was judged by the author's own inspection rather than an independent or blinded evaluation.

Inferences:

Teams with high per-seat token spend and an I/O-heavy mix of Claude Code usage should see comparable savings from a similar routing setup — though the piece never establishes what fraction of a typical coding session is genuinely I/O-bound versus reasoning-bound, so the achievable session-level (not per-delegated-task) savings remain unestablished.

Routing decisions must be enforced by the harness (deterministic hooks), not left to the model to self-apply from written instructions. strength: high