Skip to content
Back to search

jev-pruner

Claude Code plugin: trim long Bash output with TypeSafe Jev before the model sees it

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/jev-pruner 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/jev-pruner'

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--jev-pruner/badge.svg)](/listings/tamaratran--jev-pruner)

HTML

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

Install

i

Install instructions from the README

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

These terminal commands use Bash or Zsh on macOS/Linux. Install [Git](https://git-scm.com/downloads) and [Node.js 18+](https://nodejs.org/en/download) (which includes npm), then install the Codex CLI version used in our validation:

npm install -g @openai/codex@0.152.1
codex --version
codex login
codex login status

Complete the browser sign-in with your ChatGPT account. If you already have Codex 0.152.1 installed and authenticated, skip the install and login commands.

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-output",
  3. "owner": {
  4. "name": "tamaratran",
  5. "url": "https://github.com/tamaratran"
  6. },
  7. "plugins": [
  8. {
  9. "name": "fast-jev-output",
  10. "source": "./",
  11. "description": "Trim long Bash output with Jev before the model sees it (Claude Code plugin)",
  12. "version": "0.1.0",
  13. "license": "MIT"
  14. }
  15. ]
  16. }
README.md · README · 644 lines

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

  1. # jev-pruner
  2. A Claude Code plugin that uses TypeSafe's Jev to trim noisy Bash output **after
  3. the command runs, but before its result is sent back to the main LLM**. This
  4. reduces the output carried into later turns without generating a summary.
  5. Using Codex? See [Codex installation and usage](#codex).
  6. ```text
  7. Claude requests a Bash command → Command runs → Jev prunes stdout → Claude receives the result
  8. ```
  9. 1. A `tool.call` hook wraps the Bash tool's `next()` result.
  10. 2. Stdout of **10,000 estimated tokens or fewer** passes through untouched,
  11. without reading history, writing an archive, or calling Jev. The gate uses
  12. `estimateTokens` on raw stdout, not a character count or an exact model tokenizer.
  13. `minTokens` can raise this threshold but cannot lower it. If Claude already saved
  14. the output to a file, the hook reads and counts that full output instead of its
  15. short preview. Errors, JSON/XML/YAML/diff/binary output,
  16. whole-document commands (`cat`, `jq`, `git diff`, `git show`, `base64`, and
  17. `openssl`) are left untouched. Recognized documentation, source code, and
  18. disassembly are also preserved, regardless of which command printed them.
  19. 3. Output is split into chunks of `chunkLines` lines, capped at 200 chunks;
  20. lines longer than 2,000 characters are split first.
  21. The opt-in `chunkChars` setting groups these lines toward a character target
  22. instead. Adjacent groups merge as needed to retain the 200-chunk cap, so the
  23. target is not a hard maximum. Neither mode bypasses the token floor or
  24. document/error protections.
  25. 4. Jev receives `{ context, task, history, command, chunks }`, plus `category` and
  26. `categoryGuidance` for recognized build/test/install or search/excerpt commands,
  27. and one noul question
  28. per chunk: “does any line in this chunk need to remain available?”. A single
  29. needed line protects the chunk, including values required by earlier
  30. instructions even when the next reply must not repeat them. `history` includes
  31. user/assistant text, complete tool inputs, and tool-result text and structured
  32. data from the current session. Identical results attached to both a tool call
  33. and a result message are sent once, linked by their tool-use ID.
  34. Questions are batched so each request stays under 30,000 estimated tokens.
  35. 5. History and output share `maxStateTokens`, using a digit-aware estimate.
  36. History gets at least half the budget, with more available when the current
  37. output is small. Oversized history is partitioned in order across requests,
  38. without truncating or omitting message text, tool arguments, or results.
  39. Individual oversized fields become continuations labeled with their field
  40. name and character offset. Complete output chunks are grouped to fit alongside
  41. each history segment. Scoring requests run in parallel within the request
  42. allowance. A chunk is fully scored only after evaluation against every
  43. history segment. A `max_tokens_exceeded` response
  44. retries twice with a halved state budget and repartitions the original history.
  45. 6. A chunk stays when **any query** gives it a noul of at least `keepThreshold`
  46. or above `0.1`, it is first or last, it contains a recognized diagnostic or
  47. result (including warnings, test totals, and artifact paths), or its complete text was not
  48. scored against every history segment (for example, a single chunk that cannot
  49. fit beside a segment). No partially shown chunk can be discarded.
  50. 7. Each dropped run becomes `[N lines omitted]`.
  51. Adjacent omissions across chunk boundaries share one marker. The Claude hook
  52. labels retained lines as verbatim and puts the archive path in a single footer;
  53. all metadata counts toward the native preview budget. Library callers can
  54. enable this rendering with `compactMarkers: true`.
  55. 8. Before the first scoring request, the complete stdout and stderr are saved
  56. under the project's `.claude/fast-jev-output/` directory (self-gitignored).
  57. When Claude already persisted the complete output, that file is reused as the
  58. archive. Successful pruning replaces Claude's file-preview metadata with the
  59. retained text and archive footer. Read or scoring failures preserve the original
  60. result and its file reference. Claude may persist the pruned result again if it
  61. still exceeds its display limit; the archive footer then lives inside that file.
  62. A final `[fast-jev-output full output: <path> (Read or grep it if needed)]`
  63. footer follows the trimmed stdout. Archives persist for later recovery,
  64. including when scoring ultimately keeps everything or fails.
  65. Credential-like commands or output are not archived by the plugin; their omission
  66. markers instruct the agent to re-run the command instead.
  67. 9. Any archive write failure, Jev failure, or state that cannot fit leaves the original output untouched.
  68. Separate inline stderr is left unchanged. Host-persisted output is scored as
  69. the combined stream supplied by Claude.
  70. Explicit Bash commands containing a successfully pruned archive's path bypass
  71. further pruning in the same hook instance. Read and Grep are already unaffected.
  72. Recovery remains available; the plugin does not prevent the agent from checking
  73. an archive. Indirect reads through aliases or variables are not recognized.
  74. The hook reads the current transcript for each command; it does not maintain a
  75. separate history store. Claude Code's `session.messages()` returns the main
  76. conversation's user/assistant messages (up to the newest 4,096), not the system
  77. prompt or a subagent's own transcript. `task` is still a short extract of the
  78. last three user prompts; `history` supplies the earlier instructions and
  79. assistant decisions and tool results as returned by the host, including any
  80. pruning already applied to earlier results. Archived originals are not reloaded.
  81. Partitioning preserves coverage, but a query sees only its own history segment;
  82. facts that require combining distant segments are not guaranteed to be recognized.
  83. More segments and output groups mean more Jev requests.
  84. Library callers can pass the same transcript shape through
  85. `trimOutput({ command, goal, output, messages }, asker)`.
  86. ### Command categories
  87. Categories add guidance to the same relevance question; they never mark an entire
  88. command's output as disposable or change the keep threshold.
  89. | Category | Examples | Behavior |
  90. | --- | --- | --- |
  91. | Build, install, test | `npm run build`, `pnpm test`, `npm ci`, `make`, `pytest`, `cargo test` | Ask Jev to retain diagnostics, failing tests, result counts, final status, artifact paths, and task-required values; repeated progress may be dropped. |
  92. | Search or file excerpt | `rg`, `grep`, `git grep`, `find`, `head`, `tail`, `sed` | Treat paths, line numbers, matches, and surrounding source as evidence. Repeated matches can still matter, particularly when the task requires complete results or counts. |
  93. | Whole document | JSON objects/arrays, XML root tags or declarations, YAML headers, diffs; recognized Markdown, API help, source definitions, disassembly; `cat`, `bat`, `jq`, `yq`, `git diff`, `git show`, `diff`, `base64`, `openssl` | Preserve the output verbatim without scoring. Content detection takes precedence over a build or search command. |
  94. | Unknown | Custom scripts, unrecognized subcommands, wrappers, pipelines, compound commands | Use the existing general scoring guidance. Existing whole-document safeguards still take precedence. |
  95. Command recognition is deliberately limited to simple invocations. Executable
  96. paths and leading environment assignments are recognized; shell operators,
  97. substitutions, and wrappers fall back to general guidance unless a whole-document
  98. safeguard applies. This is a heuristic, not a shell parser. All categories keep
  99. the strict **over 10,000 estimated tokens** gate. Category guidance counts toward
  100. the state budget in every history segment and output batch.
  101. ### Information retention rules
  102. Each scoring question labels its content as reference, diagnostic, result,
  103. progress, or unknown. Content classification is independent of command
  104. classification: a Python command can print documentation, and a build command
  105. can print source code.
  106. | Information | Retention rule |
  107. | --- | --- |
  108. | Recognized documentation, source code, or assembly | Preserve the entire output without calling Jev, including mixed output with an initial log banner. |
  109. | Diagnostics and results | Keep matching lines and adjacent context even if Jev considers them disposable. Includes warnings, failures, test totals, exit status, and explicit artifact/report paths. |
  110. | Task-dependent facts | Ask Jev against every history segment. A keep vote from any segment protects the content. Refinement uses the same rule for smaller groups. |
  111. | Uncertain meaning | Preserve: removal requires a keep probability at most `0.1` and below `keepThreshold` in every history segment. |
  112. | Progress and boilerplate | Eligible for removal only after that confidence check; a progress label alone never authorizes removal. |
  113. | Missing scoring coverage or failed refinement | Preserve the unscored content or original chunk. |
  114. The content recognizer is a conservative heuristic, not a parser for every
  115. language or document format. Unrecognized content still goes to Jev with the
  116. instruction to retain information whose meaning or relevance is uncertain.
  117. The probability cutoff is a retention policy, not a measured error guarantee.
  118. All rules apply above the existing token floor; none lowers that floor.
  119. Refinement scores individual lines when a retained chunk exceeds its share of
  120. the character budget; otherwise it scores five-line groups. Each line still
  121. requires complete history coverage and the same confidence check before
  122. removal. Diagnostics, results, and their adjacent context remain protected.
  123. Scoring includes detected diagnostic and result lines from the complete output,
  124. so a progress-only fragment can be evaluated alongside the final outcome.
  125. Only the complete output's boundaries and context beside protected facts are
  126. mandatory; internal chunk edges can be removed after complete line scoring.
  127. Retention takes precedence over the output-size budget. If safe refinement
  128. cannot fit, the hook returns the original host result, including its native
  129. preview and full-output reference. It does not force a smaller replacement by
  130. dropping content classified as needed. Diagnostics include `informationCategory`
  131. without logging the output text.
  132. ## Codex
  133. Codex CLI 0.152.1 does not support replacing native shell output from
  134. `PostToolUse`. The Codex integration is an **opt-in command wrapper and skill**,
  135. not automatic interception. Its `PreToolUse` hook only records a transcript
  136. pointer; it never rewrites commands or returns an approval decision.
  137. ### 1. Install Codex and sign in
  138. These terminal commands use Bash or Zsh on macOS/Linux. Install
  139. [Git](https://git-scm.com/downloads) and [Node.js 18+](https://nodejs.org/en/download)
  140. (which includes npm), then install the Codex CLI version used in our validation:
  141. ```sh
  142. npm install -g @openai/codex@0.152.1
  143. codex --version
  144. codex login
  145. codex login status
  146. ```
  147. Complete the browser sign-in with your ChatGPT account. If you already have
  148. Codex 0.152.1 installed and authenticated, skip the install and login commands.
  149. ### 2. Configure Jev access
  150. Create a [TypeSafe API key](https://console.typesafe.ai/settings/keys) and ensure
  151. your account has [API credits](https://console.typesafe.ai/settings/billing).
  152. **Your Codex subscription runs Codex; Jev scoring uses the separate TypeSafe API
  153. and incurs TypeSafe usage.**
  154. Make `TYPESAFE_API_KEY` available in the terminal where you will launch Codex.
  155. You can use your existing secret manager or enter it without echoing the key
  156. or putting it in shell history:
  157. ```sh
  158. printf 'TypeSafe API key: '
  159. read -r -s TYPESAFE_API_KEY
  160. printf '\n'
  161. export TYPESAFE_API_KEY
  162. ```
  163. Paste the key at the prompt and press Enter. This export lasts for the current
  164. terminal session; repeat it in a new terminal or use your existing environment
  165. configuration. Do not put the key in a Codex prompt or commit it to the repository.
  166. ### 3. Build and install the plugin
  167. Run these commands in your terminal:
  168. ```sh
  169. git clone https://github.com/tamaratran/jev-pruner.git
  170. cd jev-pruner
  171. npm ci
  172. npm run build
  173. codex plugin marketplace add "$PWD"
  174. codex plugin add jev-pruner@jev-pruner-codex
  175. codex plugin list --json
  176. ```
  177. The list should show `jev-pruner@jev-pruner-codex` with `installed: true` and
  178. `enabled: true`. Keep the checkout: the registered local marketplace points to it.
  179. **Build before installing.** Installing directly from the Git URL does not
  180. compile TypeScript or supply the required `dist/codex/run.js`.
  181. ### 4. Start Codex and trust the hook
  182. From the project you want to work on, in the terminal containing your API key:
  183. ```sh
  184. cd /path/to/your/project
  185. codex --sandbox workspace-write \
  186. -c sandbox_workspace_write.network_access=true \
  187. -c tool_output_token_limit=30000
  188. ```
  189. This starts a new session with workspace-write sandboxing and network access so
  190. the wrapper can reach `https://api.typesafe.ai/v1/systemone`. Command approvals
  191. still apply. The 30,000-token setting raises Codex's separate host output limit;
  192. otherwise Codex can truncate a result even after the wrapper has pruned it.
  193. Inside Codex, open `/hooks`, review the `jev-pruner` `PreToolUse` hook, and trust
  194. it. That hook records the current transcript location so Jev can score against
  195. the conversation. An untrusted hook leaves the wrapper without the history it
  196. needs, so output passes through unchanged.
  197. The API key must also reach Codex's shell commands. The wrapper does not change
  198. Codex's environment filtering, network policy, or approval settings. If your
  199. configuration blocks the key or endpoint, use your approved environment/network
  200. configuration; pruning fails open while access is unavailable.
  201. ### 5. Use the skill
  202. In the Codex prompt, explicitly invoke the installed skill:
  203. ```text
  204. $jev-pruner Run npm test through the pruner and report the test results.
  205. ```
  206. Replace `npm test` with your non-interactive build, test, install, or search
  207. command. The skill resolves its installed location and calls the wrapper for
  208. you. Commands that Codex runs outside the wrapper are not intercepted.
  209. For a known noisy example, start Codex in the `jev-pruner` checkout and send:
  210. ```text
  211. $jev-pruner Run node tests/fixtures/codex-noisy-build.mjs 1 once through the wrapper.
  212. This is a synthetic fixture; do not fix its simulated deployment error.
  213. Report the bundle Q7 and rollback stable-snapshot values.
  214. ```
  215. That fixture produces output above the 10,000-estimated-token gate. When Jev
  216. removes output, the tool result contains `[fast-jev-output trimmed ...]` markers
  217. and ends with:
  218. ```text
  219. [fast-jev-output full output: <archive-path> (Read or grep it if needed)]
  220. ```
  221. The complete original stdout is in `.jev-pruner/` under the command's working
  222. directory. To read more detail later, ask Codex:
  223. ```text
  224. Read the full-output archive referenced in the last result and show the exact
  225. line containing "cache entry 20 ". Do not rerun the command.
  226. ```
  227. Short output, failed commands, protected formats, and output Jev considers
  228. necessary may remain unchanged. Only an omission marker confirms pruning;
  229. the absence of an error does not.
  230. ### Updating or removing the Codex plugin
  231. From your original `jev-pruner` checkout:
  232. ```sh
  233. git pull --ff-only
  234. npm ci
  235. npm run build
  236. codex plugin remove jev-pruner@jev-pruner-codex
  237. codex plugin add jev-pruner@jev-pruner-codex
  238. ```
  239. Start a new Codex session and review any changed hook through `/hooks`.
  240. Rebuilding the checkout alone does not refresh the installed plugin's cached files.
  241. To uninstall without reinstalling, run only
  242. `codex plugin remove jev-pruner@jev-pruner-codex`. Existing output archives remain
  243. in the projects where the commands ran.
  244. ### Troubleshooting
  245. | Symptom | Check |
  246. | --- | --- |
  247. | `codex: command not found`, or no `plugin` subcommand | Check that npm's global executables are on `PATH` and `codex --version` reports the tested CLI version above. |
  248. | The skill is unavailable | Check `codex plugin list --json`, then start a new session after installation. |
  249. | `dist/codex/run.js` cannot be found | Run `npm ci` and `npm run build` in the checkout, then remove and reinstall the cached plugin as above. |
  250. | Large output is unchanged | Confirm Codex used the wrapper, the hook is trusted, the command succeeded, and the output is eligible. Check API-key availability, Jev network access, and TypeSafe credits; missing access or scoring failures preserve stdout. |
  251. | Jev returns HTTP 402 | Add TypeSafe API credits. Your Codex subscription does not fund Jev requests. |
  252. | Codex reports output truncation | Use the larger `tool_output_token_limit` shown above and read the original archive when available. This limit is separate from the pruning threshold. |
  253. To check key availability without revealing it, ask Codex to run:
  254. ```sh
  255. node -e 'console.log(process.env.TYPESAFE_API_KEY ? "TYPESAFE_API_KEY is set" : "TYPESAFE_API_KEY is missing")'
  256. ```
  257. ### How the Codex wrapper works
  258. The skill runs non-interactive commands through the native Codex shell using
  259. the installed plugin root, not necessarily the source checkout:
  260. ```sh
  261. node "<installed-plugin-root>/dist/codex/run.js" -- npm test
  262. ```
  263. The executable and arguments after `--` are passed directly, preserving cwd,
  264. environment, stdin, stderr, and exit status. Explicitly select a shell for a
  265. shell program (`-- bash -c 'command1 && command2'`). Interactive commands, live
  266. progress streams, servers, and machine-readable nested tool calls should use
  267. the ordinary shell. Stdout is buffered until command completion; above 8 MiB,
  268. the wrapper switches to unchanged streaming to bound memory use. Nonzero exits,
  269. invalid UTF-8, and credential-like commands/output pass through without scoring.
  270. The strict over-10,000-token gate, categories, complete-history partitioning,
  271. verbatim retention, and incomplete-scoring safeguards reuse the same pruning
  272. engine as Claude. The host transcript pointer is stored under
  273. `~/.cache/jev-pruner/codex/<session-id>.json`. `CODEX_THREAD_ID` selects the
  274. current session; the rollout's session ID must match. The adapter reads recorded
  275. user/assistant messages and full tool inputs/results, including custom tools.
  276. It does not load reasoning items or system/developer prompts. Earlier originals
  277. that Codex already truncated or compacted are not reconstructed.
  278. Unavailable, malformed, or mismatched history disables pruning.
  279. Before scoring, original stdout is archived in the command workdir's
  280. `.jev-pruner/` directory with private file permissions and a local `.gitignore`.
  281. Stderr remains unchanged on its original stream. Successful pruning ends with
  282. the archive recovery footer. Archives and transcript pointers persist until
  283. manually removed. API requests time out after 30 seconds and failures preserve
  284. stdout. Jev receives the recorded conversation and tool results; secret detection
  285. is a heuristic for the current command/output, not transcript redaction.
  286. ### Sustained Codex validation
  287. After building and installing the local plugin, authenticate Codex and supply
  288. `TYPESAFE_API_KEY` to run the billable CLI integration test:
  289. ```sh
  290. JEV_CODEX_STAGES=2 npm run test:codex-session # short harness check
  291. npm run test:codex-session # 40 stages, handoff, then archive recovery
  292. ```
  293. Set `JEV_CODEX_PLUGIN_ROOT` if the installed plugin is outside the default
  294. `~/.codex/plugins/cache/jev-pruner-codex/jev-pruner/0.1.0` directory.
  295. Set `JEV_CODEX_MODEL` to select an available Codex model instead of its default.
  296. Reinstall the plugin after rebuilding changed source so the test exercises that revision.
  297. The harness runs this reviewed local plugin with Codex's per-invocation hook-trust
  298. bypass. It retains the `workspace-write` sandbox and enables network access for
  299. Jev; it does not disable command approvals or change persistent Codex settings.
  300. It sets `tool_output_token_limit=30000` for each invocation: a larger shell-call
  301. `max_output_tokens` alone does not override the host's default 10,000-token limit.
  302. Each stage checks required values from an early user requirement and an earlier
  303. tool result, exact retained lines, stderr, pruning markers, archive bytes, and
  304. complete Jev responses. Later stages must exercise parallel history partitions.
  305. The final handoff cannot read archives. A separate turn then requires Codex to
  306. use the archive footer to recover an omitted line with one read-only command;
  307. the full line is withheld from that request. Missing commands, host truncation,
  308. rate limits, timeouts, retention failures, and incomplete runs fail the test.
  309. Private evidence under `~/jev-codex-session-*` includes per-turn CLI events,
  310. header-free Jev requests/responses, per-stage metrics, and the final verdict.
  311. Generate a self-contained HTML report with
  312. `node tests/codex-session-report.mjs <evidence-directory> [...]`.
  313. The report shows the last stage's complete original and model-visible outputs,
  314. the lines retained verbatim, and the archive-recovery command and result.
  315. The synthetic fixture tests sustained history growth; it is not a benchmark of
  316. typical coding sessions.
  317. ### Paired Codex source investigations
  318. With the same installed plugin, Codex login, and TypeSafe key, run
  319. `npm run test:codex-real` to compare native and pruned output on three source
  320. investigations. The test clones the current committed checkout into a private
  321. workspace, runs real repository searches above the token threshold, and checks
  322. each answer against facts withheld from the prompt. It requires actual pruning,
  323. unchanged retained lines, complete native output, and byte-exact archives.
  324. Private evidence is saved under `~/jev-codex-real-tasks-*`. Generate a side-by-side
  325. HTML report with `node tests/codex-real-tasks-report.mjs <evidence-directory>`.
  326. These are code-analysis checks with one run per condition, not implementation
  327. benchmarks or proof of general accuracy or total-cost savings.
  328. ## Claude Code install
  329. The project is named **jev-pruner**, but its current Claude Code plugin and
  330. marketplace identifiers are still `fast-jev-output`. Use those identifiers in
  331. the commands and settings below.
  332. ### 1. Enable function hooks and configure your API key
  333. You need Claude Code with early-access function-hook support and a TypeSafe API
  334. key. In your personal Claude Code settings, merge in:
  335. ```json
  336. {
  337. "env": {
  338. "CLAUDE_CODE_ENABLE_FUNCTION_HOOKS": "1",
  339. "TYPESAFE_API_KEY": "<your key>"
  340. }
  341. }
  342. ```
  343. Replace `<your key>` with your TypeSafe API key. Keep it out of version control.
  344. You can also supply `TYPESAFE_API_KEY` through your shell environment or set the
  345. plugin's `apiKey` option. Restart Claude Code after changing the environment
  346. settings.
  347. Function hooks are early access and may change between Claude Code releases.
  348. The checked-in declarations were generated by Claude Code 2.1.274.
  349. ### 2. Install the plugin
  350. Run in your terminal:
  351. ```sh
  352. claude plugin marketplace add tamaratran/jev-pruner
  353. claude plugin install fast-jev-output@fast-jev-output
  354. ```
  355. Start a new Claude Code session after installation.
  356. ### 3. Use Claude Code normally
  357. No special prompt is required. When an eligible Bash result is pruned, a toast
  358. reports the reduction and the result includes markers where output was removed.
  359. When saved, those markers point to the full output under
  360. `.claude/fast-jev-output/`, which Claude can read if needed.
  361. Not every long result will be trimmed: important output may be kept in full.
  362. ### Local checkout alternative
  363. Instead of the marketplace install, run this from the repository root with your
  364. TypeSafe API key configured as above:
  365. ```sh
  366. CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 claude --plugin-dir .
  367. ```
  368. ## Output the engine saved
  369. When Bash output is too large to show inline, Claude Code saves the whole thing
  370. and hands the model a head-of-file preview — usually the least interesting part.
  371. The plugin prunes that saved file instead, caps the result at
  372. `persistedMaxChars` so it fits inline, and cites the engine's own saved copy in
  373. the markers, so nothing becomes unrecoverable. Set `persistedOutputs` to false
  374. to leave those results alone.
  375. When the host supplies its model-visible preview, that preview's character count
  376. also caps the replacement, including omission markers and the archive footer.
  377. Compressing a large archive must not expand an already-short native preview.
  378. If protected content cannot fit, the original result passes through.
  379. The budget includes omission markers and the archive footer. Reference material,
  380. diagnostics, results, uncertain or task-required content, and output that could
  381. not be fully scored take precedence over this budget. If safe refinement cannot
  382. fit, the original result passes through; failed refinement never falls back to
  383. keeping only error-shaped lines.
  384. Before scoring, a lower bound counts protected diagnostics/results, their adjacent
  385. context, boundary lines, and fixed compact metadata. If these cannot fit, no Jev
  386. request is made. Refinement also stops once lines already retained make a fit
  387. impossible.
  388. The Claude hook allows at most 12 total Jev requests by default, further limited
  389. to `ceil(visibleChars / 192)` (minimum one). `visibleChars` is the smaller of the
  390. native preview size and the configured output cap; without a native preview it
  391. uses the source size capped by the configured output budget. For a 2,146-character
  392. preview this allows twelve requests. This is an effort heuristic, not a pricing or
  393. savings guarantee.
  394. `maxScoringRequests` limits additional calls beyond the first, shared by initial
  395. scoring, retries, and refinement; zero permits one call. The hook default is 11.
  396. Direct library callers retain the default of 40 additional requests and can
  397. override it explicitly. Incomplete scoring always preserves the unscored content.
  398. Requests take one output batch from every history segment before moving to the
  399. next batch, so a limited allowance can still finish scoring some chunks.
  400. A 76,379-char log went from a 2,227-char preview that did not contain the error
  401. line to 4,013 chars of pruned output that did.
  402. ## Configuration
  403. Use `/plugin configure fast-jev-output` inside Claude Code, or merge a
  404. `pluginConfigs` entry into your Claude Code settings:
  405. ```json
  406. {
  407. "pluginConfigs": {
  408. "fast-jev-output@fast-jev-output": {
  409. "options": { "minTokens": 10000, "chunkLines": 20, "keepThreshold": 0.5 }
  410. }
  411. }
  412. }
  413. ```
  414. | Option | Default | Description |
  415. | --- | ---: | --- |
  416. | `apiKey` | `TYPESAFE_API_KEY` | TypeSafe API key |
  417. | `minTokens` | `10000` | Estimated stdout token threshold; minimum 10,000; equality skips pruning |
  418. | `persistedOutputs` | `true` | Prune eligible output saved by Claude |
  419. | `persistedMaxChars` | `8000` | Rendered budget for saved output, including markers and the footer; 0 disables this configured cap. The native preview size, when available, remains an upper bound |
  420. | `maxScoringRequests` | `11` | Additional Jev calls beyond the first; shared across scoring, retries and refinement. Also bounded by visible preview size. 0 permits one call |
  421. | `chunkLines` | `20` | Lines grouped into each Jev decision chunk |
  422. | `chunkChars` | `0` | Optional character target instead of line grouping; 0 uses `chunkLines` |
  423. | `diagnostics` | `false` | Log decision reasons, source/hook sizes, native model-visible size before pruning when available, request count and elapsed time; no commands or output text |
  424. | `keepThreshold` | `0.5` | Minimum Jev probability for a chunk to remain; the uncertainty safeguard also retains scores above `0.1` |
  425. | `maxStateTokens` | `25000` | Estimated token budget for the Jev state |
  426. | `model` | `jev-latest` | TypeSafe Jev model name |
  427. The old `minChars` option is no longer used; replace it with `minTokens`.
  428. Diagnostics distinguish the complete source from the host's preview and the
  429. native text the model would have seen. The post-pruning model-visible size must
  430. be read from the final transcript: the host may persist the returned text again.
  431. Character counts are UTF-16 code units, not billed tokens. Library callers may
  432. use `onDecision(reason)` in `trimOutput` options for the terminal decision.
  433. ## Data and privacy
  434. Jev receives command output and partitioned conversation context through the TypeSafe
  435. API to decide what to keep. The main LLM receives the pruned result when trimming
  436. succeeds. Jev requests incur API usage.
  437. Full output is saved locally before the first scoring request. The archive directory
  438. is self-gitignored. Credential-like commands or output detected by the plugin
  439. are not archived; their markers say to re-run the command instead. **This check
  440. only prevents local archiving—it does not redact secrets or prevent content
  441. from being sent to Jev.**
  442. ## Tests
  443. Run the offline checks with `npm test`, `npm run typecheck`, and `npm run build`.
  444. `npm run validate:plugin` checks the plugin with the installed Claude Code CLI.
  445. For live Jev checks, provide `TYPESAFE_API_KEY` in the environment and run
  446. `npm run test:live`. This makes billable requests using synthetic conversation
  447. and output fixtures. It checks task-dependent retention, tool-result inclusion,
  448. parallel history/output batching, digit-heavy state budgets, paired comparisons
  449. of general versus category guidance on build and search fixtures, and the hook's behavior when Jev
  450. rejects authentication. It runs separately from `npm test` and does not exercise
  451. the Claude Code host itself.
  452. ### Long Claude Code session
  453. With an authenticated Claude CLI and `TYPESAFE_API_KEY` in the environment, run
  454. `npm run test:long-session`. This starts one continuous Claude process, loads the
  455. production plugin plus a test-only observer, and runs a bootstrap followed by
  456. 40 noisy Bash commands against synthetic fixtures. Both Claude and Jev incur
  457. API usage; the Claude process has a $10 budget. Each prompt explicitly confirms
  458. the finite benchmark because Claude may otherwise decline the repeated
  459. simulated failures. If a stage contains no tool call, the runner sends one
  460. direct confirmation in the same session; a second refusal stops the run.
  461. Confirmations are saved in the evidence and counted as additional user turns.
  462. The one-command-per-stage and retention assertions still apply.
  463. Set `JEV_LONG_SESSION_BUDGET_USD` to override the Claude cap for longer runs,
  464. for example `JEV_LONG_SESSION_TURNS=100 JEV_LONG_SESSION_BUDGET_USD=25 npm run test:long-session`.
  465. The selected cap and stage count are saved with the evidence; the cap excludes Jev charges.
  466. `npm run test:archive-recovery` runs a separate two-turn Claude session. It checks
  467. that an unpredictable cache hash is absent from the compacted output, then asks
  468. Claude to recover it using `Read` and the archive footer. Each CLI invocation
  469. has a $2 Claude cap; this billable test requires the same authentication as the
  470. long-session test.
  471. The test checks early requirements, tool-result inclusion,
  472. target bundle and rollback retention, archives, stderr, history partitioning, and
  473. the final answer. Conversation text that quotes tool output is preserved.
  474. Raw events and header-free Jev request/response captures are saved under
  475. `~/jev-long-sessions/`. The path is printed when the run starts.
  476. Run `npm run report:long-session -- <evidence-directory>` to generate a
  477. self-contained HTML evidence report. For a quick harness smoke check,
  478. set `JEV_LONG_SESSION_TURNS=2`; runs of at least 40 stages require history-partitioning coverage.
  479. Use `JEV_LONG_SESSION_DIR` to choose a different persistent output directory.
  480. The long test is separate from the offline suite and `test:live`.
  481. Retention failures produce a failing exit status and a summary containing all
  482. misses. To reanalyze saved evidence without making API calls, run
  483. `npm run test:long-session -- --analyze <evidence-directory>`.
  484. Related: [fast-jev-compaction](https://github.com/tamaratran/fast-jev-compaction)
  485. (same author) applies Jev to session compaction; the two are independent and
  486. can be installed together.
  487. ## Animated demo (macOS)
  488. `demo/JevPrunerDemo` matches the dark terminal, scanning beam and collapsing
  489. output of the fast-jev-compaction demo. An `npm install` is followed by a scan,
  490. pruning, and a pause on the retained summary. The terminal's top bar
  491. shows estimated output tokens. There are no surrounding captions or sidebar.
  492. Retained text stays verbatim and a saved-log card shows where the original
  493. output can be read.
  494. `npm-install.json` records each output line's arrival time and the process
  495. duration from an actual install of a small React project with
  496. `npm_config_loglevel=verbose`; the displayed command remains `npm install`.
  497. Machine-specific CLI, log-file and working-directory metadata were removed.
  498. The original install takes **4.648 seconds**. Playback shortens gaps between
  499. visible output arrivals to at most **0.35 seconds**, so the preview does not
  500. appear stalled while unshown lines arrive. Shorter intervals retain their
  501. recorded timing. The same time mapping drives the token count and completion.
  502. The install now plays in approximately **1.85 seconds**; the complete animation
  503. is approximately **5.6 seconds**, including scanning, a smooth shared collapse
  504. and a 1.25-second final hold.
  505. Representative rows append and stay in place, instead of cycling a scrolling
  506. viewport or switching to a different layout at completion. The status labels
  507. the shortened pauses. Export plays once; Space manually replays the native app.
  508. This is recorded playback, not a live install or benchmark; it makes no API
  509. requests. The pruning animation and keep/drop decisions are illustrative at
  510. line granularity, rather than the default 20-line chunks.
  511. Token estimates use one token per four characters of the capture and the
  512. illustrated compact text, including its archive marker; they are not measured
  513. model usage. Omission markers are shortened for readability.
  514. The full-output path uses the plugin's existing `fast-jev-output` directory.
  515. Requires macOS 14+ and the Xcode command-line tools. No extra packages are needed.
  516. ```sh
  517. demo/JevPrunerDemo/build.sh # build and open; Space replays
  518. demo/JevPrunerDemo/build.sh --no-launch # build without opening a window
  519. demo/JevPrunerDemo/build.sh --export "$PWD/demo/JevPrunerDemo/build/jev-pruner.mp4"
  520. demo/JevPrunerDemo/build.sh --frame 5 "$PWD/demo/JevPrunerDemo/build/poster.png"
  521. ```
  522. Export renders the same timeline directly to a 1100×720 H.264 MP4 at 30 fps.
  523. Use a new output filename for each movie export; existing movies are not
  524. overwritten. Build products and exports under the demo's `build/` are ignored.

Ratings and comments

Sign in to rate this skill.

Sign in

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