pulse-for-claude-code 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nikita Vdoudikoff
+
+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,292 @@
+# Pulse for Claude Code
+
+**A local dashboard for [Claude Code](https://claude.com/claude-code) that shows what Claude is doing, what it is spending, and lets you approve its tool calls from your phone.** Zero dependencies, nothing leaves your machine.
+
+![Overview](docs/overview.png)
+
+Claude Code already writes every session to disk. Pulse reads those files (read only) and turns them into a live dashboard: token spend by hour, day and week, the context fill of your active session, an ambient view of Claude at work, full-text search across everything you have ever run, and a notification with `Allow` / `Allow all` / `Deny` buttons when Claude needs you, on your desktop or your phone. No account, no telemetry, no network calls.
+
+## Why you might want it
+
+- **Approve from your phone.** A push with working `Allow` / `Allow all` / `Deny` buttons. No Wi-Fi setup, no IP, no open port: it works from anywhere, even on cellular.
+- **Never lose a session.** One command recovers your last session as a readable transcript, and Pulse auto-snapshots active ones, so a crash or a frozen laptop never costs you context.
+- **See the spend.** Live tokens and API-equivalent cost by hour, day, week, model and project, against budgets you set, with a phone alert when you cross one.
+- **Ambient office.** A full-screen view of a little mascot working, resting, or waiting on you, with a rough ETA. Quietly addictive on a second monitor.
+- **Search everything.** Full-text search across every session on disk, one click to the transcript.
+- **Local and private.** Reads `~/.claude` read only, serves on `127.0.0.1`, zero dependencies, no telemetry.
+
+| Ambient office view | Approve from the dashboard or your phone |
+| --- | --- |
+| ![Office](docs/office.png) | ![Approve](docs/approve.png) |
+
+## Quick start
+
+Requires Node 18+. Run it with no install:
+
+```bash
+npx pulse-for-claude-code
+```
+
+Or clone it:
+
+```bash
+git clone https://github.com/nikitadoudikov/claude-pulse.git
+cd claude-pulse
+node bin/cli.js
+```
+
+Either way it opens `http://127.0.0.1:4317`. To get desktop and phone
+notifications and to approve tool calls, wire the hooks (one command, safe to
+re-run):
+
+```bash
+claude-pulse install-hooks   # adds the hooks to ~/.claude/settings.json
+```
+
+Then restart Claude Code, and you are set. Other options:
+
+```
+claude-pulse --port 4317   # change the port
+claude-pulse --no-open     # do not open the browser
+```
+
+## Keep it running
+
+Run in the foreground and Pulse dies when you close that terminal. To keep it
+alive independently, run it in the background:
+
+```bash
+claude-pulse start     # run detached, survives closing the terminal
+claude-pulse status    # is it running?
+claude-pulse stop      # stop it
+claude-pulse restart   # stop and start again
+```
+
+If your terminal crashes, `claude-pulse start` brings it back in one command,
+and a background instance is not affected by the crash in the first place.
+
+On macOS you can hand Pulse to the system so it starts at login and respawns
+itself if it ever dies:
+
+```bash
+claude-pulse install-service     # start at login, auto-restart
+claude-pulse uninstall-service   # remove it
+```
+
+## Recover a lost session
+
+Terminal crashed, laptop froze, hit a session limit? Nothing is lost: Claude
+Code writes every session to disk as it happens. One command brings the last one
+back, prints a recap and saves a readable transcript:
+
+```bash
+claude-pulse recover        # the most recent session
+claude-pulse recover 2      # the one before that
+claude-pulse recover <id>   # a specific session
+```
+
+It saves a light markdown file under `~/.claude-pulse/exports/` (a 15 MB log
+becomes a ~180 KB file) and prints a link to read the full transcript in the
+browser or on your phone. You can also open any session in the dashboard and use
+**open transcript** / **download .md**.
+
+While Pulse runs it also **auto-snapshots** every recently active session to
+`~/.claude-pulse/exports/snapshots/` (one file per session, rewritten only when
+it changes). So the latest state is always on disk even if you never run
+`recover`. Set `snapshotMinutes` to `0` in `~/.claude-pulse.json` to turn it off.
+
+To back up everything at once, `claude-pulse export-all` writes every session
+into a single small gzipped markdown file, or use **download all history** on the
+Sessions screen.
+
+## Search every session
+
+Lost where you did something? The **Sessions** screen has a search box that
+scans every session on disk for a word or phrase and jumps you straight to the
+transcript. It works from your phone too.
+
+## On your phone
+
+The simplest phone control is the ntfy notification itself: it carries working
+`Allow` / `Allow all` / `Deny` buttons (see above), no network setup at all.
+
+For a richer view, open `http://<your-machine>:4317/phone` on the same Wi-Fi
+(needs `bindLan: true`) to see what Claude is doing right now plus a **Pause /
+Resume** button. Pausing stops Claude from running further tools until you
+resume. Both need the `PreToolUse` hook wired.
+
+## How it works
+
+```
+  ┌──────────────┐   writes .jsonl    ┌──────────────────────┐   SSE    ┌──────────────┐
+  │  Claude Code │ ─────────────────▶ │  Pulse  (read only)  │ ───────▶ │  dashboard   │
+  │  (terminal)  │                    │   127.0.0.1:4317     │          │  + phone     │
+  └──────┬───────┘                    └──────────────────────┘          └──────────────┘
+         │
+         │  hooks:  Notification  ·  Stop  ·  PreToolUse
+         ▼
+  ┌─────────────────────────────┐
+  │  ~/.claude-pulse/           │   pending approvals · decisions · events
+  └─────────────────────────────┘
+```
+
+Claude Code logs every session as JSONL under `~/.claude/projects/`. Each assistant
+message carries a `usage` block (input, output and cache tokens) with a timestamp.
+Pulse reads those files (read only), caches each file by modification time so
+unchanged sessions are never re-parsed, and aggregates the numbers. The browser
+gets live updates over Server-Sent Events. Three small hooks let Claude Code tell
+Pulse when it needs you, when a turn ends, and when it wants to run a tool.
+
+## Notifications when Claude needs you
+
+Claude Code can run a hook when it needs your attention. Point its `Notification`
+event at the bundled script and Pulse will show a banner and fire a desktop
+notification, even if the tab is in the background.
+
+The easy way is one command:
+
+```bash
+claude-pulse install-hooks     # wires the hooks into ~/.claude/settings.json (safe to re-run)
+claude-pulse uninstall-hooks   # removes them
+```
+
+It backs up your settings once, merges next to any hooks you already have, and
+never adds a duplicate. Restart Claude Code afterwards. To do it by hand instead,
+add this to `~/.claude/settings.json` (use the absolute path to your clone):
+
+```json
+{
+  "hooks": {
+    "Notification": [
+      {
+        "matcher": "",
+        "hooks": [
+          { "type": "command", "command": "node /absolute/path/to/claude-pulse/hooks/notify-hook.js" }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          { "type": "command", "command": "node /absolute/path/to/claude-pulse/hooks/stop-hook.js" }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "",
+        "hooks": [
+          { "type": "command", "command": "node /absolute/path/to/claude-pulse/hooks/permission-hook.js" }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Keep `claude-pulse` running and you are set.
+
+## Approve tools from the dashboard (and your phone)
+
+With the `PreToolUse` hook wired, when Claude wants to run something that needs
+permission, an approval card appears in Pulse with `Allow`, `Allow all` and
+`Deny`. `Allow all` stops asking for the rest of the run.
+
+This is built to never hang Claude. Read only tools pass straight through, and if
+Pulse is not running, has not heard from you within the approval timeout (60s by
+default, set `approvalTimeoutMs`), or hits any error, it falls back to the normal
+terminal prompt. Nothing breaks if you ignore it. The phone push carries `Allow`,
+`Allow all` and `Deny` buttons.
+
+To approve from your phone, you only need an `ntfyTopic` (below) and the ntfy
+app. The push notification carries `Allow`, `Allow all` and `Deny` buttons, and
+tapping one sends the answer back through ntfy to a private reply topic that
+Pulse listens on. No same Wi-Fi, no IP, no open port: it works from anywhere,
+even on cellular. Pulse only acts on a reply while it is actually waiting for
+that request, so a stale notification can do nothing.
+
+```
+  Claude wants to run a tool
+          │
+          ▼
+   PreToolUse hook ──▶ Pulse ──push──▶ phone notification
+          │                                   │
+          │                              tap "Allow"
+          │                                   │
+          │                    answer returns over ntfy
+          │                                   │
+          ▼                                   ▼
+   hook is still waiting ◀── decision ◀── Pulse (subscribed to the reply topic)
+          │
+          ▼
+   hook returns "allow" ──▶ Claude runs the tool
+```
+
+## Phone push (optional)
+
+To get a push on your phone when Claude needs you or finishes, pick a hard to
+guess topic name, install the free [ntfy](https://ntfy.sh) app and subscribe to
+that topic, then set it in `~/.claude-pulse.json`:
+
+```json
+{ "ntfyTopic": "claude-pulse-9f3a7c" }
+```
+
+With the hooks above wired, the `Notification` hook pushes when Claude is waiting
+for you, and the `Stop` hook pushes when a turn finishes (debounced to 30s so a
+back and forth does not spam you). Anyone who knows the topic can read it, so use
+a random name.
+
+If you set `budgets` (below), Pulse also pushes when a rolling window crosses 80%
+then 100% of its budget, so you find out from your pocket, not by checking.
+
+## Configuration
+
+Copy `config.example.json` to `~/.claude-pulse.json` and edit. Every field is optional.
+
+```json
+{
+  "plan": "max20",
+  "contextLimit": 200000,
+  "idleMinutes": 10,
+  "approvalTimeoutMs": 60000,
+  "budgets": { "fiveHour": 140, "day": 360, "week": 1100 }
+}
+```
+
+### About limits
+
+Anthropic does not publish exact subscription limits, and they are usage based
+rather than a fixed token count. Pulse cannot read your real plan ceiling, so the
+budgets above are rough API-equivalent estimates you adjust to match what you
+observe. The `pro`, `max5` and `max20` presets are starting points, not official
+numbers. Token cost is estimated from public API list prices purely as a usage
+proxy; subscription users do not pay per token.
+
+## Security and privacy
+
+Pulse is local-first and opt-in. Out of the box it binds to `127.0.0.1` only,
+makes no outbound calls, has zero dependencies (no supply chain), and reads
+`~/.claude` read only. Nothing leaves your machine and there is no analytics. Two
+optional features change that, and both are off until you turn them on:
+
+- **Phone push (`ntfyTopic`)** routes through the public
+  [ntfy.sh](https://ntfy.sh) relay. Approval prompts (with a short command
+  summary) and your taps pass through a topic you name, so anyone who learns the
+  topic can read those prompts and answer them. Use a long random topic, and
+  self-host ntfy or use ntfy access tokens if you want stronger guarantees. Pulse
+  only acts on a reply while it is genuinely waiting for that exact request, so a
+  stale or guessed message cannot approve anything by itself.
+- **LAN access (`bindLan`)** binds the server to your whole network so a phone on
+  the same Wi-Fi can open the live `/phone` page. While it is on, other devices
+  on that network can also read the dashboard and your transcripts, so only
+  enable it on a network you trust. You do not need it for phone approvals (those
+  go through ntfy), so most people should leave it off.
+
+Runtime state, the device token and your config live in your home directory under
+`~/.claude-pulse/`, and are never committed or sent anywhere.
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+'use strict';
+
+const os = require('os');
+const { spawn } = require('child_process');
+const { start } = require('../src/server');
+
+const COMMANDS = new Set(['run', 'start', 'stop', 'restart', 'status', 'recover', 'export-all',
+  'install-hooks', 'uninstall-hooks', 'install-service', 'uninstall-service']);
+
+function lanIp() {
+  try {
+    const ifs = os.networkInterfaces();
+    for (const k in ifs) for (const a of ifs[k]) if (a.family === 'IPv4' && !a.internal) return a.address;
+  } catch (e) {}
+  return '';
+}
+
+function parseArgs(argv) {
+  const out = { port: 4317, open: true };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--port' || a === '-p') out.port = parseInt(argv[++i], 10) || out.port;
+    else if (a === '--no-open') out.open = false;
+    else if (a === '--help' || a === '-h') out.help = true;
+    else if (a === '--version' || a === '-v') out.version = true;
+  }
+  return out;
+}
+
+function openBrowser(url) {
+  const platform = process.platform;
+  const cmd = platform === 'darwin' ? 'open' : platform === 'win32' ? 'start' : 'xdg-open';
+  try {
+    const child = spawn(cmd, [url], { stdio: 'ignore', detached: true, shell: platform === 'win32' });
+    child.unref();
+  } catch (e) {}
+}
+
+function printHelp() {
+  console.log(`claude-pulse - local dashboard for Claude Code
+
+Usage: claude-pulse [command] [options]
+
+Commands:
+  (none) / run        run in the foreground (ctrl+c to stop)
+  start               run in the background, survives closing the terminal
+  stop                stop the background instance
+  restart             restart the background instance
+  status              show whether Pulse is running
+  recover [n|id]      show + save the last session (lost it after a crash? run this)
+  export-all          save every session as one small gzipped markdown file
+  install-hooks       wire the Pulse hooks into ~/.claude/settings.json
+  uninstall-hooks     remove the Pulse hooks from ~/.claude/settings.json
+  install-service     macOS: start at login and auto-restart if it dies
+  uninstall-service   macOS: remove the login service
+
+Options:
+  -p, --port <n>   port to listen on (default 4317)
+      --no-open    do not open the browser automatically
+  -h, --help       show this help
+  -v, --version    show version
+`);
+}
+
+function recover(rest) {
+  const t = require('../src/transcript');
+  const daemon = require('../src/daemon');
+  const positional = rest.find((a) => !a.startsWith('-'));
+  const sessions = t.listSessions();
+  if (!sessions.length) { console.log('no sessions found under ~/.claude/projects'); return; }
+
+  let s;
+  if (positional && /^\d+$/.test(positional)) s = sessions[parseInt(positional, 10) - 1];
+  else if (positional) s = sessions.find((x) => x.sid.startsWith(positional));
+  else s = sessions[0];
+  if (!s) { console.log(`no session for "${positional}". recent ones:`); sessions.slice(0, 6).forEach((x, i) => console.log(`  ${i + 1}. ${x.sid.slice(0, 8)}  ${new Date(x.mtimeMs).toISOString().slice(0, 16).replace('T', ' ')}`)); return; }
+
+  console.log('');
+  console.log(t.recapText(s.file, 8));
+  const r = t.saveExport(s, {});
+  const running = daemon.running();
+  const port = running ? running.port : 4317;
+  console.log('');
+  console.log(`full transcript saved: ${r.path}`);
+  console.log(`read it in the browser or on your phone: http://127.0.0.1:${port}/transcript?sid=${s.sid}`);
+  if (sessions.length > 1) console.log(`a different one? claude-pulse recover 2  (or an id)`);
+}
+
+function installHooks() {
+  const r = require('../src/hooksetup').installHooks();
+  if (r.added) console.log(`wired ${r.added} hook(s) into ~/.claude/settings.json`);
+  if (r.already) console.log(`${r.already} hook(s) were already set`);
+  console.log('restart Claude Code (or open a new session) for the hooks to take effect');
+}
+
+function uninstallHooks() {
+  const r = require('../src/hooksetup').uninstallHooks();
+  console.log(r.removed ? `removed Pulse hooks from ${r.removed} event(s)` : 'no Pulse hooks were set');
+}
+
+function exportAll(rest) {
+  const t = require('../src/transcript');
+  const zlib = require('zlib');
+  const fs = require('fs'), os = require('os'), path = require('path');
+  const md = t.combinedMarkdown({ full: rest.indexOf('--full') !== -1 });
+  const dir = path.join(os.homedir(), '.claude-pulse', 'exports');
+  try { fs.mkdirSync(dir, { recursive: true }); } catch (e) {}
+  const dest = path.join(dir, 'history-' + new Date().toISOString().slice(0, 10) + '.md.gz');
+  fs.writeFileSync(dest, zlib.gzipSync(md));
+  console.log('exported every session to one file:');
+  console.log(`  ${dest}`);
+  console.log(`  ${(Buffer.byteLength(md) / 1048576).toFixed(1)} MB markdown -> ${(fs.statSync(dest).size / 1024).toFixed(0)} KB gzipped`);
+}
+
+async function runForeground(args) {
+  try {
+    const { port } = await start({ port: args.port });
+    const url = `http://127.0.0.1:${port}`;
+    console.log(`\n  Pulse for Claude Code`);
+    console.log(`  running at ${url}`);
+    console.log(`  reading ~/.claude/projects (read only)`);
+    const cfg = require('../src/config').loadConfig();
+    if (cfg.bindLan) {
+      const ip = lanIp();
+      if (ip) console.log(`  on your network: http://${ip}:${port}`);
+    }
+    console.log(cfg.ntfyTopic
+      ? `  phone push: ntfy topic "${cfg.ntfyTopic}"`
+      : `  phone push: set "ntfyTopic" in ~/.claude-pulse.json`);
+    console.log(`\n  press ctrl+c to stop\n`);
+    if (args.open) openBrowser(url);
+  } catch (e) {
+    if (e && e.code === 'EADDRINUSE') {
+      console.error(`\n  port ${args.port} is busy. is Pulse already running? try: claude-pulse status`);
+      console.error(`  or pick another port: claude-pulse --port ${args.port + 1}\n`);
+    } else {
+      console.error('  failed to start:', e && e.message);
+    }
+    process.exit(1);
+  }
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const cmd = argv[0] && !argv[0].startsWith('-') && COMMANDS.has(argv[0]) ? argv[0] : null;
+  const args = parseArgs(cmd ? argv.slice(1) : argv);
+
+  if (args.help) { printHelp(); return; }
+  if (args.version) { console.log(require('../package.json').version); return; }
+
+  if (cmd && cmd !== 'run') {
+    const daemon = require('../src/daemon');
+    if (cmd === 'start') return daemon.start({ port: args.port });
+    if (cmd === 'stop') return daemon.stop();
+    if (cmd === 'restart') return daemon.restart({ port: args.port });
+    if (cmd === 'status') return daemon.status();
+    if (cmd === 'recover') return recover(argv.slice(1));
+    if (cmd === 'export-all') return exportAll(argv.slice(1));
+    if (cmd === 'install-hooks') return installHooks();
+    if (cmd === 'uninstall-hooks') return uninstallHooks();
+    if (cmd === 'install-service') return daemon.installService({ port: args.port });
+    if (cmd === 'uninstall-service') return daemon.uninstallService();
+  }
+
+  await runForeground(args);
+}
+
+main();

package/bin/export.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+'use strict';
+
+// Save a Claude Code session to a light markdown file. Works with no server
+// running. See src/transcript.js for the rendering.
+
+const fs = require('fs');
+const t = require('../src/transcript');
+
+function parseArgs(argv) {
+  const out = { full: false, gz: false, list: false, sid: null };
+  for (const a of argv) {
+    if (a === '--full') out.full = true;
+    else if (a === '--gz') out.gz = true;
+    else if (a === '--list' || a === '-l') out.list = true;
+    else if (a === '--help' || a === '-h') out.help = true;
+    else if (!a.startsWith('-')) out.sid = a;
+  }
+  return out;
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (args.help) {
+    console.log(`claude-pulse-export - save a Claude Code session to a light markdown file
+
+Usage:
+  claude-pulse-export [session] [options]
+
+  session   session id (or prefix), or "latest" (default)
+
+Options:
+  -l, --list   list recent sessions and exit
+      --full   include full tool inputs (bigger file)
+      --gz     also write a gzipped copy
+  -h, --help   show this help
+
+Works with no server running. Reads ~/.claude/projects (read only),
+writes to ~/.claude-pulse/exports/.`);
+    return;
+  }
+
+  if (args.list) {
+    const all = t.listSessions().slice(0, 25);
+    if (!all.length) { console.log('no sessions found under ~/.claude/projects'); return; }
+    for (const s of all) {
+      const mb = (s.size / 1048576).toFixed(1);
+      console.log(`${s.sid}  ${new Date(s.mtimeMs).toISOString().slice(0, 16).replace('T', ' ')}  ${mb} MB`);
+    }
+    return;
+  }
+
+  const s = t.findSession(args.sid);
+  if (!s) { console.error(`no session matching "${args.sid || 'latest'}". try --list`); process.exit(1); }
+
+  const r = t.saveExport(s, args);
+  console.log(`exported ${s.sid}`);
+  console.log(`  raw log: ${(s.size / 1048576).toFixed(1)} MB  ->  export: ${(Buffer.byteLength(r.md) / 1024).toFixed(0)} KB`);
+  console.log(`  ${r.path}`);
+  if (r.gz) console.log(`  ${r.gz}  (${(fs.statSync(r.gz).size / 1024).toFixed(0)} KB)`);
+}
+
+main();

package/hooks/notify-hook.js

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+'use strict';
+
+/*
+ * Claude Code "Notification" hook for Pulse.
+ *
+ * Claude Code runs this and pipes a JSON object on stdin whenever it needs
+ * your attention (a permission / Allow prompt, or it has been idle waiting for
+ * input). This script does two things:
+ *   1. appends the event to ~/.claude-pulse/events.jsonl  (the dashboard reads it)
+ *   2. fires a native desktop notification so you notice even if the tab is hidden
+ *
+ * Wire it up in ~/.claude/settings.json (see README), then keep `claude-pulse`
+ * running. The script is intentionally tiny and never blocks Claude.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const https = require('https');
+const { spawn } = require('child_process');
+
+const RUNTIME_DIR = path.join(os.homedir(), '.claude-pulse');
+const EVENTS_FILE = path.join(RUNTIME_DIR, 'events.jsonl');
+const MAX_LINES = 200; // keep the events file small
+
+function readStdin() {
+  return new Promise((resolve) => {
+    let data = '';
+    if (process.stdin.isTTY) return resolve('');
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (c) => { data += c; });
+    process.stdin.on('end', () => resolve(data));
+    setTimeout(() => resolve(data), 500); // never hang
+  });
+}
+
+function classify(message) {
+  const m = String(message || '').toLowerCase();
+  if (m.includes('permission') || m.includes('approve') || m.includes('allow')) return 'permission';
+  return 'notification';
+}
+
+function appendEvent(ev) {
+  try { fs.mkdirSync(RUNTIME_DIR, { recursive: true }); } catch (e) {}
+  let lines = [];
+  try { lines = fs.readFileSync(EVENTS_FILE, 'utf8').split('\n').filter(Boolean); } catch (e) {}
+  lines.push(JSON.stringify(ev));
+  if (lines.length > MAX_LINES) lines = lines.slice(lines.length - MAX_LINES);
+  try { fs.writeFileSync(EVENTS_FILE, lines.join('\n') + '\n'); } catch (e) {}
+}
+
+function desktopNotify(title, body) {
+  try {
+    if (process.platform === 'darwin') {
+      const script = 'display notification ' + q(body) + ' with title ' + q(title) + ' sound name "Ping"';
+      spawn('osascript', ['-e', script], { stdio: 'ignore', detached: true }).unref();
+    } else if (process.platform === 'linux') {
+      spawn('notify-send', [title, body], { stdio: 'ignore', detached: true }).unref();
+    }
+  } catch (e) {}
+}
+function q(s) { return '"' + String(s).replace(/["\\]/g, '\\$&') + '"'; }
+
+function readNtfyTopic() {
+  try { return JSON.parse(fs.readFileSync(path.join(os.homedir(), '.claude-pulse.json'), 'utf8')).ntfyTopic || ''; }
+  catch (e) { return ''; }
+}
+function pushNtfy(topic, title, message, tags) {
+  if (!topic) return Promise.resolve();
+  return new Promise(function (resolve) {
+    var data = Buffer.from(message || '', 'utf8');
+    var req = https.request({
+      method: 'POST', hostname: 'ntfy.sh', path: '/' + encodeURIComponent(topic),
+      headers: {
+        'Content-Type': 'text/plain; charset=utf-8',
+        'Content-Length': data.length,
+        'Title': String(title || 'Claude Code').replace(/[^\x20-\x7E]/g, ''),
+        'Tags': tags || 'warning',
+        'Priority': 'high',
+      },
+    }, function (res) { res.on('data', function () {}); res.on('end', resolve); });
+    req.on('error', resolve);
+    req.write(data); req.end();
+    setTimeout(resolve, 2500);
+  });
+}
+
+(async function main() {
+  const raw = await readStdin();
+  let input = {};
+  try { input = JSON.parse(raw); } catch (e) {}
+
+  const message = input.message || input.notification || 'Claude needs your attention';
+  const ev = {
+    time: Date.now(),
+    type: classify(message),
+    sessionId: input.session_id || input.sessionId || null,
+    cwd: input.cwd || null,
+    message: message,
+  };
+
+  appendEvent(ev);
+  const project = ev.cwd ? path.basename(ev.cwd) : '';
+  desktopNotify('Claude Code' + (project ? ' · ' + project : ''), message);
+  await pushNtfy(readNtfyTopic(), 'Claude needs you' + (project ? ' (' + project + ')' : ''), message, 'warning');
+
+  process.exit(0);
+})();