@ricky-stevens/context-guardian 2.1.0

package/biome.json

@@ -0,0 +1,34 @@
+{
+	"$schema": "https://biomejs.dev/schemas/2.4.10/schema.json",
+	"vcs": {
+		"enabled": true,
+		"clientKind": "git",
+		"useIgnoreFile": true
+	},
+	"files": {
+		"ignoreUnknown": false
+	},
+	"formatter": {
+		"enabled": true,
+		"indentStyle": "tab"
+	},
+	"linter": {
+		"enabled": true,
+		"rules": {
+			"recommended": true
+		}
+	},
+	"javascript": {
+		"formatter": {
+			"quoteStyle": "double"
+		}
+	},
+	"assist": {
+		"enabled": true,
+		"actions": {
+			"source": {
+				"organizeImports": "on"
+			}
+		}
+	}
+}

package/bun.lock

@@ -0,0 +1,31 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "context-guardian",
+      "devDependencies": {
+        "@biomejs/biome": "^2.4.10",
+      },
+    },
+  },
+  "packages": {
+    "@biomejs/biome": ["@biomejs/biome@2.4.10", "", { "optionalDependencies": { "@biomejs/cli-darwin-arm64": "2.4.10", "@biomejs/cli-darwin-x64": "2.4.10", "@biomejs/cli-linux-arm64": "2.4.10", "@biomejs/cli-linux-arm64-musl": "2.4.10", "@biomejs/cli-linux-x64": "2.4.10", "@biomejs/cli-linux-x64-musl": "2.4.10", "@biomejs/cli-win32-arm64": "2.4.10", "@biomejs/cli-win32-x64": "2.4.10" }, "bin": { "biome": "bin/biome" } }, "sha512-xxA3AphFQ1geij4JTHXv4EeSTda1IFn22ye9LdyVPoJU19fNVl0uzfEuhsfQ4Yue/0FaLs2/ccVi4UDiE7R30w=="],
+
+    "@biomejs/cli-darwin-arm64": ["@biomejs/cli-darwin-arm64@2.4.10", "", { "os": "darwin", "cpu": "arm64" }, "sha512-vuzzI1cWqDVzOMIkYyHbKqp+AkQq4K7k+UCXWpkYcY/HDn1UxdsbsfgtVpa40shem8Kax4TLDLlx8kMAecgqiw=="],
+
+    "@biomejs/cli-darwin-x64": ["@biomejs/cli-darwin-x64@2.4.10", "", { "os": "darwin", "cpu": "x64" }, "sha512-14fzASRo+BPotwp7nWULy2W5xeUyFnTaq1V13Etrrxkrih+ez/2QfgFm5Ehtf5vSjtgx/IJycMMpn5kPd5ZNaA=="],
+
+    "@biomejs/cli-linux-arm64": ["@biomejs/cli-linux-arm64@2.4.10", "", { "os": "linux", "cpu": "arm64" }, "sha512-7MH1CMW5uuxQ/s7FLST63qF8B3Hgu2HRdZ7tA1X1+mk+St4JOuIrqdhIBnnyqeyWJNI+Bww7Es5QZ0wIc1Cmkw=="],
+
+    "@biomejs/cli-linux-arm64-musl": ["@biomejs/cli-linux-arm64-musl@2.4.10", "", { "os": "linux", "cpu": "arm64" }, "sha512-WrJY6UuiSD/Dh+nwK2qOTu8kdMDlLV3dLMmychIghHPAysWFq1/DGC1pVZx8POE3ZkzKR3PUUnVrtZfMfaJjyQ=="],
+
+    "@biomejs/cli-linux-x64": ["@biomejs/cli-linux-x64@2.4.10", "", { "os": "linux", "cpu": "x64" }, "sha512-tZLvEEi2u9Xu1zAqRjTcpIDGVtldigVvzug2fTuPG0ME/g8/mXpRPcNgLB22bGn6FvLJpHHnqLnwliOu8xjYrg=="],
+
+    "@biomejs/cli-linux-x64-musl": ["@biomejs/cli-linux-x64-musl@2.4.10", "", { "os": "linux", "cpu": "x64" }, "sha512-kDTi3pI6PBN6CiczsWYOyP2zk0IJI08EWEQyDMQWW221rPaaEz6FvjLhnU07KMzLv8q3qSuoB93ua6inSQ55Tw=="],
+
+    "@biomejs/cli-win32-arm64": ["@biomejs/cli-win32-arm64@2.4.10", "", { "os": "win32", "cpu": "arm64" }, "sha512-umwQU6qPzH+ISTf/eHyJ/QoQnJs3V9Vpjz2OjZXe9MVBZ7prgGafMy7yYeRGnlmDAn87AKTF3Q6weLoMGpeqdQ=="],
+
+    "@biomejs/cli-win32-x64": ["@biomejs/cli-win32-x64@2.4.10", "", { "os": "win32", "cpu": "x64" }, "sha512-aW/JU5GuyH4uxMrNYpoC2kjaHlyJGLgIa3XkhPEZI0uKhZhJZU8BuEyJmvgzSPQNGozBwWjC972RaNdcJ9KyJg=="],
+  }
+}

package/hooks/precompact.mjs

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+/**
+ * PreCompact hook — safety net for native auto-compaction.
+ *
+ * When Claude Code's built-in compaction fires (auto or manual /compact),
+ * this hook runs CG's deterministic extraction and injects it as
+ * additionalContext. The native compaction model then works with pre-cleaned
+ * input, producing a better summary than it would from the raw transcript.
+ *
+ * This is a silent safety net — no user-facing output.
+ *
+ * @module precompact-hook
+ */
+import fs from "node:fs";
+import { log } from "../lib/logger.mjs";
+import { extractConversation } from "../lib/transcript.mjs";
+
+let input;
+try {
+	input = JSON.parse(fs.readFileSync(0, "utf8"));
+} catch (e) {
+	process.stderr.write(`cg: precompact parse error: ${e.message}\n`);
+	process.exit(0);
+}
+
+const { session_id = "unknown", transcript_path, trigger = "unknown" } = input;
+log(`PRECOMPACT session=${session_id} trigger=${trigger}`);
+
+if (!transcript_path || !fs.existsSync(transcript_path)) {
+	log(`precompact-skip: no transcript`);
+	process.exit(0);
+}
+
+try {
+	const extraction = extractConversation(transcript_path);
+
+	if (!extraction || extraction === "(no transcript available)") {
+		log(`precompact-skip: empty extraction`);
+		process.exit(0);
+	}
+
+	// Inject the extraction as context for the compaction model.
+	// Limit to 50K chars to avoid overwhelming the compaction prompt.
+	const MAX_INJECT = 50000;
+	const trimmed =
+		extraction.length > MAX_INJECT
+			? `${extraction.slice(0, MAX_INJECT)}\n\n[...extraction truncated at ${MAX_INJECT} chars for compaction input...]`
+			: extraction;
+
+	const output = {
+		hookSpecificOutput: {
+			hookEventName: "PreCompact",
+			additionalContext: [
+				"[Context Guardian — Pre-Compaction Extraction]",
+				"The following is a high-fidelity deterministic extraction of the conversation.",
+				"Tool outputs that can be re-obtained (file reads, search results) have been stripped.",
+				"All user messages, assistant reasoning, code changes, and command outputs are preserved.",
+				"Use this extraction as the primary input for your compaction. It is already noise-reduced — prefer keeping its content over re-summarizing.",
+				"",
+				trimmed,
+			].join("\n"),
+		},
+	};
+
+	process.stdout.write(JSON.stringify(output));
+	log(
+		`precompact-injected session=${session_id} chars=${extraction.length} injected=${trimmed.length}`,
+	);
+} catch (e) {
+	log(`precompact-error: ${e.message}`);
+	// Fail silently — don't block compaction
+	process.exit(0);
+}

package/hooks/session-start.mjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { log } from "../lib/logger.mjs";
+import { atomicWriteFileSync, resolveDataDir } from "../lib/paths.mjs";
+
+let input;
+try {
+	input = JSON.parse(fs.readFileSync(0, "utf8"));
+} catch (e) {
+	process.stderr.write(`cg: failed to parse stdin: ${e.message}\n`);
+	process.exit(0);
+}
+
+const STALE_MS = 30 * 60 * 1000;
+
+// Clean up stale session-scoped state files (state-*.json) in data dir.
+// Each session writes its own state file; old ones accumulate.
+const dataDir = resolveDataDir();
+if (fs.existsSync(dataDir)) {
+	try {
+		const now3 = Date.now();
+		for (const f of fs
+			.readdirSync(dataDir)
+			.filter((f) => f.startsWith("state-") && f.endsWith(".json"))) {
+			const filePath = path.join(dataDir, f);
+			try {
+				if (now3 - fs.statSync(filePath).mtimeMs > STALE_MS) {
+					fs.unlinkSync(filePath);
+				}
+			} catch {}
+		}
+	} catch {}
+}
+
+// ---------------------------------------------------------------------------
+// Compact synthetics use unique titles (cg:{hash}) per cycle, so stale-title
+// collisions are no longer possible. No defensive purge needed at startup.
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// Self-healing: if the marketplace repo dir is missing, background-clone it.
+// Claude Code resolves CLAUDE_PLUGIN_ROOT from the marketplace location for
+// some hooks; if that dir doesn't exist, hooks fail with
+// "Plugin directory does not exist". Fire-and-forget so we don't block startup.
+// ---------------------------------------------------------------------------
+try {
+	const knownPath = path.join(
+		os.homedir(),
+		".claude",
+		"plugins",
+		"known_marketplaces.json",
+	);
+	if (fs.existsSync(knownPath)) {
+		const known = JSON.parse(fs.readFileSync(knownPath, "utf8"));
+		const entry = known["context-guardian"];
+		if (entry?.installLocation && !fs.existsSync(entry.installLocation)) {
+			const url =
+				entry.source?.url ||
+				(entry.source?.repo
+					? `https://github.com/${entry.source.repo}.git`
+					: null);
+			if (url?.startsWith("https://")) {
+				log(
+					`self-heal: marketplace dir missing at ${entry.installLocation}, cloning from ${url}`,
+				);
+				const { spawn } = await import("node:child_process");
+				const child = spawn(
+					"git",
+					["clone", "--depth", "1", url, entry.installLocation],
+					{ stdio: "ignore", detached: true },
+				);
+				child.on("error", (e) => log(`self-heal-clone-error: ${e.message}`));
+				child.unref();
+			}
+		}
+	}
+} catch (e) {
+	log(`self-heal-error: ${e.message}`);
+}
+
+// ---------------------------------------------------------------------------
+// Statusline dominance — the statusline is CG's primary UX for context
+// pressure. We ensure it's always configured and reclaim it if overwritten.
+// Takes effect next session (Claude Code reads settings at startup, before hooks).
+// ---------------------------------------------------------------------------
+let statuslineReclaimed = false;
+try {
+	const settingsPath = path.join(os.homedir(), ".claude", "settings.json");
+	let settings = {};
+	if (fs.existsSync(settingsPath)) {
+		settings = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
+	}
+	const pluginRoot =
+		process.env.CLAUDE_PLUGIN_ROOT || path.resolve(import.meta.dirname, "..");
+	const statuslineCmd = `node ${pluginRoot}/lib/statusline.mjs`;
+	const isCG = settings.statusLine?.command?.includes("statusline.mjs");
+
+	if (!settings.statusLine) {
+		// No statusline configured — set ours
+		settings.statusLine = { type: "command", command: statuslineCmd };
+		fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+		atomicWriteFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
+		log("auto-configured statusline in settings.json");
+	} else if (!isCG) {
+		// Another statusline is configured — reclaim it for CG
+		const prev = settings.statusLine.command || "(unknown)";
+		settings.statusLine = { type: "command", command: statuslineCmd };
+		atomicWriteFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
+		log(`statusline-reclaimed: overwriting "${prev}" with CG statusline`);
+		statuslineReclaimed = true;
+	}
+} catch (e) {
+	log(`statusline-autoconfig-error: ${e.message}`);
+}
+
+log(
+	`session-start session=${input.session_id || "unknown"} cwd=${input.cwd || "unknown"}`,
+);
+
+// Warn user if statusline was reclaimed from another tool
+if (statuslineReclaimed) {
+	process.stdout.write(
+		JSON.stringify({
+			hookSpecificOutput: {
+				hookEventName: "SessionStart",
+				additionalContext:
+					"[Context Guardian] Statusline reclaimed — another tool had overwritten it. Takes effect next session.",
+			},
+		}),
+	);
+}

package/hooks/stop.mjs

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import { loadConfig, resolveMaxTokens } from "../lib/config.mjs";
+import { estimateSavings } from "../lib/estimate.mjs";
+import { log } from "../lib/logger.mjs";
+import {
+	atomicWriteFileSync,
+	ensureDataDir,
+	STATUSLINE_STATE_DIR,
+	stateFile,
+	statuslineStateFile,
+} from "../lib/paths.mjs";
+import { estimateTokens, getTokenUsage } from "../lib/tokens.mjs";
+
+// ---------------------------------------------------------------------------
+// Stop hook — writes fresh token counts after each assistant response.
+//
+// PERFORMANCE: Does NOT call estimateSavings (which reads the full transcript).
+// The submit hook already computed and saved savings estimates. This hook only
+// updates the token counts (cheap — tail-reads 32KB) and carries forward the
+// existing savings estimates from the state file.
+// ---------------------------------------------------------------------------
+let input;
+try {
+	input = JSON.parse(fs.readFileSync(0, "utf8"));
+} catch (e) {
+	process.stderr.write(`cg: failed to parse stdin: ${e.message}\n`);
+	process.exit(0);
+}
+
+const { session_id = "unknown", transcript_path } = input;
+log(`STOP session=${session_id}`);
+
+if (!transcript_path || !fs.existsSync(transcript_path)) process.exit(0);
+
+// Measure raw transcript file size — proxy for API request payload size.
+let payloadBytes = 0;
+try {
+	payloadBytes = fs.statSync(transcript_path).size;
+} catch {}
+
+const cfg = loadConfig();
+const threshold = cfg.threshold ?? 0.35;
+
+const realUsage = getTokenUsage(transcript_path);
+const currentTokens = realUsage
+	? realUsage.current_tokens
+	: estimateTokens(transcript_path);
+const maxTokens = realUsage?.max_tokens || resolveMaxTokens() || 200000;
+const pct = currentTokens / maxTokens;
+const source = realUsage ? "real" : "estimated";
+
+const headroom = Math.max(0, Math.round(maxTokens * threshold - currentTokens));
+const pctDisplay = (pct * 100).toFixed(1);
+const thresholdDisplay = Math.round(threshold * 100);
+let recommendation;
+if (pct < threshold * 0.5)
+	recommendation = "All clear. Plenty of context remaining.";
+else if (pct < threshold)
+	recommendation = "Approaching threshold. Consider wrapping up complex tasks.";
+else
+	recommendation =
+		"At threshold. Compaction recommended — run /cg:compact or /cg:prune.";
+
+// Don't overwrite a recent state file with estimated data — checkpoint writes
+// or the submit hook may have written accurate post-compaction counts that we'd clobber.
+if (source === "estimated") {
+	const sf = stateFile(session_id);
+	try {
+		const sfStat = fs.statSync(sf);
+		if (Date.now() - sfStat.mtimeMs < 30000) {
+			log(
+				`state-skip session=${session_id} — not overwriting recent state with estimate`,
+			);
+			process.exit(0);
+		}
+	} catch {}
+}
+
+// Carry forward savings estimates and baseline overhead from the existing state file.
+// This avoids re-reading and re-parsing the full transcript (~50MB at scale).
+let smartEstimatePct = 0;
+let recentEstimatePct = 0;
+let baselineOverhead = 0;
+let baselineResponseCount = 0;
+try {
+	const sf = stateFile(session_id);
+	if (fs.existsSync(sf)) {
+		const prev = JSON.parse(fs.readFileSync(sf, "utf8"));
+		smartEstimatePct = prev.smart_estimate_pct ?? 0;
+		recentEstimatePct = prev.recent_estimate_pct ?? 0;
+		baselineOverhead = prev.baseline_overhead ?? 0;
+		baselineResponseCount = prev.baseline_response_count ?? 0;
+	}
+} catch (e) {
+	log(`state-read-error session=${session_id}: ${e.message}`);
+}
+
+if (baselineResponseCount < 2 && currentTokens > 0) {
+	if (baselineOverhead) {
+		baselineOverhead = Math.min(baselineOverhead, currentTokens);
+	} else {
+		baselineOverhead = currentTokens;
+	}
+	baselineResponseCount++;
+	log(
+		`baseline-overhead session=${session_id} tokens=${baselineOverhead} response=${baselineResponseCount}`,
+	);
+
+	// Recompute estimates now that we have the baseline — the submit hook ran
+	// before us and wrote 0 estimates because it didn't have the baseline yet.
+	try {
+		const savings = estimateSavings(
+			transcript_path,
+			currentTokens,
+			maxTokens,
+			baselineOverhead,
+		);
+		smartEstimatePct = savings.smartPct;
+		recentEstimatePct = savings.recentPct;
+		log(
+			`baseline-recompute session=${session_id} smart=${smartEstimatePct}% recent=${recentEstimatePct}%`,
+		);
+	} catch (e) {
+		log(`baseline-recompute-error: ${e.message}`);
+	}
+}
+
+try {
+	ensureDataDir();
+	const remaining = Math.max(
+		0,
+		Math.round(thresholdDisplay - Number.parseFloat(pctDisplay)),
+	);
+	const stateJson = JSON.stringify({
+		current_tokens: currentTokens,
+		max_tokens: maxTokens,
+		pct,
+		pct_display: pctDisplay,
+		threshold,
+		threshold_display: thresholdDisplay,
+		remaining_to_alert: remaining,
+		headroom,
+		recommendation,
+		source,
+		model: realUsage?.model || "unknown",
+		smart_estimate_pct: smartEstimatePct,
+		recent_estimate_pct: recentEstimatePct,
+		baseline_overhead: baselineOverhead,
+		baseline_response_count: baselineResponseCount,
+		payload_bytes: payloadBytes,
+		session_id,
+		transcript_path,
+		ts: Date.now(),
+	});
+	atomicWriteFileSync(stateFile(session_id), stateJson);
+
+	// Also write to fixed fallback location so the statusline can find it
+	// (statusline process doesn't receive CLAUDE_PLUGIN_DATA).
+	const slFile = statuslineStateFile(session_id);
+	if (slFile !== stateFile(session_id)) {
+		fs.mkdirSync(STATUSLINE_STATE_DIR, { recursive: true });
+		atomicWriteFileSync(slFile, stateJson);
+	}
+} catch (e) {
+	log(`state-write-error session=${session_id}: ${e.message}`);
+	process.stderr.write(`cg: state-write-error: ${e.message}\n`);
+}
+
+log(
+	`state-update session=${session_id} tokens=${currentTokens}/${maxTokens} pct=${pctDisplay}% source=${source}`,
+);

package/hooks/submit.mjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+/**
+ * UserPromptSubmit hook — Context Guardian's main entry point.
+ *
+ * Runs on every user message. Writes token usage state for the statusline
+ * and /cg:stats. Compaction is handled entirely by skills (compact-cli.mjs).
+ *
+ * @module submit-hook
+ */
+import fs from "node:fs";
+import { loadConfig, resolveMaxTokens } from "../lib/config.mjs";
+import { estimateSavings } from "../lib/estimate.mjs";
+import { log } from "../lib/logger.mjs";
+import {
+	atomicWriteFileSync,
+	ensureDataDir,
+	STATUSLINE_STATE_DIR,
+	stateFile,
+	statuslineStateFile,
+} from "../lib/paths.mjs";
+import { estimateTokens, getTokenUsage } from "../lib/tokens.mjs";
+
+// ---------------------------------------------------------------------------
+// Input
+// ---------------------------------------------------------------------------
+let input;
+try {
+	input = JSON.parse(fs.readFileSync(0, "utf8"));
+} catch (e) {
+	process.stderr.write(`cg: failed to parse stdin: ${e.message}\n`);
+	process.exit(0);
+}
+const { session_id = "unknown", transcript_path } = input;
+
+// ---------------------------------------------------------------------------
+// Token usage check — write state for statusline and /cg:stats
+// ---------------------------------------------------------------------------
+if (!transcript_path || !fs.existsSync(transcript_path)) process.exit(0);
+
+// Measure raw transcript file size — proxy for API request payload size.
+// The ~20MB API payload limit is separate from the token context window and
+// can lock users out of a session entirely (can't even compact).
+let payloadBytes = 0;
+try {
+	payloadBytes = fs.statSync(transcript_path).size;
+} catch {}
+
+const cfg = loadConfig();
+const threshold = cfg.threshold ?? 0.35;
+
+const realUsage = getTokenUsage(transcript_path);
+const currentTokens = realUsage
+	? realUsage.current_tokens
+	: estimateTokens(transcript_path);
+const maxTokens = realUsage?.max_tokens || resolveMaxTokens() || 200000;
+const pct = currentTokens / maxTokens;
+const source = realUsage ? "real" : "estimated";
+
+log(
+	`check session=${session_id} tokens=${currentTokens}/${maxTokens} pct=${(pct * 100).toFixed(1)}% threshold=${(threshold * 100).toFixed(0)}% source=${source}`,
+);
+
+// Write state for statusline and /cg:stats
+const headroom = Math.max(0, Math.round(maxTokens * threshold - currentTokens));
+const pctDisplay = (pct * 100).toFixed(1);
+const thresholdDisplay = Math.round(threshold * 100);
+let recommendation;
+if (pct < threshold * 0.5)
+	recommendation = "All clear. Plenty of context remaining.";
+else if (pct < threshold)
+	recommendation = "Approaching threshold. Consider wrapping up complex tasks.";
+else
+	recommendation =
+		"At threshold. Compaction recommended — run /cg:compact or /cg:prune.";
+
+// Read measured baseline overhead from state (captured by stop hook on first response)
+let baselineOverhead = 0;
+try {
+	const sf = stateFile(session_id);
+	if (fs.existsSync(sf)) {
+		const prev = JSON.parse(fs.readFileSync(sf, "utf8"));
+		baselineOverhead = prev.baseline_overhead ?? 0;
+	}
+} catch (e) {
+	log(`state-read-error session=${session_id}: ${e.message}`);
+}
+
+const savings = estimateSavings(
+	transcript_path,
+	currentTokens,
+	maxTokens,
+	baselineOverhead,
+);
+
+try {
+	ensureDataDir();
+	const remaining = Math.max(
+		0,
+		Math.round(thresholdDisplay - Number.parseFloat(pctDisplay)),
+	);
+	const stateJson = JSON.stringify({
+		current_tokens: currentTokens,
+		max_tokens: maxTokens,
+		pct,
+		pct_display: pctDisplay,
+		threshold,
+		threshold_display: thresholdDisplay,
+		remaining_to_alert: remaining,
+		headroom,
+		recommendation,
+		source,
+		model: realUsage?.model || "unknown",
+		smart_estimate_pct: savings.smartPct,
+		recent_estimate_pct: savings.recentPct,
+		baseline_overhead: baselineOverhead,
+		payload_bytes: payloadBytes,
+		session_id,
+		transcript_path,
+		ts: Date.now(),
+	});
+	atomicWriteFileSync(stateFile(session_id), stateJson);
+
+	// Also write to fixed fallback location so the statusline can find it
+	// (statusline process doesn't receive CLAUDE_PLUGIN_DATA).
+	const slFile = statuslineStateFile(session_id);
+	if (slFile !== stateFile(session_id)) {
+		fs.mkdirSync(STATUSLINE_STATE_DIR, { recursive: true });
+		atomicWriteFileSync(slFile, stateJson);
+	}
+} catch (e) {
+	log(`state-write-error session=${session_id}: ${e.message}`);
+	process.stderr.write(`cg: state-write-error: ${e.message}\n`);
+}