Skip to content
Back to search

fast-jev-compaction

MarketplaceWorks with Claude CodeGitHub

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.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

Its scripts were only partly scanned.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/tamaratran/fast-jev-compaction with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/tamaratran/fast-jev-compaction'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/tamaratran-fast-jev-compaction/badge.svg)](/listings/tamaratran-fast-jev-compaction)

HTML

<a href="/listings/tamaratran-fast-jev-compaction"><img src="/api/listings/tamaratran-fast-jev-compaction/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 16 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "fast-jev-compaction",
  3. "owner": {
  4. "name": "tamaratran",
  5. "url": "https://github.com/tamaratran"
  6. },
  7. "plugins": [
  8. {
  9. "name": "fast-jev-compaction",
  10. "source": "./",
  11. "description": "Verbatim Jev-guided compaction for Claude Code sessions.",
  12. "version": "0.3.0",
  13. "license": "MIT"
  14. }
  15. ]
  16. }
README.md · README · 191 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # fast-jev-compaction
  2. Claude Code plugin that replaces the compaction summary with Jev decisions:
  3. every tool call and result is scored in one fast request, stale ones are
  4. dropped or truncated, everything kept stays verbatim. Also usable as an npm
  5. library.
  6. ## What and why
  7. Most context compaction asks an LLM to summarize old turns. A summary is
  8. lossy: a file path, exact error, constraint, or command can disappear even when
  9. it matters later. This library never rewrites anything. It only deletes tool
  10. calls and tool results Jev says are no longer needed, and it asks Jev while
  11. showing it the whole conversation. User and assistant text stays verbatim and
  12. in order.
  13. The repository is both an npm package (`src/`) and a Claude Code plugin
  14. (`hooks/`, `.claude-plugin/`) that uses the package to replace Claude Code's
  15. built-in compaction summary with the original messages.
  16. ## How it works
  17. 1. Every `tool_use` is paired with its `tool_result` by `tool_use_id`. Calls in
  18. the first message or in the newest `preserveRecentMessages` messages are
  19. pinned and never touched.
  20. 2. The **state** sent to Jev is the whole conversation so far, oldest first,
  21. with every tool result replaced by a short note (`ok, 4213 chars (omitted)`).
  22. Tool inputs are included, texts are included, nothing is summarized.
  23. 3. The state is fitted into `maxStateTokens` (25k by default) in stages, each
  24. applied only if the previous one was not enough: tool inputs truncated to
  25. 1000, then 200, then 60 characters; long texts abridged to head + tail,
  26. oldest non-pinned messages first; old non-pinned messages collapsed to a
  27. `[… N chars omitted …]` note; old tool calls reduced to one line each
  28. (`t12 Read file_path=src/a.ts → ok 480ch`); old call-less messages left
  29. out; runs of old call-only messages folded into one entry. If it still
  30. does not fit, compaction throws. Tokens are estimated without a tokenizer (a
  31. word per six letters, half a token per digit, ~one per other symbol),
  32. calibrated to land a little above the counts Jev reports.
  33. 4. For every non-pinned call Jev gets two `noul` questions: should the **call**
  34. stay (knowing it was made, with its input, still matters), and should the
  35. **result** stay verbatim (its contents are still needed and re-running the
  36. tool would not do).
  37. 5. Questions are split into as many requests as needed so state plus questions
  38. stays under `maxRequestTokens` (30k by default, under Jev's 32k request
  39. limit). The same full state is resent with every request; requests run
  40. concurrently and their answers are merged.
  41. 6. Decisions per call, against `keepThreshold`:
  42. - `keepResult ≥ threshold` → keep call and result;
  43. - else `keepCall ≥ threshold` → keep the call, truncate the result to its
  44. first `truncateHeadChars` characters plus a one-line note;
  45. - else → remove the call together with its result.
  46. 7. The message list is rebuilt: a message that loses all its content is
  47. removed, untouched messages are returned as the same objects, and no result
  48. is ever left without its call.
  49. Jev failures, malformed answers, a missing key, or a history that cannot be
  50. fitted throw; the caller (or the Claude Code hook) decides what to fall back to.
  51. ## Install and usage
  52. ```sh
  53. npm install fast-jev-compaction
  54. export TYPESAFE_API_KEY=...
  55. ```
  56. ```ts
  57. import { compactMessages, reductionRatio, type Message } from 'fast-jev-compaction';
  58. const transcript: Message[] = [
  59. { role: 'user', text: 'Fix the failing test. Never edit src/generated.', toolUses: [] },
  60. {
  61. role: 'assistant',
  62. text: '',
  63. toolUses: [{ tool_use_id: 'toolu_1', tool: 'Read', input: { file_path: 'src/a.ts' } }],
  64. },
  65. { role: 'user', text: '', toolUses: [], toolResults: [{ tool_use_id: 'toolu_1', text: '…file…' }] },
  66. // …
  67. ];
  68. const result = await compactMessages(transcript, { preserveRecentMessages: 4 });
  69. console.log(result.messages, result.decisions, result.stats);
  70. if (reductionRatio(result) < 0.25) {
  71. // not worth it: keep the original transcript, or summarize instead
  72. }
  73. ```
  74. `Message` is a subset of Claude Code's `SessionMessage`, so a session transcript
  75. can be passed in as is.
  76. To bring your own transport, implement `JevAsker` (one `ask(state, questions)`
  77. method) and call `compact(messages, asker, options)`; `buildJevRequest` and
  78. `parseJevResponse` give you the HTTP request body and response validation.
  79. The building blocks (`collectToolCalls`, `fitState`, `batchCalls`,
  80. `decideCall`, `applyDecisions`) are exported too.
  81. `apiKey` defaults to `process.env.TYPESAFE_API_KEY`. Never commit the key or
  82. put it in a source file.
  83. ## Options
  84. | Option | Default | Description |
  85. | --- | --- | --- |
  86. | `apiKey` | `TYPESAFE_API_KEY` | TypeSafe API key (`compactMessages`/`JevClient`) |
  87. | `model` | `jev-latest` | Jev model name |
  88. | `baseUrl` | `https://api.typesafe.ai/v1/systemone` | System One endpoint |
  89. | `fetch` | native `fetch` | Injectable fetch implementation for tests |
  90. | `goal` | last 3 user prompts | Ongoing task description included in the state |
  91. | `keepThreshold` | `0.5` | Minimum keep probability for a call or result to stay |
  92. | `preserveRecentMessages` | `6` | Newest messages never touched (the first is always kept) |
  93. | `maxStateTokens` | `25000` | Estimated token ceiling for the state |
  94. | `maxRequestTokens` | `30000` | Estimated ceiling for state plus one batch of questions |
  95. | `truncateHeadChars` | `300` | Characters of a dropped tool result retained before its note |
  96. `result.stats` reports message and character counts before and after, the
  97. per-reason decision counts, the state size in estimated tokens, which fitting
  98. stage was needed, and the number of requests.
  99. ## Limitations
  100. - Only tool calls and results are candidates; text messages are never removed
  101. or shortened in the output (they are only abridged in the state Jev sees).
  102. - Token sizes are estimates from character counts, not a tokenizer.
  103. - Calibration is at the request level; a probability is not a proof that a
  104. result is safe to delete. The assistant can always re-run the tool.
  105. - The full state is repeated with every request, so a history near the state
  106. ceiling costs one request per handful of questions.
  107. ## Claude Code plugin
  108. The repository root is a Claude Code function-hook plugin: `hooks/fast-jev.ts`
  109. is a thin adapter that feeds `session.compact` transcripts through `src/` and
  110. falls back to Claude Code's built-in summary on errors or insufficient
  111. reduction. See [`hooks/README.md`](hooks/README.md) for configuration and the
  112. Claude Code 2.1.274 type reference.
  113. ### Install in Claude Code
  114. Function hooks are an early-access Claude Code feature (2.1.274+), so the
  115. opt-in flag must be set wherever Claude Code runs, e.g. in `~/.claude/settings.json`:
  116. ```json
  117. { "env": { "CLAUDE_CODE_ENABLE_FUNCTION_HOOKS": "1", "TYPESAFE_API_KEY": "<your key>" } }
  118. ```
  119. Then add this repository as a plugin marketplace and install the plugin,
  120. either from the shell or as slash commands inside a session:
  121. ```sh
  122. claude plugin marketplace add tamaratran/fast-jev-compaction
  123. claude plugin install fast-jev-compaction@fast-jev-compaction
  124. ```
  125. The install prompts for the plugin options (API key, thresholds, `truncateHeadChars`,
  126. …); leave them at their defaults to use `TYPESAFE_API_KEY` from the environment.
  127. Restart Claude Code or run `/reload-plugins`. From then on `/compact` (and
  128. auto-compaction) goes through Jev: the toast reads
  129. `fast-jev-compaction: kept N/M messages, no summary (…)` when the pruned history
  130. replaced the built-in summary, or `fallback to built-in summary (…)` when Jev
  131. could not remove enough (short sessions, or when it fails).
  132. To run from a checkout without installing: `CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 claude --plugin-dir .`
  133. from the repository root. No publishing step is required; the marketplace is
  134. just the repo's `.claude-plugin/marketplace.json`.
  135. ## Development
  136. ```sh
  137. npm install
  138. npm run typecheck # library + hook
  139. npm test
  140. npm run build
  141. npm run validate:plugin # claude plugin validate
  142. TYPESAFE_API_KEY="$(cat ~/.typesafe_key)" npm run demo
  143. ```
  144. The unit tests use a fake Jev and never contact TypeSafe. The demo is the live
  145. network check.
  146. ## Animated demo (macOS)
  147. `demo/JevDemo` is a small native SwiftUI app that plays a scripted, dramatized
  148. version of the compaction flow inside a Claude Code-style terminal: the tool
  149. calls of a canned transcript are scored, results and calls Jev lets go turn red
  150. and collapse away, and the rest stays verbatim. It never calls the API; it
  151. exists to be screen recorded.
  152. ```sh
  153. demo/JevDemo/build.sh # builds demo/JevDemo/build/JevDemo.app and launches it
  154. ```
  155. Press space in the app to replay from the start.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.