SuperMarioYL/blastevict

English | 简体中文

blastevict is the context-eviction CLI that replay-proves which tool outputs SREs can safely drop. When your coding agent blows through context mid-incident, blastevict traces which persisted tool outputs are silently eating your budget — and replay-proves which ones are safe to evict without breaking the next decision.

Coding-agent sessions (Claude Code, Cursor-class tools) run long and multi-turn. Every tool call — a file read, a log dump, a grep — leaves its output persisted in context for every later turn. Wider context windows didn't fix this; they enabled longer runs, so persisted output accumulates past the point any prevention strategy can keep flat. Mid-run, the agent hits its limit and you must either abort (losing the chain of thought) or blindly trim context the agent may still need.

Existing tools each miss the decision blastevict makes:

blastevict introduces a new flow primitive — observability-to-control: it traces how far each output's footprint propagated across turns, then replay-proves the cut is safe by re-running the agent under ablation. The verdict is the product.

A single Python process, four stages:

1. Ingest — parses a Claude Code session JSONL into an ordered turn model: events, tool calls, and which outputs persisted into later context windows.
2. Trace — builds the blast-radius footprint for every persisted tool output: how many subsequent turns it propagated across and its cumulative token cost while it sat there.
3. Replay — for the top-footprint candidates, re-runs the agent's next decision without that output in context (temperature=0, N=3 samples) and compares the action distribution to the original. A compaction event truncates the visible tail — outputs before it stop propagating.
4. Report — ranks every output by footprint and stamps a replay-proven verdict.

ToolOutputFootprint
  tool_call_id          # which persisted tool output
  origin_turn           # turn where it was produced
  propagated_turns      # turns where it still sat in context
  token_footprint       # cumulative tokens occupied across turns
  propagation_depth     # max turns it persisted

EvictionVerdict
  tool_call_id
  footprint
  replay_samples        # N=3 ablation runs
  action_overlap        # 0.0–1.0, action-distribution similarity
  verdict               # safe-to-evict | load-bearing | uncertain
  determinism_note      # temp=0, N=3, action-distribution comparison basis

Replay calls use temperature=0 with N=3 samples per candidate. Comparison is action-distribution similarity (does the agent still call the same tools / reach the same decision), not exact-token match — because even temperature=0 has residual non-determinism on frontier models. High cross-sample variance forces an uncertain verdict and never produces a false safe-to-evict. This follows the leave-one-out replay-ablation precedent (fixed-seed action-distribution comparison).

Eviction removes the tool_use + tool_result pair together: the messages API requires every tool call to be answered, so the candidate's call and output are ablated as a unit.

# 1. Install (Python 3.12+)
uv tool install blastevict            # or: pip install blastevict
# from source:
git clone https://github.com/SuperMarioYL/blastevict && cd blastevict
uv pip install -e .

# 2. (Optional) enable replay-proven verdicts
export ANTHROPIC_API_KEY=sk-ant-...

# 3. Analyze a Claude Code session
blastevict analyze examples/sample_session.jsonl
# replay is skipped without an API key — you still get the full footprint report;
# set ANTHROPIC_API_KEY to replay-prove the top candidates.

Replay is bounded by cost: only the top-K footprint candidates (default --top-k 5) are replayed. Lower-footprint outputs are reported as not-replayed.

A real blastevict analyze run on a Claude Code session JSONL (replay skipped, no API key — the footprint report is fully reproducible without secrets):

$ blastevict analyze examples/sample_session.jsonl

 ─ blastevict v0.2.0 ─
 examples/sample_session.jsonl
 12 events · 6 persisted tool outputs

 Blast-radius eviction report
 #  tool    origin  depth  tok/turn  footprint  overlap  verdict
 1  Bash       6       3       224       672     —     pending
 2  Read       4       4        89       356     —     pending
 3  Read       2       5        49       245     —     pending
 4  Grep       2       5        33       165     —     pending
 5  Bash      10       1        39        39     —     pending
 6  Edit       8       2        17        34     —     pending

 Cumulative footprint: 1511 token-turns across 6 outputs.
 Verdicts: 6 pending.

 replay not run (ANTHROPIC_API_KEY not set): footprints are exact;
 verdicts are pending, not replay-proven.

With ANTHROPIC_API_KEY set, the top-K rows carry replay-proven safe-to-evict / load-bearing / uncertain verdicts and an overlap column showing the action-distribution similarity. An asciinema cast of a full run is shipped at assets/demo.cast.

blastevict analyze SESSION.jsonl [OPTIONS]

  SESSION.jsonl              Path to a Claude Code session JSONL.

  --top-k INTEGER             Replay only the top-K footprint candidates.   [default: 5]
  --n-samples INTEGER          Replay samples per candidate (temp=0).       [default: 3]
  --no-replay                  Skip replay; footprint report only.
  --json                       Emit machine-readable JSON.
  --help                       Show this message and exit.

Verdict reference:

Machine-readable output (--json) mirrors docs/demo-results.json.

• Input: Claude Code session JSONL (~/.claude/projects/<session>.jsonl). v0.1 supports Claude Code transcripts only — Cursor / Aider / generic agent-transcript adapters are post-v0.1.
• Replay backend: the Anthropic messages API, at the model that produced the original session.
• Output: a ranked rich-text report to stdout, or JSON via --json.
• Mode: read-only post-mortem analysis. It tells you what to cut; it does not auto-apply evictions to a running session.

Planned post-v0.1: Cursor / Aider adapters; live in-session eviction once the safety claim holds on real transcripts; richer action-distribution metrics beyond tool-name Jaccard.

• Determinism kill (pre-launch): if no stable decision-diff emerges from replay ablation on 3+ real Claude Code sessions at temp=0 / N=3, the central safety claim ("eviction is replay-proven safe") is unprovable — kill regardless of other signal.
• Star kill (post-launch): after 30 days on GitHub with 3 launch activities, fewer than 50 stars AND no organic user files an issue describing the eviction decision → kill.
• Demand kill: if no interviewee or issue-filer describes the eviction decision unprompted within 60 days → the primitive solves a problem users haven't articulated; kill or re-scope.

MIT — Copyright (c) 2026 SuperMarioYL. See LICENSE.