claude-context-saver 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 simsibaq
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,172 @@
+# claude-context-saver
+
+Automatic context backup for Claude Code. Saves your conversation state before auto-compaction wipes it.
+
+## The Problem
+
+Claude Code auto-compacts conversations when the context window fills up, losing detailed session history. This package monitors token usage and creates structured markdown backups before that happens.
+
+## Install
+
+### Default — local (this project only)
+
+```bash
+npx claude-context-saver
+```
+
+Hooks install to `.claude/` in the current project directory.
+
+### Global (all projects)
+
+```bash
+npx claude-context-saver -g
+```
+
+Hooks install to `~/.claude/` — active for every project.
+
+### Other methods
+
+```bash
+# Global install via npm
+npm install -g claude-context-saver
+claude-context-saver            # local (default)
+claude-context-saver -g         # global
+
+# Manual / from source
+git clone https://github.com/panbergco/claude-context-saver.git
+cd claude-context-saver
+node setup.mjs                  # local (default)
+node setup.mjs -g               # global
+```
+
+Restart Claude Code after installing.
+
+## Uninstall
+
+```bash
+# Local
+npx claude-context-saver -u
+
+# Global
+npx claude-context-saver -g -u
+```
+
+## How It Works
+
+### StatusLine Monitor
+
+Runs every turn. Reads token usage from Claude Code and displays a live status line:
+
+```
+[!] Opus 4.6 | 65k/200k | 32% used | 51% free -> backup-3.md
+```
+
+Triggers backups based on dual thresholds:
+
+- **Token-based**: First backup at 50K tokens, then every 10K (60K, 70K, 80K...)
+- **Percentage-based**: At 30%, 15%, 5% free-until-compaction, continuous under 5%
+
+Accounts for Claude Code's 33K auto-compaction buffer in free-space calculations.
+
+### PreCompact Hook
+
+Fires right before compaction as a final safety net. Synchronously reads the full conversation transcript before compaction can modify it.
+
+### Backups
+
+Numbered markdown files saved to `{project}/.claude/backups/`:
+
+```
+1-backup-2026-03-07-14-15.md
+2-backup-2026-03-07-15-30.md
+```
+
+Each backup contains:
+- User requests
+- Files modified (Write/Edit operations)
+- Tasks created/updated
+- Skills invoked
+- Bash commands run
+- Key assistant responses
+- Token state at time of backup
+
+## File Layout After Install
+
+### Local mode (default) — `{project}/.claude/`
+
+```
+your-project/
+└── .claude/
+    ├── hooks/ContextRecoveryHook/
+    │   ├── backup-core.mjs
+    │   ├── statusline-monitor.mjs
+    │   └── conv-backup.mjs
+    ├── settings.json                  (statusLine + PreCompact hook added)
+    └── backups/
+        ├── 1-backup-2026-03-07-14-15.md
+        └── 2-backup-2026-03-07-15-30.md
+```
+
+### Global mode (`-g`) — `~/.claude/`
+
+```
+~/.claude/
+├── hooks/ContextRecoveryHook/
+│   ├── backup-core.mjs
+│   ├── statusline-monitor.mjs
+│   └── conv-backup.mjs
+├── settings.json                      (statusLine + PreCompact hook added)
+└── claudefast-statusline-state.json   (runtime state)
+```
+
+## Settings.json Changes
+
+The installer merges these entries into your settings (all existing settings preserved):
+
+**Local** (default) uses relative paths:
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "node \".claude/hooks/ContextRecoveryHook/statusline-monitor.mjs\""
+  },
+  "hooks": {
+    "PreCompact": [{
+      "hooks": [{
+        "type": "command",
+        "command": "node \".claude/hooks/ContextRecoveryHook/conv-backup.mjs\"",
+        "async": true
+      }]
+    }]
+  }
+}
+```
+
+**Global** (`-g`) uses `$HOME` paths:
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "node \"$HOME/.claude/hooks/ContextRecoveryHook/statusline-monitor.mjs\""
+  },
+  "hooks": {
+    "PreCompact": [{
+      "hooks": [{
+        "type": "command",
+        "command": "node \"$HOME/.claude/hooks/ContextRecoveryHook/conv-backup.mjs\"",
+        "async": true
+      }]
+    }]
+  }
+}
+```
+
+## Requirements
+
+- Node.js >= 18
+- Claude Code CLI
+- Zero npm dependencies
+
+## License
+
+MIT

package/backup-core.mjs

@@ -0,0 +1,306 @@
+// backup-core.mjs — Engine: JSONL parsing, markdown backup, state management
+// Pure Node.js ESM, zero dependencies
+
+import { readFileSync, writeFileSync, mkdirSync, readdirSync, existsSync } from 'node:fs';
+import { join, basename } from 'node:path';
+import { homedir } from 'node:os';
+import { createReadStream } from 'node:fs';
+import { createInterface } from 'node:readline';
+
+const STATE_PATH = join(homedir(), '.claude', 'claudefast-statusline-state.json');
+
+// --- State Management ---
+
+export function readState() {
+  try {
+    return JSON.parse(readFileSync(STATE_PATH, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+export function writeState(state) {
+  try {
+    const dir = join(homedir(), '.claude');
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    writeFileSync(STATE_PATH, JSON.stringify(state, null, 2), 'utf8');
+  } catch {
+    // Concurrent access — silently fail, next write wins
+  }
+}
+
+// --- JSONL Parsing ---
+
+// Skip these message types — they're 91%+ of lines and not useful for backups
+const SKIP_TYPES = new Set(['progress', 'file-history-snapshot']);
+
+export async function parseTranscript(transcriptPath) {
+  const messages = [];
+
+  if (!existsSync(transcriptPath)) return messages;
+
+  const rl = createInterface({
+    input: createReadStream(transcriptPath, { encoding: 'utf8' }),
+    crlfDelay: Infinity,
+  });
+
+  for await (const line of rl) {
+    if (!line.trim()) continue;
+    try {
+      const obj = JSON.parse(line);
+      if (obj.type && SKIP_TYPES.has(obj.type)) continue;
+      messages.push(obj);
+    } catch {
+      // Malformed line — skip
+    }
+  }
+
+  return messages;
+}
+
+// Synchronous version for PreCompact hook (must read before compaction starts)
+export function parseTranscriptSync(transcriptPath) {
+  const messages = [];
+
+  if (!existsSync(transcriptPath)) return messages;
+
+  const content = readFileSync(transcriptPath, 'utf8');
+  for (const line of content.split('\n')) {
+    if (!line.trim()) continue;
+    try {
+      const obj = JSON.parse(line);
+      if (obj.type && SKIP_TYPES.has(obj.type)) continue;
+      messages.push(obj);
+    } catch {
+      // Malformed line — skip
+    }
+  }
+
+  return messages;
+}
+
+// --- Data Extraction ---
+
+export function extractSessionData(messages) {
+  const data = {
+    userRequests: [],
+    fileModifications: [],
+    tasksCreated: [],
+    tasksUpdated: [],
+    skillCalls: [],
+    bashCommands: [],
+    keyResponses: [],
+  };
+
+  for (const msg of messages) {
+    // User messages / requests
+    if (msg.type === 'human' || msg.role === 'user') {
+      const text = extractText(msg);
+      if (text) data.userRequests.push(truncate(text, 500));
+    }
+
+    // Assistant messages — scan for tool use
+    if (msg.type === 'assistant' || msg.role === 'assistant') {
+      const content = msg.content || msg.message?.content;
+      if (!content) continue;
+
+      const blocks = Array.isArray(content) ? content : [content];
+
+      for (const block of blocks) {
+        if (typeof block === 'string') {
+          // Text response — capture if substantial
+          if (block.length > 100) {
+            data.keyResponses.push(truncate(block, 300));
+          }
+          continue;
+        }
+
+        if (block.type === 'text' && block.text && block.text.length > 100) {
+          data.keyResponses.push(truncate(block.text, 300));
+          continue;
+        }
+
+        if (block.type !== 'tool_use') continue;
+
+        const name = block.name;
+        const input = block.input || {};
+
+        if (name === 'Write' || name === 'Edit') {
+          const fp = input.file_path;
+          if (fp) data.fileModifications.push(fp);
+        } else if (name === 'TaskCreate') {
+          data.tasksCreated.push(input.subject || input.description || '(untitled)');
+        } else if (name === 'TaskUpdate') {
+          const desc = input.status
+            ? `#${input.taskId} → ${input.status}`
+            : `#${input.taskId} updated`;
+          data.tasksUpdated.push(desc);
+        } else if (name === 'Skill') {
+          data.skillCalls.push(input.skill || '(unknown)');
+        } else if (name === 'Bash') {
+          const cmd = input.command;
+          if (cmd) data.bashCommands.push(truncate(cmd, 200));
+        }
+      }
+    }
+  }
+
+  // Deduplicate file modifications
+  data.fileModifications = [...new Set(data.fileModifications)];
+
+  return data;
+}
+
+function extractText(msg) {
+  if (typeof msg.content === 'string') return msg.content;
+  if (msg.message?.content && typeof msg.message.content === 'string') return msg.message.content;
+  const content = msg.content || msg.message?.content;
+  if (Array.isArray(content)) {
+    return content
+      .filter(b => b.type === 'text')
+      .map(b => b.text)
+      .join('\n');
+  }
+  return null;
+}
+
+function truncate(str, max) {
+  if (str.length <= max) return str;
+  return str.slice(0, max) + '...';
+}
+
+// --- Markdown Formatting ---
+
+export function formatBackupMarkdown(data, meta) {
+  const lines = [];
+  const ts = new Date().toISOString().replace('T', ' ').slice(0, 16);
+
+  lines.push(`# Context Backup`);
+  lines.push(`- **Date**: ${ts}`);
+  lines.push(`- **Session**: ${meta.sessionId || 'unknown'}`);
+  lines.push(`- **Trigger**: ${meta.trigger || 'unknown'}`);
+  if (meta.tokensUsed) lines.push(`- **Tokens Used**: ${meta.tokensUsed.toLocaleString()}`);
+  if (meta.windowSize) lines.push(`- **Context Window**: ${meta.windowSize.toLocaleString()}`);
+  if (meta.freePercent != null) lines.push(`- **Free Until Compaction**: ${meta.freePercent.toFixed(1)}%`);
+  lines.push('');
+
+  if (data.userRequests.length) {
+    lines.push(`## User Requests`);
+    for (const r of data.userRequests) {
+      lines.push(`- ${r.replace(/\n/g, ' ').trim()}`);
+    }
+    lines.push('');
+  }
+
+  if (data.fileModifications.length) {
+    lines.push(`## Files Modified`);
+    for (const f of data.fileModifications) {
+      lines.push(`- \`${f}\``);
+    }
+    lines.push('');
+  }
+
+  if (data.tasksCreated.length) {
+    lines.push(`## Tasks Created`);
+    for (const t of data.tasksCreated) {
+      lines.push(`- ${t}`);
+    }
+    lines.push('');
+  }
+
+  if (data.tasksUpdated.length) {
+    lines.push(`## Tasks Updated`);
+    for (const t of data.tasksUpdated) {
+      lines.push(`- ${t}`);
+    }
+    lines.push('');
+  }
+
+  if (data.skillCalls.length) {
+    lines.push(`## Skills Used`);
+    for (const s of data.skillCalls) {
+      lines.push(`- ${s}`);
+    }
+    lines.push('');
+  }
+
+  if (data.bashCommands.length) {
+    lines.push(`## Bash Commands`);
+    for (const c of data.bashCommands) {
+      lines.push(`- \`${c.replace(/\n/g, ' ')}\``);
+    }
+    lines.push('');
+  }
+
+  if (data.keyResponses.length) {
+    lines.push(`## Key Responses`);
+    for (const r of data.keyResponses.slice(0, 10)) {
+      lines.push(`> ${r.replace(/\n/g, ' ').trim()}`);
+      lines.push('');
+    }
+  }
+
+  return lines.join('\n');
+}
+
+// --- Backup Path ---
+
+export function getBackupPath(projectDir) {
+  const backupDir = join(projectDir, '.claude', 'backups');
+  mkdirSync(backupDir, { recursive: true });
+
+  // Find next number
+  let maxNum = 0;
+  try {
+    const files = readdirSync(backupDir);
+    for (const f of files) {
+      const match = f.match(/^(\d+)-backup-/);
+      if (match) {
+        const n = parseInt(match[1], 10);
+        if (n > maxNum) maxNum = n;
+      }
+    }
+  } catch {
+    // Directory read failed — start at 1
+  }
+
+  const num = maxNum + 1;
+  const now = new Date();
+  const dateStr = [
+    now.getFullYear(),
+    String(now.getMonth() + 1).padStart(2, '0'),
+    String(now.getDate()).padStart(2, '0'),
+  ].join('-');
+  const timeStr = [
+    String(now.getHours()).padStart(2, '0'),
+    String(now.getMinutes()).padStart(2, '0'),
+  ].join('-');
+
+  const filename = `${num}-backup-${dateStr}-${timeStr}.md`;
+  return { dir: backupDir, path: join(backupDir, filename), num };
+}
+
+// --- Orchestrator ---
+
+export async function createBackup({ transcriptPath, sessionId, projectDir, trigger, tokensUsed, windowSize, freePercent, sync = false }) {
+  try {
+    const messages = sync
+      ? parseTranscriptSync(transcriptPath)
+      : await parseTranscript(transcriptPath);
+
+    if (messages.length === 0) return null;
+
+    const data = extractSessionData(messages);
+    const meta = { sessionId, trigger, tokensUsed, windowSize, freePercent };
+    const markdown = formatBackupMarkdown(data, meta);
+
+    const { path, num } = getBackupPath(projectDir);
+    writeFileSync(path, markdown, 'utf8');
+
+    return { path, num };
+  } catch (err) {
+    // Backup should never crash the host process
+    process.stderr.write(`[context-recovery] Backup failed: ${err.message}\n`);
+    return null;
+  }
+}

package/conv-backup.mjs

@@ -0,0 +1,47 @@
+// conv-backup.mjs — PreCompact hook: last-chance backup before auto-compaction
+// CRITICAL: Must read JSONL synchronously BEFORE compaction modifies it
+// Runs async (won't block compaction, but reads data first)
+
+import { createBackup } from './backup-core.mjs';
+
+async function main() {
+  // Read JSON from stdin
+  let input = '';
+  for await (const chunk of process.stdin) {
+    input += chunk;
+  }
+
+  let data;
+  try {
+    data = JSON.parse(input);
+  } catch {
+    process.stderr.write('[context-recovery] PreCompact: invalid stdin\n');
+    process.exit(0);
+  }
+
+  const sessionId = data.session_id || 'unknown';
+  const transcriptPath = data.transcript_path || '';
+  const projectDir = data.workspace?.project_dir || data.workspace?.cwd || process.cwd();
+
+  // Determine trigger type
+  const trigger = data.trigger === 'manual'
+    ? 'precompact_manual'
+    : 'precompact_auto';
+
+  // Use sync mode — must read JSONL before compaction modifies it
+  const result = await createBackup({
+    transcriptPath,
+    sessionId,
+    projectDir,
+    trigger,
+    sync: true,
+  });
+
+  if (result) {
+    process.stderr.write(`[context-recovery] PreCompact backup saved: ${result.path}\n`);
+  }
+}
+
+main().catch(err => {
+  process.stderr.write(`[context-recovery] PreCompact error: ${err.message}\n`);
+});

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "claude-context-saver",
+  "version": "1.0.0",
+  "description": "Automatic context backup for Claude Code — saves conversation state before auto-compaction wipes it",
+  "type": "module",
+  "bin": {
+    "claude-context-saver": "./setup.mjs"
+  },
+  "scripts": {
+    "install-hooks": "node setup.mjs",
+    "uninstall-hooks": "node setup.mjs --uninstall"
+  },
+  "files": [
+    "backup-core.mjs",
+    "statusline-monitor.mjs",
+    "conv-backup.mjs",
+    "setup.mjs"
+  ],
+  "keywords": [
+    "claude",
+    "claude-code",
+    "context",
+    "backup",
+    "compaction",
+    "hooks",
+    "statusline"
+  ],
+  "author": "panbergco",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/panbergco/claude-context-saver.git"
+  },
+  "homepage": "https://github.com/panbergco/claude-context-saver#readme",
+  "bugs": {
+    "url": "https://github.com/panbergco/claude-context-saver/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/setup.mjs

@@ -0,0 +1,197 @@
+#!/usr/bin/env node
+// setup.mjs — One-command installer for Context Recovery Hook
+// Usage: node setup.mjs [-g] [--uninstall]
+// Default: local install to project .claude/
+// -g: install globally to ~/.claude/ (all projects)
+
+import { readFileSync, writeFileSync, mkdirSync, cpSync, rmSync, existsSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const args = process.argv.slice(2);
+const isGlobal = args.includes('-g') || args.includes('--global');
+const isLocal = !isGlobal;
+const isUninstall = args.includes('--uninstall') || args.includes('-u');
+const isHelp = args.includes('--help') || args.includes('-h');
+
+// Resolve target directories based on mode
+const CLAUDE_DIR = isLocal
+  ? join(process.cwd(), '.claude')
+  : join(homedir(), '.claude');
+const HOOKS_DIR = join(CLAUDE_DIR, 'hooks', 'ContextRecoveryHook');
+const SETTINGS_PATH = join(CLAUDE_DIR, 'settings.json');
+
+// Command paths used inside settings.json
+// Global: use $HOME so it works across shells (Git Bash, etc.)
+// Local: use .claude/ relative path (Claude Code runs from project root)
+const HOOK_CMD_PREFIX = isLocal
+  ? '.claude/hooks/ContextRecoveryHook'
+  : '$HOME/.claude/hooks/ContextRecoveryHook';
+
+const SCRIPTS = ['backup-core.mjs', 'statusline-monitor.mjs', 'conv-backup.mjs'];
+
+function makeConfigs() {
+  return {
+    statusLine: {
+      type: 'command',
+      command: `node "${HOOK_CMD_PREFIX}/statusline-monitor.mjs"`,
+    },
+    preCompact: [{
+      hooks: [{
+        type: 'command',
+        command: `node "${HOOK_CMD_PREFIX}/conv-backup.mjs"`,
+        async: true,
+      }],
+    }],
+  };
+}
+
+function readSettings() {
+  try {
+    return JSON.parse(readFileSync(SETTINGS_PATH, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function writeSettings(settings) {
+  mkdirSync(CLAUDE_DIR, { recursive: true });
+  writeFileSync(SETTINGS_PATH, JSON.stringify(settings, null, 2) + '\n', 'utf8');
+}
+
+function install() {
+  const mode = isLocal ? 'local (this project only)' : 'global (all projects)';
+  console.log(`Context Recovery Hook — Installing ${mode}...\n`);
+
+  // 1. Copy scripts to hooks dir
+  mkdirSync(HOOKS_DIR, { recursive: true });
+  for (const script of SCRIPTS) {
+    const src = join(__dirname, script);
+    const dst = join(HOOKS_DIR, script);
+    cpSync(src, dst, { force: true });
+    console.log(`  Copied: ${script}`);
+  }
+  console.log(`  -> ${HOOKS_DIR}\n`);
+
+  // 2. Update settings.json
+  const settings = readSettings();
+  const configs = makeConfigs();
+
+  // Check for existing statusLine
+  if (settings.statusLine && settings.statusLine.command && !settings.statusLine.command.includes('ContextRecoveryHook')) {
+    console.log(`  WARNING: Existing statusLine config will be overwritten:`);
+    console.log(`    Old: ${JSON.stringify(settings.statusLine)}`);
+    console.log(`    New: ${JSON.stringify(configs.statusLine)}`);
+    console.log('');
+  }
+
+  settings.statusLine = configs.statusLine;
+
+  // Merge PreCompact hook — preserve existing hooks
+  if (!settings.hooks) settings.hooks = {};
+
+  const existingPreCompact = settings.hooks.PreCompact || [];
+  const alreadyInstalled = existingPreCompact.some(entry =>
+    entry.hooks?.some(h => h.command?.includes('ContextRecoveryHook'))
+  );
+
+  if (alreadyInstalled) {
+    console.log('  PreCompact hook already registered — skipping.');
+  } else {
+    settings.hooks.PreCompact = [...existingPreCompact, ...configs.preCompact];
+    console.log('  Added PreCompact hook.');
+  }
+
+  writeSettings(settings);
+  console.log(`  Updated: ${SETTINGS_PATH}\n`);
+
+  console.log('Installation complete!\n');
+  if (isLocal) {
+    console.log('Mode:                  local (this project only)');
+    console.log(`Hooks installed to:    .claude/hooks/ContextRecoveryHook/`);
+    console.log(`Settings updated:      .claude/settings.json`);
+  } else {
+    console.log('Mode:                  global (all projects)');
+    console.log('Hooks installed to:    ~/.claude/hooks/ContextRecoveryHook/');
+    console.log('Settings updated:      ~/.claude/settings.json');
+  }
+  console.log('Backups will appear:   {project}/.claude/backups/');
+  console.log('\nRestart Claude Code to activate.');
+}
+
+function uninstall() {
+  const mode = isLocal ? 'local' : 'global';
+  console.log(`Context Recovery Hook — Uninstalling ${mode}...\n`);
+
+  // 1. Remove hooks directory
+  if (existsSync(HOOKS_DIR)) {
+    rmSync(HOOKS_DIR, { recursive: true, force: true });
+    console.log(`  Removed: ${HOOKS_DIR}`);
+  } else {
+    console.log('  Hooks directory not found — skipping.');
+  }
+
+  // 2. Clean settings.json
+  if (existsSync(SETTINGS_PATH)) {
+    const settings = readSettings();
+    let changed = false;
+
+    // Remove statusLine if it's ours
+    if (settings.statusLine?.command?.includes('ContextRecoveryHook')) {
+      delete settings.statusLine;
+      console.log('  Removed statusLine config.');
+      changed = true;
+    }
+
+    // Remove our PreCompact hook entry
+    if (settings.hooks?.PreCompact) {
+      const filtered = settings.hooks.PreCompact.filter(entry =>
+        !entry.hooks?.some(h => h.command?.includes('ContextRecoveryHook'))
+      );
+      if (filtered.length !== settings.hooks.PreCompact.length) {
+        settings.hooks.PreCompact = filtered.length > 0 ? filtered : undefined;
+        if (!settings.hooks.PreCompact) delete settings.hooks.PreCompact;
+        if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
+        console.log('  Removed PreCompact hook.');
+        changed = true;
+      }
+    }
+
+    if (changed) {
+      writeSettings(settings);
+      console.log(`  Updated: ${SETTINGS_PATH}`);
+    } else {
+      console.log('  No hook config found in settings — skipping.');
+    }
+  }
+
+  // 3. Remove state file (only for global installs)
+  if (!isLocal) {
+    const statePath = join(CLAUDE_DIR, 'claudefast-statusline-state.json');
+    if (existsSync(statePath)) {
+      rmSync(statePath, { force: true });
+      console.log('  Removed state file.');
+    }
+  }
+
+  console.log('\nUninstall complete. Restart Claude Code to apply.');
+}
+
+// --- Main ---
+if (isHelp) {
+  console.log('claude-context-saver — Setup\n');
+  console.log('Usage:');
+  console.log('  node setup.mjs              Install for this project (.claude/)');
+  console.log('  node setup.mjs -g           Install globally (~/.claude/)');
+  console.log('  node setup.mjs -u           Uninstall local hooks');
+  console.log('  node setup.mjs -g -u        Uninstall global hooks');
+  console.log('\nAfter install, restart Claude Code to activate.');
+} else if (isUninstall) {
+  uninstall();
+} else {
+  install();
+}

package/statusline-monitor.mjs

@@ -0,0 +1,134 @@
+// statusline-monitor.mjs — StatusLine hook: monitors tokens, triggers backups, prints status
+// Receives JSON on stdin from Claude Code every turn
+// Must be FAST — gets cancelled if slow
+
+import { readState, writeState, createBackup } from './backup-core.mjs';
+
+const AUTO_COMPACT_BUFFER = 33_000;
+
+// Token-based thresholds: first at 50K, then every 10K
+const FIRST_TOKEN_THRESHOLD = 50_000;
+const TOKEN_INCREMENT = 10_000;
+
+// Percentage-based thresholds (free-until-compaction)
+const PCT_THRESHOLDS = [30, 15, 5];
+
+async function main() {
+  // Read JSON from stdin
+  let input = '';
+  for await (const chunk of process.stdin) {
+    input += chunk;
+  }
+
+  let data;
+  try {
+    data = JSON.parse(input);
+  } catch {
+    process.stdout.write('[?] No data');
+    process.exit(0);
+  }
+
+  const sessionId = data.session_id || 'unknown';
+  const transcriptPath = data.transcript_path || '';
+  const tokensUsed = data.context_window?.tokens_used ?? 0;
+  const windowSize = data.context_window?.window_size ?? 200_000;
+  const modelName = data.model?.name || data.model?.model_id || 'unknown';
+  const projectDir = data.workspace?.project_dir || data.workspace?.cwd || process.cwd();
+
+  // Calculate free-until-compaction percentage
+  const freeTokens = windowSize - tokensUsed - AUTO_COMPACT_BUFFER;
+  const freePercent = Math.max(0, (freeTokens / windowSize) * 100);
+
+  // Format token counts for display
+  const usedK = Math.round(tokensUsed / 1000);
+  const windowK = Math.round(windowSize / 1000);
+  const usedPercent = Math.round((tokensUsed / windowSize) * 100);
+  const freeDisplay = Math.round(freePercent);
+
+  // Load/reset state for this session
+  let state = readState();
+  if (state.sessionId !== sessionId) {
+    state = {
+      sessionId,
+      lastTokenThreshold: 0,
+      triggeredPctThresholds: [],
+      backupCount: 0,
+    };
+  }
+
+  let triggered = false;
+  let triggerReason = '';
+
+  // --- Token-based triggers ---
+  if (tokensUsed >= FIRST_TOKEN_THRESHOLD) {
+    // Calculate which threshold we should be at
+    const expectedThreshold = tokensUsed >= FIRST_TOKEN_THRESHOLD
+      ? FIRST_TOKEN_THRESHOLD + Math.floor((tokensUsed - FIRST_TOKEN_THRESHOLD) / TOKEN_INCREMENT) * TOKEN_INCREMENT
+      : 0;
+
+    if (expectedThreshold > (state.lastTokenThreshold || 0)) {
+      triggered = true;
+      triggerReason = `tokens_${Math.round(tokensUsed / 1000)}k`;
+      state.lastTokenThreshold = expectedThreshold;
+    }
+  }
+
+  // --- Percentage-based triggers ---
+  if (!triggered) {
+    const alreadyTriggered = new Set(state.triggeredPctThresholds || []);
+
+    for (const threshold of PCT_THRESHOLDS) {
+      if (freePercent <= threshold && !alreadyTriggered.has(threshold)) {
+        triggered = true;
+        triggerReason = `free_${threshold}pct`;
+        state.triggeredPctThresholds = [...alreadyTriggered, threshold];
+        break;
+      }
+    }
+
+    // Continuous backup under 5% free
+    if (!triggered && freePercent < 5 && tokensUsed > (state.lastContinuousTokens || 0) + TOKEN_INCREMENT) {
+      triggered = true;
+      triggerReason = `continuous_${freeDisplay}pct`;
+      state.lastContinuousTokens = tokensUsed;
+    }
+  }
+
+  // --- Perform backup if triggered ---
+  let backupLabel = '';
+  if (triggered) {
+    const result = await createBackup({
+      transcriptPath,
+      sessionId,
+      projectDir,
+      trigger: triggerReason,
+      tokensUsed,
+      windowSize,
+      freePercent,
+    });
+    if (result) {
+      state.backupCount = (state.backupCount || 0) + 1;
+      backupLabel = ` -> backup-${result.num}.md`;
+    }
+  }
+
+  // Save state
+  writeState(state);
+
+  // --- Build status line ---
+  // Format: [!] Opus 4.6 | 65k/200k | 32% used | 51% free -> backup-3.md
+  const shortModel = modelName
+    .replace(/^claude-/, '')
+    .replace(/-\d{8}$/, '')
+    .replace(/-/g, ' ')
+    .replace(/\b\w/g, c => c.toUpperCase());
+
+  const warn = freePercent < 15 ? '[!] ' : '';
+  const statusLine = `${warn}${shortModel} | ${usedK}k/${windowK}k | ${usedPercent}% used | ${freeDisplay}% free${backupLabel}`;
+
+  process.stdout.write(statusLine);
+}
+
+main().catch(() => {
+  process.stdout.write('[!] Monitor error');
+});