TRY IT HANDS-ON functional ~ tested 2026-09-18
// sandboxed in macOS (host) Β· aarch64 Β·install log Β· why not fully functional: The library core was fully asserted with a scripted mock JevAsker plus live-endpoint negative probes (28 of 28 checks, positive and negative cases). Live Jev decision quality and the Claude Code session.compact hook path were not exercised: no TypeSafe API key was available, and the host runs Claude Code 2.1.152, which predates the 2.1.274+ function-hooks surface the plugin requires. Β·functional log

fast-jev-compaction

by tamaratran · https://github.com/tamaratran/fast-jev-compaction · MIT · vv0.3.0 (plugin) / 0.2.0 (library, unpublished) · updated 2026-09-18
Don't install your next skill blind. One email a week: what's worth installing.

The best-engineered compaction idea of the Jev wave, trapped behind an unpublished npm package and an early-access-only host.

⚙ ⚙ ⚙ ⚙ ⚙ 3 / 5
quality 4/5
documentation 4/5
setup 2/5
value 3/5
ecosystem fit 2/5
// bottom line

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.

Get the skill digest The best and the broken from 100+ hands-on tests. One email a week.
install via Claude Code marketplace
$claude plugin marketplace add tamaratran/fast-jev-compaction

requires Claude Code 2.1.274+ and CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1

install the plugin
$claude plugin install fast-jev-compaction@fast-jev-compaction

prompts for a TypeSafe key, or set TYPESAFE_API_KEY

run from a checkout
$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 JevAsker interface, exported building blocks (collectToolCalls, fitState, batchCalls, applyDecisions), and per-decision stats make the core embeddable in other harnesses today, clone-built.

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.

Full fresh log β†’

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.

Full with-deps log β†’

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.

Full functional log β†’

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

  1. Clone the repo: git clone --depth 1 https://github.com/tamaratran/fast-jev-compaction (the README's npm install fast-jev-compaction 404s today).
  2. For library use: npm install && npm run build, then import from dist/ (or register a git dependency). Export TYPESAFE_API_KEY or pass apiKey.
  3. For plugin use: set CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 and your key in ~/.claude/settings.json env, then claude plugin marketplace add tamaratran/fast-jev-compaction and claude plugin install fast-jev-compaction@fast-jev-compaction. This requires Claude Code 2.1.274 or newer.
  4. Quick local trial without installing: CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 claude --plugin-dir . from the repo root.
  5. After install, /compact and auto-compaction route through Jev; the toast reports kept N/M messages, no summary (...) or fallback 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

  1. 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.
  2. 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.
  3. 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.
// review provenance
reviewed by
GearScope
tested
2026-09-18 · macOS (Apple Silicon)
last verified
2026-09-18
depth
HANDS-ON
sponsorship
none, ever
// share this review
// feedback
was this review helpful?

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.