fast-jev-compaction README

The project's README from github.com/tamaratran/fast-jev-compaction. As one markdown file: README.md.

fast-jev-compaction

Claude Code plugin that replaces the compaction summary with Jev decisions: every tool call and result is scored in one fast request, stale ones are dropped or truncated, everything kept stays verbatim. Also usable as an npm library.

What and why

Most context compaction asks an LLM to summarize old turns. A summary is lossy: a file path, exact error, constraint, or command can disappear even when it matters later. This library never rewrites anything. It only deletes tool calls and tool results Jev says are no longer needed, and it asks Jev while showing it the whole conversation. User and assistant text stays verbatim and in order.

The repository is both an npm package (src/) and a Claude Code plugin (hooks/, .claude-plugin/) that uses the package to replace Claude Code's built-in compaction summary with the original messages.

How it works

  1. Every tool_use is paired with its tool_result by tool_use_id. Calls in the first message or in the newest preserveRecentMessages messages are pinned and never touched.
  2. The state sent to Jev is the whole conversation so far, oldest first, with every tool result replaced by a short note (ok, 4213 chars (omitted)). Tool inputs are included, texts are included, nothing is summarized.
  3. The state is fitted into maxStateTokens (25k by default) in stages, each applied only if the previous one was not enough: tool inputs truncated to 1000, then 200, then 60 characters; long texts abridged to head + tail, oldest non-pinned messages first; old non-pinned messages collapsed to a [… N chars omitted …] note; old tool calls reduced to one line each (t12 Read file_path=src/a.ts → ok 480ch); old call-less messages left out; runs of old call-only messages folded into one entry. If it still does not fit, compaction throws. Tokens are estimated without a tokenizer (a word per six letters, half a token per digit, ~one per other symbol), calibrated to land a little above the counts Jev reports.
  4. For every non-pinned call Jev gets two noul questions: should the call stay (knowing it was made, with its input, still matters), and should the result stay verbatim (its contents are still needed and re-running the tool would not do).
  5. Questions are split into as many requests as needed so state plus questions stays under maxRequestTokens (30k by default, under Jev's 32k request limit). The same full state is resent with every request; requests run concurrently and their answers are merged.
  6. Decisions per call, against keepThreshold:
    • keepResult ≥ threshold → keep call and result;
    • else keepCall ≥ threshold → keep the call, truncate the result to its first truncateHeadChars characters plus a one-line note;
    • else → remove the call together with its result.
  7. The message list is rebuilt: a message that loses all its content is removed, untouched messages are returned as the same objects, and no result is ever left without its call.

Jev failures, malformed answers, a missing key, or a history that cannot be fitted throw; the caller (or the Claude Code hook) decides what to fall back to.

Install and usage

npm install fast-jev-compaction
export TYPESAFE_API_KEY=...

import { compactMessages, reductionRatio, type Message } from 'fast-jev-compaction';

const transcript: Message[] = [
  { role: 'user', text: 'Fix the failing test. Never edit src/generated.', toolUses: [] },
  {
    role: 'assistant',
    text: '',
    toolUses: [{ tool_use_id: 'toolu_1', tool: 'Read', input: { file_path: 'src/a.ts' } }],
  },
  { role: 'user', text: '', toolUses: [], toolResults: [{ tool_use_id: 'toolu_1', text: '…file…' }] },
  // …
];

const result = await compactMessages(transcript, { preserveRecentMessages: 4 });
console.log(result.messages, result.decisions, result.stats);
if (reductionRatio(result) < 0.25) {
  // not worth it: keep the original transcript, or summarize instead
}

Message is a subset of Claude Code's SessionMessage, so a session transcript can be passed in as is.

To bring your own transport, implement JevAsker (one ask(state, questions) method) and call compact(messages, asker, options); buildJevRequest and parseJevResponse give you the HTTP request body and response validation. The building blocks (collectToolCalls, fitState, batchCalls, decideCall, applyDecisions) are exported too.

apiKey defaults to process.env.TYPESAFE_API_KEY. Never commit the key or put it in a source file.

Options

Option Default Description
apiKey TYPESAFE_API_KEY TypeSafe API key (compactMessages/JevClient)
model jev-latest Jev model name
baseUrl https://api.typesafe.ai/v1/systemone System One endpoint
fetch native fetch Injectable fetch implementation for tests
goal last 3 user prompts Ongoing task description included in the state
keepThreshold 0.5 Minimum keep probability for a call or result to stay
preserveRecentMessages 6 Newest messages never touched (the first is always kept)
maxStateTokens 25000 Estimated token ceiling for the state
maxRequestTokens 30000 Estimated ceiling for state plus one batch of questions
truncateHeadChars 300 Characters of a dropped tool result retained before its note

result.stats reports message and character counts before and after, the per-reason decision counts, the state size in estimated tokens, which fitting stage was needed, and the number of requests.

Limitations

Claude Code plugin

The repository root is a Claude Code function-hook plugin: hooks/fast-jev.ts is a thin adapter that feeds session.compact transcripts through src/ and falls back to Claude Code's built-in summary on errors or insufficient reduction. See hooks/README.md for configuration and the Claude Code 2.1.274 type reference.

Install in Claude Code

Function hooks are an early-access Claude Code feature (2.1.274+), so the opt-in flag must be set wherever Claude Code runs, e.g. in ~/.claude/settings.json:

{ "env": { "CLAUDE_CODE_ENABLE_FUNCTION_HOOKS": "1", "TYPESAFE_API_KEY": "<your key>" } }

Then add this repository as a plugin marketplace and install the plugin, either from the shell or as slash commands inside a session:

claude plugin marketplace add tamaratran/fast-jev-compaction
claude plugin install fast-jev-compaction@fast-jev-compaction

The install prompts for the plugin options (API key, thresholds, truncateHeadChars, …); leave them at their defaults to use TYPESAFE_API_KEY from the environment. Restart Claude Code or run /reload-plugins. From then on /compact (and auto-compaction) goes through Jev: the toast reads fast-jev-compaction: kept N/M messages, no summary (…) when the pruned history replaced the built-in summary, or fallback to built-in summary (…) when Jev could not remove enough (short sessions, or when it fails).

To run from a checkout without installing: CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 claude --plugin-dir . from the repository root. No publishing step is required; the marketplace is just the repo's .claude-plugin/marketplace.json.

Development

npm install
npm run typecheck        # library + hook
npm test
npm run build
npm run validate:plugin  # claude plugin validate
TYPESAFE_API_KEY="$(cat ~/.typesafe_key)" npm run demo

The unit tests use a fake Jev and never contact TypeSafe. The demo is the live network check.

Animated demo (macOS)

demo/JevDemo is a small native SwiftUI app that plays a scripted, dramatized version of the compaction flow inside a Claude Code-style terminal: the tool calls of a canned transcript are scored, results and calls Jev lets go turn red and collapse away, and the rest stays verbatim. It never calls the API; it exists to be screen recorded.

demo/JevDemo/build.sh   # builds demo/JevDemo/build/JevDemo.app and launches it

Press space in the app to replay from the start.

fast-jev-compaction (tamaratran/fast-jev-compaction)

Searching Database…

7.7K ·GitHub
Fast-jev-compaction
Что это такое?Плагин для Claude Code, который также можно использовать как npm-библиотеку. Он заменяет итоговое резюме при сжатии контекста на решения Jev: каждый вызов инструмента и его результат оцениваются в быстрых запросах, устаревшие отбрасываются или обрезаются, а всё, что осталось, сохраняется дословно.
Так это плагин для Claude Code или npm-библиотека?И то, и другое. Репозиторий — это npm-пакет (src/) и одновременно плагин для Claude Code (hooks/, .claude-plugin/), который использует пакет, чтобы вместо резюме от /compact и автосжатия подставлять исходные, но прореженные сообщения.
Как запустить это в Claude Code?Function hooks — это ранняя функция Claude Code (2.1.274+): установите флаг включения там, где запускается Claude Code (например, в ~/.claude/settings.json), добавьте этот репозиторий как маркетплейс плагинов, установите плагин, затем перезапустите Claude Code или выполните /reload-plugins.
Нужен ли какой-нибудь API-ключ или сервис?Нужен API-ключ TypeSafe для Jev: apiKey по умолчанию берётся из process.env.TYPESAFE_API_KEY, и если оставить ответы на вопросы при установке по умолчанию, будет использована именно эта переменная окружения. В README предупреждают: никогда не добавляйте ключ в репозиторий и не помещайте его в файл с исходным кодом.
На что стоит обратить внимание?Кандидатами на удаление являются только вызовы инструментов и их результаты — текстовые сообщения никогда не удаляются и не сокращаются. Размеры в токенах — это оценки по количеству символов, а не настоящий токенизатор, и вероятность сохранения не гарантирует, что удаление безопасно: ассистент всегда может вызвать инструмент заново.
Что мне покажет уведомление после /compact?Если прореженная история заменила встроенное резюме, там будет написано 'fast-jev-compaction: kept N/M messages, no summary (...)'. Если Jev не смог удалить достаточно — при короткой сессии или сбое — там будет 'fallback to built-in summary (...)'.
Можно ли запустить это из склонированного репозитория без установки?Да: выполните claude --plugin-dir . из корня репозитория с включённым флагом function-hooks. Публиковать ничего не нужно — маркетплейсом служит файл .claude-plugin/marketplace.json в самом репозитории.
Что содержит result.stats после запуска?Количество сообщений и символов до и после, счётчики решений по каждой причине, размер состояния в оценённых токенах, какой этап подгонки понадобился и число запросов.
Зачем нужно приложение JevDemo?Это небольшое нативное приложение на SwiftUI (macOS), которое проигрывает заранее записанную, поставленную как спектакль версию процесса сжатия внутри терминала в стиле Claude Code: вызовы и результаты, которые Jev отпускает, краснеют и схлопываются, а остальное остаётся дословно. Оно никогда не обращается к API; нажмите пробел, чтобы запустить заново.
What are similar projects?billion-context, headroom, pi-posthorse, operator-memory, context-mode, OpenViking, pxpipe, claude-devtools
Which topics is it in?context-window, long-context, memory-management, agent-tools, token-usage, claude-code-plugin, context-engineering, agent-memory, anthropic, plugin, claude, claude-code
Creator
tamaratran
Size
0.2 MB
Stars
7.7K
Updated
CommitSep 17
Age
1mo
Commits · 90 Days