compact-adviser

compact-adviser is an agent plugin that answers a single question: should I /compact now?

It uses Jev to instantly judge whether the current session is likely at a boundary that's safe to compact.

It can give you a hint to run /compact - or, on Pi and Claude Code, if you opt in, it can run it for you at the right time automatically. Codex CLI and Grok are hint-only: nothing outside their sessions can trigger /compact.

Judgment is two one-sentence Jev questions in one request (is the unit finished; is this hands-on work or coordination), composed in code into one score. The hint floor is 0.90 while the context is mostly empty (through about 10%) and relaxes toward 0.50 by about 90% full - a wrong hint costs most when there is still room. "Full" means the point where the host compacts: on Claude Code that is its auto-compact threshold when enabled, elsewhere the model's window. If you would rather compact well before that (long contexts cost more every turn), set a context budget: the floor then relaxes as the context approaches the smaller of your budget and that point. Automatic mode is the same gate, plus a first-use confirmation.

Quick Start

Prerequisites: Node 22+ (22.18+ for Codex and Grok), and one of Pi 0.82.0 or newer (verified on 0.85.1), Claude Code 2.1.274 or newer (verified on 2.1.275), Codex CLI 0.153.0 or newer (verified on 0.153.4), or Grok Build 1.0.34 or newer (verified on 1.0.34), plus a TypeSafe API key. Supply it as TYPESAFE_API_KEY in the launch environment or put it in the session cwd's ./.env; Pi and Claude Code can also save it through their settings, while Codex and Grok provide an external compact-adviser CLI. Jev is TypeSafe's structured decision model; this package asks it two one-sentence classification questions and never asks it to write a summary.

Installing the package is consent to send eligible checkpoint context to TypeSafe when a key is available and the other product gates pass. With TYPESAFE_BASE set, that context and the key go to that base instead.

Pi

pi install npm:compact-adviser

Restart Pi or run /reload, then /compact-adviser. /compact-adviser status should say Key: env, Key: saved, or Key: .env.

To install from git: pi install git:github.com/kunchenguid/compact-adviser (add -l for project-local).

Claude Code

This plugin uses Claude Mod which is an experimental feature that requires CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 in your environment.

claude plugin marketplace add kunchenguid/compact-adviser
claude plugin install compact-adviser@compact-adviser
CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 claude

Then /compact-adviser.

Codex CLI

Codex support is macOS and Linux only. The plugin's hooks run through POSIX sh, matching this repository's platform badge; Windows is not supported this ship.

codex plugin marketplace add kunchenguid/compact-adviser
codex plugin add compact-adviser@compact-adviser

Restart Codex and review the hook in /hooks once, so it is trusted. After a completed checkpoint the advice appears as a ↳ Hook · Compact adviser: ... line under the answer.

Codex is hint-only: it has no surface that lets another process run /compact, so there is no automatic mode there. Settings live in a small CLI instead of a slash command; ask Codex for "compact-adviser status" and the bundled skill runs it, or run it yourself:

node "$(ls -d "${CODEX_HOME:-$HOME/.codex}"/plugins/cache/*/compact-adviser/*/ | tail -1)src/cli.ts" status

Grok Build

Grok is hint-only: nothing outside a running session can trigger /compact, so there is no automatic mode here. The hint is painted on the status row and never enters the model's context.

grok plugin install kunchenguid/compact-adviser#packages/grok-plugin --trust

(Install from the subdirectory, not the repository root: Grok also reads the Claude marketplace index in this repo, so a plain grok plugin marketplace add offers two plugins of the same name and refuses an unqualified install.)

Then two one-time steps, because Grok does not let a plugin do either of them for you. Start Grok and run:

/compact-adviser-install

That writes ${GROK_HOME:-~/.grok}/hooks/compact-adviser.json, because Grok 1.0.34 lists a plugin's own hooks/hooks.json but never loads it into a session. Hooks in your own Grok home are always trusted, so nothing else is needed; delete that file to remove them. From a shell it is node "$(node -e 'const l=JSON.parse(require("child_process").execFileSync("grok",["plugin","list","--json"],{encoding:"utf8"})); const p=(Array.isArray(l)?l:[]).find(x=>x&&x.name==="compact-adviser"); if(!p||typeof p.path!=="string") throw new Error("compact-adviser is not installed"); process.stdout.write(p.path)')/bin/adviser.ts" install. After install, ${GROK_HOME:-~/.grok}/compact-adviser/adviser.sh resolves the currently installed plugin the same way.

Then paste the [ui.status_line] block install printed into the config.toml path it named and restart Grok. The status row is off by default and only your own config can turn it on - a plugin cannot, and neither can a repository. Grok has one status row, so this script paints the built-in segments (cwd, model, context) too. Minimal render mode has no status row at all.

On Grok, save the TypeSafe key as TYPESAFE_API_KEY or a cwd .env, or with the CLI key command from a shell outside Grok. Do not type secrets after a Grok slash command; Grok appends those words to the model.

If it does nothing

Environment variables

Export COMPACT_ADVISER_DISABLE=1 for unattended agent sessions, where advice has nobody to read it.

What is sent to TypeSafe

Requests go to https://api.typesafe.ai/v1/systemone, or <TYPESAFE_BASE>/v1/systemone when that is set, are capped at 32,000 serialized UTF-8 bytes, and never treat an error as an affirmative judgment. The TypeSafe API key never enters the model context or the request body; it is sent as the Authorization header to authenticate the call. Details: SECURITY.md.

How It Works

settled turn
      │
      ▼
┌───────────────────┐
│ cheap local gates │  mode, 40k minimum, idle session, key, cooldowns
└─────────┬─────────┘
          ▼
┌───────────────────┐
│ TypeSafe Jev      │  done × shape score, floor slides 0.90→0.50 with usage
└─────────┬─────────┘
          ▼
 hint: run /compact     or, with explicit auto, native compaction

Automatic compaction is available on Pi and Claude Code. On Codex the same judgment only ever produces the hint, as a ↳ Hook · line in the scrollback. On Grok the two halves are separate processes: a Stop hook judges and records a verdict, and the [ui.status_line] script reads that verdict and paints the hint. The Grok hook always allows the stop and prints nothing, so a hint can never be fed back to the model.

On Claude Code, an optional beforeCompactPrompt setting (empty by default; set it in /config) runs one turn before that automatic compaction, and only after auto mode is confirmed. Set it to /stow to run the stow command first. Claude Code does not expand slash commands or @file mentions in a prompt a plugin submits, and it rejects a plugin prompt that starts with /, so a value that starts with / is run as a command instead of being sent to the model as text. If you send your own prompt or run a command in between, or that turn is interrupted, errors, or does not finish within 5 minutes, nothing is compacted. Hint mode, off, and an empty setting are unchanged. Pi, Codex, and Grok do not have this setting.

Usage