@ricky-stevens/context-guardian 2.1.0

package/lib/stats.mjs

@@ -0,0 +1,81 @@
+import { Buffer } from "node:buffer";
+
+/**
+ * Calculate compaction stats and format a display block.
+ *
+ * @param {number} preTokens  — token count before compaction (0 = unavailable)
+ * @param {number} maxTokens  — context window limit
+ * @param {string} checkpointContent — the exported checkpoint text
+ * @returns {{ stats: object, block: string }}
+ */
+export function formatCompactionStats(
+	preTokens,
+	maxTokens,
+	checkpointContent,
+	{ overhead = 0, prePayloadBytes = 0 } = {},
+) {
+	const postTokens =
+		Math.round(Buffer.byteLength(checkpointContent, "utf8") / 4) + overhead;
+
+	// If preTokens is missing/zero, stats are unreliable — show what we can.
+	const hasPreData = preTokens > 0;
+	const saved = hasPreData ? Math.max(0, preTokens - postTokens) : 0;
+	const savedPct =
+		hasPreData && preTokens > 0
+			? ((saved / preTokens) * 100).toFixed(1)
+			: "0.0";
+	const prePct =
+		hasPreData && maxTokens > 0
+			? ((preTokens / maxTokens) * 100).toFixed(1)
+			: "?";
+	const postPct =
+		maxTokens > 0 ? ((postTokens / maxTokens) * 100).toFixed(1) : "0.0";
+
+	// Session size: transcript file + system overhead (before), checkpoint content (after)
+	const overheadBytes = overhead * 4;
+	const totalPreBytes = prePayloadBytes + overheadBytes;
+	const postPayloadBytes = Buffer.byteLength(checkpointContent, "utf8");
+
+	const stats = {
+		preTokens,
+		postTokens,
+		maxTokens,
+		saved,
+		savedPct: Number.parseFloat(savedPct),
+		prePct: hasPreData ? Number.parseFloat(prePct) : 0,
+		postPct: Number.parseFloat(postPct),
+		prePayloadBytes: totalPreBytes,
+		postPayloadBytes,
+	};
+
+	const beforeLine = hasPreData
+		? `│  Before:  ${preTokens.toLocaleString()} tokens (~${prePct}% of context)`
+		: `│  Before:  unknown (token data unavailable)`;
+	const savedLine = hasPreData
+		? `│  Saved:   ~${saved.toLocaleString()} tokens (${savedPct}% reduction)`
+		: `│  Saved:   unknown`;
+
+	// Session size line — only shown if we have the pre-compaction file size
+	const payloadLine =
+		totalPreBytes > 0
+			? `│  Session: ${Math.max(0.1, totalPreBytes / (1024 * 1024)).toFixed(1)}MB → ${Math.max(0.1, postPayloadBytes / (1024 * 1024)).toFixed(1)}MB`
+			: "";
+
+	const lines = [
+		`┌──────────────────────────────────────────────────────────────────────────────────────────────────`,
+		`│  Compaction Stats`,
+		`│`,
+		beforeLine,
+		`│  After:   ~${postTokens.toLocaleString()} tokens (~${postPct}% of context)`,
+		savedLine,
+	];
+	if (payloadLine) lines.push(payloadLine);
+	lines.push(
+		`│`,
+		`└──────────────────────────────────────────────────────────────────────────────────────────────────`,
+	);
+
+	const block = lines.join("\n");
+
+	return { stats, block };
+}

package/lib/statusline.mjs

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+/**
+ * Statusline renderer for Claude Code's terminal status bar.
+ *
+ * Reads JSON from stdin (piped by Claude Code) containing session stats,
+ * outputs a compact context usage line. Zero context window cost.
+ *
+ * Auto-configured by the session-start hook.
+ *
+ * @module statusline
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+let raw = "";
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", (chunk) => {
+	raw += chunk;
+});
+process.stdin.on("error", () => {
+	process.stdout.write("Context: --");
+});
+process.stdin.on("end", () => {
+	try {
+		const data = JSON.parse(raw);
+		process.stdout.write(render(data));
+	} catch {
+		process.stdout.write("Context: --");
+	}
+});
+
+/**
+ * Render the statusline output from Claude Code's session data.
+ *
+ * Claude Code pipes JSON with this structure:
+ *   context_window: { used_percentage, remaining_percentage, total_input_tokens, total_output_tokens }
+ *   model: { id, display_name }
+ */
+function render(data) {
+	const pctRaw = data.context_window?.used_percentage;
+	if (pctRaw == null) {
+		const dim = "\x1b[2m";
+		const reset = "\x1b[0m";
+		return `${dim}Context usage: --${reset}`;
+	}
+
+	const pct = Math.round(pctRaw);
+
+	// Read threshold from config if available, fallback to 35%
+	const dataDir =
+		process.env.CLAUDE_PLUGIN_DATA || path.join(os.homedir(), ".claude", "cg");
+	let threshold = 35;
+	try {
+		const configPath = path.join(dataDir, "config.json");
+		if (fs.existsSync(configPath)) {
+			const cfg = JSON.parse(fs.readFileSync(configPath, "utf8"));
+			if (cfg.threshold) threshold = Math.round(cfg.threshold * 100);
+		}
+	} catch {}
+
+	// Color strategy:
+	// - Green: labels dim/grey, only numbers colored green
+	// - Yellow: labels dim/grey, only numbers colored yellow
+	// - Red: entire label+number is bold red (maximum visibility)
+	const reset = "\x1b[0m";
+	const dim = "\x1b[2m";
+
+	let contextStr;
+	if (pct >= threshold) {
+		contextStr = `\x1b[1;31mContext usage: ${pct}%${reset}`;
+	} else {
+		const numColor = pct < threshold * 0.7 ? "\x1b[32m" : "\x1b[33m";
+		contextStr = `${dim}Context usage:${reset} ${numColor}${pct}%${reset}`;
+	}
+
+	// Session size — proxy for the ~20MB API request limit (separate from token limit).
+	// Read from the most recent state file written by submit/stop hooks.
+	let sessionStr = `${dim}--${reset}`;
+	try {
+		const stateFiles = fs
+			.readdirSync(dataDir)
+			.filter((f) => f.startsWith("state-") && f.endsWith(".json"));
+		if (stateFiles.length > 0) {
+			// Pick the most recently modified state file
+			let newest = stateFiles[0];
+			let newestMtime = 0;
+			for (const f of stateFiles) {
+				const mt = fs.statSync(path.join(dataDir, f)).mtimeMs;
+				if (mt > newestMtime) {
+					newestMtime = mt;
+					newest = f;
+				}
+			}
+			const state = JSON.parse(
+				fs.readFileSync(path.join(dataDir, newest), "utf8"),
+			);
+			// Total payload = transcript file + system overhead (prompts, tools, CLAUDE.md).
+			// The transcript JSONL only contains conversation messages, not the full
+			// API request. baseline_overhead (tokens) × 4 ≈ system overhead in bytes.
+			const overheadBytes = (state.baseline_overhead || 0) * 4;
+			const totalBytes = (state.payload_bytes || 0) + overheadBytes;
+			if (totalBytes > 0) {
+				const mb = Math.max(0.1, totalBytes / (1024 * 1024)).toFixed(1);
+				if (mb >= 15) {
+					sessionStr = `\x1b[1;31mSession size: ${mb}/20MB${reset}`;
+				} else {
+					const numColor = mb < 10 ? "\x1b[32m" : "\x1b[33m";
+					sessionStr = `${dim}Session size:${reset} ${numColor}${mb}${dim}/20MB${reset}`;
+				}
+			}
+		}
+	} catch {}
+
+	const untilAlert = Math.max(0, threshold - pct);
+	const tail =
+		untilAlert > 0
+			? `${dim}/cg:stats for more${reset}`
+			: `\x1b[1;31mcompaction recommended \u2014 /cg:compact${reset}`;
+
+	return `${contextStr} ${dim}|${reset} ${sessionStr} ${dim}|${reset} ${tail}`;
+}

package/lib/synthetic-session.mjs

@@ -0,0 +1,273 @@
+/**
+ * Writes a synthetic JSONL session file to Claude Code's session directory.
+ * This enables `/resume cg:{hash}` (or `/resume cg:{name}`) to load CG
+ * checkpoints as real conversation messages — not additionalContext.
+ *
+ * The synthetic session contains:
+ *   Line 1: User message with the checkpoint content
+ *   Line 2: Assistant message acknowledging the context
+ *   Line 3: custom-title metadata entry
+ *
+ * Each compact cycle generates a unique title (`cg:{4-hex}`) to avoid
+ * CC's in-memory session caching, which prevents reuse of a static title
+ * across multiple resume cycles within the same CC process.
+ *
+ * Manifest entries carry a `type` field ("compact" or "handoff").
+ * Compact entries are ephemeral — deleted on next compact.
+ * Handoff entries persist until explicitly removed.
+ */
+
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { log } from "./logger.mjs";
+
+/**
+ * Max length before hash truncation, matching CC's sessionStoragePortable.ts.
+ */
+const MAX_SANITIZED_LENGTH = 200;
+
+/**
+ * djb2 string hash — matches CC's utils/hash.ts.
+ * Used as fallback when Bun.hash isn't available.
+ */
+function djb2Hash(str) {
+	let hash = 0;
+	for (let i = 0; i < str.length; i++) {
+		hash = Math.trunc((hash << 5) - hash + str.codePointAt(i));
+	}
+	return hash;
+}
+
+/**
+ * Sanitize a cwd path to match Claude Code's project directory naming.
+ * Mirrors sanitizePath() from sessionStoragePortable.ts exactly:
+ *   1. Replace all non-alphanumeric chars with hyphens
+ *   2. If > 200 chars, truncate and append a djb2 hash suffix
+ *
+ * /home/ricky/myapp → -home-ricky-myapp
+ */
+function sanitizeCwd(cwd) {
+	const sanitized = cwd.replaceAll(/[^a-zA-Z0-9]/g, "-");
+	if (sanitized.length <= MAX_SANITIZED_LENGTH) {
+		return sanitized;
+	}
+	// CC uses Bun.hash (wyhash) when running in Bun, djb2Hash in Node.
+	// Hooks run as Node subprocesses, but CC itself runs in Bun — so for
+	// long paths the hashes would differ. In practice, paths > 200 chars
+	// are extremely rare. If this becomes an issue, we can read the actual
+	// directory name from disk instead of computing it.
+	const hash = Math.abs(djb2Hash(cwd)).toString(36);
+	return `${sanitized.slice(0, MAX_SANITIZED_LENGTH)}-${hash}`;
+}
+
+/**
+ * Get the sessions directory for a project.
+ */
+export function getSessionsDir(projectCwd) {
+	return path.join(
+		os.homedir(),
+		".claude",
+		"projects",
+		sanitizeCwd(projectCwd),
+	);
+}
+
+/**
+ * Get the manifest file path. Stored in plugin data dir alongside other state.
+ */
+function getManifestPath() {
+	const dataDir =
+		process.env.CLAUDE_PLUGIN_DATA || path.join(os.homedir(), ".claude", "cg");
+	return path.join(dataDir, "synthetic-sessions.json");
+}
+
+/**
+ * Read the manifest of tracked synthetic sessions.
+ * @returns {Record<string, { uuid: string, path: string }>}
+ */
+export function readManifest() {
+	try {
+		return JSON.parse(fs.readFileSync(getManifestPath(), "utf8"));
+	} catch {
+		return {};
+	}
+}
+
+/**
+ * Write the manifest.
+ */
+function writeManifest(manifest) {
+	const manifestPath = getManifestPath();
+	fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
+	fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), {
+		mode: 0o600,
+	});
+}
+
+/**
+ * Scan a sessions directory for JSONL files whose custom-title matches `title`
+ * and delete them. Skips the file tracked by the manifest (identified by
+ * `knownUuid`) since that's already handled above.
+ *
+ * This is a defensive sweep for orphaned files: pre-manifest synthetics,
+ * files CC grew by appending messages after /resume, or files left behind
+ * when the manifest was corrupted. Without this, CC's title search returns
+ * multiple matches and /resume fails with "Found N sessions matching cg".
+ *
+ * Reads only the last 200 bytes of each file (the custom-title line is always
+ * last), so this is fast even with hundreds of sessions.
+ */
+export function purgeStaleTitle(sessionsDir, title, knownUuid) {
+	if (!fs.existsSync(sessionsDir)) return;
+
+	const files = fs.readdirSync(sessionsDir).filter((f) => f.endsWith(".jsonl"));
+	const needle = `"customTitle":"${title}"`;
+
+	for (const f of files) {
+		// Skip the file we already handled via manifest (retitled or about to create)
+		if (knownUuid && f.startsWith(knownUuid)) continue;
+
+		const fullPath = path.join(sessionsDir, f);
+		try {
+			// Scan the full file — after /resume, CC appends real conversation
+			// data which pushes the original custom-title entries far from the
+			// tail. A tail-only read misses them, leaving stale "cg" titles that
+			// cause /resume to match the wrong session.
+			const content = fs.readFileSync(fullPath, "utf8");
+			if (content.includes(needle) && content.includes('"custom-title"')) {
+				fs.unlinkSync(fullPath);
+				log(`synthetic-session: purged stale title="${title}" file=${f}`);
+			}
+		} catch {
+			// Skip unreadable files
+		}
+	}
+}
+
+/**
+ * Write a synthetic JSONL session that `/resume <title>` can find and load.
+ *
+ * @param {object} opts
+ * @param {string} opts.checkpointContent - Full checkpoint markdown text
+ * @param {string} opts.title - Session title: "cg:{hash}" or "cg:{label}"
+ * @param {"compact"|"handoff"} opts.type - Entry type for manifest cleanup
+ * @param {string} opts.projectCwd - Absolute path to project root
+ * @returns {{ sessionUuid: string, jsonlPath: string }}
+ */
+export function writeSyntheticSession({
+	checkpointContent,
+	title,
+	type = "compact",
+	projectCwd,
+}) {
+	const sessionsDir = getSessionsDir(projectCwd);
+	const manifest = readManifest();
+
+	// Clean up previous compact synthetics — they're ephemeral.
+	// Each compact cycle generates a unique title (cg:{hash}), so there's no
+	// title collision with CC's in-memory cache. Safe to delete unconditionally.
+	// Handoff entries are never cleaned up by compaction.
+	if (type === "compact") {
+		for (const [key, entry] of Object.entries(manifest)) {
+			if (entry.type !== "compact") continue;
+			try {
+				fs.unlinkSync(entry.path);
+				log(`synthetic-session: cleaned compact ${entry.uuid}`);
+			} catch {
+				// File may already be gone
+			}
+			delete manifest[key];
+		}
+	}
+
+	// For handoff titles, clean up any previous entry with the same title
+	if (type === "handoff" && manifest[title]) {
+		try {
+			fs.unlinkSync(manifest[title].path);
+			log(
+				`synthetic-session: cleaned previous handoff ${manifest[title].uuid}`,
+			);
+		} catch {
+			// File may already be gone
+		}
+		delete manifest[title];
+	}
+
+	// Generate a fresh random UUID for the new synthetic session
+	const sessionUuid = crypto.randomUUID();
+	const userUuid = crypto.randomUUID();
+	const assistantUuid = crypto.randomUUID();
+
+	const now = new Date();
+	const userTimestamp = now.toISOString();
+	const assistantTimestamp = new Date(now.getTime() + 1).toISOString();
+
+	// Line 1: User message with checkpoint as plain string content
+	const userMsg = {
+		parentUuid: null,
+		isSidechain: false,
+		type: "user",
+		message: {
+			role: "user",
+			content: checkpointContent,
+		},
+		uuid: userUuid,
+		timestamp: userTimestamp,
+		userType: "external",
+		cwd: projectCwd,
+		sessionId: sessionUuid,
+		version: "1.0.0",
+	};
+
+	// Line 2: Assistant acknowledgment
+	const assistantMsg = {
+		parentUuid: userUuid,
+		isSidechain: false,
+		type: "assistant",
+		message: {
+			role: "assistant",
+			content: [
+				{
+					type: "text",
+					text: "Context restored from checkpoint. I have the full session history above including all decisions, code changes, errors, and reasoning. Ready to continue — what would you like to work on?",
+				},
+			],
+			stop_reason: "end_turn",
+		},
+		uuid: assistantUuid,
+		timestamp: assistantTimestamp,
+		userType: "external",
+		cwd: projectCwd,
+		sessionId: sessionUuid,
+		version: "1.0.0",
+	};
+
+	// Line 3: Custom title for /resume search
+	const titleEntry = {
+		type: "custom-title",
+		customTitle: title,
+		sessionId: sessionUuid,
+	};
+
+	// Build JSONL content
+	const jsonlContent = `${[userMsg, assistantMsg, titleEntry]
+		.map((entry) => JSON.stringify(entry))
+		.join("\n")}\n`;
+
+	// Write to Claude Code's session directory
+	fs.mkdirSync(sessionsDir, { recursive: true });
+	const jsonlPath = path.join(sessionsDir, `${sessionUuid}.jsonl`);
+	fs.writeFileSync(jsonlPath, jsonlContent, { mode: 0o600 });
+
+	// Update manifest with type for cleanup discrimination
+	manifest[title] = { uuid: sessionUuid, path: jsonlPath, type };
+	writeManifest(manifest);
+
+	log(
+		`synthetic-session written: title="${title}" uuid=${sessionUuid} path=${jsonlPath}`,
+	);
+
+	return { sessionUuid, jsonlPath };
+}

package/lib/tokens.mjs

@@ -0,0 +1,170 @@
+import fs from "node:fs";
+import { contentBytesOf, flattenContent } from "./content.mjs";
+
+// Matches any compact/restore marker that signals a compaction boundary.
+const COMPACT_MARKER_RE = /^\[(SMART COMPACT|KEEP RECENT|RESTORED CONTEXT)/;
+
+// ---------------------------------------------------------------------------
+// Get real token usage from the transcript JSONL.
+//
+// Every assistant message includes `message.usage` with:
+//   input_tokens, cache_creation_input_tokens, cache_read_input_tokens
+//
+// Total context used = input_tokens + cache_creation + cache_read
+//
+// Reads backwards from the end of the file for efficiency.
+// Returns { current_tokens, output_tokens } or null if no usage data found.
+// ---------------------------------------------------------------------------
+export function getTokenUsage(transcriptPath) {
+	if (!transcriptPath) return null;
+
+	let stat;
+	try {
+		stat = fs.statSync(transcriptPath);
+	} catch {
+		return null;
+	}
+
+	// Tiered read: try a small chunk first (covers most cases where the last
+	// assistant message is recent and short). Fall back to 2MB for large responses.
+	const tiers = [32 * 1024, 2 * 1024 * 1024];
+	const fd = fs.openSync(transcriptPath, "r");
+	try {
+		for (const tier of tiers) {
+			const readSize = Math.min(stat.size, tier);
+			const buf = Buffer.alloc(readSize);
+			fs.readSync(fd, buf, 0, readSize, Math.max(0, stat.size - readSize));
+
+			const text = buf.toString("utf8");
+			const lines = text.split("\n").filter((l) => l.trim());
+			const result = _findUsage(lines);
+			if (result) return result;
+			// If file is smaller than tier, no point trying a bigger read
+			if (stat.size <= tier) return null;
+		}
+		return null;
+	} finally {
+		fs.closeSync(fd);
+	}
+}
+
+function _findUsage(lines) {
+	for (let i = lines.length - 1; i >= 0; i--) {
+		try {
+			const obj = JSON.parse(lines[i]);
+			const usage = obj.message?.usage;
+			if (usage && typeof usage.input_tokens === "number") {
+				const inputTokens = usage.input_tokens || 0;
+				const cacheCreate = usage.cache_creation_input_tokens || 0;
+				const cacheRead = usage.cache_read_input_tokens || 0;
+				const output = usage.output_tokens || 0;
+
+				// Detect max_tokens from model name in the same message.
+				// Only Opus 4.6+ has 1M tokens. Format: "claude-opus-4-6"
+				const model = (obj.message?.model || "").toLowerCase();
+				let max_tokens = 200000; // default for all Sonnet/Haiku/older Opus
+				const opusMatch = model.match(/opus[- ]?(\d+)[- .]?(\d+)?/);
+				if (opusMatch) {
+					const major = Number.parseInt(opusMatch[1], 10);
+					const minor = Number.parseInt(opusMatch[2] || "0", 10);
+					if (major > 4 || (major === 4 && minor >= 6)) {
+						max_tokens = 1000000;
+					}
+				}
+
+				return {
+					current_tokens: inputTokens + cacheCreate + cacheRead,
+					output_tokens: output,
+					max_tokens,
+					model: obj.message?.model || "unknown",
+				};
+			}
+		} catch {}
+	}
+
+	return null;
+}
+
+// ---------------------------------------------------------------------------
+// Byte-based token estimation — fallback when no usage data is available
+// (e.g., very first message before any assistant response).
+// Counts content bytes after the last compact marker, divides by 4.
+// ---------------------------------------------------------------------------
+export function estimateTokens(transcriptPath) {
+	if (!transcriptPath) return 0;
+
+	// Read the last ~1MB — enough to cover content since the last compact marker.
+	let stat;
+	try {
+		stat = fs.statSync(transcriptPath);
+	} catch {
+		return 0;
+	}
+	const readSize = Math.min(stat.size, 1024 * 1024);
+	const buf = Buffer.alloc(readSize);
+	const fd = fs.openSync(transcriptPath, "r");
+	try {
+		fs.readSync(fd, buf, 0, readSize, Math.max(0, stat.size - readSize));
+	} finally {
+		fs.closeSync(fd);
+	}
+
+	const lines = buf
+		.toString("utf8")
+		.split("\n")
+		.filter((l) => l.trim());
+
+	let startIdx = 0;
+	for (let i = lines.length - 1; i >= 0; i--) {
+		try {
+			const obj = JSON.parse(lines[i]);
+			const text = flattenContent(obj.message?.content);
+			if (
+				COMPACT_MARKER_RE.test(text) ||
+				text.startsWith("# Context Checkpoint")
+			) {
+				startIdx = i;
+				break;
+			}
+		} catch {}
+	}
+
+	let bytes = 0;
+	for (let i = startIdx; i < lines.length; i++) {
+		try {
+			bytes += contentBytesOf(JSON.parse(lines[i]).message?.content);
+		} catch {}
+	}
+	return Math.round(bytes / 4);
+}
+
+// ---------------------------------------------------------------------------
+// Session overhead estimation — tokens from system prompt, tool definitions,
+// memory files, and skills that survive compaction unchanged.
+// Uses transcript file size / 4 to estimate conversation tokens, then
+// subtracts from real token count. Both estimate.mjs and checkpoint.mjs
+// use this for consistent predictions.
+// ---------------------------------------------------------------------------
+export function estimateOverhead(
+	currentTokens,
+	transcriptPath,
+	baselineOverhead = 0,
+) {
+	// If we have a measured baseline from the first response, use it.
+	// This was captured by the stop hook when context was almost entirely
+	// system prompts, CLAUDE.md, tool definitions, etc.
+	if (baselineOverhead > 0) return baselineOverhead;
+
+	// Fallback: conservative minimum. System prompts + CLAUDE.md + tool
+	// definitions are always present and can never be compacted away.
+	const MIN_OVERHEAD = 15_000;
+
+	if (!transcriptPath || !currentTokens) return MIN_OVERHEAD;
+	try {
+		const conversationTokens = Math.round(fs.statSync(transcriptPath).size / 4);
+		const computed = Math.max(0, currentTokens - conversationTokens);
+		return Math.max(MIN_OVERHEAD, computed);
+	} catch {
+		return MIN_OVERHEAD;
+	}
+}