context-guardian 0.1.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,28 @@
+{
+  "name": "context-guardian",
+  "description": "Graceful context wind-down with session handoff for Claude Code",
+  "owner": {
+    "name": "zeroToOneProjects"
+  },
+  "plugins": [
+    {
+      "name": "context-guardian",
+      "source": "./",
+      "hooks": {
+        "StatusLine": [
+          {
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/cg-statusline.cjs\"",
+            "timeout": 2000
+          }
+        ],
+        "PostToolUse": [
+          {
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/cg-context-monitor.cjs\"",
+            "matcher": "*",
+            "timeout": 1000
+          }
+        ]
+      }
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,14 @@
+{
+  "name": "context-guardian",
+  "version": "0.1.0",
+  "description": "Graceful context wind-down with session handoff for Claude Code",
+  "author": {
+    "name": "zeroToOneProjects"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zeroToOneProjects/context-guardian"
+  },
+  "license": "MIT",
+  "keywords": ["context", "guardian", "statusline", "session", "handoff"]
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Hector Ros
+
+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,136 @@
+# Context Guardian
+
+[![npm version](https://img.shields.io/npm/v/context-guardian)](https://www.npmjs.com/package/context-guardian)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
+
+Graceful context wind-down with session handoff for Claude Code.
+
+## Quick Start
+
+```bash
+npx context-guardian
+```
+
+That's it. One command. The installer copies two hook scripts to `~/.claude/hooks/` and configures your `settings.json` with a statusline and a PostToolUse hook. It merges with your existing settings -- nothing is overwritten.
+
+To install for the current project only (instead of globally):
+
+```bash
+npx context-guardian --local
+```
+
+### What You Get
+
+After installation, your Claude Code statusline shows a live context usage bar:
+
+```
+Claude Opus 4.6 | my-project  ████████░░ 78%      <- normal (green)
+Claude Opus 4.6 | my-project  █████████░ 85%      <- wind down (orange)
+Claude Opus 4.6 | my-project  💀 ██████████ 96%   <- emergency (red+blink)
+```
+
+As context fills up, Claude receives escalating warnings that shift its behavior:
+
+- **At 80%** -- Wrap up current work, avoid starting new tasks.
+- **At 85%** -- Finish in-progress work only, no new work.
+- **At 95%** -- Stop immediately. Write a handoff file with what was done, what remains, and the exact prompt to continue. Suggest `/clear`.
+
+The result: every session ends with a handoff file. No work lost, no context wasted.
+
+### Uninstall
+
+```bash
+npx context-guardian --uninstall
+npx context-guardian --uninstall --local
+```
+
+## The Problem
+
+Claude Code conversations have a finite context window. When it fills up, Claude Code auto-compacts -- silently summarizing and discarding older messages. This means:
+
+- **Work gets lost mid-task.** Claude forgets what it was doing, why, and what remains.
+- **No warning before it happens.** A productive session becomes amnesia with no transition.
+- **No graceful handoff.** There is no mechanism for Claude to document its state or prepare a continuation plan before context is wiped.
+
+The problem is not that context is finite -- it is that there is no protocol for winding down gracefully.
+
+## How It Works
+
+Two scripts, two hooks -- a sensor and an actuator:
+
+- **`cg-statusline.cjs`** (StatusLine hook) -- The sensor. Runs on every statusline render. Reads `context_window.remaining_percentage` from Claude Code's stdin, calculates the scaled usage percentage, persists session state to disk, and renders a colored progress bar.
+
+- **`cg-context-monitor.cjs`** (PostToolUse hook) -- The actuator. Runs after every tool call. Reads the session state and, when a threshold is crossed, injects a system-level warning into Claude's context via `additionalContext`. Fires once per level transition to avoid noise.
+
+### Data Flow
+
+```
+Claude Code statusline refresh
+  -> stdin JSON with context_window.remaining_percentage
+  -> cg-statusline.cjs calculates scaled used%
+  -> Writes to ~/.claude/context-guardian/sessions/session-{id}.json
+  -> Returns statusline text with visual progress bar
+
+Claude uses any tool
+  -> PostToolUse fires cg-context-monitor.cjs
+  -> Reads session-{id}.json
+  -> If level CHANGED (not repeated) -> injects additionalContext
+  -> Claude receives the warning and acts accordingly
+```
+
+### Key Design Decisions
+
+- **Statusline writes, PostToolUse reads.** The StatusLine hook is the only one that receives `context_window` data from Claude Code. PostToolUse hooks do not get this data, so state is persisted to a file that the PostToolUse hook reads. This two-file architecture is the core of the plugin.
+
+- **Scaled percentage.** Context usage is scaled so that 100% on our bar means Claude has only 5% of its raw context remaining. This gives the user a percentage that matches their intuition ("100% means full") while leaving a small safety margin.
+
+- **One-shot warnings.** Each level fires exactly once. Crossing a threshold triggers one notification; re-notification only occurs when the next threshold is crossed. This prevents spam while ensuring every transition is communicated.
+
+- **Advisory, not blocking.** The plugin never executes `/clear` or `/compact` automatically. It injects messages that Claude reads and acts on. The user makes the final call.
+
+- **claude-mem detection.** At Level 3, the plugin checks if claude-mem is installed. If yes, the emergency message notes that persistent memory is active. If not, it emphasizes that everything must be written to the handoff file.
+
+## Alert Levels
+
+| Level | Threshold | Action |
+|-------|-----------|--------|
+| 0 | < 80% | Normal operation |
+| 1 | >= 80% | Wrap up current work, avoid starting new tasks |
+| 2 | >= 85% | Finish in-progress work only, no new work |
+| 3 | >= 95% | Write handoff summary and suggest `/clear` |
+
+Levels are one-way during a session -- once escalated, the level never drops back down.
+
+## Session Data
+
+All state is stored in `~/.claude/context-guardian/`:
+
+- `sessions/` -- Per-session state files (current alert level, context percentage, timestamps). Auto-cleaned after 24 hours.
+- `handoffs/` -- Handoff summaries written by Claude at Level 3.
+
+This directory lives outside any repository. Context Guardian never reads or writes files in your project.
+
+## Dependencies
+
+None. Pure Node.js with no external packages. Uses only `fs`, `path`, and `os` from the standard library.
+
+## Compatibility
+
+Context Guardian operates independently through its own hooks and state directory. It works alongside other Claude Code plugins -- claude-mem, KanClaw, or any combination -- without conflicts.
+
+**Note on GSD StatusLine**: If you also use GSD (Get Shit Done), the installer will detect its existing statusline and warn you rather than overwriting it. Use `--force` to replace the GSD statusline with Context Guardian's. The PostToolUse warning hook works regardless of which statusline is active, as long as one writes the session state file.
+
+## Contributing
+
+Contributions are welcome. Please open an issue to discuss proposed changes before submitting a pull request. Bug reports, feature requests, and documentation improvements are all appreciated.
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Run the tests: `node --test test/*.test.js`
+5. Open a pull request against `main`
+
+## License
+
+MIT

package/bin/install.js

@@ -0,0 +1,299 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// ---------------------------------------------------------------------------
+// Colors
+// ---------------------------------------------------------------------------
+const cyan = '\x1b[36m';
+const green = '\x1b[32m';
+const yellow = '\x1b[33m';
+const dim = '\x1b[2m';
+const reset = '\x1b[0m';
+
+// ---------------------------------------------------------------------------
+// Version & banner
+// ---------------------------------------------------------------------------
+const pkg = require('../package.json');
+
+const banner = '\n' +
+  cyan + '   ██████╗ ██████╗ \n' +
+  '  ██╔════╝██╔════╝ \n' +
+  '  ██║     ██║  ███╗\n' +
+  '  ██║     ██║   ██║\n' +
+  '  ╚██████╗╚██████╔╝\n' +
+  '   ╚═════╝ ╚═════╝' + reset + '\n' +
+  '\n' +
+  '  Context Guardian ' + dim + 'v' + pkg.version + reset + '\n' +
+  '  Graceful context wind-down with session handoff for Claude Code.\n';
+
+// ---------------------------------------------------------------------------
+// Parse args
+// ---------------------------------------------------------------------------
+const args = process.argv.slice(2);
+const hasGlobal = args.includes('--global') || args.includes('-g');
+const hasLocal = args.includes('--local') || args.includes('-l');
+const hasUninstall = args.includes('--uninstall') || args.includes('-u');
+const hasForce = args.includes('--force');
+const hasHelp = args.includes('--help') || args.includes('-h');
+
+console.log(banner);
+
+if (hasHelp) {
+  console.log(`  ${yellow}Usage:${reset} npx context-guardian [options]\n`);
+  console.log(`  ${yellow}Options:${reset}`);
+  console.log(`    ${cyan}-g, --global${reset}       Install globally to ~/.claude/ (default)`);
+  console.log(`    ${cyan}-l, --local${reset}        Install locally to ./.claude/`);
+  console.log(`    ${cyan}-u, --uninstall${reset}    Remove Context Guardian hooks and scripts`);
+  console.log(`    ${cyan}--force${reset}            Replace existing statusline (e.g., GSD's)`);
+  console.log(`    ${cyan}-h, --help${reset}         Show this help message`);
+  console.log('');
+  console.log(`  ${yellow}Examples:${reset}`);
+  console.log(`    ${dim}# Install globally (default)${reset}`);
+  console.log(`    npx context-guardian`);
+  console.log('');
+  console.log(`    ${dim}# Install for current project only${reset}`);
+  console.log(`    npx context-guardian --local`);
+  console.log('');
+  console.log(`    ${dim}# Replace existing statusline${reset}`);
+  console.log(`    npx context-guardian --force`);
+  console.log('');
+  console.log(`    ${dim}# Uninstall${reset}`);
+  console.log(`    npx context-guardian --uninstall`);
+  console.log('');
+  process.exit(0);
+}
+
+if (hasGlobal && hasLocal) {
+  console.error(`  ${yellow}Cannot specify both --global and --local${reset}\n`);
+  process.exit(1);
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function getConfigDir(isGlobal) {
+  if (!isGlobal) return path.join(process.cwd(), '.claude');
+  if (process.env.CLAUDE_CONFIG_DIR) {
+    const p = process.env.CLAUDE_CONFIG_DIR;
+    return p.startsWith('~/') ? path.join(os.homedir(), p.slice(2)) : p;
+  }
+  return path.join(os.homedir(), '.claude');
+}
+
+function readSettings(settingsPath) {
+  if (!fs.existsSync(settingsPath)) return {};
+  const raw = fs.readFileSync(settingsPath, 'utf8');
+  try {
+    return JSON.parse(raw);
+  } catch {
+    console.error(`  ${yellow}Error:${reset} ${settingsPath} contains invalid JSON.`);
+    console.error(`  Fix it manually and re-run the installer.\n`);
+    process.exit(1);
+  }
+}
+
+function writeSettings(settingsPath, settings) {
+  fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+}
+
+function buildHookCommand(configDir, hookName) {
+  const hooksPath = configDir.replace(/\\/g, '/') + '/hooks/' + hookName;
+  return `node "${hooksPath}"`;
+}
+
+function configLabel(configDir, isGlobal) {
+  return isGlobal
+    ? configDir.replace(os.homedir(), '~')
+    : configDir.replace(process.cwd(), '.');
+}
+
+function hasCgCommand(entry, hookName) {
+  return entry.hooks && entry.hooks.some(h => h.command && h.command.includes(hookName));
+}
+
+// ---------------------------------------------------------------------------
+// Uninstall
+// ---------------------------------------------------------------------------
+
+function uninstall(isGlobal) {
+  const configDir = getConfigDir(isGlobal);
+  const label = configLabel(configDir, isGlobal);
+
+  console.log(`  Uninstalling from ${cyan}${label}${reset}\n`);
+
+  if (!fs.existsSync(configDir)) {
+    console.log(`  ${yellow}!${reset} Directory does not exist: ${label}`);
+    console.log('  Nothing to uninstall.\n');
+    return;
+  }
+
+  let removedCount = 0;
+
+  // 1. Remove hook scripts
+  const hooksDir = path.join(configDir, 'hooks');
+  if (fs.existsSync(hooksDir)) {
+    const hookFiles = ['cg-statusline.cjs', 'cg-context-monitor.cjs'];
+    let hookCount = 0;
+    for (const file of hookFiles) {
+      const hookPath = path.join(hooksDir, file);
+      if (fs.existsSync(hookPath)) {
+        fs.unlinkSync(hookPath);
+        hookCount++;
+      }
+    }
+    if (hookCount > 0) {
+      removedCount++;
+      console.log(`  ${green}+${reset} Removed ${hookCount} hook script(s)`);
+    }
+  }
+
+  // 2. Clean up settings.json
+  const settingsPath = path.join(configDir, 'settings.json');
+  if (fs.existsSync(settingsPath)) {
+    const settings = readSettings(settingsPath);
+    let modified = false;
+
+    if (settings.statusLine && settings.statusLine.command &&
+        settings.statusLine.command.includes('cg-statusline')) {
+      delete settings.statusLine;
+      modified = true;
+      console.log(`  ${green}+${reset} Removed statusline from settings`);
+    }
+
+    if (settings.hooks && settings.hooks.PostToolUse) {
+      const before = settings.hooks.PostToolUse.length;
+      settings.hooks.PostToolUse = settings.hooks.PostToolUse.filter(
+        entry => !hasCgCommand(entry, 'cg-context-monitor')
+      );
+      if (settings.hooks.PostToolUse.length < before) {
+        modified = true;
+        console.log(`  ${green}+${reset} Removed PostToolUse hook from settings`);
+      }
+      if (settings.hooks.PostToolUse.length === 0) delete settings.hooks.PostToolUse;
+    }
+
+    if (settings.hooks && Object.keys(settings.hooks).length === 0) {
+      delete settings.hooks;
+    }
+
+    if (modified) {
+      writeSettings(settingsPath, settings);
+      removedCount++;
+    }
+  }
+
+  if (removedCount === 0) {
+    console.log(`  ${yellow}!${reset} No Context Guardian files found to remove.`);
+  }
+
+  console.log(`\n  ${green}Done!${reset} Context Guardian has been uninstalled.\n`);
+}
+
+// ---------------------------------------------------------------------------
+// Install
+// ---------------------------------------------------------------------------
+
+function install(isGlobal) {
+  const configDir = getConfigDir(isGlobal);
+  const label = configLabel(configDir, isGlobal);
+
+  console.log(`  Installing to ${cyan}${label}${reset}\n`);
+
+  // 1. Copy hook scripts to target hooks/ directory
+  const hooksDestDir = path.join(configDir, 'hooks');
+  fs.mkdirSync(hooksDestDir, { recursive: true });
+
+  const srcRoot = path.join(__dirname, '..');
+  const hookFiles = ['cg-statusline.cjs', 'cg-context-monitor.cjs'];
+
+  for (const file of hookFiles) {
+    fs.copyFileSync(path.join(srcRoot, 'hooks', file), path.join(hooksDestDir, file));
+    console.log(`  ${green}+${reset} Installed ${file}`);
+  }
+
+  // 2. Configure settings.json (merge, not overwrite)
+  const settingsPath = path.join(configDir, 'settings.json');
+  const settings = readSettings(settingsPath);
+
+  // 2a. StatusLine (top-level key, NOT inside hooks)
+  const statuslineConfig = {
+    type: 'command',
+    command: buildHookCommand(configDir, 'cg-statusline.cjs'),
+  };
+
+  let statuslineInstalled = false;
+  const existingCmd = settings.statusLine && settings.statusLine.command;
+  const isOurStatusline = existingCmd && existingCmd.includes('cg-statusline');
+
+  if (!settings.statusLine || isOurStatusline || hasForce) {
+    const verb = isOurStatusline ? 'Updated' : settings.statusLine ? 'Replaced existing' : 'Configured';
+    settings.statusLine = statuslineConfig;
+    statuslineInstalled = true;
+    console.log(`  ${green}+${reset} ${verb} statusline`);
+  } else {
+    console.log(`  ${yellow}!${reset} Existing statusline detected (${dim}${existingCmd || '(custom)'}${reset})`);
+    console.log(`    Skipping statusline. Use ${cyan}--force${reset} to replace it.`);
+  }
+
+  // 2b. PostToolUse hook (inside hooks section)
+  if (!settings.hooks) settings.hooks = {};
+  if (!settings.hooks.PostToolUse) settings.hooks.PostToolUse = [];
+
+  const contextMonitorCommand = buildHookCommand(configDir, 'cg-context-monitor.cjs');
+  const hasCgMonitor = settings.hooks.PostToolUse.some(
+    entry => hasCgCommand(entry, 'cg-context-monitor')
+  );
+
+  if (hasCgMonitor) {
+    for (const entry of settings.hooks.PostToolUse) {
+      if (!entry.hooks) continue;
+      for (const h of entry.hooks) {
+        if (h.command && h.command.includes('cg-context-monitor')) {
+          h.command = contextMonitorCommand;
+        }
+      }
+    }
+    console.log(`  ${green}+${reset} Updated PostToolUse hook`);
+  } else {
+    settings.hooks.PostToolUse.push({
+      matcher: '*',
+      hooks: [{ type: 'command', command: contextMonitorCommand }],
+    });
+    console.log(`  ${green}+${reset} Configured PostToolUse hook`);
+  }
+
+  // 3. Write settings.json
+  writeSettings(settingsPath, settings);
+
+  // 4. Print summary
+  console.log('');
+  console.log(`  ${green}Done!${reset} Context Guardian is installed.\n`);
+  console.log(`  ${dim}What was installed:${reset}`);
+  console.log(`    ${dim}Scripts:${reset}    ${label}/hooks/cg-statusline.cjs`);
+  console.log(`                ${label}/hooks/cg-context-monitor.cjs`);
+  if (statuslineInstalled) {
+    console.log(`    ${dim}StatusLine:${reset} Colored progress bar in the bottom status bar`);
+  }
+  console.log(`    ${dim}PostToolUse:${reset} Escalating warnings at 80%, 85%, 95% context usage`);
+  console.log('');
+  console.log(`  ${dim}Session data:${reset} ~/.claude/context-guardian/`);
+  console.log(`  ${dim}Uninstall:${reset}    npx context-guardian --uninstall${isGlobal ? '' : ' --local'}`);
+  console.log('');
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+const isGlobal = !hasLocal;
+
+if (hasUninstall) {
+  uninstall(isGlobal);
+} else {
+  install(isGlobal);
+}

package/hooks/cg-context-monitor.cjs

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+
+// Context Guardian -- PostToolUse Hook
+// Injects context-window warnings when usage crosses threshold levels.
+// Fires once per level transition to avoid spamming.
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const GUARDIAN_DIR = path.join(os.homedir(), '.claude', 'context-guardian');
+const SESSIONS_DIR = path.join(GUARDIAN_DIR, 'sessions');
+const HANDOFFS_DIR = path.join(GUARDIAN_DIR, 'handoffs');
+
+const SUPPRESS = JSON.stringify({ continue: true, suppressOutput: true });
+
+// IMPORTANT: thresholds must match getLevel() in cg-statusline.cjs
+function getLevel(used) {
+  if (used >= 95) return 3;
+  if (used >= 85) return 2;
+  if (used >= 80) return 1;
+  return 0;
+}
+
+function readJson(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeJson(filePath, data) {
+  try {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, JSON.stringify(data, null, 2), 'utf-8');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function isClaudeMemActive() {
+  try {
+    return fs.existsSync(
+      path.join(os.homedir(), '.claude', 'plugins', 'cache', 'thedotmack', 'claude-mem')
+    );
+  } catch {
+    return false;
+  }
+}
+
+function buildWarning(level, used, sessionId) {
+  if (level === 1) {
+    return [
+      '\u26a0\ufe0f CONTEXT GUARDIAN \u2014 Heads Up (80%)',
+      `Context window is at ${used}%. Wrap up current work, avoid starting new tasks.`,
+    ].join('\n');
+  }
+
+  if (level === 2) {
+    return [
+      '\ud83d\udfe0 CONTEXT GUARDIAN \u2014 Wind Down (85%)',
+      `Context window is at ${used}%. Finish in-progress work only, no new work.`,
+    ].join('\n');
+  }
+
+  if (level === 3) {
+    const claudeMemNote = isClaudeMemActive()
+      ? 'Note: claude-mem is active. Your important observations from this session are already persisted in memory.'
+      : 'Important: There is no persistent memory system. Make sure ALL important context is written to the handoff file.';
+
+    return [
+      '\ud83d\udd34 CONTEXT GUARDIAN \u2014 Emergency Save (95%)',
+      `Context window is at ${used}%. STOP all work immediately.`,
+      '',
+      'You MUST do the following RIGHT NOW:',
+      `1. Write a handoff file to ~/.claude/context-guardian/handoffs/handoff-${sessionId}.md with:`,
+      '   - What you were working on',
+      '   - Current state of each task',
+      '   - What remains to be done',
+      '   - The exact prompt the user should paste to continue',
+      '2. Tell the user to run /clear and paste the continuation prompt',
+      '',
+      claudeMemNote,
+    ].join('\n');
+  }
+
+  return '';
+}
+
+function suppress() {
+  process.stdout.write(SUPPRESS);
+}
+
+// Read JSON from stdin
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => { input += chunk; });
+
+process.stdin.on('end', () => {
+  try {
+    const data = JSON.parse(input);
+    const sessionId = data.session_id;
+
+    if (!sessionId) return suppress();
+
+    // Read session state written by the statusline script
+    const state = readJson(path.join(SESSIONS_DIR, `session-${sessionId}.json`));
+
+    if (!state || typeof state.used !== 'number') return suppress();
+
+    const currentLevel = getLevel(state.used);
+
+    if (currentLevel === 0) return suppress();
+
+    // Only inject a warning when crossing into a NEW, higher level
+    const notifiedFile = path.join(SESSIONS_DIR, `notified-${sessionId}.json`);
+    const lastNotifiedLevel = (readJson(notifiedFile) || {}).last_notified_level || 0;
+
+    if (currentLevel <= lastNotifiedLevel) return suppress();
+
+    // Update tracking BEFORE output; suppress on failure to avoid spam
+    if (!writeJson(notifiedFile, { last_notified_level: currentLevel })) return suppress();
+
+    // Ensure handoffs directory exists (Level 3 tells Claude to write there)
+    if (currentLevel === 3) {
+      try { fs.mkdirSync(HANDOFFS_DIR, { recursive: true }); } catch { /* best-effort */ }
+    }
+
+    process.stdout.write(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PostToolUse',
+        additionalContext: buildWarning(currentLevel, state.used, sessionId),
+      },
+    }));
+  } catch {
+    suppress();
+  }
+});

package/hooks/cg-statusline.cjs

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+
+// Context Guardian -- StatusLine Hook
+// Renders a colored progress bar and persists session state for the monitor.
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const SESSIONS_DIR = path.join(os.homedir(), '.claude', 'context-guardian', 'sessions');
+const MAX_AGE_MS = 24 * 60 * 60 * 1000;
+
+// IMPORTANT: thresholds must match getLevel() in cg-context-monitor.cjs
+function getLevel(used) {
+  if (used >= 95) return 3;
+  if (used >= 85) return 2;
+  if (used >= 80) return 1;
+  return 0;
+}
+
+function getBarColor(used) {
+  if (used >= 95) return '\x1b[5;31m'; // red + blink
+  if (used >= 80) return '\x1b[38;5;208m'; // orange
+  if (used >= 63) return '\x1b[33m'; // yellow
+  return '\x1b[32m'; // green
+}
+
+// Scale raw usage so our 100% = 5% remaining in Claude (rawUsed 95)
+function scaleUsage(remainingPct) {
+  if (typeof remainingPct !== 'number') return 0;
+  const rawUsed = Math.max(0, Math.min(100, 100 - remainingPct));
+  return Math.min(100, Math.round((rawUsed / 95) * 100));
+}
+
+// Remove stale session files (~5% of runs to avoid unnecessary I/O)
+function cleanupStaleSessions(sessionId) {
+  if (Math.random() >= 0.05) return;
+  try {
+    const now = Date.now();
+    for (const file of fs.readdirSync(SESSIONS_DIR)) {
+      if (file === `session-${sessionId}.json` || file === `notified-${sessionId}.json`) continue;
+      const filePath = path.join(SESSIONS_DIR, file);
+      if (now - fs.statSync(filePath).mtimeMs > MAX_AGE_MS) {
+        fs.unlinkSync(filePath);
+      }
+    }
+  } catch (_) {
+    // Best-effort cleanup
+  }
+}
+
+function persistState(sessionId, used) {
+  if (!sessionId) return;
+  try {
+    fs.mkdirSync(SESSIONS_DIR, { recursive: true });
+    const stateFile = path.join(SESSIONS_DIR, `session-${sessionId}.json`);
+    fs.writeFileSync(stateFile, JSON.stringify({
+      used,
+      level: getLevel(used),
+      session_id: sessionId,
+      ts: Date.now(),
+    }));
+    cleanupStaleSessions(sessionId);
+  } catch (_) {
+    // Best-effort -- never break statusline for a file write failure
+  }
+}
+
+function renderBar(used) {
+  const filled = Math.round(used / 10);
+  return '\u2588'.repeat(filled) + '\u2591'.repeat(10 - filled);
+}
+
+// Read JSON from stdin
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => { input += chunk; });
+
+process.stdin.on('end', () => {
+  try {
+    const data = JSON.parse(input);
+    const model = data.model || {};
+    const workspace = data.workspace || {};
+    const used = scaleUsage((data.context_window || {}).remaining_percentage);
+
+    persistState(data.session_id, used);
+
+    const reset = '\x1b[0m';
+    const dim = '\x1b[2m';
+    const color = getBarColor(used);
+    const prefix = used >= 95 ? '\uD83D\uDC80 ' : '';
+    const modelName = model.display_name || model.id || 'Claude';
+    const dirname = workspace.current_dir ? path.basename(workspace.current_dir) : '';
+
+    const parts = [
+      `${dim}${modelName}${reset}`,
+      dirname ? `${dim}${dirname}${reset}` : null,
+      `${color}${prefix}${renderBar(used)} ${used}%${reset}`,
+    ].filter(Boolean);
+
+    process.stdout.write(parts.join(' \u2502 '));
+  } catch (_) {
+    // Silent failure -- never break Claude Code statusline
+  }
+});

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "context-guardian",
+  "version": "0.1.0",
+  "description": "Graceful context wind-down with session handoff for Claude Code",
+  "bin": {
+    "context-guardian": "bin/install.js"
+  },
+  "author": "Hector Ros",
+  "license": "MIT",
+  "keywords": [
+    "claude-code",
+    "context",
+    "statusline",
+    "plugin",
+    "session-handoff",
+    "context-window"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zeroToOneProjects/context-guardian"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "files": [
+    ".claude-plugin/",
+    "bin/",
+    "hooks/",
+    "skills/",
+    "LICENSE",
+    "README.md"
+  ]
+}

package/skills/context-status/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: context-status
+description: "Check current context window usage. Use when the user asks about context usage, remaining context, how much context is left, or similar questions about the current session's context window."
+---
+
+# Context Status
+
+Read the current context window usage from the Context Guardian session state file.
+
+## How to check
+
+Read the file at `~/.claude/context-guardian/sessions/session-{SESSION_ID}.json` where `{SESSION_ID}` is the current session ID.
+
+The file contains:
+```json
+{
+  "used": 78,
+  "level": 1,
+  "session_id": "abc123",
+  "ts": 1709000000000
+}
+```
+
+## Fields
+
+- `used` — Scaled context usage percentage (0-100). Scaled so that 100% displayed means only 5% of real context remains.
+- `level` — Alert level: 0 (normal, < 80%), 1 (heads up, >= 80%), 2 (wind down, >= 85%), 3 (emergency, >= 95%)
+- `ts` — Timestamp of last update (updated on every statusline refresh)
+
+## How to respond
+
+Report the usage to the user in a clear format. Examples:
+
+**Normal (level 0):**
+> Context usage: 45%. Plenty of room.
+
+**Heads up (level 1):**
+> Context usage: 82%. Getting there — I'm wrapping up current work and avoiding new tasks.
+
+**Wind down (level 2):**
+> Context usage: 87%. I'm finishing what's in progress and preparing handoff notes.
+
+**Emergency (level 3):**
+> Context usage: 96%. Critical — I need to write the handoff file and you should /clear soon.
+
+## If the file doesn't exist
+
+The session state file is written by the Context Guardian statusline hook. If it doesn't exist, respond:
+
+> I can't check context usage right now — the Context Guardian statusline hook hasn't written any state for this session yet. The statusline needs to be configured and running for context tracking to work.