smart-compaction 0.2.0 → 0.2.1

package/README.md

@@ -87,8 +87,18 @@ installs cleanly and just reports `available: false` instead of erroring.
 
 ### Tell the model when to use it
 
-Neither tool calls itself — nothing uses them unless instructed to. Add something like this to
-your `AGENTS.md` (or whatever your profile injects as standing instructions):
+This is baked into both tools' own descriptions, so it works out of the box with no setup: each
+tool's description tells the model to check `context_status` right after finishing a
+self-contained step (e.g. right after `todo_write` marks an item `completed`) and to follow up
+with `compact_now` once usage climbs past roughly 70-90%. Since both descriptions are sent to the
+model on every request automatically, no `AGENTS.md` edit is required for this behavior — unlike
+an early version of this plugin, which relied entirely on a hand-written `AGENTS.md` rule and
+(measured directly against real session logs) got essentially no organic use as a result: the
+description alone wasn't a strong enough signal.
+
+That said, standing instructions carry more weight than a tool description competing against
+everything else in a long tool catalog. If you want to reinforce it further, add something like
+this to your `AGENTS.md` (or whatever your profile injects as standing instructions):
 
 > After marking a todo item `completed` (never while one is `in_progress`), call `context_status`.
 > If usage is climbing past roughly 70-80% of the context window, call `compact_now` too. Both are

package/index.js

@@ -33,9 +33,12 @@ const DESCRIPTION =
   'Voluntarily compact older conversation history now, at a point you know is safe: '
   + 'right after finishing a concrete step (e.g. just marked a todo item completed), '
   + 'never mid-edit or with unfinished work pending. Use this instead of waiting to be '
-  + 'interrupted by automatic compaction, if the conversation feels like it has gotten '
-  + 'long. Harmless to call speculatively — it no-ops if there is not enough history to '
-  + 'compact yet.'
+  + 'interrupted by automatic compaction. Call context_status first if unsure whether now '
+  + 'is a good time — usage past roughly 70-90% of the context window is a concrete signal '
+  + 'to call this proactively, not just a vague feeling that the conversation has gotten '
+  + 'long. As a habit: check context_status after every completed step, and call this '
+  + 'whenever that check comes back high. Harmless to call speculatively either way — it '
+  + 'no-ops if there is not enough history to compact yet.'
 
 /**
  * @param {import('@deepseek-ai/cordis').Context} ctx
@@ -125,11 +128,13 @@ export function apply(ctx) {
 const CONTEXT_STATUS_DESCRIPTION =
   'Check real, current context-window usage for this session: tokens used so far and the '
   + 'model\'s actual context-window size, whatever model this session happens to be running. '
-  + 'Use this instead of guessing whether the conversation "feels long" before deciding to call '
-  + 'compact_now — automatic compaction generally triggers well before the window fills, '
-  + 'typically somewhere around 70-90% depending on profile config, so usage climbing past that '
-  + 'range is a good signal to call compact_now proactively rather than wait to be interrupted. '
-  + 'Harmless to call anytime; read-only, never modifies the session.'
+  + 'Call this right after finishing any self-contained step — e.g. right after todo_write '
+  + 'marks an item completed, never mid-edit or with unfinished work pending — instead of '
+  + 'guessing whether the conversation "feels long." Automatic compaction generally triggers '
+  + 'well before the window fills, typically somewhere around 70-90% depending on profile '
+  + 'config, so if percentUsed comes back past that range, follow up by calling compact_now '
+  + 'proactively rather than wait to be interrupted. Harmless to call anytime — read-only, '
+  + 'never modifies the session.'
 
 function renderContextStatus(value) {
   if (!value.available) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smart-compaction",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "dsh plugin: a compact_now tool letting the model trigger compaction itself at a safe point, plus a context_status tool so it can check real token usage against its context window, instead of only the automatic token-threshold trigger.",
   "type": "module",
   "main": "./index.js",