SMC Reader

Save My Context Reader — keep large tool outputs out of your agent's context window.

A big Bash or WebFetch output does not have to land in the model's context. SMC Reader's hook catches it before the model sees it, spills it to disk and hands the model a short pointer. The model then pulls only what it needs — exact lines, or an answer to a question.

Quick start

In Claude Code (Node.js ≥ 20 on PATH):

/plugin marketplace add bulatko/SMCReader
/plugin install smcreader@smcreader

That's it — no settings.json or --mcp-config edits. Run something noisy and the model gets this instead of 3000 lines:

[READER ctx_b4c9b23c] Bash output intercepted: 13893 bytes, 3001 lines (>2048 chars).
1
2
...
... (2989 lines omitted — in the reader) ...
2999
3000
Full output is in reader ctx_b4c9b23c: mcp__plugin_smcreader_smcreader__reader_ask(id, question) to analyze, mcp__plugin_smcreader_smcreader__reader_peek(id, start_line, end_line) for exact lines, mcp__plugin_smcreader_smcreader__reader_close(id) when done.

Why

Agents run commands whose output is mostly noise for the task at hand: test logs, build output, grep -r, git log, fetched pages. Every byte of it stays in the context for the rest of the session, pushes out what matters and makes every following turn more expensive. Truncating is not a fix — the one line the agent needs may be in the middle.

Measured on our own agent transcripts over 5 days (19–23 Oct 2026): 472 interceptions, 2.88 MB of tool output.

54% of the intercepted bytes (1.55 MB) never entered the context. On outputs of 16 KB and more the saving is about 21 KB per interception.

How it works

The main model (Opus, Fable) runs a command as usual — but the output never reaches it. SMC Reader's hook catches it on the way, saves it to disk and gives the model a short note instead: what was caught and how to read it. When the model needs something, it asks a cheap model (Haiku) with reader_ask; Haiku reads the whole output and returns only the lines that answer the question, verbatim. Exact lines by number (reader_peek) come straight from disk, with no model at all.

Under the hood:

1. Claude Code runs a tool and passes the result to the PostToolUse command hook.
2. If the output is large (≥ 2048 chars by default), the hook writes it to ~/.cache/smcreader/ctx_<id>.txt and replaces it with a pointer in the same shape as the original output — the engine silently ignores a replacement of a different shape.
3. The model sees the pointer: id, size, head and tail of the output.
4. It pulls what it needs through the smcreader MCP server:

The hook and the MCP server are separate processes sharing one directory; the directory is the source of truth (open-document limit, LRU eviction, 48 h expiry since last use).

Install

As a plugin (recommended) — see Quick start; the repository is its own plugin marketplace. The hook has no dependencies and runs from the plugin directory. The MCP server is started with npx -y --omit=optional --package=smcreader@<plugin version> smcreader-mcp: the first start downloads the npm package once (~40 MB with dependencies, ~60 MB on disk). --omit=optional skips the Agent SDK's bundled Claude Code binaries (~280 MB per platform variant); reader_ask runs your own claude from PATH instead (or READER_CLAUDE_EXECUTABLE). Loaded as a plugin, the tools are named mcp__plugin_smcreader_smcreader__reader_*, and the hook writes these names into the pointer.

For a one-off session from a checkout: git clone https://github.com/bulatko/SMCReader ~/smcreader and claude --plugin-dir ~/smcreader.

npm install -g smcreader        # or: git clone … && npm install --omit=dev

{
  "hooks": {
    "PostToolUse": [
      { "matcher": "Bash|WebFetch",
        "hooks": [{ "type": "command", "command": "READER_TOOL_PREFIX=mcp__smcreader__ smcreader-hook" }] }
    ]
  }
}

claude mcp add smcreader -- smcreader-mcp

npm test                                         # unit + cross-process (spawns the real bin/ scripts)
sh e2e/claude-code.sh                            # real Claude Code: hook via --settings, server via --mcp-config
READER_E2E_NO_HOOK=1 sh e2e/claude-code.sh       # negative control: no hook — must fail
sh e2e/plugin.sh                                 # real Claude Code, everything from the plugin
READER_E2E_NO_PLUGIN=1 sh e2e/plugin.sh          # negative control: no --plugin-dir — must fail
READER_E2E_PACKAGE=registry sh e2e/plugin.sh     # the published npm version instead of `npm pack`

Limitations

• Needs a Claude Code version that applies hookSpecificOutput.updatedToolOutput from command hooks (verified on 2.1.282). Older versions call the hook but keep the original output.
• Supported output shapes: string, {stdout,…} (Bash), {content:[…]} (MCP), {output}, {file:{content}} (Read), arrays of content blocks. Unknown shape → passed through untouched.
• Read is not intercepted by default — Edit needs exact bytes. Use the read guard instead.
• reader_ask needs Claude Code credentials and a claude binary (Agent SDK, model Haiku); reader_open / reader_peek / reader_list work without them. Documents above 700 KB can only be peeked; above 5 MB reader_open refuses them.
• The plugin's hook sets an environment variable inline (VAR=… node …), which needs a POSIX shell; Windows is not tested.
• The server does not know the Claude Code session by itself (it outlives /clear and resumes); set READER_OWNER if you need per-session isolation in a shared READER_DIR.

License

MIT — see LICENSE.