@ricky-stevens/context-guardian 2.1.0

package/lib/trim.mjs

@@ -0,0 +1,158 @@
+/**
+ * Universal text trimming and classification utilities.
+ *
+ * These functions implement Context Guardian's "keep-start-and-end" strategy:
+ * when content exceeds a size limit, we keep the first N and last N characters,
+ * trimming only the middle. This preserves intent (start) and outcome (end).
+ *
+ * @module trim
+ */
+
+// ---------------------------------------------------------------------------
+// Start+end trim — the universal truncation strategy
+// ---------------------------------------------------------------------------
+
+/**
+ * Trim content by keeping the first and last portions, removing the middle.
+ * Returns content unchanged if it's within the limit.
+ *
+ * @param {string} content - The text to potentially trim
+ * @param {number} limit - Maximum total character length before trimming
+ * @param {number} [keepStart] - Characters to keep from the start (default: limit/2)
+ * @param {number} [keepEnd] - Characters to keep from the end (default: limit/2)
+ * @returns {string} The original or trimmed content
+ */
+export function startEndTrim(content, limit, keepStart, keepEnd) {
+	if (!content || content.length <= limit) return content || "";
+	const half = Math.floor(limit / 2);
+	const start = keepStart ?? half;
+	const end = keepEnd ?? half;
+	const trimmed = content.length - start - end;
+	return (
+		content.slice(0, start) +
+		`\n[...${trimmed} chars trimmed from middle...]\n` +
+		content.slice(-end)
+	);
+}
+
+// ---------------------------------------------------------------------------
+// Error detection for tool results
+// ---------------------------------------------------------------------------
+
+/** Patterns that indicate a tool result is an error, not normal output. */
+const ERROR_PATTERNS = [
+	/\berror\b/i,
+	/\bfailed\b/i,
+	/\bdenied\b/i,
+	/\bnot found\b/i,
+	/\bexception\b/i,
+	/\bdoes not exist\b/i,
+	/\bpermission\b/i,
+	/\bEACCES\b/,
+	/\bENOENT\b/,
+	/\btimeout\b/i,
+	/exit code [1-9]/i,
+	/non-zero exit/i,
+];
+
+/**
+ * Check whether a tool result string looks like an error response.
+ * Used to decide whether to preserve results that would otherwise be removed.
+ *
+ * @param {string} content - The tool result text
+ * @returns {boolean} True if the content appears to be an error
+ */
+export function isErrorResponse(content) {
+	if (!content || typeof content !== "string") return false;
+	return ERROR_PATTERNS.some((re) => re.test(content));
+}
+
+/**
+ * Check whether a tool result is a SHORT error response (< 500 chars).
+ * Used specifically for re-obtainable tools (Read/Grep/Glob) where we only
+ * want to keep actual tool failures, not successful results that happen
+ * to contain error-related strings in their content.
+ *
+ * @param {string} content - The tool result text
+ * @returns {boolean} True if it's a short error-like response
+ */
+export function isShortErrorResponse(content) {
+	if (!content || typeof content !== "string") return false;
+	return content.length < 500 && isErrorResponse(content);
+}
+
+// ---------------------------------------------------------------------------
+// Confirmation message detection
+// ---------------------------------------------------------------------------
+
+/**
+ * Affirmative zero-information words that can be safely skipped.
+ * These are user messages that confirm a direction without adding context.
+ * NOT included: "no", "n" (rejections = decisions), bare numbers (selections).
+ */
+const CONFIRMATIONS = new Set([
+	"yes",
+	"y",
+	"ok",
+	"okay",
+	"sure",
+	"go ahead",
+	"continue",
+	"proceed",
+	"do it",
+	"correct",
+	"right",
+	"exactly",
+	"thanks",
+	"thank you",
+	"yep",
+	"yea",
+	"yeah",
+	"sounds good",
+	"go for it",
+	"please",
+	"agreed",
+	"lgtm",
+	"ship it",
+]);
+
+/**
+ * Check whether a user message is a short affirmative confirmation
+ * that adds no meaningful context to the conversation.
+ *
+ * @param {string} text - The trimmed user message text
+ * @returns {boolean} True if the message is a skippable confirmation
+ */
+export function isAffirmativeConfirmation(text) {
+	if (!text || typeof text !== "string") return false;
+	const normalised = text
+		.trim()
+		.toLowerCase()
+		.replace(/[.!,]+$/, "");
+	return CONFIRMATIONS.has(normalised);
+}
+
+// ---------------------------------------------------------------------------
+// Structured injection detection
+// ---------------------------------------------------------------------------
+
+/**
+ * Check whether a user message is a known system injection (checkpoint restore,
+ * skill injection, etc.) rather than actual user input.
+ * Only matches specific known patterns — never drops content based on size alone.
+ *
+ * @param {string} text - The user message text
+ * @returns {boolean} True if the message is a known system injection
+ */
+export function isSystemInjection(text) {
+	if (!text) return false;
+	if (text.startsWith("# Context Checkpoint (") && text.includes("> Created:"))
+		return true;
+	if (text.includes("<prior_conversation_history>")) return true;
+	if (text.includes("SKILL.md") && text.includes("plugin")) return true;
+	// Skill invocation injections from Claude Code
+	if (text.includes("<command-message>")) return true;
+	if (text.includes("<command-name>")) return true;
+	if (text.includes("Base directory for this skill:")) return true;
+	return false;
+}

package/package.json

@@ -0,0 +1,22 @@
+{
+	"name": "@ricky-stevens/context-guardian",
+	"version": "2.1.0",
+	"description": "Automatic context window monitoring and smart compaction for Claude Code",
+	"author": "Ricky Stevens",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/Ricky-Stevens/context-guardian"
+	},
+	"type": "module",
+	"scripts": {
+		"test": "node --test test/*.test.mjs",
+		"lint": "biome check hooks/ lib/"
+	},
+	"engines": {
+		"node": ">=18.0.0"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.4.10"
+	}
+}

package/skills/compact/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: compact
+description: Run Smart Compact — extract full conversation history, strip tool calls and noise
+context: inline
+allowed-tools: Bash
+---
+
+# Context Guardian — Smart Compact
+
+Run this command:
+
+```
+node ${CLAUDE_PLUGIN_ROOT}/lib/compact-cli.mjs smart ${CLAUDE_SESSION_ID} ${CLAUDE_PLUGIN_DATA}
+```
+
+The output is JSON. If `success` is `true`, display the `statsBlock` value verbatim — it is a pre-formatted box. Then on the next line, display the `resumeInstruction` value verbatim (it is already bold-formatted markdown). Do not add any extra text.
+
+If `success` is `false`, display the `error` value.
+
+$ARGUMENTS

package/skills/config/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: config
+description: View or update Context Guardian configuration (threshold, max_tokens)
+context: inline
+disable-model-invocation: true
+allowed-tools: Read, Edit, Bash
+---
+
+# Context Guardian Config
+
+Manage the configuration file at `${CLAUDE_PLUGIN_DATA}/config.json`.
+If `${CLAUDE_PLUGIN_DATA}` is empty, use `~/.claude/cg/config.json`.
+
+## No arguments — show current config
+
+If `$ARGUMENTS` is empty, read these files:
+
+1. `${CLAUDE_PLUGIN_DATA}/config.json` (may not exist — defaults: threshold 0.35, max_tokens 200000)
+2. `${CLAUDE_PLUGIN_DATA}/state-${CLAUDE_SESSION_ID}.json` (may not exist)
+
+If the state file exists and has a `model` field, display:
+
+```
+┌─────────────────────────────────────────────────
+│  Context Guardian Config
+│
+│  threshold:        {threshold}  (trigger warning at {threshold_display}% usage, or threshold × 100 if threshold_display is missing)
+│  max_tokens:       {max_tokens formatted with commas}  (config default)
+│  detected model:   {model from state file}
+│  detected limit:   {max_tokens from state file, formatted with commas} tokens
+│
+│  Config file:  {path to config.json}
+│
+│  Usage:
+│    /cg:config threshold 0.50
+│    /cg:config max_tokens 1000000
+│    /cg:config reset
+│
+└─────────────────────────────────────────────────
+```
+
+If the state file doesn't exist or has no model field, omit the "detected" lines and show:
+
+```
+│  max_tokens:       {max_tokens formatted with commas}  (will auto-detect after first response)
+```
+
+Output ONLY the box. No extra commentary.
+
+## With arguments — update config
+
+Parse `$ARGUMENTS` as `<key> <value>`.
+
+**threshold**: Must be 0.01–0.99 after normalization. Normalize the user's input:
+- Whole number like "50" → divide by 100 → 0.50
+- Percentage like "50%" → strip the %, divide by 100 → 0.50
+- Decimal like "0.50" or ".5" → use as-is → 0.50
+- If the result is < 0.01 or > 0.99, show an error: "Threshold must be between 1% and 99%."
+
+**max_tokens**: Must be a positive integer.
+
+**reset**: No value needed. Write `{"threshold": 0.35, "max_tokens": 200000}` to the config file.
+
+For threshold/max_tokens: Read the existing config (or use defaults if missing), update the key, write back with `JSON.stringify(cfg, null, 2)`.
+
+After updating, read back the file and display the config box with a confirmation line: "Config updated. Changes take effect on the next message."
+
+If the key is unrecognized, show the Usage section from the box above.
+
+$ARGUMENTS

package/skills/handoff/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: handoff
+description: Save session context to a handoff file for cross-session continuity
+context: inline
+allowed-tools: Bash
+---
+
+# Context Guardian — Session Handoff
+
+If `$ARGUMENTS` is not empty, pass it as a quoted label argument at the end of the command. If empty, omit it.
+
+With label:
+```
+node ${CLAUDE_PLUGIN_ROOT}/lib/compact-cli.mjs handoff ${CLAUDE_SESSION_ID} ${CLAUDE_PLUGIN_DATA} "the label text"
+```
+
+Without label:
+```
+node ${CLAUDE_PLUGIN_ROOT}/lib/compact-cli.mjs handoff ${CLAUDE_SESSION_ID} ${CLAUDE_PLUGIN_DATA}
+```
+
+The output is JSON. If `success` is `true`, display the `statsBlock` value verbatim — it is a pre-formatted box. Then on the next line, display the `resumeInstruction` value verbatim (it is already bold-formatted markdown). Do not add any extra text.
+
+If `success` is `false`, display the `error` value.
+
+$ARGUMENTS

package/skills/prune/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: prune
+description: Run Keep Recent — drop oldest messages, keep last 10 exchanges
+context: inline
+allowed-tools: Bash
+---
+
+# Context Guardian — Prune (Keep Recent)
+
+Run this command:
+
+```
+node ${CLAUDE_PLUGIN_ROOT}/lib/compact-cli.mjs recent ${CLAUDE_SESSION_ID} ${CLAUDE_PLUGIN_DATA}
+```
+
+The output is JSON. If `success` is `true`, display the `statsBlock` value verbatim — it is a pre-formatted box. Then on the next line, display the `resumeInstruction` value verbatim (it is already bold-formatted markdown). Do not add any extra text.
+
+If `success` is `false`, display the `error` value.
+
+$ARGUMENTS

package/skills/stats/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: stats
+description: Show current context window usage, threshold, and compaction recommendation
+context: inline
+disable-model-invocation: true
+allowed-tools: Read, Bash
+---
+
+# Context Guardian Stats
+
+Read the session-scoped state file and display the status box. Follow these steps exactly.
+
+## Step 1 — Read the state file
+
+Read the file at `${CLAUDE_PLUGIN_DATA}/state-${CLAUDE_SESSION_ID}.json`.
+
+If `${CLAUDE_PLUGIN_DATA}` is empty, use `~/.claude/cg/` instead.
+
+If the file does not exist, display this and stop:
+
+```
+┌─────────────────────────────────────────────────
+│  Context Guardian Stats
+│
+│  No data for this session.
+│  Send a non-slash-command message first so the
+│  submit hook can capture token counts.
+│
+└─────────────────────────────────────────────────
+```
+
+## Step 2 — Compute "Last updated"
+
+Run: `echo $(( $(date +%s) - JSON_TS_VALUE / 1000 ))`
+
+Replace `JSON_TS_VALUE` with the `ts` field from the JSON. The command outputs the age in seconds. Display it as:
+- Under 60: "Xs ago"
+- 60–3599: "Xm ago"
+- 3600+: "Xh ago"
+
+If the result is greater than 300, append " (stale)".
+
+## Step 3 — Display the status box
+
+All values come directly from the JSON — use them as-is. Do NOT compute any values yourself.
+
+- `pct_display` — already a string like "2.5"
+- `threshold_display` — already a number like 35
+- `remaining_to_alert` — already computed (threshold minus current, rounded)
+- `smart_estimate_pct` and `recent_estimate_pct` — already computed
+
+```
+┌─────────────────────────────────────────────────
+│  Context Guardian Stats
+│
+│  Current usage:   {current_tokens with commas} / {max_tokens with commas} tokens ({pct_display}%)
+│  Session size:    {(payload_bytes + baseline_overhead × 4) ÷ 1048576, to 1 decimal, minimum 0.1}MB / 20MB
+│  Threshold:       {threshold_display}% ({remaining_to_alert}% remaining to alert)
+│  Data source:     {source: "real" → "real counts", "estimated" → "estimated"}
+│
+│  Model:           {model} / {max_tokens with commas} tokens
+│  Last updated:    {computed from Step 2}
+│
+│  /cg:compact         ~{pct_display}% → ~{smart_estimate_pct}%
+│  /cg:prune           ~{pct_display}% → ~{recent_estimate_pct}%
+│
+│  /cg:handoff [name]  save session for later
+│
+└─────────────────────────────────────────────────
+```
+
+## Step 4 — Run diagnostics (optional)
+
+Run: `node ${CLAUDE_PLUGIN_ROOT}/lib/diagnostics.mjs ${CLAUDE_SESSION_ID} ${CLAUDE_PLUGIN_ROOT} ${CLAUDE_PLUGIN_DATA}`
+
+If the command fails or returns invalid JSON, omit the Health section entirely.
+
+Parse the JSON output. If **all** checks have `ok: true`, append this line inside the box before the closing `└`:
+
+```
+│
+│  Health:          All checks passed
+```
+
+If **any** check has `ok: false`, append this instead:
+
+```
+│
+│  Health:          {count} issue(s) detected
+│    ✗ {check.name}: {check.detail}
+│    ✗ {check.name}: {check.detail}
+```
+
+List only the failed checks. Each on its own `│    ✗` line.
+
+## Output
+
+Output the box and nothing else. No extra text, explanation, or commentary beyond what the steps above specify.
+
+$ARGUMENTS

package/sonar-project.properties

@@ -0,0 +1,12 @@
+sonar.projectKey=Ricky-Stevens_context-guardian
+sonar.organization=ricky-stevens
+sonar.projectName=Context Guardian
+
+sonar.sources=lib,hooks
+sonar.tests=test
+sonar.sourceEncoding=UTF-8
+
+sonar.javascript.lcov.reportPaths=coverage/lcov.info
+
+sonar.coverage.exclusions=test/**,skills/**,hooks/**
+sonar.cpd.exclusions=test/**

package/test/checkpoint.test.mjs

@@ -0,0 +1,171 @@
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, before, describe, it } from "node:test";
+
+// DATA_DIR is computed at module load time from process.env.CLAUDE_PLUGIN_DATA,
+// so we must set the env var BEFORE importing checkpoint.mjs.
+const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "cg-checkpoint-test-"));
+process.env.CLAUDE_PLUGIN_DATA = tmpDir;
+
+const { writeCompactionState } = await import("../lib/checkpoint.mjs");
+
+function stateFilePath(sessionId) {
+	return path.join(tmpDir, `state-${sessionId}.json`);
+}
+
+function readState(sessionId) {
+	return JSON.parse(fs.readFileSync(stateFilePath(sessionId), "utf-8"));
+}
+
+// Clean up state files between tests (but keep the tmpDir)
+afterEach(() => {
+	for (const f of fs.readdirSync(tmpDir)) {
+		if (f.startsWith("state-")) {
+			fs.unlinkSync(path.join(tmpDir, f));
+		}
+	}
+	// Also remove config.json if it was written by a test
+	const configPath = path.join(tmpDir, "config.json");
+	if (fs.existsSync(configPath)) fs.unlinkSync(configPath);
+});
+
+// Clean up the tmpDir after all tests
+before(() => {
+	process.on("exit", () => {
+		fs.rmSync(tmpDir, { recursive: true, force: true });
+	});
+});
+
+describe("writeCompactionState", () => {
+	it("writes state file with correct computed fields", () => {
+		writeCompactionState(
+			"sess1",
+			"/tmp/transcript.jsonl",
+			50000,
+			200000,
+			"Smart Compact",
+		);
+
+		const state = readState("sess1");
+		assert.equal(state.current_tokens, 50000);
+		assert.equal(state.max_tokens, 200000);
+		assert.equal(state.pct, 0.25);
+		assert.equal(state.pct_display, "25.0");
+		// Default threshold is 0.35: headroom = max(0, round(200000 * 0.35 - 50000)) = 20000
+		assert.equal(state.headroom, 20000);
+		assert.equal(state.source, "estimated");
+		assert.equal(state.recommendation, "Smart Compact");
+		assert.equal(state.transcript_path, "/tmp/transcript.jsonl");
+		assert.equal(state.session_id, "sess1");
+		assert.equal(state.model, "unknown");
+		assert.equal(state.smart_estimate_pct, 0);
+		assert.equal(state.recent_estimate_pct, 0);
+		assert.equal(typeof state.ts, "number");
+	});
+
+	it("writes threshold and threshold_display from loaded config", () => {
+		// loadConfig() caches on first call; since no config.json existed at
+		// import time, the default threshold (0.35) is used for all tests.
+		writeCompactionState("sess2", "/tmp/t.jsonl", 60000, 200000, "Keep Recent");
+
+		const state = readState("sess2");
+		assert.equal(state.threshold, 0.35);
+		assert.equal(state.threshold_display, 35);
+		// headroom = max(0, round(200000 * 0.35 - 60000)) = 10000
+		assert.equal(state.headroom, 10000);
+	});
+
+	it("carries forward baseline_overhead from existing state file", () => {
+		fs.writeFileSync(
+			stateFilePath("sess4"),
+			JSON.stringify({ baseline_overhead: 42000, current_tokens: 100000 }),
+		);
+
+		writeCompactionState(
+			"sess4",
+			"/tmp/t.jsonl",
+			30000,
+			200000,
+			"Smart Compact",
+		);
+
+		const state = readState("sess4");
+		assert.equal(state.baseline_overhead, 42000);
+	});
+
+	it("defaults baseline_overhead to 0 when no existing state", () => {
+		writeCompactionState(
+			"sess5",
+			"/tmp/t.jsonl",
+			30000,
+			200000,
+			"Smart Compact",
+		);
+
+		const state = readState("sess5");
+		assert.equal(state.baseline_overhead, 0);
+	});
+
+	it("defaults baseline_overhead to 0 when existing state lacks the field", () => {
+		fs.writeFileSync(
+			stateFilePath("sess6"),
+			JSON.stringify({ current_tokens: 100000 }),
+		);
+
+		writeCompactionState(
+			"sess6",
+			"/tmp/t.jsonl",
+			30000,
+			200000,
+			"Smart Compact",
+		);
+
+		const state = readState("sess6");
+		assert.equal(state.baseline_overhead, 0);
+	});
+
+	it("handles corrupt existing state file gracefully", () => {
+		fs.writeFileSync(stateFilePath("sess7"), "not json at all{{{");
+
+		// Inner try/catch handles corrupt JSON, falls back to baseline_overhead=0
+		writeCompactionState(
+			"sess7",
+			"/tmp/t.jsonl",
+			30000,
+			200000,
+			"Smart Compact",
+		);
+
+		const state = readState("sess7");
+		assert.equal(state.current_tokens, 30000);
+		assert.equal(state.baseline_overhead, 0);
+	});
+
+	it("has source set to estimated", () => {
+		writeCompactionState(
+			"sess8",
+			"/tmp/t.jsonl",
+			10000,
+			200000,
+			"Smart Compact",
+		);
+
+		const state = readState("sess8");
+		assert.equal(state.source, "estimated");
+	});
+
+	it("handles max=0 without throwing", () => {
+		// tokens/max = Infinity, but JSON.stringify handles Infinity → null
+		writeCompactionState("sess9", "/tmp/t.jsonl", 10000, 0, "Smart Compact");
+
+		const state = readState("sess9");
+		assert.equal(state.current_tokens, 10000);
+		assert.equal(state.max_tokens, 0);
+		// pct: 10000/0 = Infinity, JSON serializes to null
+		assert.equal(state.pct, null);
+		// headroom: Math.max(0, Math.round(0 * 0.35 - 10000)) = 0
+		assert.equal(state.headroom, 0);
+	});
+});