# fast-jev-compaction Claude Code mod

This plugin uses Claude Code function hooks to replace a compaction with the
original messages, minus the tool calls and tool results Jev judged no longer
needed. `hooks/fast-jev.ts` is a thin adapter: it reads the plugin options,
finds the TypeSafe key, hands `session.compact` transcripts to the
`fast-jev-compaction` library in `src/` (the plugin folder is the repository
root, so the hook imports it directly) and maps the result back onto session
messages. User and assistant text is never touched. Jev is sent the whole
conversation as `state` (tool outputs replaced by a one-line note) and, for
every tool call outside the pinned first and newest messages, two questions:
whether the call should stay and whether its full output should stay. An
item is kept when Jev's probability reaches `keepThreshold`; a dropped result
is truncated to its first `truncateHeadChars` characters plus a one-line note,
and a dropped call disappears with its result.

The state is fitted into `maxStateTokens` in stages: tool inputs are
truncated, then long texts are abridged (oldest first, pinned messages last),
then old messages collapse to a `[… N chars omitted …]` note, then old tool
calls shrink to one line each, then old call-less messages are left out and
runs of old call-only messages fold together. Questions are split into as many requests as
needed so each request (state plus questions) stays under `maxRequestTokens`;
the full state is resent with every request. Token counts are estimated
without a tokenizer, calibrated to land a little above what Jev reports.

The mod is an early-access Claude Code function-hook module. The checked-in
type reference was generated by Claude Code **2.1.274**. Enable the function
hooks surface before installing or loading it:

```sh
export CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1
export TYPESAFE_API_KEY="<your TypeSafe key>"

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

For local development:

```sh
CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 claude --plugin-dir .
```

## Configuration

The plugin declares these `userConfig` values in
`.claude-plugin/plugin.json`:

| Option | Default |
| --- | ---: |
| `keepThreshold` | `0.5` |
| `preserveRecentMessages` | `6` |
| `compactAtPercent` | `60` |
| `minReductionRatio` | `0.25` |
| `maxStateTokens` | `25000` |
| `maxRequestTokens` | `30000` |
| `truncateHeadChars` | `300` |
| `model` | `jev-latest` |

The TypeSafe key can be supplied as the sensitive `apiKey` plugin option or
through `TYPESAFE_API_KEY`. The environment variable is the recommended
development setup.

Every option except `apiKey`, `compactAtPercent`, `minReductionRatio` and
`model` is passed straight to the library; see the root README for what they
do. The `session.compact` hook runs the Jev requests concurrently. If Jev fails,
the response is malformed, the key is unavailable, the history cannot be
fitted into the state budget, or the estimated reduction is below
`minReductionRatio`, the hook logs a fallback and delegates to Claude Code's
built-in compaction. The outcome is shown as a toast and logged with the
reduction, per-reason counts, state size and request count; a per-call
`decisions:` line with both probabilities is logged for diagnosis. The
`turn.complete` hook requests
compaction when `context.percent` reaches `compactAtPercent`, with an
in-flight guard.

## Scope and caveat

Function hooks are early access and may change between Claude Code releases.
This mod uses the generated declarations from 2.1.274 in
`types/claude-code.d.ts`; regenerate and review that file after a
Claude Code upgrade.

References:

- [Claude Code plugins](https://code.claude.com/docs/en/plugins)
- [Claude Code plugins reference](https://code.claude.com/docs/en/plugins-reference)
- [Claude Code hooks](https://code.claude.com/docs/en/hooks)