Compact Adviser Claude Code mod: know when to run /compact in Claude Code

Compact Adviser tells you when to run /compact in Claude Code. It answers one question: should I run /compact now? It is written by Kun Chen (kunchenguid) and ships for Claude Code, Pi, Codex CLI and Grok from one repository. This page covers the Claude Code mod in packages/claude-mod.

Compacting too early throws away context you still need; compacting too late means every turn carries a long history. After each finished turn, the mod checks a few cheap local conditions and, when they pass, asks TypeSafe's Jev model two short questions about the conversation: is the assistant's latest unit of work finished, and did the assistant do the work itself or mostly coordinate? The two answers are combined into one score. If the score clears a floor, a status line appears: "work appears completed or recorded. Run /compact to save tokens."

The floor is strict (0.90) while the context is mostly empty and relaxes toward 0.50 as the context approaches Claude Code's auto-compact point, because a wrong hint costs most when there is still room. If you opt in to automatic mode, the mod runs the compaction itself at such a checkpoint instead of only hinting.

It needs a TypeSafe API key, which you supply yourself.

A real hint needs more than 40,000 tokens of context and a TypeSafe key, which does not fit a short clip. The recording starts Claude Code with the mod loaded, runs /compact-adviser status (mode, minimum, budget and key state), then opens the /compact-adviser settings pane and moves to the TypeSafe API key row, which shows missing.

Use either method in the install block; both install straight from the author's marketplace. The mod is a complete no-op unless Claude Code starts with CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1, so launch it with that variable, then run /compact-adviser to add your TypeSafe key.

Everything starts in the turn.complete hook in hooks/register.ts:

on("turn.complete", async ($, e, next) => {
  const result = await next(e);
  if (!(await isActivated($)) || !interactive) return result;
  if (e.agentId !== undefined || e.reason !== "answer" || e.isAborted || !e.answer.trim()) {
    return result;
  }
  try {
    await settle($);
  } catch {
    notice($, "Compact adviser could not inspect this checkpoint; context left unchanged.");
  }
  return result;
});

Only a main-loop turn that ended with a real answer counts; subagent turns and aborted turns are skipped. settle counts the exchange and runs the cheap gates: mode not off, a key present, context at or above minContextTokens, and no cooldown or snooze. If they pass, it schedules judgeCheckpoint with $.clock.after(0, …) so the turn is not held up.

judgeCheckpoint builds a bounded snapshot from $.session.messages() (see lib/snapshot.ts), skips the request if the conversation is under 20,000 tokens or the same checkpoint was already judged, and posts it to https://api.typesafe.ai/v1/systemone with $.http.fetch. The request times out after 2 seconds, and an error, a timeout or a malformed reply never counts as a yes: the mod backs off and shows a toast instead. When the score qualifies, hint mode calls $.ui.status with the hint, and auto mode calls $.session.compact with instructions to keep the current work, pending tasks and next step exact.

Any compaction, yours or Claude Code's, resets the session's cooldown through the session.compact hook.

Run /compact-adviser to open the settings pane, or use its subcommands: auto, hint and off switch the mode; threshold 60000 sets the minimum context; budget 450000 sets a context budget the floor measures against instead of the auto-compact point; snooze skips the next three exchanges; dismiss clears the current hint; status prints the current state. The mode, minimum, budget and request logging are also rows in /config. A judge profile (JSON in the profile setting) can change the questions, the score weight or the floor schedule.

We read register.ts, every file under lib/, plugin.json, hooks.json, package.json and the test helpers before running anything.

• Network: the mod sends one request per qualifying checkpoint to https://api.typesafe.ai/v1/systemone, a third-party service, with your key in the Authorization header. The body is a snapshot of recent conversation, capped at 32,000 bytes, after best-effort redaction of key patterns, .env, auth.json, id_rsa/id_ed25519, .pem and .key files. TYPESAFE_BASE can point it at another https base, or at a loopback http one. Installing the plugin is treated as consent to send this when a key is available, so set the mode to off for work that must not leave your machine.
• Files: it reads .env in the session folder to look for TYPESAFE_API_KEY. It writes only when you turn on request logging: ~/.claude/compact-adviser-requests-<session-id>.jsonl, which never contains the key.
• Settings: saving from the pane writes the plugin's own userConfig rows through $.config.set. The saved key is hidden from /config.
• Compaction: only in automatic mode, after a one-time confirmation dialog.

There are no install scripts, no bundled or minified code, and no telemetry beyond the TypeSafe request itself.

Validated with Claude Code 2.1.291: claude plugin validate passes with no warnings, and claude plugin test runs 114 tests, all passing. The author lists Claude Code 2.1.274 or newer. If nothing happens, check these in order:

• /compact-adviser is missing: CLAUDE_CODE_ENABLE_FUNCTION_HOOKS is not exactly 1, or COMPACT_ADVISER_DISABLE is set.
• /compact-adviser status says Key: missing: add a key in the pane, the environment or ./.env.
• The command works but no hint appears: the context is below the minimum, or the last turn did not end with a settled answer.
• A toast mentions "nonessential network traffic": CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC blocks the request to TypeSafe.
• claude -p sessions are always inactive by design.