context-brake

1// context-brake: one gentle, one-time nudge when the context window gets full.
2import { DEFAULT_THRESHOLD, note, parseThreshold, step } from "./core.mjs";
3
4const PERCENT = { plugin: "context-brake", key: "percent" };
5const ARMED = { plugin: "context-brake", key: "armed" };
6const FIRED = { plugin: "context-brake", key: "fired" };
7const STORE_KEY = "context-brake:threshold"; // persists across sessions
8
9const val = (r, fallback) => r?.value ?? fallback;
10
11async function threshold($) {
12  try {
13    const v = await $.store.get(STORE_KEY); // $.store.get resolves to the stored value itself
14    if (v === "off") return null;
15    return Number.isInteger(v) ? v : DEFAULT_THRESHOLD;
16  } catch {
17    return DEFAULT_THRESHOLD;
18  }
19}
20
21async function reading($) {
22  const { context } = await $.session.usage();
23  if (!context?.window) return null;
24  return context.percent ?? Math.round(((context.tokens ?? 0) / context.window) * 100);
25}
26
27async function update($) {
28  const percent = await reading($);
29  if (percent == null) return;
30  const limit = await threshold($);
31  const before = { armed: val(await $.state.get(ARMED), false), fired: val(await $.state.get(FIRED), false) };
32  const after = step(before, percent, limit);
33  await $.state.set(PERCENT, percent);
34  await $.state.set(ARMED, after.armed);
35  await $.state.set(FIRED, after.fired);
36  if (after.armed && !before.armed) {
37    try { $.ui.toast(`Context ${percent}% full: Claude will wrap up at a clean boundary. /compact when ready.`); } catch { /* no UI */ }
38  }
39}
40
41export function register(on) {
42  on("session.start", async ($, e, next) => {
43    const result = await next(e);
44    try {
45      await $.command.register({ name: "brake", description: "Context brake: /brake [status | <10-99> | off]" });
46    } catch { /* never block startup */ }
47    try { await update($); } catch { /* usage unavailable */ }
48    return result;
49  });
50
51  on("turn.complete", async ($, e, next) => {
52    const result = await next(e);
53    if (!e.agentId) {
54      try { await update($); } catch { /* usage unavailable */ }
55    }
56    return result;
57  });
58
59  // The only rewrite: attach the note once, as context beside the user's own prompt (never edits the prompt text).
60  on("prompt.submit", async ($, e, next) => {
61    let armed = false;
62    try { armed = val(await $.state.get(ARMED), false); } catch { /* fall through */ }
63    if (!armed) return next(e);
64    const percent = val(await $.state.get(PERCENT), 0);
65    await $.state.set(ARMED, false);
66    await $.state.set(FIRED, true);
67    return next({ ...e, context: [...(Array.isArray(e.context) ? e.context : []), note(percent)] });
68  });
69
70  on("command.run", { command: "brake" }, async ($, e) => {
71    const arg = String(e.args ?? "").trim();
72    if (arg && arg !== "status") {
73      const parsed = parseThreshold(arg);
74      if (!parsed) return { text: "Usage: /brake [status | <10-99> | off]" };
75      await $.store.set(STORE_KEY, parsed.off ? "off" : parsed.threshold);
76      await $.state.set(ARMED, false);
77      await $.state.set(FIRED, false);
78      try { await update($); } catch { /* ignore */ }
79      return { text: parsed.off ? "Context brake off." : `Context brake set to ${parsed.threshold}%.` };
80    }
81    const limit = await threshold($);
82    const percent = val(await $.state.get(PERCENT), null);
83    const fired = val(await $.state.get(FIRED), false);
84    const armed = val(await $.state.get(ARMED), false);
85    const where = percent == null ? "no reading yet" : `context ${percent}%`;
86    const status = limit == null ? "off" : armed ? "armed: the note goes out with your next prompt" : fired ? "already sent for this fill; re-arms after /compact or /clear" : "waiting";
87    return { text: `Context brake ${limit == null ? "" : `at ${limit}% `}(${where}): ${status}.` };
88  });
89}
90

1// Pure decision logic for context-brake.
2
3export const DEFAULT_THRESHOLD = 80;
4export const REARM_GAP = 15; // percentage points below the threshold before the brake re-arms
5
6/**
7 * Next brake state after a context reading.
8 * - crosses threshold while not yet fired  -> armed (note goes out with the next prompt)
9 * - drops REARM_GAP below threshold         -> reset (after /compact or /clear)
10 */
11export function step(state, percent, threshold) {
12  const s = { armed: !!state?.armed, fired: !!state?.fired };
13  if (threshold == null || !Number.isFinite(percent)) return s;
14  if (percent >= threshold && !s.fired) return { armed: true, fired: false };
15  if (percent < threshold - REARM_GAP) return { armed: false, fired: false };
16  return s;
17}
18
19export function parseThreshold(arg) {
20  const a = String(arg ?? "").trim().toLowerCase();
21  if (a === "off") return { off: true };
22  const n = Number(a.replace(/%$/, ""));
23  if (a !== "" && Number.isInteger(n) && n >= 10 && n <= 99) return { threshold: n };
24  return null;
25}
26
27export function note(percent) {
28  return [
29    `[context-brake] The context window is ${percent}% full and auto-compaction is approaching.`,
30    "Finish the step you are on, then stop at a clean boundary instead of starting large new work.",
31    "Before stopping, give a short handoff: goal, what is done, what is left, key files and decisions.",
32    "This is a one-time note from a user-installed mod; the user may run /compact afterwards.",
33  ].join(" ");
34}
35

1declare module "claude-code" {
2  interface PluginState {
3    "context-brake": { percent: number | null; armed: boolean; fired: boolean }
4  }
5}
6export type ContextBrakeState = { percent: number | null; armed: boolean; fired: boolean }
7