Skip to content

SYSTEM Cited by 1 source

shunt (Claude Code plugin)

shunt is a Claude Code plugin (open-sourced by Spotify under spotify/portal-ai-plugins) that enforces model routing for a coding agent: it intercepts expensive I/O tool calls and redirects them to cheaper Portal AiKA Modes instead of letting them run against the frontier model. Delegation goes through the Portal CLI actions registry, so shunt works against any Portal instance with the AiKA plugin enabled (Source: sources/2026-09-03-spotify-portal-by-spotify-cut-my-claude-code-token-usage-by-90).

An earlier version was just a block of routing rules in CLAUDE.md, but those rules were advisory (Claude could ignore them) and had to be copied per project. shunt makes the routing enforced and centrally installed.

The three layers

shunt is a canonical instance of layered graceful-degradation enforcement: each layer works even if the layer above is skipped.

  1. Hooks (enforcement). Two PreToolUse hooks fire before every tool call:
  2. check-file-size — on every Read; if the file exceeds a configurable line threshold (default 350, SHUNT_MIN_LINES), the hook blocks the read and tells Claude to use the /bulk-reader skill. Targeted reads pass through (Claude already knows the section it needs).
  3. check-bash-read — catches cat, head, tail, less, more on large files. Piped commands (cat file | grep) pass through as targeted reads.
  4. Threshold is configurable via SHUNT_MIN_LINES in the shell profile or .claude/settings.json.
  5. Scripts (mechanism). Two bash wrappers around the Portal CLI:
  6. bulk-read --question ... --paths ... — wraps each file in XML tags for clear boundaries and sends them with the question to the bulk-reader mode. Re-sending the same paths on a follow-up is free where it matters: the corpus goes to the worker, never into Claude's context.
  7. code-write --spec ... --reference ... --target ... — sends a spec + a required reference file to the code-writer mode, strips markdown fences, and can write straight to disk. The reference is required so the worker matches project patterns instead of generating context-free code.
  8. Both report token usage to stderr and unwrap errors internally.
  9. Skills (guidance). Two markdown skill files tell Claude when and how to call the scripts. When a hook blocks a read, its message points Claude at the /bulk-reader skill, which shows the exact invocation syntax. The skill only makes the redirect smoother — the hook already enforces it.

What it deliberately does not route

shunt encodes the I/O-vs-reasoning boundary directly:

  • No delegated editing — worker summaries lack reliable line numbers, so edits still need Claude to read the specific section (hooks allow targeted offset/limit reads for exactly this).
  • No delegated reasoning — debugging, architectural decisions, and safety-critical code stay on the frontier model (the worker missed a subtle thread-safety bug Claude caught).
  • Latency floor — each delegation is a 10–30s round-trip (Portal caps a single invocation at 30s), so the line threshold prevents delegating small reads where overhead would exceed savings.

Seen in

Last updated · 766 distilled / 2,225 read