Skip to content
Back to search

compact-adviser

A single-plugin marketplace for compact-adviser, which tells you when your Claude Code session has reached a good point to run /compact.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/kunchenguid--compact-adviser/badge.svg)](/listings/kunchenguid--compact-adviser)

HTML

<a href="/listings/kunchenguid--compact-adviser"><img src="/api/listings/kunchenguid--compact-adviser/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites: Node 22+ (22.18+ for Codex and Grok), and one of [Pi](https://pi.dev) 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](https://docs.x.ai/build/overview) 1.0.34 or newer (verified on **1.0.34**), plus a [TypeSafe API key](https://console.typesafe.ai/settings/keys). 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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 30 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "compact-adviser",
  3. "description": "A single-plugin marketplace for compact-adviser, which tells you when your Claude Code session has reached a good point to run /compact.",
  4. "owner": {
  5. "name": "Kun Chen",
  6. "url": "https://github.com/kunchenguid"
  7. },
  8. "plugins": [
  9. {
  10. "name": "compact-adviser",
  11. "source": "./packages/claude-mod",
  12. "description": "Stop guessing when to run /compact. Watches your session and suggests compaction at a completed checkpoint - after work lands, not mid-task - so you keep context you still need and drop what you do not. Optionally compacts for you. Judgment runs through the TypeSafe Jev API and needs your own key.",
  13. "version": "0.1.14",
  14. "category": "productivity",
  15. "author": {
  16. "name": "Kun Chen"
  17. },
  18. "homepage": "https://github.com/kunchenguid/compact-adviser#readme",
  19. "repository": "https://github.com/kunchenguid/compact-adviser",
  20. "license": "MIT",
  21. "keywords": [
  22. "compact",
  23. "context",
  24. "context-management",
  25. "checkpoint",
  26. "productivity"
  27. ]
  28. }
  29. ]
  30. }
README.md · README · 211 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <h1 align="center">compact-adviser</h1>
  2. <p align="center">
  3. <a href="LICENSE"
  4. ><img
  5. alt="License"
  6. src="https://img.shields.io/badge/license-MIT-green?style=flat-square"
  7. /></a>
  8. <a
  9. href="https://img.shields.io/badge/platform-macOS%20%7C%20Linux-blue?style=flat-square"
  10. ><img
  11. alt="Platform"
  12. src="https://img.shields.io/badge/platform-macOS%20%7C%20Linux-blue?style=flat-square"
  13. /></a>
  14. <a href="https://x.com/kunchenguid"
  15. ><img
  16. alt="X"
  17. src="https://img.shields.io/badge/X-@kunchenguid-black?style=flat-square"
  18. /></a>
  19. <a href="https://discord.gg/Wsy2NpnZDu"
  20. ><img
  21. alt="Discord"
  22. src="https://img.shields.io/discord/1439901831038763092?style=flat-square&label=discord"
  23. /></a>
  24. </p>
  25. **compact-adviser** is an agent plugin that answers a single question: should I /compact now?
  26. ![Compact adviser status line: "Compact adviser: work appears completed or recorded. Run /compact to save tokens." shown above a terminal prompt](docs/hint-status-line.png)
  27. It uses [Jev](https://typesafe.ai) to instantly judge whether the current session is likely at a boundary that's safe to compact.
  28. 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`.
  29. 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.
  30. ## Quick Start
  31. Prerequisites: Node 22+ (22.18+ for Codex and Grok), and one of [Pi](https://pi.dev) 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](https://docs.x.ai/build/overview) 1.0.34 or newer (verified on **1.0.34**), plus a [TypeSafe API key](https://console.typesafe.ai/settings/keys). 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.
  32. 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.
  33. ### Pi
  34. ```sh
  35. pi install npm:compact-adviser
  36. ```
  37. Restart Pi or run `/reload`, then `/compact-adviser`.
  38. `/compact-adviser status` should say `Key: env`, `Key: saved`, or `Key: .env`.
  39. To install from git: `pi install git:github.com/kunchenguid/compact-adviser` (add `-l` for project-local).
  40. ### Claude Code
  41. This plugin uses Claude Mod which is an experimental feature that requires `CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1` in your environment.
  42. ```sh
  43. claude plugin marketplace add kunchenguid/compact-adviser
  44. claude plugin install compact-adviser@compact-adviser
  45. CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 claude
  46. ```
  47. Then `/compact-adviser`.
  48. ### Codex CLI
  49. Codex support is **macOS and Linux only**. The plugin's hooks run through POSIX `sh`, matching
  50. this repository's platform badge; Windows is not supported this ship.
  51. ```sh
  52. codex plugin marketplace add kunchenguid/compact-adviser
  53. codex plugin add compact-adviser@compact-adviser
  54. ```
  55. Restart Codex and review the hook in `/hooks` once, so it is trusted. After a completed
  56. checkpoint the advice appears as a `↳ Hook · Compact adviser: ...` line under the answer.
  57. Codex is **hint-only**: it has no surface that lets another process run `/compact`, so there is
  58. no automatic mode there. Settings live in a small CLI instead of a slash command; ask Codex for
  59. "compact-adviser status" and the bundled skill runs it, or run it yourself:
  60. ```sh
  61. node "$(ls -d "${CODEX_HOME:-$HOME/.codex}"/plugins/cache/*/compact-adviser/*/ | tail -1)src/cli.ts" status
  62. ```
  63. ### Grok Build
  64. 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.
  65. ```sh
  66. grok plugin install kunchenguid/compact-adviser#packages/grok-plugin --trust
  67. ```
  68. (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.)
  69. Then two one-time steps, because Grok does not let a plugin do either of them for you. Start Grok and run:
  70. ```
  71. /compact-adviser-install
  72. ```
  73. 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.
  74. 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.
  75. 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.
  76. ## If it does nothing
  77. | Symptom | Cause |
  78. | --- | --- |
  79. | TypeSafe requires payment (HTTP 402) | Check the TypeSafe account's billing and credits; waiting alone will not resolve a payment requirement. Context stays unchanged. |
  80. | `Key: missing` in `/compact-adviser status` (Pi, Claude Code) or `/compact-adviser` (Grok) | No `TYPESAFE_API_KEY` in the launch environment, saved settings, or the session cwd's `./.env` |
  81. | No `/compact-adviser` command in Claude Code | `CLAUDE_CODE_ENABLE_FUNCTION_HOOKS` is not exactly `1` |
  82. | Command exists, no hint | Context is below the constant 40,000-token minimum, the session is not idle, or the last turn was not a settled final answer |
  83. | Claude Code: "nonessential traffic" | `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` blocks plugin network requests |
  84. | No hint in Codex | The hook is untrusted (review it in `/hooks`), Node is older than 22.18, or the hook cannot find Node at all - Codex rebuilds its PATH, so set `COMPACT_ADVISER_NODE` to an absolute `node` path |
  85. | Grok: no hint row at all | `[ui.status_line]` is not set in the `config.toml` `install` named, or Grok is in minimal render mode |
  86. | Grok: no hint after a completed turn | `/compact-adviser-install` has not run, so no Stop hook is judging |
  87. | Pi print / RPC / JSON, Claude `-p`, or `codex exec` | The adviser stays inert in reliably detected non-interactive sessions |
  88. | Nothing at all, in any host | `COMPACT_ADVISER_DISABLE` is set to a truthy value |
  89. ## Environment variables
  90. | Variable | Effect |
  91. | --- | --- |
  92. | `TYPESAFE_API_KEY` | The Jev key; a saved key or the session cwd's `./.env` is used when this is unset |
  93. | `TYPESAFE_BASE` | Replaces the TypeSafe API base URL, `https://api.typesafe.ai` by default; the request goes to `<base>/v1/systemone` with a trailing slash dropped. Read from the launch environment only, never a saved setting or `./.env`. It must be an `https` URL; plain `http` is accepted only for a loopback host (`127.0.0.1`, `[::1]`, `localhost`). Any other value, or one that carries credentials, a query or a fragment, is a configuration error: no request and no advice |
  94. | `COMPACT_ADVISER_DISABLE` | `1`, `true`, `yes` or `on` (any case) makes the session inert: no TypeSafe request, no hint, no automatic compaction, no command. It wins over a saved `hint` or `auto` mode |
  95. | `CLAUDE_CODE_ENABLE_FUNCTION_HOOKS` | Claude Code only; must be exactly `1` for the mod to load |
  96. | `COMPACT_ADVISER_NODE` | Codex only; absolute path to a Node 22.18 or newer executable when the hook cannot find one on its rebuilt PATH |
  97. Export `COMPACT_ADVISER_DISABLE=1` for unattended agent sessions, where advice has nobody to read it.
  98. ## What is sent to TypeSafe
  99. | Included | Not sent |
  100. | --- | --- |
  101. | Bounded user constraints, up to the last 64 visible replies and tool results (clipped), short tool-result excerpts, an existing summary, saved-artifact names, omission markers | System prompts, hidden reasoning, images, environment variables, the API key in the model context and request body, complete transcripts |
  102. | Best-effort redaction of known key patterns and obvious sensitive-file results | A guarantee. Uninstall or set mode Off for material that must not leave the machine |
  103. 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.
  104. The TypeSafe API key never enters the model context or the request body; it is sent as the Authorization header to authenticate the call.
  105. Details: [SECURITY.md](SECURITY.md).
  106. ## How It Works
  107. ```
  108. settled turn
  109. │
  110. ▼
  111. ┌───────────────────┐
  112. │ cheap local gates │ mode, 40k minimum, idle session, key, cooldowns
  113. └─────────┬─────────┘
  114. ▼
  115. ┌───────────────────┐
  116. │ TypeSafe Jev │ done × shape score, floor slides 0.90→0.50 with usage
  117. └─────────┬─────────┘
  118. ▼
  119. hint: run /compact or, with explicit auto, native compaction
  120. ```
  121. Automatic compaction is available on Pi and Claude Code. On Codex the same judgment only ever
  122. produces the hint, as a `↳ Hook ·` line in the scrollback. On Grok the two halves are separate
  123. processes: a `Stop` hook judges and records a verdict, and the `[ui.status_line]` script reads
  124. that verdict and paints the hint. The Grok hook always allows the stop and prints nothing, so a
  125. hint can never be fed back to the model.
  126. On Claude Code, an optional `beforeCompactPrompt` setting (empty by default; set it in `/config`)
  127. runs one turn before that automatic compaction, and only after auto mode is confirmed. Set it to
  128. `/stow` to run the `stow` command first. Claude Code does not expand slash commands or `@file`
  129. mentions in a prompt a plugin submits, and it rejects a plugin prompt that starts with `/`, so a
  130. value that starts with `/` is run as a command instead of being sent to the model as text. If you
  131. send your own prompt or run a command in between, or that turn is interrupted, errors, or does not
  132. finish within 5 minutes, nothing is compacted. Hint mode, off, and an empty setting are unchanged. Pi, Codex, and
  133. Grok do not have this setting.
  134. ## Usage
  135. | Command | Effect |
  136. | --- | --- |
  137. | `/compact-adviser` (Pi and Claude Code) | Settings (mode, minimum, request log, TypeSafe API key) |
  138. | `/compact-adviser auto` / `hint` / `off` (Pi and Claude Code) | Save that mode; auto asks for first-use confirmation |
  139. | `/compact-adviser status` (Pi and Claude Code) | Mode, minimum, budget, context, key source (`env` / `saved` / `.env` / `missing`), cooldown |
  140. | `/compact-adviser threshold 60000` (Pi and Claude Code) | Save an absolute token minimum |
  141. | `/compact-adviser budget 450000` / `budget off` (Pi and Claude Code) | Save a context budget: the hint floor is fully relaxed at this many tokens, or at the host's own compaction point if that is smaller (off by default) |
  142. | `/compact-adviser snooze` / `dismiss` (Pi and Claude Code) | Suppress the next three exchanges, or clear the current hint |
  143. | `beforeCompactPrompt` in `/config` (Claude Code) | Optional text run before automatic compaction. Empty by default. `/stow` runs that command |
  144. | `/compact-adviser` (Grok) | Show status; do not add arguments because Grok sends them to the model |
  145. | `/compact-adviser-hint` / `/compact-adviser-off` (Grok) | Save hint-only mode, or disable the adviser |
  146. | `/compact-adviser-snooze` / `/compact-adviser-dismiss` (Grok) | Suppress the next three exchanges, or clear the current hint |
  147. | `/compact-adviser-install` (Grok) | Register the hooks and print the status-line block to paste into the named `config.toml` |
  148. | `${GROK_HOME:-$HOME/.grok}/compact-adviser/adviser.sh threshold 60000` (Grok shell) | Save an absolute token minimum; `budget <tokens\|off>` saves a context budget; `help` lists the other shell-only settings |
  149. On Codex the same commands are arguments to the plugin's `src/cli.ts` (`status`, `hint`, `off`,
  150. `threshold`, `budget <tokens|off>`, `log on|off`, `key set|clear|status`) rather than a slash
  151. command, because Codex plugins cannot register a command with code behind it. Codex has no
  152. snooze or dismiss: the CLI cannot tell which session is current.
  153. ## Judge profiles
  154. An optional [judge profile](docs/judge-profiles.md) changes the two questions, score weight, or floor schedule without changing shipped defaults. All four hosts accept the same bounded JSON string in the `profile` setting. Keep hint mode while evaluating a profile. Invalid profiles disable advice, and loading a profile never grants automatic-mode consent.
  155. ## Eval
  156. Local judgment eval uses real session checkpoints to score when the adviser should suggest `/compact`. The curve below is from a follow-up-aware gold set (96 checkpoints, 40 sessions): as the context window fills, the score threshold loosens from **0.90** (≤10% used) to **0.50** (≥90% used) so **recall rises** while precision stays high - favoring token savings when compaction is about to be forced anyway.
  157. ![Use Jev to answer "should I /compact now?" — precision stays high while recall rises as context used goes from ≤10% to ≥90%](docs/eval-usage-floor-curve.png)
  158. The judgment-eval harness lives in [packages/pi-extension/eval/](packages/pi-extension/eval/README.md). It is not a published dataset: point it at your own sessions and keep transcripts local.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.