fast-jev-compaction
The best-engineered compaction idea of the Jev wave, trapped behind an unpublished npm package and an early-access-only host.
Instead of summarizing old turns, a cheap judgment model decides which tool calls and results survive compaction, and everything kept stays verbatim; the library core passed all 28 of our functional assertions and the code quality is unusual for a two-day-old repo. But the README's first install command 404s because the npm package was never published, and the plugin only loads on early-access Claude Code 2.1.274+ builds, so almost nobody can run it today. Try it when the package ships and function hooks go stable.
$claude plugin marketplace add tamaratran/fast-jev-compaction
requires Claude Code 2.1.274+ and CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1
$claude plugin install fast-jev-compaction@fast-jev-compaction
prompts for a TypeSafe key, or set TYPESAFE_API_KEY
$CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 claude --plugin-dir .
npm install fast-jev-compaction currently 404s, clone instead
install if
- Claude Code users on 2.1.274+ insider builds with a TypeSafe key who lose exact file paths, commands, or error strings during long sessions. This is the only compaction path that keeps surviving content byte-identical instead of summarized.
- Agent and tool authors who want a compaction engine, not a plugin. The bring-your-own-transport
JevAskerinterface, exported building blocks (collectToolCalls, fitState, batchCalls, applyDecisions), and per-decision stats make the core embeddable in other harnesses today, clone-built.
skip if
- Anyone on stable Claude Code. The function-hooks surface does not exist there; the plugin registers zero hooks and the validator rejects the manifest. Wait for the surface to stabilize and the npm package to ship.
- Anyone without a TypeSafe account. Every compaction call hits the paid System One endpoint; there is no local or free tier.
- Teams whose transcripts contain non-reproducible tool results. Deletion is permanent and driven by a probability threshold on a model that never sees result contents; issue #25's concern is unresolved.
What It Does
fast-jev-compaction is a Claude Code plugin and npm library that replaces Claude Code's built-in compaction summary with selective deletion. When a session compacts, it sends the whole conversation (tool outputs replaced by short notes, fitted into a 25k-token budget through six named shrinking stages) to Jev, TypeSafe's cheap judgment model, and asks two scored questions per tool call: should the call stay, and should its full result stay verbatim. Calls below the keep threshold disappear with their results, borderline results keep a 300-character head plus an honest truncation note, and every user and assistant text message stays byte-identical and in order. A turn.complete hook also triggers compaction automatically at 60 percent context usage. It targets Claude Code power users on long sessions and library authors who want a compaction engine with an injectable transport.
The Good
The verbatim-preservation contract holds under test, exactly as documented. We drove the library through its documented bring-your-own-transport path with a scripted mock JevAsker over a 14-message, 6-call transcript. The first user message came back as the same object with identical text, a kept 4,000-character result stayed intact, a dropped result was truncated to its first 300 characters followed by [fast-jev-compaction truncated 1710 chars of this tool result; re-run the tool if needed], a dropped call removed both the tool_use and its tool_result, no orphaned result ever survived without its call, and pinned calls stayed untouched even when we fed them a 0.1 keep score. All 28 functional checks passed.
Fail-closed discipline is real, not aspirational. A missing key throws TYPESAFE_API_KEY is not configured, malformed JSON throws Jev returned malformed JSON, a response without an answers object throws Jev response is missing answers, a non-numeric probability throws Invalid Jev answer, and an HTTP failure surfaces the status code and the first 200 characters of the body. We also probed the live System One endpoint with a dummy key: the 4xx came back through the same clean error path. The hook wraps everything in a fallback to Claude Code's built-in summary, so the worst case is the status quo, not a broken session.
The engineering is unusual for a two-day-old repo. Zero runtime dependencies (4 devDependencies), full TypeScript types on every export, doc comments explaining the why (the token estimator's comment explains its calibration against usage Jev reports, and why a characters-per-token ratio undercounts JSON-heavy states by up to 40 percent), a six-stage state-fitting ladder with the achieved stage reported in stats, question batching under a 30k request ceiling with the full state resent per batch, and 29 unit tests that run in 285 milliseconds without touching the network. Our batching probe confirmed a tight request budget splits into multiple requests whose answers merge correctly, and a short transcript makes zero Jev calls.
The README is honest about limits. The Limitations section states that a probability is not proof a result is safe to delete, that token counts are estimates, and that a history near the state ceiling costs one request per handful of questions. The tracker is equally honest: issue #26 reports a user replay where 0 of 256 results scored at or above the 0.5 keep threshold, and issue #21 reports the plugin registering zero hooks on Claude Code 2.1.272.
The Bad
The README's first install command does not work. npm install fast-jev-compaction returns 404 because the package has never been published to npm, despite a fully packaged package.json (exports map, files whitelist) and a README section titled "Also usable as an npm library." Issues #37 and #48 ("Build exported files before creating an npm package") are open. Today the library is clone-and-build only, which the README never says.
The plugin is unusable on any stable Claude Code. Function hooks are an early-access 2.1.274+ feature behind the CLAUDE_CODE_ENABLE_FUNCTION_HOOKS flag. On our host (Claude Code 2.1.152), claude plugin validate rejects the manifest outright with Invalid input: expected record, received undefined because the validator predates the {"modules": [...]} hooks format, and issue #21 confirms zero hooks register even on 2.1.272. The repo documents the requirement, but that does not change the outcome: the only installable surface today requires an insider build plus a paid TypeSafe key.
Version drift and distribution gaps. package.json says 0.2.0 while plugin.json and marketplace.json say 0.3.0. There is no SKILL.md, so the skills.sh universal installer cannot see it (11 other Jev-wave faces are registered there). There are no tags, no releases, no CI workflows, and 17 of the 30 commits come from devin-ai-integration[bot] against 13 from the owner. The hooks/README.md install block also has a mangled shell line (export TYPESAFE_API_KEY=*** TypeSafe key>").
The result-blindness critique has evidence behind it. Jev never sees tool result contents, only notes like ok, 4213 chars (omitted), yet it is asked whether those contents are still needed. Issue #26's replay (0 of 256 results kept) suggests the practical outcome is truncating nearly every old result, and issue #25 asks what happens to non-reproducible results (a deleted CI log or a one-time command output) that a probability threshold wrongly discards. Neither is resolved.
Smoke Test Results
Hands-on host test on macOS 26.5.2 (aarch64), Node 24.13.1, Claude Code 2.1.152, clone at commit e3f262a (944 KB, 26 tracked files plus a vendored 11,267-line Claude Code 2.1.274 type reference; about 1,900 authored TypeScript lines across src, hooks, tests, and examples).
Run A. Fresh sandbox, no deps preinstalled
$ git clone --depth 1 https://github.com/tamaratran/fast-jev-compaction
β
944 KB clone, 26 tracked files, ~1,915 authored TS lines
$ head -3 LICENSE
β
MIT LICENSE present
$ python3 -c "import json; json.load(open('.claude-plugin/plugin.json'))"
β
plugin.json valid JSON
$ python3 -c "import json; json.load(open('.claude-plugin/marketplace.json'))"
β
marketplace.json valid JSON
$ python3 -c "import json; json.load(open('hooks/hooks.json'))"
β
hooks.json valid JSON
$ diff <(manifest userConfig defaults) <(README options table)
β
all 8 userConfig defaults match the documented table (keepThreshold 0.5, preserveRecentMessages 6, maxStateTokens 25000, maxRequestTokens 30000, truncateHeadChars 300, compactAtPercent 60, minReductionRatio 0.25, model jev-latest)
$ manifest version cross-check
β version drift: package.json 0.2.0 vs plugin.json 0.3.0 vs marketplace.json 0.3.0
$ python3 -c "deps check on package.json"
β
zero runtime dependencies (devDeps only)
$ grep -q '2\.1\.274' README.md
β
README names the 2.1.274+ host requirement
$ grep -q CLAUDE_CODE_ENABLE_FUNCTION_HOOKS README.md
β
README documents the opt-in flag
$ grep -rniE secret-patterns .
β
no secrets in tracked files
$ ls tests/*.test.ts
β
2 test files present (433 + 149 lines)
$ grep -rn 'typesafe\.ai' tests/
β
tests never contact TypeSafe (endpoint appears only inside a toBe() string assertion)
$ curl -sf https://registry.npmjs.org/fast-jev-compaction
β 404: package not published, README's primary library install path is broken
$ curl -s 'https://skills.sh/api/search?q=fast-jev-compaction'
β not on the skills.sh registry (no SKILL.md, invisible to npx skills add)
Pass rate: 11 of 14. All three failures are real distribution defects, not test-environment noise: the npm package does not exist, the universal installer cannot index the repo, and the manifests disagree on version.
Run B. Sandbox with deps preinstalled
$ npm install --no-audit --no-fund
β
50 dev packages in 4s, zero runtime deps
$ npm run typecheck
β
tsc --noEmit clean for the library and the hook
$ npm test
β
Tests 29 passed (29) in 285ms, 2 test files, no network
$ npm run build
β
tsc build clean, dist/index.js plus 7 modules
$ claude plugin validate .claude-plugin/plugin.json
β on Claude Code 2.1.152: Invalid input: expected record, received undefined (validator predates the 2.1.274+ function-hooks "modules" format)
$ grep "from 'claude-code'" hooks/fast-jev.ts
β
hook compiles against the vendored types/claude-code.d.ts (generated on 2.1.274)
$ npm run build (script exists in package.json)
β
npm script build present
$ npm run typecheck (script exists in package.json)
β
npm script typecheck present
$ npm test (script exists in package.json)
β
npm script test present
$ npm run demo (script exists in package.json)
β
npm script demo present
$ npm run validate:plugin (script exists in package.json)
β
npm script validate:plugin present
Pass rate: 10 of 11. The one failure is the host gate: the plugin is built for early-access Claude Code builds, and everything else (install, typecheck, 29 tests, build) works on a stock Node 24 host.
Run C. Functional verification (does it do what it claims?)
Scripted mock JevAsker (the documented bring-your-own-transport path) over a 14-message, 6-call transcript, plus negative probes and one live-endpoint check. The test script ships at sandbox/skills/fast-jev-compaction/functional-test.mjs.
$ node functional-test.mjs
β
first and last user messages kept verbatim (same objects)
β
kept result verbatim (4,000 chars intact)
β
dropped result keeps 300-char head + honest truncation note (1710 chars cut)
β
dropped call removes call AND result; no orphaned tool results anywhere
β
pinned calls survive a 0.1 keep score (first + newest messages never touched)
β
stats coherent: 14 -> 12 messages, 11,324 -> 9,659 chars, 1 kept / 1 result_dropped / 1 call_dropped / 3 pinned, state 759 tokens at the "full" fitting stage
β
state = whole history, tool outputs omitted, goal defaults to last 3 user prompts
β
tight request budget splits into multiple requests, answers merge across batches
β
short transcript makes zero Jev requests
β
negatives: missing key, malformed JSON, missing answers, bad probabilities, HTTP 401 all throw named errors
β
live endpoint probe with dummy key: clean 4xx through parseJevResponse
28 pass, 0 fail
Functional pass rate: 28 of 28.
What the runs tell you
The library does exactly what its README claims on every axis we could assert, with a deterministic mock standing in for Jev. What we could not verify is the part that matters most in production: whether Jev's scores separate needed from unneeded results on real transcripts (the repo's own issue #26 says they may not), and whether the hook fires inside a live 2.1.274+ session, which our 2.1.152 host cannot run.
Setup Walkthrough
- Clone the repo:
git clone --depth 1 https://github.com/tamaratran/fast-jev-compaction(the README'snpm install fast-jev-compaction404s today). - For library use:
npm install && npm run build, then import fromdist/(or register a git dependency). ExportTYPESAFE_API_KEYor passapiKey. - For plugin use: set
CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1and your key in~/.claude/settings.jsonenv, thenclaude plugin marketplace add tamaratran/fast-jev-compactionandclaude plugin install fast-jev-compaction@fast-jev-compaction. This requires Claude Code 2.1.274 or newer. - Quick local trial without installing:
CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 claude --plugin-dir .from the repo root. - After install,
/compactand auto-compaction route through Jev; the toast reportskept N/M messages, no summary (...)orfallback to built-in summary (...).
Gotchas: the install prompts accept plugin options (key, thresholds); leaving them unset falls back to TYPESAFE_API_KEY. On any Claude Code older than 2.1.274 the plugin registers nothing, and the validator rejects the manifest with a confusing record-format error rather than a version message.
Alternatives
- Claude Code built-in /compact and auto-compaction - free, zero setup, works on every build, but lossy: the summary can silently drop the exact path or command you needed, which is precisely the failure this plugin exists to fix.
- chopratejas/headroom - attacks context cost from the prevention side (compressing what enters context) rather than pruning at compaction time; broader host support, no paid-key dependency.
- thedotmack/claude-mem - keeps what matters across sessions via persistent memory and hybrid search rather than in-session pruning; complementary if your real need is recall across sessions, not room inside one.
Reviews stay honest because nobody pays us to publish them. If this one saved you time, throw a coin.
Tip the reviewer- reviewed by
- GearScope
- tested
- 2026-09-18 · macOS (Apple Silicon)
- last verified
- 2026-09-18
- depth
- HANDS-ON
- sponsorship
- none, ever
Don't install your next skill blind.
Every week: the shortlist of skills worth installing β and the ones to skip β from 100+ hands-on tests. No spam, no affiliate links.