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 window 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. 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 ./.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.

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, 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.

Usage