claude-code-pulsify 1.0.0

package/README.md

@@ -0,0 +1,39 @@
+# claude-code-pulsify
+
+Context-aware statusline and context monitor for [Claude Code](https://docs.anthropic.com/en/docs/claude-code).
+
+Shows a live progress bar of context window usage, active task info, and warns you when context is running low.
+
+## Install
+
+```bash
+npx claude-code-pulsify@latest
+```
+
+This copies hooks to `~/.claude/hooks/claude-code-pulsify/` and patches `~/.claude/settings.json`. Restart Claude Code to activate.
+
+## Update
+
+Run the same command:
+
+```bash
+npx claude-code-pulsify@latest
+```
+
+The statusline also shows an arrow indicator when an update is available.
+
+## Uninstall
+
+```bash
+npx claude-code-pulsify@latest --uninstall
+```
+
+## What it does
+
+- **Statusline** -- Shows model name, working directory, context usage bar (color-coded), and active task
+- **Context monitor** -- Warns at 65% and 75% context usage via PostToolUse hook
+- **Update checker** -- Background version check on session start, non-blocking
+
+## Configuration
+
+Respects the `CLAUDE_CONFIG_DIR` environment variable. Defaults to `~/.claude`.

package/bin/install.js

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+
+const PACKAGE_VERSION = require('../package.json').version
+const HOOKS_SOURCE = path.join(__dirname, '..', 'hooks')
+const HOOK_FILES = ['statusline.js', 'context-monitor.js', 'check-update.js']
+
+const configDir = process.env.CLAUDE_CONFIG_DIR || path.join(require('os').homedir(), '.claude')
+const hooksTarget = path.join(configDir, 'hooks', 'claude-code-pulsify')
+const settingsPath = path.join(configDir, 'settings.json')
+
+// --- Helpers ---
+
+function readJSON(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'))
+  } catch {
+    return {}
+  }
+}
+
+function writeJSON(filePath, data) {
+  fs.writeFileSync(filePath, JSON.stringify(data, null, 2) + '\n', 'utf8')
+}
+
+function isOurEntry(entry) {
+  const cmd = entry?.hooks?.[0]?.command || ''
+  return cmd.includes('claude-code-pulsify')
+}
+
+function upsertHookArray(arr, newEntry) {
+  const idx = arr.findIndex(isOurEntry)
+  if (idx >= 0) {
+    arr[idx] = newEntry
+  } else {
+    arr.push(newEntry)
+  }
+  return arr
+}
+
+function removeFromHookArray(arr) {
+  return arr.filter((entry) => !isOurEntry(entry))
+}
+
+// --- Install ---
+
+function install() {
+  console.log(`\nInstalling claude-code-pulsify v${PACKAGE_VERSION}...\n`)
+
+  // 1. Copy hooks
+  fs.mkdirSync(hooksTarget, { recursive: true })
+  for (const file of HOOK_FILES) {
+    const src = path.join(HOOKS_SOURCE, file)
+    const dst = path.join(hooksTarget, file)
+    fs.copyFileSync(src, dst)
+    console.log(`  Copied ${file}`)
+  }
+
+  // 2. Write VERSION
+  fs.writeFileSync(path.join(hooksTarget, 'VERSION'), PACKAGE_VERSION, 'utf8')
+  console.log(`  Wrote VERSION (${PACKAGE_VERSION})`)
+
+  // 3. Patch settings.json
+  const settings = readJSON(settingsPath)
+
+  // statusLine
+  settings.statusLine = {
+    type: 'command',
+    command: `node ${path.join(hooksTarget, 'statusline.js')}`,
+  }
+
+  // hooks
+  if (!settings.hooks) settings.hooks = {}
+
+  // PostToolUse — context-monitor
+  if (!settings.hooks.PostToolUse) settings.hooks.PostToolUse = []
+  upsertHookArray(settings.hooks.PostToolUse, {
+    hooks: [
+      {
+        type: 'command',
+        command: `node ${path.join(hooksTarget, 'context-monitor.js')}`,
+      },
+    ],
+  })
+
+  // SessionStart — check-update
+  if (!settings.hooks.SessionStart) settings.hooks.SessionStart = []
+  upsertHookArray(settings.hooks.SessionStart, {
+    hooks: [
+      {
+        type: 'command',
+        command: `node ${path.join(hooksTarget, 'check-update.js')}`,
+      },
+    ],
+  })
+
+  writeJSON(settingsPath, settings)
+  console.log(`  Patched settings.json`)
+
+  console.log(`\nDone! Restart Claude Code to activate the statusline.\n`)
+}
+
+// --- Uninstall ---
+
+function uninstall() {
+  console.log(`\nUninstalling claude-code-pulsify...\n`)
+
+  // 1. Remove hooks directory
+  if (fs.existsSync(hooksTarget)) {
+    fs.rmSync(hooksTarget, { recursive: true })
+    console.log(`  Removed ${hooksTarget}`)
+  }
+
+  // 2. Clean settings.json
+  if (fs.existsSync(settingsPath)) {
+    const settings = readJSON(settingsPath)
+
+    // Remove statusLine if it's ours
+    if (settings.statusLine?.command?.includes('claude-code-pulsify')) {
+      delete settings.statusLine
+      console.log(`  Removed statusLine config`)
+    }
+
+    // Remove hook entries
+    if (settings.hooks) {
+      for (const event of ['PostToolUse', 'SessionStart']) {
+        if (Array.isArray(settings.hooks[event])) {
+          settings.hooks[event] = removeFromHookArray(settings.hooks[event])
+          if (settings.hooks[event].length === 0) {
+            delete settings.hooks[event]
+          }
+        }
+      }
+      if (Object.keys(settings.hooks).length === 0) {
+        delete settings.hooks
+      }
+      console.log(`  Cleaned hook entries`)
+    }
+
+    writeJSON(settingsPath, settings)
+  }
+
+  // 3. Remove cache file
+  const cachePath = path.join(configDir, 'cache', 'claude-code-pulsify-update.json')
+  try {
+    fs.unlinkSync(cachePath)
+  } catch {
+    // Doesn't exist — fine
+  }
+
+  console.log(`\nDone! claude-code-pulsify has been removed.\n`)
+}
+
+// --- Main ---
+
+const args = process.argv.slice(2)
+
+if (args.includes('--version')) {
+  console.log(PACKAGE_VERSION)
+} else if (args.includes('--uninstall')) {
+  uninstall()
+} else {
+  install()
+}

package/hooks/check-update.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+'use strict'
+
+/**
+ * SessionStart hook -- background version check for claude-code-pulsify.
+ * Spawns a detached process to compare installed version vs npm latest,
+ * writes result to a cache file that statusline.js reads.
+ */
+
+const { spawn } = require('child_process')
+const fs = require('fs')
+const path = require('path')
+
+const configDir = process.env.CLAUDE_CONFIG_DIR || path.join(require('os').homedir(), '.claude')
+const hooksDir = path.join(configDir, 'hooks', 'claude-code-pulsify')
+const cacheDir = path.join(configDir, 'cache')
+const cachePath = path.join(cacheDir, 'claude-code-pulsify-update.json')
+
+async function main() {
+  // Consume stdin (required by hook protocol)
+  let input = ''
+  for await (const chunk of process.stdin) {
+    input += chunk
+  }
+
+  // Read installed version
+  const versionFile = path.join(hooksDir, 'VERSION')
+  let installed
+  try {
+    installed = fs.readFileSync(versionFile, 'utf8').trim()
+  } catch {
+    return // No VERSION file — not installed properly
+  }
+
+  // Spawn detached background check so we don't block session startup
+  const script = `
+    const { execSync } = require('child_process');
+    const fs = require('fs');
+    const cachePath = ${JSON.stringify(cachePath)};
+    const cacheDir = ${JSON.stringify(cacheDir)};
+    const installed = ${JSON.stringify(installed)};
+    try {
+      const latest = execSync('npm view claude-code-pulsify version', {
+        timeout: 10000,
+        encoding: 'utf8',
+        stdio: ['pipe', 'pipe', 'pipe']
+      }).trim();
+      fs.mkdirSync(cacheDir, { recursive: true });
+      fs.writeFileSync(cachePath, JSON.stringify({
+        installed,
+        latest,
+        updateAvailable: latest !== installed,
+        checkedAt: Date.now()
+      }));
+    } catch {
+      // Network error or npm not available — silently ignore
+    }
+  `
+
+  const child = spawn(process.execPath, ['-e', script], {
+    detached: true,
+    stdio: 'ignore',
+  })
+  child.unref()
+}
+
+main().catch(() => process.exit(0))

package/hooks/context-monitor.js

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+'use strict'
+
+/**
+ * Claude Code PostToolUse hook -- context monitor.
+ * Reads the bridge file written by statusline.js and injects
+ * warnings when context is running low.
+ */
+
+const fs = require('fs')
+const path = require('path')
+
+// Thresholds on "used percentage" (normalized, 0-100)
+const WARNING_THRESHOLD = 65 // remaining ~35% usable
+const CRITICAL_THRESHOLD = 75 // remaining ~25% usable
+
+// Debounce: minimum tool calls between repeated warnings at the same severity
+const DEBOUNCE_COUNT = 5
+
+// State file to track debounce across invocations
+function getStateFile(sessionId) {
+  return `/tmp/claude-ctx-monitor-state-${sessionId}.json`
+}
+
+function readState(sessionId) {
+  try {
+    return JSON.parse(fs.readFileSync(getStateFile(sessionId), 'utf8'))
+  } catch {
+    return { lastSeverity: null, callsSinceWarning: 0 }
+  }
+}
+
+function writeState(sessionId, state) {
+  try {
+    fs.writeFileSync(getStateFile(sessionId), JSON.stringify(state), 'utf8')
+  } catch {
+    // Silently ignore
+  }
+}
+
+async function main() {
+  let input = ''
+  for await (const chunk of process.stdin) {
+    input += chunk
+  }
+
+  let hookData
+  try {
+    hookData = JSON.parse(input)
+  } catch {
+    return
+  }
+
+  const sessionId = hookData.session?.id || hookData.session_id || null
+  if (!sessionId) return
+
+  // Read bridge file from statusline
+  const bridgePath = `/tmp/claude-ctx-${sessionId}.json`
+  let metrics
+  try {
+    metrics = JSON.parse(fs.readFileSync(bridgePath, 'utf8'))
+  } catch {
+    return // No bridge file yet -- statusline hasn't run
+  }
+
+  // Check staleness (>60s old)
+  if (Date.now() - (metrics.timestamp || 0) > 60_000) return
+
+  const usedPct = metrics.used_percentage
+  if (usedPct == null) return
+
+  // Determine severity
+  let severity = null
+  if (usedPct >= CRITICAL_THRESHOLD) severity = 'CRITICAL'
+  else if (usedPct >= WARNING_THRESHOLD) severity = 'WARNING'
+
+  if (!severity) return // Context is fine
+
+  // Debounce logic
+  const state = readState(sessionId)
+  state.callsSinceWarning = (state.callsSinceWarning || 0) + 1
+
+  const isEscalation = severity === 'CRITICAL' && state.lastSeverity === 'WARNING'
+  const shouldWarn = isEscalation || state.callsSinceWarning >= DEBOUNCE_COUNT
+
+  if (!shouldWarn) {
+    writeState(sessionId, state)
+    return
+  }
+
+  // Reset debounce counter
+  state.callsSinceWarning = 0
+  state.lastSeverity = severity
+  writeState(sessionId, state)
+
+  // Emit warning
+  const pct = Math.round(usedPct)
+  const remaining = 100 - pct
+
+  if (severity === 'CRITICAL') {
+    process.stderr.write(
+      `\n⚠️  CONTEXT CRITICAL (${pct}% used, ~${remaining}% remaining)\n` +
+        `Context window is nearly exhausted. Inform the user and ask how to proceed.\n` +
+        `Consider: summarize progress, commit work, or start a new session.\n`,
+    )
+  } else {
+    process.stderr.write(
+      `\n⚡ CONTEXT WARNING (${pct}% used, ~${remaining}% remaining)\n` +
+        `Context is getting limited. Avoid starting new complex work.\n` +
+        `Focus on completing current tasks and wrapping up.\n`,
+    )
+  }
+}
+
+main().catch(() => process.exit(0))

package/hooks/statusline.js

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+'use strict'
+
+/**
+ * Claude Code statusline hook.
+ * Reads session JSON from stdin, outputs a formatted statusline,
+ * and writes a bridge file for the context monitor.
+ */
+
+const fs = require('fs')
+const path = require('path')
+
+// ANSI helpers
+const ESC = '\x1b['
+const RESET = `${ESC}0m`
+const BOLD = `${ESC}1m`
+const DIM = `${ESC}2m`
+const FG = (r, g, b) => `${ESC}38;2;${r};${g};${b}m`
+
+// Colors
+const GRAY = FG(100, 100, 100)
+const WHITE = FG(200, 200, 200)
+const GREEN = FG(80, 200, 80)
+const YELLOW = FG(220, 200, 60)
+const ORANGE = FG(230, 140, 40)
+const RED = FG(220, 60, 60)
+const CYAN = FG(80, 200, 220)
+
+const SEPARATOR = `${GRAY}\u2502${RESET}`
+
+// Autocompact kicks in around 16.5% remaining -- normalize so bar reflects usable context
+const AUTOCOMPACT_BUFFER = 16.5
+
+function normalizeUsage(remainingPct) {
+  // remaining_percentage goes from 100 (empty) to 0 (full)
+  // usable range is 100 down to ~16.5 (autocompact buffer)
+  const usableRange = 100 - AUTOCOMPACT_BUFFER
+  const usableRemaining = Math.max(0, remainingPct - AUTOCOMPACT_BUFFER)
+  const usedPct = ((usableRange - usableRemaining) / usableRange) * 100
+  return Math.min(100, Math.max(0, usedPct))
+}
+
+function getBarColor(usedPct) {
+  if (usedPct < 50) return { fg: GREEN, label: GREEN }
+  if (usedPct < 65) return { fg: YELLOW, label: YELLOW }
+  if (usedPct < 80) return { fg: ORANGE, label: ORANGE }
+  return { fg: RED, label: RED }
+}
+
+function buildProgressBar(usedPct, segments = 15) {
+  const filled = Math.round((usedPct / 100) * segments)
+  const empty = segments - filled
+  const colors = getBarColor(usedPct)
+  const emphasis = usedPct >= 80 ? BOLD : ''
+
+  const filledBar = `${emphasis}${colors.fg}${'█'.repeat(filled)}${RESET}`
+  const emptyBar = `${GRAY}${'░'.repeat(empty)}${RESET}`
+  const pctLabel = `${colors.label}${BOLD}${Math.round(usedPct)}%${RESET}`
+
+  return `${filledBar}${emptyBar} ${pctLabel}`
+}
+
+function getActiveTask(data) {
+  const todos = data.todos || []
+  const active = todos.find((t) => t.status === 'in_progress') || todos.find((t) => t.status === 'pending')
+  if (!active) return null
+  const label = active.content || active.description || ''
+  return label.length > 40 ? label.slice(0, 37) + '...' : label
+}
+
+function getUpdateIndicator() {
+  const configDir = process.env.CLAUDE_CONFIG_DIR || path.join(require('os').homedir(), '.claude')
+  const cachePath = path.join(configDir, 'cache', 'claude-code-pulsify-update.json')
+  try {
+    const cache = JSON.parse(fs.readFileSync(cachePath, 'utf8'))
+    if (cache.updateAvailable && cache.latest) {
+      return ` ${CYAN}\u2191${cache.latest}${RESET}`
+    }
+  } catch {
+    // No cache file or invalid — no indicator
+  }
+  return ''
+}
+
+function getGitBranch(cwd) {
+  try {
+    const head = fs.readFileSync(path.join(cwd, '.git', 'HEAD'), 'utf8').trim()
+    const match = head.match(/^ref: refs\/heads\/(.+)$/)
+    return match ? match[1] : null
+  } catch {
+    return null
+  }
+}
+
+function writeBridgeFile(sessionId, metrics) {
+  if (!sessionId) return
+  const bridgePath = `/tmp/claude-ctx-${sessionId}.json`
+  try {
+    fs.writeFileSync(bridgePath, JSON.stringify({ ...metrics, timestamp: Date.now() }), 'utf8')
+  } catch {
+    // Silently ignore write errors
+  }
+}
+
+async function main() {
+  let input = ''
+  for await (const chunk of process.stdin) {
+    input += chunk
+  }
+
+  let data
+  try {
+    data = JSON.parse(input)
+  } catch {
+    process.stdout.write(`${DIM}statusline: no data${RESET}`)
+    return
+  }
+
+  // Debug payload dump
+  if (process.env.CLAUDE_PULSIFY_DEBUG) {
+    try {
+      fs.writeFileSync('/tmp/claude-pulsify-debug.json', JSON.stringify(data, null, 2), 'utf8')
+    } catch {
+      // Silently ignore write errors
+    }
+  }
+
+  // Extract fields
+  const model = data.model?.display_name || data.model?.name || 'unknown'
+  const cwd = data.workspace?.current_dir || process.cwd()
+  const dir = path.basename(cwd)
+  const remainingPct = data.context_window?.remaining_percentage ?? 100
+  const sessionId = data.session?.id || data.session_id || null
+
+  // Normalize and build bar
+  const usedPct = normalizeUsage(remainingPct)
+  const bar = buildProgressBar(usedPct)
+
+  // Git branch
+  const branch = getGitBranch(cwd)
+  const dirLabel = branch ? `${DIM}${dir} (${branch})${RESET}` : `${DIM}${dir}${RESET}`
+
+  // Active task
+  const task = getActiveTask(data)
+  const taskSegment = task ? ` ${SEPARATOR} ${DIM}${task}${RESET}` : ''
+
+  // Update indicator
+  const updateIndicator = getUpdateIndicator()
+
+  // Write bridge file for context-monitor
+  writeBridgeFile(sessionId, {
+    remaining_percentage: remainingPct,
+    used_percentage: usedPct,
+    session_id: sessionId,
+    model,
+  })
+
+  // Output statusline
+  const line = `${WHITE}${model}${RESET} ${SEPARATOR} ${dirLabel} ${SEPARATOR} ${bar}${taskSegment}${updateIndicator}`
+  process.stdout.write(line)
+}
+
+main().catch(() => process.exit(0))

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "claude-code-pulsify",
+  "version": "1.0.0",
+  "description": "Context-aware statusline and context monitor for Claude Code",
+  "bin": {
+    "claude-code-pulsify": "bin/install.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/SpitzN/claude-code-pulsify"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "bin/",
+    "hooks/"
+  ]
+}