pulse-for-claude-code 0.1.0

package/hooks/permission-hook.js

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+'use strict';
+
+/*
+ * Claude Code "PreToolUse" hook for Pulse: approve tools from the dashboard.
+ *
+ * Safety first. This hook can pause a tool while it waits for your click, so it
+ * is built to NEVER hang Claude:
+ *   - if Pulse is not running (stale heartbeat) it returns immediately and the
+ *     normal terminal prompt happens, exactly as without this hook
+ *   - read only tools are auto allowed so they never wait
+ *   - standing rules (allow all / per tool) answer instantly
+ *   - a hard timeout falls back to the normal prompt
+ *   - any error falls back to the normal prompt
+ *
+ * Wire it to PreToolUse in ~/.claude/settings.json (see README). Opt in.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const https = require('https');
+const { spawn } = require('child_process');
+
+const DIR = path.join(os.homedir(), '.claude-pulse');
+const PENDING = path.join(DIR, 'pending');
+const DECISIONS = path.join(DIR, 'decisions');
+const ALIVE = path.join(DIR, 'alive');
+const RULES = path.join(DIR, 'rules.json');
+const TOKEN = path.join(DIR, 'token');
+const CONFIG = path.join(os.homedir(), '.claude-pulse.json');
+
+const SAFE = ['Read', 'Grep', 'Glob', 'LS', 'NotebookRead', 'TodoWrite', 'WebFetch', 'WebSearch'];
+// How long to wait for your click before falling back to the normal terminal
+// prompt. Short by default so Claude never feels stuck; override with
+// "approvalTimeoutMs" in ~/.claude-pulse.json.
+function timeoutMs() {
+  var v = (readJson(CONFIG, {}) || {}).approvalTimeoutMs;
+  v = parseInt(v, 10);
+  if (!v || v < 5000) return 60 * 1000;
+  return Math.min(v, 10 * 60 * 1000);
+}
+const POLL_MS = 300;
+const HEARTBEAT_MAX = 10 * 1000;
+
+function passthrough() { process.exit(0); }                 // no output = normal permission flow
+function decide(decision, reason) {
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: decision, permissionDecisionReason: reason || 'Pulse' },
+  }));
+  process.exit(0);
+}
+function sleep(ms) { return new Promise(function (r) { setTimeout(r, ms); }); }
+function readJson(p, fb) { try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch (e) { return fb; } }
+function aliveFresh() { try { return Date.now() - (parseInt(fs.readFileSync(ALIVE, 'utf8'), 10) || 0) < HEARTBEAT_MAX; } catch (e) { return false; } }
+function readStdin() {
+  return new Promise(function (r) {
+    var d = ''; if (process.stdin.isTTY) return r('');
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', function (c) { d += c; });
+    process.stdin.on('end', function () { r(d); });
+    setTimeout(function () { r(d); }, 800);
+  });
+}
+function summarize(tool, input) {
+  if (!input || typeof input !== 'object') return tool;
+  var h = input.command || input.file_path || input.path || input.pattern || input.url || input.description || '';
+  return String(h).replace(/\s+/g, ' ').trim().slice(0, 200);
+}
+function lanIp() {
+  try {
+    var ifs = os.networkInterfaces();
+    for (var k in ifs) for (var i = 0; i < ifs[k].length; i++) {
+      var a = ifs[k][i];
+      if (a.family === 'IPv4' && !a.internal) return a.address;
+    }
+  } catch (e) {}
+  return '';
+}
+function pushNtfy(input) {
+  var topic = '';
+  try { topic = (readJson(CONFIG, {}) || {}).ntfyTopic || ''; } catch (e) {}
+  if (!topic) return Promise.resolve();
+  var tool = input._tool, summary = input._summary, id = input._id, project = input._project;
+  var rt = 'https://ntfy.sh/' + encodeURIComponent(topic + '-reply');
+  return new Promise(function (resolve) {
+    // the buttons post the answer back through ntfy; Pulse is subscribed to the
+    // reply topic, so no LAN, IP or open port is needed. Works anywhere.
+    var headers = {
+      'Title': ('Allow ' + tool + (project ? ' in ' + project : '')).replace(/[^\x20-\x7E]/g, ''),
+      'Tags': 'lock', 'Priority': 'high',
+      'Actions': [
+        'http, Allow, ' + rt + ', method=POST, body=allow|once|' + id + ', clear=true',
+        'http, Allow all, ' + rt + ', method=POST, body=allow|all|' + id + ', clear=true',
+        'http, Deny, ' + rt + ', method=POST, body=deny|once|' + id + ', clear=true',
+      ].join('; '),
+    };
+    var data = Buffer.from(String(summary || tool), 'utf8');
+    headers['Content-Length'] = data.length;
+    var req = https.request({ method: 'POST', hostname: 'ntfy.sh', path: '/' + encodeURIComponent(topic), headers: headers },
+      function (res) { res.on('data', function () {}); res.on('end', resolve); });
+    req.on('error', resolve); req.write(data); req.end();
+    setTimeout(resolve, 2500);
+  });
+}
+
+function shellQuote(s) { return '"' + String(s).replace(/["\\]/g, '\\$&') + '"'; }
+function desktopNotify(title, body, sound) {
+  try {
+    if (process.platform === 'darwin') {
+      var script = 'display notification ' + shellQuote(body) + ' with title ' + shellQuote(title);
+      spawn('osascript', ['-e', script], { stdio: 'ignore', detached: true }).unref();
+      // play the sound directly so it is heard even if notification sounds are off
+      if (sound) spawn('afplay', ['/System/Library/Sounds/' + sound + '.aiff'], { stdio: 'ignore', detached: true }).unref();
+    } else if (process.platform === 'linux') {
+      spawn('notify-send', [title, body], { stdio: 'ignore', detached: true }).unref();
+    }
+  } catch (e) {}
+}
+
+(async function () {
+  try {
+    var raw = await readStdin();
+    var input = {}; try { input = JSON.parse(raw); } catch (e) {}
+    var tool = input.tool_name || input.toolName || 'Tool';
+
+    // read only tools never wait
+    if (SAFE.indexOf(tool) !== -1) return passthrough();
+
+    var rules = readJson(RULES, { enabled: false, allowAll: false, allowTools: [], denyTools: [], paused: false });
+    // pause works independently of remote approvals: stop further actions on tap
+    if (rules.paused) return decide('deny', 'Paused from Pulse - resume on your phone or the dashboard to continue');
+    if (!rules.enabled) return passthrough();   // remote approvals are opt-in; off by default
+    if (rules.denyTools && rules.denyTools.indexOf(tool) !== -1) return decide('deny', 'Denied by Pulse rule');
+    if (rules.allowAll || (rules.allowTools && rules.allowTools.indexOf(tool) !== -1)) return decide('allow', 'Allowed by Pulse rule');
+
+    // if Pulse is not up, do nothing special: normal terminal prompt
+    if (!aliveFresh()) return passthrough();
+
+    var id = Date.now().toString(36) + Math.random().toString(36).slice(2, 8);
+    var cwd = input.cwd || '';
+    var project = cwd ? path.basename(cwd) : '';
+    var summary = summarize(tool, input.tool_input || input.toolInput);
+    try { fs.mkdirSync(PENDING, { recursive: true }); } catch (e) {}
+    try {
+      fs.writeFileSync(path.join(PENDING, id + '.json'), JSON.stringify({
+        id: id, time: Date.now(), sessionId: input.session_id || input.sessionId || null,
+        cwd: cwd, project: project, tool: tool, summary: summary,
+      }));
+    } catch (e) { return passthrough(); }
+
+    desktopNotify('Claude needs approval' + (project ? ' · ' + project : ''), tool + (summary ? ': ' + summary.slice(0, 120) : ''), 'Funk');
+    pushNtfy({ _tool: tool, _summary: summary, _id: id, _project: project });
+
+    var start = Date.now(), decision = null, deadline = timeoutMs();
+    while (Date.now() - start < deadline) {
+      decision = readJson(path.join(DECISIONS, id + '.json'), null);
+      if (decision) break;
+      // honor a standing rule set WHILE we wait: tapping "Allow all" (or a per
+      // tool rule) on ONE card must release every other waiting request too, not
+      // only the one you clicked. without this, parallel tool calls hang here
+      // until they time out, which looked like "Allow all sometimes does nothing".
+      var live = readJson(RULES, { allowAll: false, allowTools: [], denyTools: [] });
+      if (live.denyTools && live.denyTools.indexOf(tool) !== -1) { decision = { decision: 'deny' }; break; }
+      if (live.allowAll || (live.allowTools && live.allowTools.indexOf(tool) !== -1)) { decision = { decision: 'allow' }; break; }
+      await sleep(POLL_MS);
+    }
+    try { fs.unlinkSync(path.join(PENDING, id + '.json')); } catch (e) {}
+    try { fs.unlinkSync(path.join(DECISIONS, id + '.json')); } catch (e) {}
+
+    if (!decision) return passthrough();                       // timed out, normal prompt
+    if (decision.decision === 'deny') return decide('deny', 'Denied in Pulse');
+    return decide('allow', 'Approved in Pulse');
+  } catch (e) {
+    return passthrough();                                      // never block on a bug
+  }
+})();

package/hooks/stop-hook.js

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+'use strict';
+
+/*
+ * Claude Code "Stop" hook for Pulse.
+ *
+ * Fires when Claude finishes a turn (it is now your turn). Sends a phone push
+ * via ntfy.sh so you know to come back, debounced so a rapid back-and-forth
+ * does not spam you. Requires "ntfyTopic" in ~/.claude-pulse.json.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const https = require('https');
+const { spawn } = require('child_process');
+
+const RUNTIME = path.join(os.homedir(), '.claude-pulse');
+const LAST = path.join(RUNTIME, 'last-stop-push');
+const COOLDOWN = 30 * 1000;
+
+function readStdin() {
+  return new Promise(function (r) {
+    var d = '';
+    if (process.stdin.isTTY) return r('');
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', function (c) { d += c; });
+    process.stdin.on('end', function () { r(d); });
+    setTimeout(function () { r(d); }, 500);
+  });
+}
+function topic() {
+  try { return JSON.parse(fs.readFileSync(path.join(os.homedir(), '.claude-pulse.json'), 'utf8')).ntfyTopic || ''; }
+  catch (e) { return ''; }
+}
+function push(t, title, msg, tags) {
+  if (!t) return Promise.resolve();
+  return new Promise(function (res) {
+    var data = Buffer.from(msg || '', 'utf8');
+    var req = https.request({
+      method: 'POST', hostname: 'ntfy.sh', path: '/' + encodeURIComponent(t),
+      headers: {
+        'Content-Type': 'text/plain; charset=utf-8',
+        'Content-Length': data.length,
+        'Title': String(title || 'Claude Code').replace(/[^\x20-\x7E]/g, ''),
+        'Tags': tags || 'white_check_mark',
+        'Priority': 'default',
+      },
+    }, function (r) { r.on('data', function () {}); r.on('end', res); });
+    req.on('error', res);
+    req.write(data); req.end();
+    setTimeout(res, 2500);
+  });
+}
+
+function shellQuote(s) { return '"' + String(s).replace(/["\\]/g, '\\$&') + '"'; }
+function desktopNotify(title, body, sound) {
+  try {
+    if (process.platform === 'darwin') {
+      var script = 'display notification ' + shellQuote(body) + ' with title ' + shellQuote(title);
+      spawn('osascript', ['-e', script], { stdio: 'ignore', detached: true }).unref();
+      if (sound) spawn('afplay', ['/System/Library/Sounds/' + sound + '.aiff'], { stdio: 'ignore', detached: true }).unref();
+    } else if (process.platform === 'linux') {
+      spawn('notify-send', [title, body], { stdio: 'ignore', detached: true }).unref();
+    }
+  } catch (e) {}
+}
+
+(async function () {
+  const raw = await readStdin();
+  let input = {}; try { input = JSON.parse(raw); } catch (e) {}
+
+  // debounce so a rapid back-and-forth does not spam you
+  try { const last = parseInt(fs.readFileSync(LAST, 'utf8'), 10) || 0; if (Date.now() - last < COOLDOWN) return process.exit(0); } catch (e) {}
+  try { fs.mkdirSync(RUNTIME, { recursive: true }); fs.writeFileSync(LAST, String(Date.now())); } catch (e) {}
+
+  const project = input.cwd ? path.basename(input.cwd) : '';
+  // desktop banner always; phone push only if an ntfy topic is set
+  desktopNotify('Claude finished' + (project ? ' · ' + project : ''), 'Your turn', 'Glass');
+  const t = topic();
+  if (t) await push(t, 'Claude finished' + (project ? ' (' + project + ')' : ''), 'Your turn' + (project ? ' in ' + project : ''), 'white_check_mark');
+  process.exit(0);
+})();

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "pulse-for-claude-code",
+  "version": "0.1.0",
+  "description": "A local, zero-dependency dashboard for Claude Code: live token usage, context fill, lost-session recovery, and approving tool calls from your phone.",
+  "bin": {
+    "claude-pulse": "bin/cli.js",
+    "pulse-for-claude-code": "bin/cli.js",
+    "claude-pulse-export": "bin/export.js"
+  },
+  "main": "src/server.js",
+  "scripts": {
+    "start": "node bin/cli.js"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "dashboard",
+    "monitor",
+    "tokens",
+    "usage",
+    "cli"
+  ],
+  "author": "Nikita Vdoudikoff",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin",
+    "src",
+    "public",
+    "hooks",
+    "README.md",
+    "LICENSE"
+  ]
+}