shunt-muse: offload big file reads to Muse Spark

# 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](https://github.com/spotify/portal-ai-plugins/tree/main/plugins/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

```sh
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`:

```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