claude-context-meter 1.0.0

package/README.md

@@ -0,0 +1,61 @@
+# claude-context-meter
+
+A Claude Code plugin that adds a persistent context window usage meter to the status line. After every API response you'll see something like:
+
+```
+Context: 24k (18%)
+```
+
+Color-coded by pressure level:
+
+| Color  | Token range       | Example output                                          |
+|--------|-------------------|---------------------------------------------------------|
+| Green  | < 70,000          | `Context: 24k (18%)`                                    |
+| Yellow | 70,000 – 100,000  | `Context: 85k (43%)`                                    |
+| Red    | > 100,000         | `Context: 112k (56%) · Consider /compact or /clear`     |
+
+The status line updates automatically — no polling or background process required.
+
+## Prerequisites
+
+- **Claude Code** (any version that supports the `statusLine` setting)
+- **Node.js** — already installed as part of Claude Code; no additional installation required
+
+## Installation
+
+```sh
+npx claude-context-meter install
+```
+
+This copies the meter script to `~/.claude/plugins/context-meter/` and adds the required `statusLine` entry to `~/.claude/settings.json` automatically. If a `statusLine` entry already exists it is backed up, replaced, and the backup is removed after a successful write.
+
+Open a new Claude Code session to activate the meter.
+
+## Uninstalling
+
+```sh
+npx claude-context-meter uninstall
+```
+
+Removes the plugin directory and the `statusLine` entry from `~/.claude/settings.json`.
+
+## Verifying the installation
+
+After opening a new Claude Code session you should see a status line at the bottom of the terminal that reads:
+
+```
+Context: 0 (0%)
+```
+
+Send any message to Claude. After the API response the token count and percentage will update to reflect the current session context. If the status line does not appear, check that:
+
+- `~/.claude/settings.json` contains the correct `statusLine` entry (run `npx claude-context-meter install` to set it)
+- You opened a **new** Claude Code session after running the installer
+
+## Running tests
+
+```sh
+node --test tests/test_context_meter.js
+```
+
+All 26 tests pass with no external dependencies — Node.js standard library only.

package/cli.js

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const INSTALL_DIR = path.join(os.homedir(), '.claude', 'plugins', 'context-meter');
+const SCRIPT_DEST = path.join(INSTALL_DIR, 'context_meter.js');
+const SETTINGS_FILE = path.join(os.homedir(), '.claude', 'settings.json');
+const SETTINGS_BACKUP = SETTINGS_FILE + '.bak';
+
+function readSettings() {
+  if (!fs.existsSync(SETTINGS_FILE)) return {};
+  return JSON.parse(fs.readFileSync(SETTINGS_FILE, 'utf8'));
+}
+
+function writeSettings(settings) {
+  fs.writeFileSync(SETTINGS_FILE, JSON.stringify(settings, null, 2) + '\n');
+}
+
+function backupSettings() {
+  if (fs.existsSync(SETTINGS_FILE)) {
+    fs.copyFileSync(SETTINGS_FILE, SETTINGS_BACKUP);
+  }
+}
+
+function removeBackup() {
+  if (fs.existsSync(SETTINGS_BACKUP)) {
+    fs.unlinkSync(SETTINGS_BACKUP);
+  }
+}
+
+function install() {
+  fs.mkdirSync(INSTALL_DIR, { recursive: true });
+  fs.copyFileSync(path.join(__dirname, 'context_meter.js'), SCRIPT_DEST);
+
+  const settings = readSettings();
+  if (settings.statusLine) {
+    console.log('Existing statusLine found — backing up settings.json before overwriting.');
+  }
+  backupSettings();
+
+  settings.statusLine = {
+    type: 'command',
+    command: `node "${SCRIPT_DEST}"`
+  };
+  writeSettings(settings);
+
+  const written = JSON.parse(fs.readFileSync(SETTINGS_FILE, 'utf8'));
+  if (written.statusLine && written.statusLine.command === `node "${SCRIPT_DEST}"`) {
+    removeBackup();
+    console.log('Installed to ' + SCRIPT_DEST);
+    console.log('Updated ~/.claude/settings.json');
+    console.log('\nOpen a new Claude Code session to see the context meter.');
+  } else {
+    console.error('Verification failed — backup preserved at ' + SETTINGS_BACKUP);
+    process.exit(1);
+  }
+}
+
+function uninstall() {
+  const settings = readSettings();
+  if (!settings.statusLine) {
+    console.log('No statusLine entry found in settings.json — nothing to remove.');
+  } else {
+    backupSettings();
+    delete settings.statusLine;
+    writeSettings(settings);
+
+    const written = JSON.parse(fs.readFileSync(SETTINGS_FILE, 'utf8'));
+    if (!written.statusLine) {
+      removeBackup();
+      console.log('Removed statusLine from ~/.claude/settings.json');
+    } else {
+      console.error('Verification failed — backup preserved at ' + SETTINGS_BACKUP);
+      process.exit(1);
+    }
+  }
+
+  if (fs.existsSync(INSTALL_DIR)) {
+    fs.rmSync(INSTALL_DIR, { recursive: true });
+    console.log('Removed ' + INSTALL_DIR);
+  }
+
+  console.log('\nOpen a new Claude Code session to complete the uninstall.');
+}
+
+const command = process.argv[2];
+if (command === 'install') {
+  install();
+} else if (command === 'uninstall') {
+  uninstall();
+} else {
+  console.error('Usage: npx claude-context-meter <install|uninstall>');
+  process.exit(1);
+}

package/context_meter.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+'use strict';
+
+const GREEN = '\x1b[32m';
+const YELLOW = '\x1b[33m';
+const RED = '\x1b[31m';
+const RESET = '\x1b[0m';
+
+const GREEN_THRESHOLD = 70_000;
+const YELLOW_THRESHOLD = 100_000;
+const RED_ZONE_MSG = ' · Consider /compact or /clear';
+
+const ANSI = { green: GREEN, yellow: YELLOW, red: RED };
+
+function formatTokens(count) {
+  if (count >= 1_000_000) return `${Math.round(count / 1_000_000)}M`;
+  if (count >= 1_000) return `${Math.round(count / 1_000)}k`;
+  return String(count);
+}
+
+function classify(count) {
+  if (count < GREEN_THRESHOLD) return 'green';
+  if (count <= YELLOW_THRESHOLD) return 'yellow';
+  return 'red';
+}
+
+function parseInput(data) {
+  try {
+    const payload = JSON.parse(data);
+    const cw = payload.context_window || {};
+    const tokens = parseInt(cw.total_input_tokens ?? 0, 10) || 0;
+    const pct = parseFloat(cw.used_percentage ?? 0) || 0;
+    return [tokens, pct];
+  } catch {
+    return [0, 0];
+  }
+}
+
+function render(tokens, pct) {
+  const formatted = formatTokens(tokens);
+  const pctInt = Math.round(pct);
+  const category = classify(tokens);
+  let line = `Context: ${formatted} (${pctInt}%)`;
+  if (category === 'red') line += RED_ZONE_MSG;
+  return `${ANSI[category]}${line}${RESET}`;
+}
+
+if (require.main === module) {
+  let data = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', chunk => { data += chunk; });
+  process.stdin.on('end', () => {
+    const [tokens, pct] = parseInput(data);
+    console.log(render(tokens, pct));
+  });
+}
+
+module.exports = { formatTokens, classify, parseInput, render };

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "claude-context-meter",
+  "version": "1.0.0",
+  "description": "Persistent context window usage meter for the Claude Code status line",
+  "bin": {
+    "claude-context-meter": "cli.js"
+  },
+  "files": [
+    "cli.js",
+    "context_meter.js"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zbshadow/claude-context-meter.git"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "context",
+    "status-line"
+  ]
+}