shunt-muse

Keep big files out of your coding agent's context. When Claude Code or Codex tries to read a large file in full, a hook stops it and points it at a skill that hands the files to a cheaper model (Muse Spark via muse exec). Only the short answer comes back into the session.

This is a fork of Spotify's shunt. The original delegates to AiKA modes on a Spotify Portal instance. If you don't have Portal, this version does the same thing with the Muse CLI you already have installed.

What it does

• Hooks (PreToolUse) block a full Read, or a bare cat/head/tail/less/more, of any file over 350 lines. Reads with an offset or limit, piped commands and small files go through untouched.
• bulk-read sends one or more files plus a question to Muse and prints the answer.
• code-write sends a spec plus a reference file to Muse and writes the generated file (tests, config, stubs).
• Skills (bulk-reader, code-writer) tell the agent when to call the scripts.

Every call is one shot. A follow-up question sends the files again, which costs nothing in your agent's context because they never enter it.

Numbers

One run on a 617-line test file: about 4,800 tokens went to Muse and roughly 300 came back, in 24 seconds at low effort. At the default high, a 1,055-line file took about 20 seconds and every cited line number was exact (xhigh gave the same answer in about 32 seconds). Spotify reports 82-94% savings with the original plugin on a 162K-line Java monorepo; I haven't reproduced that here.

Requirements

• Muse Code (muse) with muse exec working headless
• jq and perl (both ship with macOS)
• Claude Code with plugin support, and/or Codex CLI with hooks enabled

Install in Claude Code

claude plugin marketplace add alexanderradahl/shunt-muse
claude plugin install shunt-muse@muse-shunt

Start a new session. The skills show up as shunt-muse:bulk-reader and shunt-muse:code-writer.

Install in Codex

Clone the repo somewhere stable, then add the Bash hook to ~/.codex/hooks.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|shell|exec_command|local_shell",
        "hooks": [
          { "type": "command", "command": "/path/to/shunt-muse/plugins/shunt-muse/hooks/check-bash-read", "timeou