Claude Code plugin that shunts work saving 82-94% of tokens

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.

Three layers, from hard gate to soft suggestion:

1. Hooks block Claude from reading large files and redirect to the bulk-reader skill
2. Scripts handle the AiKA invocation and output cleanup
3. Skills tell Claude when and how to call the scripts

Claude never assembles bash pipelines from prose. It calls a script with named arguments. The scripts handle everything internally.

Delegation 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.

• jq — brew install jq
• The portal plugin from this marketplace, which provides the Portal CLI that shunt delegates through:

claude plugin install portal@portal

Then, in a new session, set up and authenticate the CLI against your Portal instance:

/portal:setup

shunt 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.

Check whether the two AiKA modes (bulk-reader and code-writer) already exist on your instance — many instances ship them as public modes:

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

If 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):

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 }
}'

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 }
}'

A 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.

shunt/
├── .claude-plugin/
│   └── plugin.json          # Plugin manifest (name, description, version)
├── hooks/
│   ├── hooks.json           # Hook registration (PreToolUse matchers)
│   ├── check-file-size      # Blocks Read on files > 350 lines
│   └── check-bash-read      # Blocks cat/head/tail on large files
├── scripts/
│   ├── lib/
│   │   └── aika.sh          # Shared aika:invoke-chat plumbing
│   ├── bulk-read            # Invokes the bulk-reader mode
│   └── code-write           # Invokes the code-writer mode
├── skills/
│   ├── bulk-reader/
│   │   └── SKILL.md         # When/how to call bulk-read
│   └── code-writer/
│       └── SKILL.md         # When/how to call code-write
└── evals/
    ├── run.sh                # Runs hook + transport evals (50 tests)
    ├── hook-evals.json       # Read hook test cases (17)
    ├── bash-hook-evals.json  # Bash hook test cases (17)
    ├── transport-evals.sh    # scripts/lib/aika.sh against a stubbed CLI (16)
    ├── evals.json            # End-to-end skill test cases (3)
    ├── benchmarks.json       # Token savings scenarios (4)
    └── fixtures/             # Test fixture files

Delegates file reading to AiKA. Files are wrapped in XML tags (<file path="...">) for clear boundaries.

bulk-read --question "What does this service do?" --paths src/Service.java src/Handler.java

bulk-read --question "Which methods call the database?" --paths src/Service.java src/Handler.java

Delegates 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.

code-write --spec "Write tests for UserService" --reference tests/OrderTest.java --target tests/UserTest.java

code-write --spec "Now add edge case tests" --reference tests/UserTest.java --target tests/UserEdgeCases.java

code-write --spec "Generate a config stub" --reference config/existing.yaml

aika:invoke-chat is ephemeral: nothing is stored server-side, and the action's own follow-up mechanism is for the caller to replay prior turns. Replaying a file corpus is the exact cost this plugin exists to avoid, so shunt does not do it — every call stands alone. Re-sending files is free where it matters, because the corpus goes to the worker model and never enters Claude's context.

Fires 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:

• Targeted reads (offset or limit set)
• Files under the threshold
• Nonexistent files (let Read handle the error)

Fires on every Bash tool call. Catches cat, head, tail, less, more on large files. Allows through:

• Piped commands (cat file | grep ) — targeted reads
• Redirections (cat file > out ) — not reading into context
• Commands with flags that indicate targeted reads
• Non-read commands (git status ,grep , etc.)

All settings are environment variables — add them to the env block in .claude/settings.json.

The plugin is designed to know when NOT to delegate:

• Debugging — requires Claude's reasoning, not a summary
• Editing — Claude needs exact content in context; use targeted reads (offset/limit)
• Small files — delegation overhead exceeds savings under 350 lines
• Architectural decisions — judgment calls stay on Claude

bash evals/run.sh

bash evals/run.sh --benchmark

Tested against a 162K-line Java monorepo:

Mean bulk-read savings: 90%

• 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.
• Request size —aika:invoke-chat input is passed on the command line, so a request must fit inARG_MAX (1 MB on macOS, shared with the environment; Linux additionally caps a single argument at 128 KiB). shunt refuses anything overSHUNT_MAX_PAYLOAD_BYTES with a clear error rather than failing withE2BIG . Split into smaller batches.
• 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.