Riverbed Compact

Directed, lossless context compaction for Claude Code.

Claude Code's built-in auto-compaction summarizes your session with a separate, generic pass: you don't choose what survives, and what's dropped is gone. Riverbed Compact inverts that: the instance that lived the session decides what its successor needs — which exact phrases must survive verbatim, which threads keep their mechanism, which detours compress to a line — and nothing is truly lost, because bulky tool I/O is moved into a retrievable cache and the original session is kept untouched as a backup.

The name is the design: compaction changes the water; the riverbed — the words that carved the session — persists.

How it works

/riverbed-compact is one self-guiding command with a simple state machine, keyed on whether a summaries file exists next to the session transcript:

1. No summaries file → the hook computes a compaction plan (which assistant turns need summaries, anchored by turn uuid) and injects mode-specific authoring instructions into the live model's context. The model writes the summaries — itself, or via workers it dispatches — as riverbed-summaries.part-*.json files.
2. merge.ts validates that the partials cover every planned turn (hard-failing on gaps), writes riverbed-summaries.json, and prints the exact follow-up command.
3. Summaries file present → the same command assembles the compacted session: user messages verbatim, old assistant turns replaced by the authored summaries, bulky tool I/O replaced by omission records retrievable via the read_omitted_content MCP tool. It replies with /resume <new-session-id>; the original session is renamed [UNCOMPACTED] … and left intact. Sessions stay recompactable.

The plan is anchored to the uuid of the first preserved turn, so the orchestration turns spent authoring summaries can't drift the keep-boundary.

Usage

/riverbed-compact N                     # inline (default): the live instance writes the summaries
/riverbed-compact N --fork [K]          # K forks — inherit the live context, work in parallel (experimental)
/riverbed-compact N --subagent [K] [--model <id>]   # K blank subagents — read their turns from disk, cheap

• N — recent assistant turns to keep whole (cover your current working thread).
• Bare --fork / --subagent — the model picks K (roughly 25–40 turns per worker, max 16).
• --model — only valid with --subagent: forks always inherit the parent model, and inline is the live instance.
• Turns whose text contains the literal token [[riverbed:scaffold]] are dropped to a one-line stub instead of summarized — use it so the compaction ritual itself costs nothing in the compacted output.

Choosing a mode: inline gives the highest fidelity on modest sessions (costs main-thread turns). --fork offloads authorship at full fidelity — each fork inherits the entire live conversation. --subagent is the budget mode — workers see only their extracted slice (via slice.ts), so the orchestrator's directive must spell out anything a summary has to preserve.

--fork is experimental

Fork subagents (Agent(subagent_type: "fork")) ship inside Claude Code behind a staged rollout. If your install doesn't have them yet, enable them explicitly:

// ~/.claude/settings.json
{ "env": { "CLAUDE_CODE_FORK_SUBAGENT": "1" } }

This is an undocumented feature flag: it may change or disappear in any Claude Code release. The payload tells the model what to do if the fork type is unavailable (suggest the env var, or fall back to --subagent).

Cost honesty: each fork re-reads the parent's full live context at cache-read pricing. Two forks on a large session ran ~650k tokens total. Parallelism buys wall-clock time, not tokens.

Caveats

• This plugin parses Claude Code's undocumented session-transcript internals (JSONL rows, turn chaining, compaction markers). Any Claude Code release can break it. There is a test suite (bun test, 24 tests over synthetic transcripts) to catch drift — expect breakage, file issues.
• Requires bun on PATH (the hook, scripts, and MCP server run raw TypeScript via bun; @modelcontextprotocol/sdk resolves via bun auto-install, or run bun install).
• Omission caches live in ~/.claude/riverbed-compact/{sessionId}.json. Retrieval falls back to the ~/.claude/magic-compact/ cache, and marker rows are dual-stamped (riverbedCompact + the upstream magicCompact field), so sessions compacted by either plugin remain mutually recompactable. (Retrieval compatibility is one-directional: this plugin reads upstream's omission cache, not vice versa.)

Install

/plugin marketplace add https://github.com/CodyWhatleyMD/riverbed-compact
/plugin install riverbed-compact@riverbed

Run /reload-plugins if Claude Code is already open.

Development

bun install         # dev deps (typescript, types)
bun run typecheck   # tsc --noEmit
bun test            # parser, payload, merge/assembly round-trip, scaffold, hook e2e

Tests only ever touch synthetic transcripts in temp directories — never real sessions.

Attribution

Forked from aerovato/magic-compact, Copyright (c) 2026 Kevin Liao @ Aerovato Research, BSD-3-Clause — the lossless rebuild engine (omission cache, read_omitted_content, transcript reconstruction) is upstream's design. This fork replaces the headless summarizer with live-session authorship (inline / fork / subagent workers), adds the self-guiding command, boundary-anchored merging, and scaffold dropping. Modifications copyright (c) 2026 Cody Whatley (CodyWhatleyMD). See LICENSE.md.