Spotify Unveils a Claude Code Delegation Strategy: Large File Reading Context Cut by ~90%

Where Did the Money Go: Claude Read Thousands of Lines Just to Find a Few

Spotify just unveiled a traffic-shunting method for Claude Code. In tests on a 162,000-line Java project, it reduced the context content entering Claude's primary model during large file reads by an average of about 90%. Many people assume paid tokens are spent entirely on AI thinking. Tokens are the basic units models use to process text, and they are also standardly used to calculate API costs. In reality, a large portion of tokens is consumed by basic hauling tasks like reading lengthy files, locating function calls, and generating boilerplate code modeled after existing files.

Picture a concrete scenario: you simply want to find out "where the SMS notification is triggered after a successful payment." You might expect the assistant to jump straight to those two or three lines and give you the answer. Instead, to piece together the full context, it might read several large files spanning thousands of lines from beginning to end. Here, Claude Code refers to an AI programming assistant capable of searching and modifying code across project files. But when it pulls thousands of lines into the conversation context (the conversation history and reference material the model can draw upon for its current response), it not only takes up context space, but the lengthy text can also continue to inflate input costs for subsequent turns in the chat.

Using a premier model for mechanical reading tasks often incurs unnecessary expenses. Industry data cited in the original article indicates that a quarter of engineering leaders face token expenditures of $200–$500 per developer each month, with some even exceeding $2,000. It must be clarified that the "roughly 90% reduction" achieved by this solution is strictly limited to an approximate 90% decrease in content entering the primary model's context across three large-file reading benchmark tests; it does not equate to a 90% drop across the entire development workflow or in total monthly billing.

Reading through long code to look up a name, or generating boilerplate by copying old patterns, is fundamentally context-consuming ground work. Addressing this drain, Spotify Principal Product Manager Dimitri Mazmanov proposed a division of labor: the main assistant delegates looking up background material or drafting repetitive files to auxiliary models, keeping only distilled key takeaways for itself to make judgments.

Offloading Two Kinds of Heavy Lifting First: Reading Files and Writing Boilerplate

Within Spotify's developer portal product, Portal, there is a capability known as AiKA Modes. Users can configure dedicated helper modes for specific tasks, assign clear task prompts, and bind corresponding lightweight helper models (such as Gemini 2.5 Flash or other smaller models). These modes are invoked on demand per request, running statelessly and discarding conversational memory across turns.

To tackle the two types of tasks that consume the most context, the solution defines two corresponding helper modes:

Large File Reading Mode (bulk-reader)

This mode is dedicated to reading through long code and extracting facts. Its prompt strictly bans pleasantries and sprawling prose summaries; every bullet must start directly with a class name, method name, or line number. (A "method," in plain terms, is a block of code that performs a specific action.) Although the prompt instructs it to be concise, it cannot guarantee that every output will be perfectly terse, cover every line, or be 100% accurate. Once the main assistant receives this summary, it can answer preliminary location questions; if precise conditional evaluation or actual code editing is required, it must still look back at the original code.

Taking the payment SMS location as an example (the following is an illustrative hypothetical walkthrough, not actual runtime output or production source code):

• Input: The local script sends the complete text of PaymentService.java (approx. 3,200 lines) and NotificationService.java (approx. 1,800 lines) to the cloud mode, accompanied by the question: "After a payment succeeds, in which method is the SMS notification triggered? Please indicate the relevant class names and method names."
• Helper mode return takeaways:
  • PaymentService.java: The processPayment() method calls NotificationService.sendPaymentReceiptSms() while processing transactions.
  • NotificationService.java: The sendPaymentReceiptSms() method is responsible for assembling and dispatching the payment receipt SMS.
• Main assistant processing: Receiving these concise facts, the main assistant can clarify call relationships and point out clues to the user without first loading 5,000 lines of code into its context; if specific trigger conditions need verification later, it can conduct targeted follow-up reads on the relevant code snippet.

Boilerplate Code Generation Mode (code-writer)

This mode is used to generate structurally repetitive boilerplate code such as unit tests. When invoked, it requires both a "specification (Spec)" and a "reference file (Reference)." The spec defines the target behavior—for example, writing an automated test that inputs "payment failed" and verifies that the system does not send a payment receipt SMS. The reference file provides an existing, mature test case from the project, demonstrating which test framework, naming conventions, and structural patterns the project standardly uses.

Because the local script does not search for other source code in the project, merely telling it what to do is insufficient; real function names and call signatures must be provided as well. The reference file and specification together supply the target interface, behavior, and styling so the model can generate matching code. However, this still does not guarantee the generated code will be correct on arrival; subsequent manual and automated testing verification remains mandatory.

Cheaper Models Aren't Enough: How to Stop Claude from Reading Head-On

Having these two helper modes ready does not mean Claude will automatically call them when encountering large files.

Initially, Dimitri tried adding guidelines in the project's instruction file CLAUDE.md, recommending that Claude "use helper modes when encountering large files." However, such documentation serves only as a soft recommendation. Claude can overlook it during execution, and actual compliance relies on the model's voluntary choice; furthermore, every project would need to maintain its own copy of the instructions.

For a shunting mechanism to work reliably, one cannot rely solely on the model's discretion. Instead, there must be a pre-execution interception when a full-file read is initiated. This is precisely the core architectural purpose of the shunting plugin shunt.

How shunt Completes a Delegation Cycle: Intercept, Guide, Deliver

When Claude attempts to read a large file, the shunting mechanism coordinates through three stages: intercept, guide, and deliver:

1. 01

   Intercept (Hook Pre-check)

   Blocks unconstrained full-file reads exceeding the line threshold before tool execution, preventing large files from flooding primary model context.

   Intercept (Hook Inspection Rule): Halting unconstrained full reads When Claude calls a read tool, a pre-execution check rule (Hook) evaluates the call before the underlying tool loads the file into context. The default interception condition is: targeting a single file, strictly exceeding 350 lines, and having no specified read range (i.e., no starting offset or line limit specified). As long as either a starting offset or a line limit parameter is provided, the rule treats it as a targeted snippet read and allows it through. The value of the Hook lies in blocking full reads before tool execution whenever conditions are met, ensuring enforcement no longer depends on voluntary compliance by the model.
2. 02

   Guide (Skill Route Instructions)

   Interception prompt directs Claude to the Skill; Claude invokes the script using parameters defined in the Skill.

   Guide (Skill Invocation Documentation): Providing a clear alternative path Once intercepted, the tool returns an error message and guidance prompt to Claude, notifying it that the file exceeds the size threshold and suggesting the large-file reading approach instead. Claude then consults the invocation instructions (Skill) packaged with the plugin, which provide script parameter formats and concrete usage examples. The role of the Skill is to provide explicit routing directions, preventing the model from thrashing or stalling after being blocked.
3. 03

   Deliver (Script Local Communication)

   Local script sends code to the helper model, then forwards the generated summary and status back to Claude to continue work.

   Deliver (Local Script): Packaging and delegating communication Claude invokes the local script (bulk-read) as instructed. The script reads the local files, marks file boundaries using explicit XML tags (<file path="...">), packages them, and dispatches them to the cloud helper mode. The helper model extracts structured facts according to its prompt instructions, and the script delivers the results back to Claude, who proceeds with analysis. The script encapsulates file packaging, boundary tagging, and network requests, allowing the main assistant to delegate simply by passing arguments. (Note that the bulk-read script does not sanitize text or filter summaries from the model's response; output terseness is governed by the helper mode's prompt. Conversely, the code generation script code-write includes logic to strip Markdown code fences.)

Mechanism Difference Reminder: In this architecture, only large-file reading is configured with a mandatory Hook interception; boilerplate code generation currently has no pre-execution interception rule. Whether Claude uses the generation script to write directly to disk depends on its own task planning and proactive decision to invoke the skill.

Where the 90% Is Saved: Reading Context Drops ~90%, Billing Is Calculated Separately

When large files are read by helper models and only distilled takeaways are returned to the main model, exactly how much context entering the primary model is saved?

Dimitri tested 4 representative development scenarios across a 162,000-line Java project:

Taking the first row, "Single Large File Analysis," as an example:

• Without shunting: Claude calls its built-in read tool, reading all 4,014 lines into the chat, consuming 33,684 tokens.
• With shunting: The helper model reads the full text in the cloud and returns distilled summary bullets to the main assistant. The main assistant receives 5,737 tokens for this turn. The source report records an 82% reduction in content entering the primary model (calculating directly from the two token counts yields approximately 82.97%). In the test file pair and cross-service analysis scenarios, the reported reduction was 94%.

The benchmark report shows an average reduction of about 90% across the three file-reading scenarios. Crucially, however: the "roughly 90% reduction" strictly refers to the decrease in content entering the main assistant's context during large file reads; it does not mean actual monthly billing in development drops by 90%.

The true cost across the entire workflow must be assessed comprehensively:

• Reduced main-model input costs: Delegating large file reads drastically cuts down the volume of text entering the main model's context. Once lengthy file contents enter a conversation, they may continue to consume context in subsequent turns, although actual costs are also influenced by prompt caching, context compression, and platform billing rules.
• Offloaded large generation costs: Writing generated boilerplate directly to disk reduces the output token overhead of having the primary model generate massive blocks of code.
• Helper model invocation charges: Cloud helper models reading thousands of lines and generating code incur bills according to their own pricing rates.
• Network transmission and latency: According to the author's observations, a single delegation call typically takes 10 to 30 seconds (encompassing network transmission and helper model processing).
• Subsequent verification and deep analysis still require the main model: Complex troubleshooting, reading critical snippets, and performing subsequent edits still consume primary model tokens.

As for the default 350-line threshold, it is an empirical heuristic chosen for engineering convenience rather than an absolute measure of code complexity; developers can tune it via the environment variable (SHUNT_MIN_LINES).

Why You Can't Outsource Everything: Editing and Debugging Still Require Claude's Own Eyes

If helper models handle long texts so effectively to save context, why not outsource every task? Returning to our payment SMS example illustrates the boundaries of helper modes:

The takeaways returned by the helper model help quickly identify the relevant methods, but if your next step is to modify the code or investigate rigorous logic—such as confirming whether the SMS is dispatched only after the debit has fully completed, or whether network retries could send duplicate messages—a brief summary cannot provide sufficient evidence for these business timing and boundary conditions.

Therefore, the reliable workflow is: have the helper model conduct initial reconnaissance to surface clues, and then have the main assistant initiate targeted reads on critical snippets (for instance, reading only the ~20 lines around the relevant method) to inspect the actual code in context before making judgments. If confirmation logic or retry mechanisms are spread across other methods, follow the clues with targeted reads. Because range parameters are included, the hook allows the read through; the main assistant inspects authentic logic without loading all 3,200 lines.

In practice, helper modes should not be relied upon directly in three situations:

1. Modifying code and validating strict conditions: Helper modes provide only location leads; when fine-tuning code, validating edge conditions, and executing edits, the primary assistant must inspect the actual source.
2. Investigating subtle bugs and complex architecture: In the author's testing, the helper model missed a subtle thread-safety bug, whereas Claude spotted it within seconds once provided with the proper context. "Thread safety," in plain terms, means that when multiple tasks access shared data concurrently, the system guarantees correct results and consistent state (in the absence of this guarantee, for instance, concurrent transactions reading and writing an unsynchronized account balance simultaneously could corrupt ledger amounts—this is a general illustrative example, as the original author did not disclose specific business code from the test). Such deep reasoning and concurrency analysis must still be handled by the primary model in this division of labor.
3. Small files with few lines: A remote call typically requires 10 to 30 seconds. For smaller files of one or two hundred lines, reading them directly incurs minimal context overhead, making the additional latency of a remote call rarely worthwhile.

How to Put It to Work: Three-Step Setup, Validating on a Small Task First

Before adopting this setup, one should understand its operational characteristics and prerequisites:

• Stateless calls and follow-up queries: AiKA modes are stateless and ephemeral; the cloud does not maintain conversational context across turns. If a developer follows up asking, "What other methods in these files interact with the database?", the script must resend the files along with the new question to the helper model, which is billed again at its rate. For boilerplate generation, if you wish to write supplementary tests based on a newly generated test case, simply pass the newly created file as the reference parameter (--reference) in the next command.
• Platform prerequisite: This solution requires that your team has adopted the Spotify Portal platform with the AiKA feature enabled. Installing the client plugin locally does not automatically supply a cloud runtime environment or model accounts.

Onboarding follows three steps, each with clear verification milestones:

1. Step 1: Environment Preparation and Plugin Authentication: Install the command-line JSON processor jq locally, and install the portal and shunt plugins in Claude Code. In a fresh session, execute /portal:setup to complete authentication. Verification milestone: The terminal displays successful login, confirming the local client has a working communication channel to the Portal platform.
2. Step 2: Confirm or Create Cloud Helper Modes: Check whether the bulk-reader and code-writer modes exist in the cloud. If not pre-configured, create them according to specification and bind appropriate models. Verification milestone: Both registered mode names can be successfully queried and listed via the command line.
3. Step 3: Minimal Task Validation and Safety Checks: To verify that interception works, attempt a full-file read without a range on a file exceeding the configured threshold (default 350 lines). Verification milestone: The read request is blocked by the Hook, displaying a guidance prompt. Claude then invokes the bulk-read script and returns bullets featuring class and method names that align with key facts in the original code. When generating boilerplate, after specifying a target path, verify that the file was written to disk, and review the generated code using version control diffs (git diff) and unit tests.

The Truly Reusable Takeaway: Decoupling "When to Shunt" from "Who Executes"

The broader value of this architecture lies in establishing a clean division of engineering responsibilities: decoupling "when to shunt" from "who executes."

• The local client plugin handles "when to shunt" and workflow orchestration: It guards the local gate, intercepting and guiding full-file reads exceeding the threshold; it also packages input, initiates communication, returns results, and writes generated code directly to local disk.
• Cloud modes handle "how to execute": They configure task prompts and model bindings, focusing entirely on fact distillation or code generation upon receiving long text.

This separation makes the local invocation interface independent of backend models: when backend models are upgraded, the local script continues communicating with the designated mode via standard commands without altering call logic. The architecture exhibits strong engineering extensibility:

1. Cross-project and cross-tool reusability: Cloud reading and generation modes are general-purpose capabilities usable across Java and other languages. Any development tool supporting the CLI or API calls can reuse these backend modes; to enable automatic interception in another tool, one only needs to adapt a pre-execution check layer using that tool's extension mechanisms.
2. Swapping models and configuration precedence: When a team rebinds models to a mode in the cloud, all callers using that mode immediately benefit without requiring individual developers to update local scripts. Mode name resolution follows a precedence hierarchy: personal modes override shared team or instance modes. However, teams must ensure name and input/output schema compatibility, and output quality should still be verified through spot checks after model switches.
3. Broader vision for mode extensions: At the end of the post, the author suggests extending this delegation pattern to other long-context scenarios. Examples include a documentation mode (doc-writer) for drafting documentation, a review mode (reviewer) for generating PR review summaries, and a translation mode (translator) for internationalization across multiple languages. (These represent exploratory concepts proposed in the author's blog, not built-in features of the current plugin.)

In software workflows, having helper models shoulder the heavy lifting of reading long files and drafting boilerplate while preserving the primary model for deep reasoning and critical decisions—paired with disciplined quality checks and cost tracking across the entire shunted pipeline—strikes a far more balanced compromise between development efficiency and token expenditure.

Developer Appendix: Complete Installation and Command Reference

(Non-technical readers may skip this section)

1. Installation and Authentication

Ensure the command-line JSON processor jq is installed locally (on macOS, install via brew install jq).

Add the official marketplace source and install the plugins in your terminal:

# Add official plugin marketplace source
claude plugin marketplace add spotify/portal-ai-plugins

# Install Portal connector tool and shunt plugin
claude plugin install portal@portal
claude plugin install shunt@portal

Once installed, launch a new Claude Code session and run the setup command to log in:

/portal:setup

2. Inspecting and Creating Helper Modes

Run the following commands to check if the corresponding modes are configured in your environment. Note that list-modes only verifies mode existence; check the supported configuration console in your instance to view the underlying bound model:

portal-cli actions aika:list-modes --json --input '{"search": "bulk-reader"}'
portal-cli actions aika:list-modes --json --input '{"search": "code-writer"}'

If not pre-configured, create them using the following commands:

# Create large-file reading mode
portal-cli actions aika:create-mode --input '{
  "name": "bulk-reader",
  "description": "Bulk file reader for code analysis",
  "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, no summaries. Lead every bullet with the exact name, type, or line number. Use nested bullets for details. Skip anything the caller did not ask for.",
  "tags": ["coding", "delegation"],
  "resource_limits": { "temperature": 0.2 }
}'

# Create boilerplate code generation mode
portal-cli actions aika:create-mode --input '{
  "name": "code-writer",
  "description": "Boilerplate code generator",
  "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 patterns in the reference code.",
  "tags": ["coding", "delegation"],
  "resource_limits": { "temperature": 0.2 }
}'

3. Script Invocation and Production Fill-in Templates

In daily interactions, the plugin is not completely hands-off: the Hook automatically detects and intercepts eligible reads, prompting Claude to invoke the script via its skill; code generation (code-writer) relies on Claude recognizing the task, without guaranteed automatic triggering. When calling manually in the terminal, replace /path/to/shunt with your local plugin's actual installation path.

Scenario 1: Large File Analysis

/path/to/shunt/scripts/bulk-read --question "What are the respective responsibilities of these two classes and how do they interact?" --paths src/Client.java src/RetryPolicy.java

Scenario 2: Boilerplate Code Generation (Production Fill-in Template)

The following is a fill-in template and cannot be run as-is; replace plugin paths, reference file paths, target file paths, and all placeholder text in the spec, preserving the surrounding quotes. The script only sends the spec and reference; it does not read target source files automatically. Together, both inputs must supply sufficient interface, behavioral, and styling contracts.

/path/to/shunt/scripts/code-write \
  --spec "[Target Language & Test Framework]: <e.g., Java / JUnit 5>
[Target Under Test & Dependencies/Mocks]: <Fill in class under test; if creating mocks, specify mock names and types; insert specific constructors or injection methods matching project architecture>
[Target Methods & Expected Logic]: <Fill in method signatures, sample inputs, and core expected outcomes>
[Exception Branches & Edge Cases]: <Fill in input conditions triggering exceptions and expected exception types>
[Assertions & Verification Criteria]: <Fill in key assertion approaches and call verification rules on mocks>" \
  --reference "/path/to/ReferenceTest.java" \
  --target "/path/to/GeneratedTest.java"

4. Developer Notes and Boundary Details

• Silent Overwrite Risk: When using code-write with --target, if the target file already exists, it will be overwritten directly without any confirmation prompt. Always specify a fresh target filename; if --target is omitted, generated code will output to stdout and enter the main model's context.
• Post-Generation Verification Flow: Never run generated code directly. We recommend following these verification steps: 1. Open the generated file in an editor to inspect logic; 2. Run git status --short to confirm the new file path; 3. Run git diff --no-index /dev/null "/path/to/GeneratedTest.java" (replacing with actual path) to review code details; 4. Execute local build and unit tests (e.g., mvn test or npm test).
• Command-Line Argument Length Limits: Arguments are passed via argv, and the script includes built-in SHUNT_MAX_PAYLOAD_BYTES protection (400,000 bytes on macOS, 120,000 bytes on Linux) to prevent operating system E2BIG (ARG_MAX) errors. If analyzing numerous files, pass them in smaller batches.
• Timeout Distinctions and Handling: The blog notes that Portal enforces a 30-second server-side limit per invocation; the current client defaults to waiting 180 seconds (SHUNT_TIMEOUT_SECONDS) and is configurable. These are two distinct limits; increasing the client timeout does not expand the server-side ceiling. Once a client timeout is confirmed, adjust accordingly or break tasks into smaller chunks.
• Limitations of Command-Line Read Inspection: check-bash-read checks commands like cat/head/tail/less/more; if a command contains a pipe | or redirection >, it is allowed through without verifying actual post-pipe volume. This is a heuristic guidance rule based on command characteristics rather than an inescapable security sandbox.
• Personal Mode Precedence Rule: Portal follows a personal precedence rule (Personal mode > Team mode > Instance public mode). If a user creates a mode with an identical name, the system prioritizes the personal version without automatically synchronizing updates from team or global public versions.
• Difference Between Reproduction Assets and Billing Logs: The TypeScript reproduction tests in the open-source repository estimate tokens by dividing character counts by 4; they are not raw Java billing logs.

References and Open-Source Repositories:

• Original Blog Post: Portal by Spotify cut my Claude Code token usage by 90%
• Official Open-Source Plugin Repository: GitHub - spotify/portal-ai-plugins (shunt directory)
• Spotify Portal Official Documentation: AiKA Modes Core Features and Plugin Configuration Guide