How to reduce tokens in Claude Code with hooks and Spotify Portal

Claude Code
, , , , , ,
1

Spotify demonstrated a concrete way to reduce token usage in Claude Code: block large reads with hooks and delegate predictable work to Portal modes.

The striking figure is the 90% savings that Spotify reports in its own benchmark. It’s worth reading carefully: it’s a Spotify measurement on a Java monorepo, not a universal guarantee. The more durable idea is different: if a code agent spends tokens from a powerful model reading enormous files or generating predictable code, it’s not enough to ask it to be disciplined. You can move that decision to the edge of your tools.

In that pattern, Claude Code keeps the reasoning, debugging, editing, and delicate decisions. Portal handles massive reads and routine generation through AiKA modes backed by cheaper working models.

How does Spotify reduce tokens in Claude Code?

Spotify reduces tokens in Claude Code with a plugin called shunt, which intercepts large reads, blocks them, and tells Claude to use scripts backed by Portal.

The pattern has three pieces:

  • Hooks that decide when Claude Code shouldn’t read something directly.
  • Scripts that invoke AiKA modes in Portal with defined arguments.
  • Skills that explain to Claude when and how to use those scripts.

The difference from a rule written in CLAUDE.md matters. A text instruction is a recommendation. Claude can follow it, forget it, or work around it. A PreToolUse hook, on the other hand, runs before the tool call and can stop the expensive operation before the context reaches the main model.

The useful move is simple: don’t use the strongest model to discover which part of five giant files matters. Use a worker to do the first read, get a structured summary, and let Claude inspect afterward the specific lines that actually need judgment.

What is Spotify’s Portal?

Spotify’s Portal is Spotify’s managed developer portal, built on Backstage, with AI capabilities like AiKA modes for specialized assistants.

In Portal’s documentation, a mode is a declarative agent configuration. It can define instructions, visibility, model, MCP tools, resource limits, and processors like planning, verification, confidence scoring, and context handling.

That matters because the worker in this pattern is not just “another prompt”. It’s a reusable mode that an organization can share, invoke from Portal, and move to another configured model without rewriting the Claude Code plugin.

Spotify uses two modes as examples:

  • bulk-reader, to read multiple large files and return concise findings.
  • code-writer, to produce predictable code like tests, type stubs, or configuration scaffolding from a reference.

In the published example, Spotify uses Gemini 2.5 Flash as the cheap model for those modes. The documentation also makes clear that the model can change based on what’s configured in the Portal instance. That’s the point: the expensive model doesn’t have to be the default destination for every task just because it’s handling the session.

How does the shunt plugin for Claude Code work?

The shunt plugin works by registering Claude Code hooks that block large reads and redirect Claude toward specialized scripts.

According to the README linked by Spotify’s article, shunt registers two read-oriented hooks:

  • check-file-size, which runs on Read calls and blocks complete reads above a line threshold.
  • check-bash-read, which detects large reads done with commands like cat, head, tail, less, and more.

The default threshold is 350 lines. Reads with offset or limit pass through, because if Claude asks for a specific section, it probably already knows what it needs. Reads with pipes like cat file | grep also pass through because they’re scoped queries, not raw context dumps.

The threshold can be adjusted with SHUNT_MIN_LINES in .claude/settings.json:

{
  "env": {
    "SHUNT_MIN_LINES": "500"
  }
}

That detail shows why this is more than prompt hygiene. Claude can still read code. It can still inspect exact sections. What the hook blocks is the expensive pattern: dumping a whole large file into the main model “just in case”.

How do you install Spotify’s Portal in Claude Code?

At the time of publishing this note, September 6, 2026, Spotify shows an installation from the spotify/portal-ai-plugins marketplace and then a Portal configuration within a new Claude Code session.

The commands published by Spotify are:

claude plugin marketplace add spotify/portal-ai-plugins
claude plugin install portal@portal
claude plugin install shunt@portal

Then, in a new Claude Code session:

/portal:setup

The portal plugin provides the Portal CLI that shunt uses to delegate work. The shunt README also lists jq as a requirement and shows brew install jq for macOS.

The relevant repositories are:

There’s a practical warning: packaging moves fast. On September 6, 2026, the install commands point to the spotify/portal-ai-plugins marketplace, while the shunt detail linked from the article lives in the add-shunt-claude branch of a fork. That doesn’t invalidate the pattern, but it does mean you should check the repo status before treating these commands as frozen documentation for production.

What tasks are worth delegating outside Claude Code?

It’s worth delegating large reads, scoped summaries, and predictable generation; it’s not worth delegating subtle debugging, direct editing, or architecture decisions.

Spotify says it pretty clearly. The cheap worker can summarize surface patterns, but in their tests it missed a subtle thread-safety bug. Claude found it quickly when it received the right context.

That’s the line worth preserving.

Delegation works well when the task is mostly I/O or routine generation:

  • Read large files and answer a specific question.
  • Generate tests following a reference file.
  • Produce a configuration stub from a known pattern.
  • Summarize code structure before Claude inspects a specific section.

Delegation becomes risky when the task depends on judgment:

  • Debug a race condition.
  • Edit code with exact line context.
  • Decide an architectural tradeoff.
  • Review sensitive security behavior.
  • Determine whether an invariant really holds.

The rule isn’t “always use the cheap model”. The rule is more useful: use the cheap model when errors are cheap, scoped, and recoverable; keep the strong model when errors get expensive.

What does this have to do with Claude Code’s price?

It has to do with Claude Code’s price because the real cost of a session doesn’t depend only on the plan, but on how many tokens you send to the strong model and how often you repeat context.

OpenSEO showed that claude code price does have measurable demand in Spanish: 880 monthly searches in Spain, 390 in Mexico, 210 in Argentina, 170 in Chile, and 320 in Colombia. I’m not using that phrase as a title because this isn’t a pricing guide. But it does confirm that the cost angle exists in several Iberoamerican markets.

The mature way to answer that concern isn’t to promise magical savings. It’s to explain where the spending goes.In a long session, Claude Code can read files, receive tool results, retain context, use cache, and execute subflows. If every large exploration enters the main model, costs grow even when the final task is small. The Spotify pattern reduces that waste before it happens: it blocks large reads and routes the initial exploration to Portal.

That turns cost into a workflow property, not a surprise at the end of the day.

How much can this pattern save?

Spotify reports average savings close to 90% in bulk-read scenarios, with individual cases ranging between 82% and 94%.

Those numbers come from the benchmark published in the shunt README, on a 162,000-line Java monorepo. Scenarios include a large file, a source-and-test pair, and a multi-file read across services. The code-writing case is harder to compare because with shunt, generated code can go straight to disk and never enter Claude’s context.

Treat the benchmark as self-reported. Still, the mechanism makes sense: if Claude receives a compact summary instead of thousands of lines, it consumes fewer tokens. The exact savings will depend on your repository, file sizes, prompts, worker model, re-read frequency, and summary quality.

There’s also a latency tradeoff. Spotify mentions typical response times between 10 and 30 seconds, and Portal CLI action invocation has a 30-second limit. That time cost may be worth it for large files. For small files, probably not.

That’s why the default threshold is 350 lines.

Why are hooks better than prompts for saving tokens?

Hooks are better than prompts for saving tokens because they enforce policy before the expensive call happens.

A prompt can say: “use the cheap worker for large reads.” That helps, but it depends on the agent following the instruction in that moment. A hook changes the environment. When Claude tries to read a large file in full, the hook blocks it and shows the expected path.

This connects to a broader trend in Claude Code: teams are moving operational policies out of prose and into the runtime. We already saw a related piece on yoDEV in Claude Code now lets you control model changes with hooks. Model choice, tool access, cache, and token spend are starting to be workflow decisions, not personal preferences inside a chat.

The Spotify pattern adds a practical example: you can apply a delegation route to cheap models without building a complete internal routing platform from scratch.

How does it differ from other token-reduction tools?

It differs because it routes work away from Claude before creating the expensive context.

That sets it apart from other similar approaches. Agentmemory reduces repeated context by saving and retrieving relevant memory. Turo reduces prompt size by compressing language before it reaches the model. Repomix packages the repository so a model can ingest it more neatly.

The Spotify pattern tackles different waste: full reads and predictable generation that don’t need to go through the main model.

Token efficiency isn’t a single trick. It’s a stack:

  • Don’t resend old context if memory can retrieve the relevant part.
  • Don’t send long prose if a compressed instruction works.
  • Don’t paste the entire repository if a structured package works better.
  • Don’t use a strong model for bulk exploration if a cheap worker can do the first pass.

Portal fits the last point.

Should your team copy this pattern?

Your team should copy this pattern if Claude Code sessions spend many tokens reading large files, generating boilerplate, or exploring monorepos before doing the real work.

Don’t copy it blindly.

Start at the frontier, not the benchmark. A reasonable first version would be to delegate only full reads of large files, allow bounded reads, and keep debugging, editing, and delicate decisions in Claude. Then measure whether the summaries are good enough and whether the added latency is worth it.

For individual developers, this can stretch your token budget without changing every prompt. For teams, the signal is stronger: platform can turn AI cost into an operable policy.

That’s the big part of Spotify’s post.

The future of cost control in code agents probably won’t be a single cheaper model. It’ll be routing: strong models for reasoning, worker models for bulk work, local tools for deterministic steps, and hooks to decide where the boundary is.

Spotify’s version is early, opinionated, and tied to Portal. But the underlying idea is portable.

Don’t ask the agent to be frugal.

Design the workflow so wasted reads never reach the expensive model.

Gloo Code vs Claude Code: cuánto cambia pagar por asiento en vez de mirar tokens