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

Most of what an AI coding supplier does for maine isn't thinking. It's I/O.

Reading 5 files to reply a mobility astir 1 method. Generating a trial record that follows the nonstop aforesaid shape arsenic the 20 trial files adjacent to it. Updating docs aft a meeting. Thousands of tokens gone and almost zero reasoning. The spot licence isn't what hurts, it's the tokens. And you're feeding each of it to a frontier exemplary that's wildly overqualified. What if you could way the grunt activity to thing cheaper that handles it conscionable arsenic well, and prevention the costly exemplary for the problems that really request it?

It’s hardly conscionable my problem. By 2028, AI coding costs are expected to rustle past the mean developer's salary. A 4th of engineering leaders already pain $200–$500 per developer per period connected tokens. Some are good past $2,000. The tooling pays for itself but only if you extremity burning frontier tokens connected activity that doesn't request them.

Turns out, the hole didn't require a level squad aliases a caller subscription. Just 2 modes. 

Two modes, zero code

This is precisely the benignant of usage lawsuit AiKA Modes successful Portal by Spotify were built for. A mode is simply a declarative supplier that runs connected an ephemeral runtime - deliberation AWS Lambda, but for agents. You specify the instructions, prime a model, group parameters for illustration temperature, and connect MCP tools. Portal handles the rest. No infra to manage, nary API keys, nary long-running servers. Modes are callable from the Portal CLI aliases API. They tin beryllium nationalist (shared pinch the full company) aliases private.

For this router to activity I created 2 modes. Both usage Gemini 2.5 Flash arsenic the worker exemplary successful the examples below, but the exemplary section accepts immoderate exemplary you person configured successful your Portal instance. Pick whichever useful for you.

Mode 1: bulk-reader

For erstwhile Claude would different publication aggregate ample files conscionable to reply 1 question.

name: bulk-reader description: Bulk record scholar for codification study - delegates I/O from Claude Code instructions: You are a precise codification analyst. Read the provided files and reply the mobility concisely. Output system bullets only. No greetings, nary prose, nary preambles. Lead each slug pinch the nonstop name, type, aliases statement number. Use nested bullets for details. Skip thing the caller did not inquire for. visibility: public model: gemini-2.5-flash resourceLimits:   temperature: 0.2 tags:   - coding   - delegation

Mode 2: code-writer

For tests, config scaffolding, type stubs aliases thing wherever the output is predictable from existing patterns.

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

That "output only the code" instruction matters. Without it, the exemplary wraps everything successful markdown fences and explanatory prose that Claude past has to parse through.

Routing

The first type of this was a artifact of routing rules successful CLAUDE.md. It benignant of worked: Claude would publication the instructions and self-route to Portal. But it had problems. The rules were advisory, not enforced. Claude could disregard them. And each task needed its ain transcript of the instructions.

The existent type is simply a Claude Code plugin called shunt. Delegation goes done the Portal CLI actions registry truthful the plugin useful against immoderate Portal lawsuit pinch AiKA plugin enabled.

Layer 1: Hooks

Claude Code hooks occurrence earlier each instrumentality call. Shunt registers 2 PreToolUse hooks:

check-file-size fires connected each Read call. If the record exceeds a configurable statement period (default: 350), the hook blocks the publication and tells Claude to usage the /bulk-reader accomplishment instead. Targeted sounds walk done - Claude already knows what conception it needs.

check-bash-read catches cat, head, tail, less, and much connected ample files. Piped commands (cat record | grep) walk done since those are targeted reads.

The period is configurable via the SHUNT_MIN_LINES situation variable. Set it successful your ammunition floor plan aliases successful .claude/settings.json:

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

Layer 2: Scripts

I person 2 bash scripts that wrap the Portal CLI calls. Claude calls a book pinch named arguments. The scripts grip everything internally: building the request, invoking the actions, unwrapping errors, and reporting token usage to stderr.

Modes are addressed by sanction and resolved by Portal: case-insensitively, preferring your ain mode, past your team's, past nationalist ones. Fork the nationalist bulk-reader into a customized type and yours automatically takes precedence - nary configuration needed.

bulk-read wraps each record successful XML tags for clear boundaries and sends them to the bulk-reader mode on pinch the question.

bulk-read --question "What does this work do?" --paths src/Service.java src/Handler.java # Follow-up: inquire again pinch the aforesaid paths bulk-read --question "Which methods telephone the database?" --paths src/Service.java src/Handler.java

Every delegation is 1 shot. The invocation is ephemeral (nothing is stored server-side) and re-sending the files connected a follow-up is free wherever it matters, because the corpus goes to the worker exemplary and ne'er enters Claude's context.

code-write sends a spec and a reference record to the code-writer mode, strips markdown fences from the output, and tin constitute straight to disk. Claude ne'er sees the generated code. The reference is required: without a record to lucifer patterns against, the worker would make context-free codification that fits thing successful your project.

code-write --spec "Write tests for UserService" --reference tests/OrderTest.java --target tests/UserTest.java # Output to stdout code-write --spec "Generate a config stub" --reference config/existing.yaml

Layer 3: Skills

Two accomplishment files show Claude when and how to telephone the scripts. Skills are markdown files pinch a explanation and usage examples. When the hook blocks a read, the artifact connection points Claude to the /bulk-reader skill, which shows the nonstop invocation syntax.

This layering intends the strategy degrades gracefully. Even if Claude doesn't publication the accomplishment description, the hook still blocks the costly read. The accomplishment conscionable makes the redirect smoother.

The benchmarks

Tested against a Java monorepo crossed 4 scenarios, measuring tokens Claude would devour reference files straight vs. consuming the bulk-reader's summary aliases penning codification via the code-writer. Mean bulk-read savings were astir a whopping 90%.

The code-write script is harder to measurement successful tokens because without shunt, Claude some sounds the reference files and generates the output arsenic costly output tokens. With shunt, the codification goes consecutive to disk, Claude ne'er sees it.

What doesn't work

You can't delegate editing. The worker model's summaries don't see reliable statement numbers. If Claude needs to make edits based connected the analysis, it still has to publication the circumstantial conception directly. The hooks let targeted sounds (with offset/limit) for precisely this reason, truthful delegation saves tokens connected understanding.

You can't delegate reasoning. The worker exemplary recovered surface-level patterns but missed a subtle thread-safety bug successful my testing. Claude spotted it successful seconds erstwhile fixed the correct context. The routing explicitly excludes debugging, architectural decisions, and safety-critical code.

Latency adds up. Each delegation is simply a web round-trip: Claude Code to the Portal backend to the worker exemplary and back. Responses typically return 10–30 seconds, and Portal caps a azygous invocation astatine 30 seconds, truthful very ample generations request to beryllium divided into smaller calls. This is acceptable for ample reads, but counterproductive for mini ones. The statement period exists for this reason, beneath it the overhead of delegation exceeds the savings.

Token savings are conscionable the starting point

The plugin is simply a Claude Code artifact, but the thought underneath is exemplary routing powered by AiKA modes. The modes are the load-bearing piece:

• They're reusable. The aforesaid bulk-reader and code-writer modes activity crossed each task and each instrumentality that tin ammunition retired to the Portal CLI.

• They're shareable. Both modes are nationalist successful AiKA. Anyone tin usage them coming without creating their own.

• They're composable. You could create a doc-writer mode for documentation, a reviewer mode for codification reappraisal summaries, a translator mode for i18n. Each 1 is simply a fewer clicks away.

• They decouple the routing determination from the worker. The plugin decides when to delegate. The mode decides how to respond. Swap Gemini Flash for a cheaper model, alteration the strategy prompt, adhd MCP devices - the plugin doesn't change.

This is the existent powerfulness of AiKA modes: they move exemplary routing from a systems engineering problem into a configuration problem. You don't build infrastructure. You picture what you want and sanction it.

Try it yourself

1. Install some plugins from the spotify/portal-ai-plugins marketplace: 

   1. claude plugin marketplace adhd spotify/portal-ai-plugins

   2. claude plugin instal portal@portal 

   3. claude plugin instal shunt@portal. 

The portal plugin provides the Portal CLI that shunt delegates through. 

1. In a caller Claude Code session, tally /portal:setup to group up and authenticate the Portal CLI against your Portal instance.

2. You’re bully to go, conscionable inquire a mobility that spans aggregate files.

The bulk-reader and code-writer modes are already public, truthful location is thing to create. If you want to customize them - different worker model, different instructions - fork them successful Portal and your type takes precedence automatically.

The modes are reusable crossed projects and shareable pinch your team. The plugin enforces the routing truthful you don't person to deliberation astir it. Learn much astir modes.