{"slug": "claude-code-plugin-that-shunts-work-saving-82-94-of-tokens", "title": "Claude Code plugin that shunts work saving 82-94% of tokens", "summary": "A new Claude Code plugin called shunt redirects I/O-heavy work to AiKA modes, saving 82-94% of tokens on large file reads and boilerplate generation. The plugin uses hooks, scripts, and skills to delegate tasks through the Portal CLI actions registry, requiring the portal plugin and jq. It includes two AiKA modes, bulk-reader and code-writer, which can be created if not present.", "body_md": "A Claude Code plugin that shunts I/O-heavy work to AiKA modes, saving 82-94% of tokens on large file reads and boilerplate generation.\n\nThree layers, from hard gate to soft suggestion:\n\n1. **Hooks** block Claude from reading large files and redirect to the bulk-reader skill\n2. **Scripts** handle the AiKA invocation and output cleanup\n3. **Skills** tell Claude when and how to call the scripts\n\nClaude never assembles bash pipelines from prose. It calls a script with named arguments. The scripts handle everything internally.\n\nDelegation goes through the Portal CLI actions registry — one `aika:invoke-chat` call per delegation — so the plugin works against any Portal instance with AiKA enabled. Modes are addressed by name and resolved server-side: case-insensitive, preferring your own mode, then your groups', then public ones; a name matching nothing or several modes equally fails with the candidate ids.\n\n- [`jq`](https://jqlang.org) —` brew install jq`\n- The **portal** plugin from this marketplace, which provides the Portal CLI that shunt delegates through:\n\n```\nclaude plugin install portal@portal\n```\n\nThen, in a new session, set up and authenticate the CLI against your Portal instance:\n\n```\n/portal:setup\n```\n\nshunt sets `PORTAL_CLI_ENABLE_EXPERIMENTAL` for its own calls (the actions registry is experimental in portal-cli 0.4.x); you only need it exported for the manual `portal-cli` commands below.\n\nCheck whether the two AiKA modes (`bulk-reader` and `code-writer`) already exist on your instance — many instances ship them as public modes:\n\n```\nportal-cli actions aika:list-modes --json --input '{\"search\": \"bulk-reader\"}'\n```\n\nIf they exist, no mode creation is needed — just install the plugin and go. If not, or to create your own customized versions (e.g. different model or instructions):\n\n```\nportal-cli actions aika:create-mode --input '{\n  \"name\": \"bulk-reader\",\n  \"description\": \"Bulk file reader for code analysis\",\n  \"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.\",\n  \"tags\": [\"coding\", \"delegation\"],\n  \"resource_limits\": { \"temperature\": 0.2 }\n}'\n\nportal-cli actions aika:create-mode --input '{\n  \"name\": \"code-writer\",\n  \"description\": \"Boilerplate code generator\",\n  \"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.\",\n  \"tags\": [\"coding\", \"delegation\"],\n  \"resource_limits\": { \"temperature\": 0.2 }\n}'\n```\n\nA mode you create is private and owned by you, and name resolution prefers your own modes — so your customized `bulk-reader` automatically shadows the public one, no configuration needed.\n\n```\nshunt/\n├── .claude-plugin/\n│   └── plugin.json          # Plugin manifest (name, description, version)\n├── hooks/\n│   ├── hooks.json           # Hook registration (PreToolUse matchers)\n│   ├── check-file-size      # Blocks Read on files > 350 lines\n│   └── check-bash-read      # Blocks cat/head/tail on large files\n├── scripts/\n│   ├── lib/\n│   │   └── aika.sh          # Shared aika:invoke-chat plumbing\n│   ├── bulk-read            # Invokes the bulk-reader mode\n│   └── code-write           # Invokes the code-writer mode\n├── skills/\n│   ├── bulk-reader/\n│   │   └── SKILL.md         # When/how to call bulk-read\n│   └── code-writer/\n│       └── SKILL.md         # When/how to call code-write\n└── evals/\n    ├── run.sh                # Runs hook + transport evals (50 tests)\n    ├── hook-evals.json       # Read hook test cases (17)\n    ├── bash-hook-evals.json  # Bash hook test cases (17)\n    ├── transport-evals.sh    # scripts/lib/aika.sh against a stubbed CLI (16)\n    ├── evals.json            # End-to-end skill test cases (3)\n    ├── benchmarks.json       # Token savings scenarios (4)\n    └── fixtures/             # Test fixture files\n```\n\nDelegates file reading to AiKA. Files are wrapped in XML tags (`<file path=\"...\">`) for clear boundaries.\n\n```\nbulk-read --question \"What does this service do?\" --paths src/Service.java src/Handler.java\n\n# Follow-up: ask again with the same paths\nbulk-read --question \"Which methods call the database?\" --paths src/Service.java src/Handler.java\n```\n\nDelegates boilerplate generation to AiKA. Strips markdown fences from output. Can write directly to disk via `--target`. `--reference` is required — without a file to match patterns against, the worker would generate context-free code that fits nothing in the project.\n\n```\n# Generate and write to file\ncode-write --spec \"Write tests for UserService\" --reference tests/OrderTest.java --target tests/UserTest.java\n\n# Build on what was just generated by referencing it\ncode-write --spec \"Now add edge case tests\" --reference tests/UserTest.java --target tests/UserEdgeCases.java\n\n# Output to stdout\ncode-write --spec \"Generate a config stub\" --reference config/existing.yaml\n```\n\n`aika:invoke-chat` is ephemeral: nothing is stored server-side, and the action's own follow-up\nmechanism is for the caller to replay prior turns. Replaying a file corpus is the exact cost this\nplugin exists to avoid, so shunt does not do it — every call stands alone. Re-sending files is\nfree where it matters, because the corpus goes to the worker model and never enters Claude's\ncontext.\n\nFires on every `Read` tool call. Blocks full-file reads on files exceeding `MIN_LINES` (default: 350, configurable via `SHUNT_MIN_LINES` env var). Allows through:\n\n- Targeted reads (offset or limit set)\n- Files under the threshold\n- Nonexistent files (let Read handle the error)\n\nFires on every `Bash` tool call. Catches `cat`, `head`, `tail`, `less`, `more` on large files. Allows through:\n\n- Piped commands (`cat file | grep` ) — targeted reads\n- Redirections (`cat file > out` ) — not reading into context\n- Commands with flags that indicate targeted reads\n- Non-read commands (`git status` ,`grep` , etc.)\n\nAll settings are environment variables — add them to the `env` block in `.claude/settings.json`.\n\n| Variable | Default | Purpose | \n|---|---|---|\n| `SHUNT_MIN_LINES` | `350` | Line count above which the Read hook blocks and redirects | \n| `SHUNT_PORTAL_INSTANCE` | CLI default | Portal instance name or URL to invoke against | \n| `PORTAL_CLI_BIN` | `portal-cli` , else`npx` | Override how portal-cli is launched | \n| `SHUNT_MAX_PAYLOAD_BYTES` | `400000` (`120000` on Linux) | Request ceiling, since input travels through argv | \n| `SHUNT_BULK_READER_MODE_ID` | — | Pin a specific mode id if the name is ambiguous | \n| `SHUNT_CODE_WRITER_MODE_ID` | — | Pin a specific mode id if the name is ambiguous | \n\nThe plugin is designed to know when NOT to delegate:\n\n- **Debugging** — requires Claude's reasoning, not a summary\n- **Editing** — Claude needs exact content in context; use targeted reads (offset/limit)\n- **Small files** — delegation overhead exceeds savings under 350 lines\n- **Architectural decisions** — judgment calls stay on Claude\n\n```\n# Hook routing + transport plumbing — needs no Portal access\nbash evals/run.sh\n\n# Also re-measure token savings against the real modes — needs portal-cli auth\nbash evals/run.sh --benchmark\n```\n\nTested against a 162K-line Java monorepo:\n\n| Scenario | Lines | Without shunt | With shunt | Savings | \n|---|---|---|---|---|\n| Single large file (SpotifyUri.java) | 4,014 | 33,684 tokens | 5,737 tokens | 82% | \n| Source + test pair (PromotionRuleRepository) | 7,408 | 75,990 tokens | 4,148 tokens | 94% | \n| Multi-file cross-service (permission handlers) | 1,281 | 16,221 tokens | 821 tokens | 94% | \n| Code-write (generate tests from reference) | 3,667 | 40,614 tokens + generation | 833 lines to disk | - | \n\nMean bulk-read savings: **90%**\n\n- **No enforcement for code-writer** — only bulk-reader has hook enforcement. Code-writer relies on Claude recognizing when to use it via the skill description.\n- **Request size** —`aika:invoke-chat` input is passed on the command line, so a request must fit in`ARG_MAX` (1 MB on macOS, shared with the environment; Linux additionally caps a single argument at 128 KiB). shunt refuses anything over`SHUNT_MAX_PAYLOAD_BYTES` with a clear error rather than failing with`E2BIG` . Split into smaller batches.\n- **30-second invocation cap** — portal-cli aborts an action invocation after 30s and does not expose a timeout flag. Large generations can exceed it; split the spec into smaller calls.", "url": "https://wpnews.pro/news/claude-code-plugin-that-shunts-work-saving-82-94-of-tokens", "canonical_source": "https://github.com/sorantis/portal-ai-plugins/tree/add-shunt-claude/plugins/shunt", "published_at": "2026-09-07 14:13:18+00:00", "updated_at": "2026-09-07 14:27:44.012840+00:00", "lang": "en", "topics": ["developer-tools", "ai-tools", "ai-agents"], "entities": ["Claude Code", "AiKA", "Portal CLI", "jq"], "alternates": {"html": "https://wpnews.pro/news/claude-code-plugin-that-shunts-work-saving-82-94-of-tokens", "markdown": "https://wpnews.pro/news/claude-code-plugin-that-shunts-work-saving-82-94-of-tokens.md", "text": "https://wpnews.pro/news/claude-code-plugin-that-shunts-work-saving-82-94-of-tokens.txt", "jsonld": "https://wpnews.pro/news/claude-code-plugin-that-shunts-work-saving-82-94-of-tokens.jsonld"}}