Spotify Portal AiKA Modes Cut Claude Code Token Usage by 90% with Cheap Model Delegation

Takeaway

Spotify’s Portal AiKA Modes enable Claude Code to off‑load large file reads and boilerplate generation to a cheap model (Gemini 2.5 Flash), cutting Claude’s token usage by roughly 90 % while keeping the same workflow.

---

Why token costs matter for AI‑assisted coding

• Input tokens (reading source files) dominate the cost of AI coding agents because they are far more frequent than output tokens.
• Gartner predicts that by 2028 AI‑coding token spend will exceed the average developer salary, with many teams already spending $200–$500 per developer per month, and some over $2,000.
• Reducing token consumption without sacrificing functionality is therefore a critical cost‑saving measure.

---

The core idea: model routing with AiKA Modes

• AiKA Modes are declarative agents that run on an ephemeral runtime (similar to AWS Lambda) and can be invoked via the Portal CLI or API.
• A mode bundles:
  • A system prompt (instructions)
  • A chosen model (any model configured in Portal)
  • Runtime parameters such as temperature
  • Optional MCP tools
• Modes are public (shareable across the company) or private (team‑specific) and require no infrastructure or API‑key management.

---

Two concrete modes used for token savings

1. bulk-reader

• Purpose – Summarize the contents of many large files so Claude can answer a question without reading each file directly.
• Key instruction – Output only structured bullets, no prose or markdown fences.
• Model – Gemini 2.5 Flash (any model can be swapped).

name: bulk-reader
description: Bulk file reader for code analysis - delegates I/O from Claude Code
instructions: |
  You are a precise code analyst. Read the provided files and answer the question concisely.
  Output structured bullets only. No greetings, no prose, no preambles.
  Lead every bullet with the exact name, type, or line number.
  Use nested bullets for details. Skip anything the caller did not ask for.
visibility: public
model: gemini-2.5-flash
resourceLimits:
  temperature: 0.2
tags:
  - coding
  - delegation

2. code-writer

• Purpose – Generate boilerplate code (tests, config stubs, type stubs) that follows existing project patterns.
• Key instruction – Output only the code; do not wrap in markdown fences.
• Model – Gemini 2.5 Flash (replaceable).

name: code-writer
description: Boilerplate code generator - delegates output‑heavy work from Claude Code
instructions: |
  You generate code files based on a spec and reference files. Match the existing patterns,
  conventions, naming, and style exactly. Output only the code — no explanations, no markdown fences unless asked.
  If the spec is ambiguous, make reasonable choices that match the reference code's patterns.
visibility: public
model: gemini-2.5-flash
resourceLimits:
  temperature: 0.2
tags:
  - coding
  - delegation

---

How routing is enforced: the shunt plugin

1. Pre‑tool hooks – shunt registers two PreToolUse hooks in Claude Code.
   • check-file-size blocks any Read call whose file exceeds a configurable line threshold (default 350). The hook returns a message directing Claude to the /bulk-reader skill.
   • check-bash-read blocks cat, head, tail, less, more on large files, while allowing targeted pipelines (e.g., cat file | grep).
2. Shell wrappers – Two Bash scripts (bulk-read and code-write) invoke the Portal CLI, passing arguments, handling errors, and reporting token usage.
   • bulk-read --question "…" --paths src/Service.java src/Handler.java
   • code-write --spec "Write tests for UserService" --reference tests/OrderTest.java --target tests/UserTest.java
3. Skill files – Markdown skill definitions give Claude the exact CLI syntax to call when a hook blocks a read.
   • The skill description is optional; the hook already prevents the expensive read.

---

Measured token savings

• Scenario – Java monorepo, four typical coding tasks (bulk file queries, test generation, config scaffolding, type‑stub creation).
• Result – Direct Claude reads consumed ~10× more input tokens than the bulk‑reader summary. The average token reduction was ≈ 90 % for bulk reads.
• Code‑writer – Savings are harder to quantify because Claude would have consumed both input (reference files) and output tokens. With shunt, the generated code never enters Claude’s context, eliminating those output tokens entirely.

---

Limitations and trade‑offs

• No editing delegation – Summaries lack reliable line numbers, so Claude must still read the original file for precise edits.
• No reasoning delegation – Complex bug‑finding or architectural decisions remain with Claude; cheap models may miss subtle issues (e.g., a thread‑safety bug).
• Latency – Each delegation adds a 10–30 s round‑trip (Claude → Portal → worker model → Claude). Portal caps calls at 30 s, so very large generations need to be split, making delegation unsuitable for tiny reads.
• Cost accounting – Token savings are measured only for Claude’s usage; the cheap model still incurs its own token cost, though it is dramatically lower per request.

---

Reusability and extensibility of AiKA Modes

• Reusable – The same bulk-reader and code-writer modes can be invoked from any project or tool that can call the Portal CLI.
• Shareable – Modes are public in the AiKA catalog; any Spotify engineer can use them without creating a new mode.
• Composable – New modes (e.g., doc-writer, reviewer, translator) can be built from the same template with a few clicks.
• Decoupled routing – The shunt plugin decides when to delegate; the mode decides how to respond. Swapping the worker model, adjusting prompts, or adding MCP tools requires only a mode edit, not a plugin change.

---

Getting started yourself

1. Install the plugins

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

2. Configure the Portal CLI – Run /portal:setup in a Claude Code session and authenticate against your Portal instance.
3. Use the modes – Ask Claude a question that spans multiple files; the shunt hooks will automatically redirect large reads to bulk-reader and boilerplate generation to code-writer.
4. Customize if needed – Fork the public modes in Portal, adjust the model or instructions, and your fork will automatically take precedence.

---

Community reactions (selected HN comments)

"It cuts token usage because they are using a different service with a different token budget for the reader/code writer tasks." – jnwatson

"Routing purely on size tells you nothing about code complexity; output tokens are far more expensive than input tokens." – ricardobeat

"The approach is essentially delegating to a cheaper model for greps and boilerplate – nothing fundamentally new, just a configuration layer." – tolugenius

"Latency of 10‑30 s per delegation can be a deal‑breaker for small tasks." – krzys

---

Bottom line

Portal’s AiKA Modes turn costly model routing into a simple declarative configuration. By delegating bulk I/O and predictable code generation to a cheap model, Spotify engineers have achieved ≈ 90 % token savings for Claude Code’s input consumption, while keeping the same developer experience. The trade‑offs—extra latency, inability to delegate editing or deep reasoning—are predictable, making the solution a practical cost‑control pattern for any organization using frontier coding agents.