compact-adviser

How we reviewed this: we ran the four packages’ test suites in Docker on Node 24, then drove the judge module directly against the live Jev API with four synthetic checkpoints — a finished hands-on unit, a mid-task pause, a finished coordination turn, and a blocker handed back to the human — and ran each through the scoring and floor logic at three levels of context usage. We didn’t install it into a live Pi, Claude Code, Codex or Grok session.

What it does

compact-adviser answers one question: should I /compact now? Compact too early and you burn a summary you didn’t need; compact mid-task and the agent loses the thread it was holding.

It hooks into Pi, Claude Code, Codex CLI and Grok Build. After a settled turn, cheap local gates run first — a mode check, a 40,000-token minimum, an idle session, a key, cooldowns — and only then does one Jev request go out with two one-sentence questions:

• done: is the assistant’s latest unit of work finished? (Waiting on a human counts as finished.)
• shape: did the assistant do the work itself, or mostly coordinate others?

Code composes the two into one score — finished × (0.5 + 0.5 × hands_on) — and compares it against a floor that slides with how full your context is: 0.90 while the window is nearly empty, relaxing toward 0.50 as it fills. The reasoning is worth stealing: a wrong hint costs most when there’s plenty of room left and least when compaction is about to happen anyway.

On Pi and Claude Code it can run /compact for you if you opt in, after a first-use confirmation. Codex and Grok are hint-only, because nothing outside those sessions can trigger a compaction — the README explains exactly why for each host, which is unusually candid.

The judgment, on real calls

We fed four checkpoints through the real thing. The right-hand columns are the same judgment at three levels of context usage:

Checkpoint	finished	hands-on	score	5% full	50%	85%
Feature shipped, 62 tests green, “anything else?”	1.00	1.00	1.00	hint	hint	hint
Mid-task: read the file, about to write the loop	0.00	0.63	0.00	quiet	quiet	quiet
Surveyed the repo with subagents, asked which to take first	0.98	0.00	0.49	quiet	quiet	quiet
Blocked on a missing DATABASE_URL, handed back	0.99	0.35	0.67	quiet	quiet	hint

That last row is the design in one line. The work is genuinely parked, but interrupting a session to compact at 5% full would be pointless; at 85% full, with compaction imminent anyway, this is as good a boundary as you’ll get. The same judgment produces different advice because the cost of being wrong changed.

The mid-task case scored a flat zero, which is what you want from a gate that must not fire while the agent is holding state.

What the scoring means in practice

A coordinating session can barely ever qualify. With hands_on at zero the score tops out at 0.50, and the loosest floor is 0.50, so only a perfectly confident “finished” at 90%-plus usage squeaks through. If your sessions are mostly research, review, or dispatching subagents, expect this to stay silent — which the author would call working as intended (the rationale in the code is that follow-ups in coordinating sessions tend to reach back into older context), but it’s worth knowing before you install it and wonder why it never speaks.

You can change all of it. A judge profile replaces the questions, the weight between the two, or the floor schedule, in a bounded JSON setting, on any of the four hosts. Invalid profiles disable advice rather than falling back, and loading a profile never grants automatic-mode consent. Both are the right defaults.

Tests

• Pi extension: 62 of 64 passed. The two failures are in the evaluation harness, which shells out to labelling CLIs we don’t have installed.
• Codex plugin: 61 of 61. Grok plugin: 46 of 46.
• Claude mod: needs the claude binary to run its tests; we didn’t run those.
• A lockstep test enforces that all four packages send byte-identical request bodies and score judgments identically. That’s a real risk in a four-host plugin, and they test for it.

Permissions and data

The README has a table of what’s sent and what isn’t, and the code matches it:

• Sent: bounded user constraints, up to the last 64 visible replies and tool results (clipped, with a 512-byte cap per tool result), an existing summary, saved-artifact names, and markers saying what was omitted. Capped at 32,000 bytes per request, to api.typesafe.ai.
• Not sent: system prompts, hidden reasoning, images, environment variables, full transcripts, and the API key — which is a header, never part of the state.
• Redaction is best-effort, and they say so. Tool results reading .env, auth.json, id_rsa, *.pem and *.key are replaced wholesale; the adviser’s own saved key is stripped from settings output; known secret patterns are scrubbed. The README’s own words: not a guarantee, so uninstall or switch to Off for material that must not leave the machine. We’d rather read that than a promise.
• Installing is consent. Stated plainly in the quickstart: installing the package means eligible checkpoint context goes to TypeSafe once a key is present and the gates pass. COMPACT_ADVISER_DISABLE=1 makes a session inert — no request, no hint, no command — and the README tells you to set it for unattended runs.
• A failed judgment never becomes a yes. Timeouts, rate limits, auth failures and unparseable replies all leave the context untouched, with a message that distinguishes “this may be temporary” from “check your key”.

Maintenance

19 commits since September 18, MIT licensed, with a changelog, a security policy, contributing guide, release automation and four packaged integrations. The documentation goes into host-specific detail most projects skip — including a workaround for Grok 1.0.34 not loading a plugin’s own hooks file, and a warning not to type secrets after a Grok slash command because Grok forwards those words to the model. Version 0.1.4, so still early, but it doesn’t read early.

Verdict

This is a small idea executed with unusual care: two atomic questions, composed in code, measured against a threshold that moves with the cost of being wrong. In our tests it was decisive where it should be and silent where it should be, and the sliding floor did real work rather than decorating the README.

Install it if you compact by guesswork today and your sessions are hands-on. Skip it — or write a profile — if your agent mostly coordinates, because the default scoring is built to keep quiet there. And before turning on automatic mode, read the data table: this one sends your recent conversation, not just a diff.

For other context-window tools, see fast-jev-compaction, which edits what compaction keeps rather than choosing when to run it. Our Best Jev Tools roundup compares what each tool sends.

See how it compares with other tools in Best Jev tools, tested hands-on.

Review updated Sep 20, 2026. Numbers quoted from the project are its author's own; we don't publish our own measurements of Jev.