noctrace 0.3.6 → 0.4.1

package/.claude-plugin/plugin.json

@@ -0,0 +1,13 @@
+{
+  "name": "noctrace",
+  "version": "0.4.0",
+  "description": "Chrome DevTools Network-tab-style waterfall visualizer for Claude Code agent workflows",
+  "author": {
+    "name": "Nyktora Group LLC",
+    "url": "https://nyktora.com"
+  },
+  "homepage": "https://nyktora.github.io/noctrace/",
+  "repository": "https://github.com/nyktora/noctrace",
+  "license": "MIT",
+  "keywords": ["devtools", "waterfall", "observability", "timeline", "context-health"]
+}

package/.mcp.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "noctrace": {
+      "command": "node",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/bin/noctrace-mcp.js"],
+      "env": {
+        "NODE_ENV": "production"
+      }
+    }
+  }
+}

package/README.md

@@ -37,7 +37,13 @@ npm install -g noctrace
 noctrace
 ```
 
-Requires Node.js 20+. That's it. No config, no hooks, no API keys.
+### As a Claude Code Plugin
+
+```bash
+claude plugin install nyktora/noctrace
+```
+
+Requires Node.js 20+. That's it. No config required. Optional hooks for real-time events.
 
 ## Features
 
@@ -54,6 +60,9 @@ Requires Node.js 20+. That's it. No config, no hooks, no API keys.
 - **Detail panel** — click any row for full tool input/output, resizable
 - **Re-read detection** — flags duplicate file reads that waste context
 - **Dark theme** — Catppuccin Mocha palette
+- **Session export** — share sessions as standalone offline HTML files
+- **Hooks integration** — optional real-time event streaming from Claude Code
+- **Context Drift Rate** — detect accelerating token growth before context rot hits
 
 ![Noctrace waterfall timeline](docs/screenshots/noctrace-waterfall.png)
 
@@ -89,7 +98,7 @@ Click any row to inspect the full tool input and output. Two-column layout shows
 4. Parses tool_use/tool_result pairs into a waterfall timeline
 5. Watches active session files for real-time updates via WebSocket
 
-No hooks to install. No config files. No cloud. Everything stays local.
+No config files. No cloud. Everything stays local. Optional hooks for richer real-time data.
 
 ## Configuration
 
@@ -98,6 +107,11 @@ No hooks to install. No config files. No cloud. Everything stays local.
 | `PORT` | `4117` | Server port (auto-increments if busy) |
 | `CLAUDE_HOME` | `~/.claude` | Override Claude home directory |
 
+| CLI Flag | Description |
+|----------|-------------|
+| `--install-hooks` | Configure Claude Code to push real-time events to noctrace |
+| `--uninstall-hooks` | Remove noctrace hooks from Claude Code |
+
 ## Development
 
 ```bash

package/bin/noctrace-mcp.js

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+/**
+ * Minimal MCP server wrapper for the noctrace plugin.
+ *
+ * Starts the noctrace Express server as a side effect and speaks just enough
+ * MCP (JSON-RPC 2.0 over stdio) to stay alive as a Claude Code managed process.
+ * Exposes a single `open_dashboard` tool so Claude can tell the user the URL.
+ */
+import { createInterface } from 'node:readline';
+
+const VERSION = '0.4.0';
+let serverPort = null;
+let browserOpened = false;
+
+// Start the Express server (lazy import to avoid loading before needed)
+async function boot() {
+  process.env.NOCTRACE_NO_AUTOSTART = '1';
+  const { startServer } = await import('../dist/server/server/index.js');
+  serverPort = await startServer();
+
+  // Open browser once on first start
+  if (!browserOpened) {
+    const open = (await import('open')).default;
+    await open(`http://localhost:${serverPort}`);
+    browserOpened = true;
+  }
+}
+
+// JSON-RPC response helper
+function respond(id, result) {
+  const msg = JSON.stringify({ jsonrpc: '2.0', id, result });
+  process.stdout.write(`${msg}\n`);
+}
+
+// Handle incoming JSON-RPC messages from Claude Code
+function handleMessage(line) {
+  let msg;
+  try {
+    msg = JSON.parse(line);
+  } catch {
+    return; // ignore malformed input
+  }
+
+  const { id, method, params } = msg;
+
+  if (method === 'initialize') {
+    respond(id, {
+      protocolVersion: '2024-11-05',
+      capabilities: { tools: {} },
+      serverInfo: { name: 'noctrace', version: VERSION },
+    });
+    return;
+  }
+
+  if (method === 'notifications/initialized') {
+    // No response needed for notifications
+    return;
+  }
+
+  if (method === 'tools/list') {
+    respond(id, {
+      tools: [
+        {
+          name: 'open_dashboard',
+          description: 'Open the noctrace waterfall dashboard in the browser',
+          inputSchema: { type: 'object', properties: {}, required: [] },
+        },
+      ],
+    });
+    return;
+  }
+
+  if (method === 'tools/call') {
+    const toolName = params?.name;
+    if (toolName === 'open_dashboard') {
+      const url = `http://localhost:${serverPort ?? 4117}`;
+      // Open browser
+      import('open').then((m) => m.default(url)).catch(() => {});
+      respond(id, {
+        content: [{ type: 'text', text: `Noctrace dashboard: ${url}` }],
+      });
+      return;
+    }
+    // Unknown tool
+    respond(id, {
+      content: [{ type: 'text', text: `Unknown tool: ${toolName}` }],
+      isError: true,
+    });
+    return;
+  }
+
+  // Unknown method — respond with empty result to avoid hanging
+  if (id !== undefined) {
+    respond(id, {});
+  }
+}
+
+// Main
+async function main() {
+  await boot();
+
+  const rl = createInterface({ input: process.stdin });
+  rl.on('line', handleMessage);
+
+  // Keep alive until stdin closes (Claude Code manages our lifecycle)
+  rl.on('close', () => {
+    process.exit(0);
+  });
+}
+
+main().catch((err) => {
+  console.error('[noctrace-mcp] Fatal:', err.message);
+  process.exit(1);
+});

package/bin/noctrace.js

@@ -1,7 +1,186 @@
 #!/usr/bin/env node
-import { startServer } from '../dist/server/server/index.js';
-import open from 'open';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
 
+const NOCTRACE_PORT = 4117;
+const NOCTRACE_BASE_URL = `http://localhost:${NOCTRACE_PORT}`;
+const HOOKS_ENDPOINT = `${NOCTRACE_BASE_URL}/api/hooks`;
+
+/**
+ * The curl command used as the hook body.
+ * Reads the hook event JSON from stdin and POSTs it to noctrace.
+ * `--data-raw "$(cat)"` captures all of stdin and sends it as the request body.
+ */
+const HOOK_COMMAND = `curl -s -X POST ${HOOKS_ENDPOINT} -H 'Content-Type: application/json' --data-raw "$(cat)"`;
+
+/**
+ * The set of Claude Code hook event names noctrace subscribes to.
+ */
+const HOOK_EVENT_NAMES = [
+  'PostToolUse',
+  'SubagentStart',
+  'SubagentStop',
+  'Stop',
+  'PreCompact',
+  'PostCompact',
+];
+
+/**
+ * Read and parse ~/.claude/settings.json.
+ * Returns an empty object if the file doesn't exist yet.
+ */
+async function readSettings(settingsPath) {
+  try {
+    const raw = await fs.readFile(settingsPath, 'utf8');
+    return JSON.parse(raw);
+  } catch (err) {
+    if (err.code === 'ENOENT') return {};
+    throw err;
+  }
+}
+
+/**
+ * Write settings back to disk, creating parent directories as needed.
+ */
+async function writeSettings(settingsPath, settings) {
+  await fs.mkdir(path.dirname(settingsPath), { recursive: true });
+  await fs.writeFile(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf8');
+}
+
+/**
+ * Install noctrace hooks into ~/.claude/settings.json.
+ * For each hook event name, adds a "command" hook that POSTs the event
+ * payload to the noctrace HTTP endpoint.
+ * Skips events that already have a noctrace hook registered.
+ */
+async function installHooks() {
+  const settingsPath = path.join(os.homedir(), '.claude', 'settings.json');
+  const settings = await readSettings(settingsPath);
+
+  if (!settings.hooks) settings.hooks = {};
+
+  const added = [];
+  const skipped = [];
+
+  for (const eventName of HOOK_EVENT_NAMES) {
+    if (!settings.hooks[eventName]) settings.hooks[eventName] = [];
+
+    const existing = settings.hooks[eventName];
+
+    // Check whether a noctrace hook is already registered for this event
+    const alreadyInstalled = existing.some(
+      (entry) =>
+        Array.isArray(entry.hooks) &&
+        entry.hooks.some(
+          (h) => h.type === 'command' && typeof h.command === 'string' && h.command.includes(HOOKS_ENDPOINT),
+        ),
+    );
+
+    if (alreadyInstalled) {
+      skipped.push(eventName);
+      continue;
+    }
+
+    existing.push({
+      hooks: [{
+        type: 'command',
+        command: HOOK_COMMAND,
+        async: true,
+      }],
+    });
+
+    added.push(eventName);
+  }
+
+  await writeSettings(settingsPath, settings);
+
+  if (added.length > 0) {
+    console.log(`[noctrace] Installed hooks for: ${added.join(', ')}`);
+  }
+  if (skipped.length > 0) {
+    console.log(`[noctrace] Already installed (skipped): ${skipped.join(', ')}`);
+  }
+  console.log(`[noctrace] Settings written to: ${settingsPath}`);
+  console.log(`[noctrace] Hook events will be forwarded to ${HOOKS_ENDPOINT}`);
+}
+
+/**
+ * Remove noctrace hooks from ~/.claude/settings.json.
+ * Only removes hooks whose command string contains the noctrace endpoint —
+ * other hooks for the same events are left untouched.
+ */
+async function uninstallHooks() {
+  const settingsPath = path.join(os.homedir(), '.claude', 'settings.json');
+  const settings = await readSettings(settingsPath);
+
+  if (!settings.hooks) {
+    console.log('[noctrace] No hooks section found in settings.json — nothing to remove.');
+    return;
+  }
+
+  const removed = [];
+
+  for (const eventName of HOOK_EVENT_NAMES) {
+    const existing = settings.hooks[eventName];
+    if (!Array.isArray(existing)) continue;
+
+    const before = existing.length;
+    settings.hooks[eventName] = existing.filter(
+      (entry) =>
+        !(
+          Array.isArray(entry.hooks) &&
+          entry.hooks.some(
+            (h) => h.type === 'command' && typeof h.command === 'string' && h.command.includes(HOOKS_ENDPOINT),
+          )
+        ),
+    );
+
+    if (settings.hooks[eventName].length < before) {
+      removed.push(eventName);
+    }
+
+    // Clean up empty arrays
+    if (settings.hooks[eventName].length === 0) {
+      delete settings.hooks[eventName];
+    }
+  }
+
+  // Clean up empty hooks object
+  if (Object.keys(settings.hooks).length === 0) {
+    delete settings.hooks;
+  }
+
+  await writeSettings(settingsPath, settings);
+
+  if (removed.length > 0) {
+    console.log(`[noctrace] Removed hooks for: ${removed.join(', ')}`);
+    console.log(`[noctrace] Settings written to: ${settingsPath}`);
+  } else {
+    console.log('[noctrace] No noctrace hooks found — nothing to remove.');
+  }
+}
+
+// ---------------------------------------------------------------------------
+// CLI dispatch
+// ---------------------------------------------------------------------------
+
+const args = process.argv.slice(2);
+
+if (args.includes('--install-hooks')) {
+  await installHooks();
+  process.exit(0);
+}
+
+if (args.includes('--uninstall-hooks')) {
+  await uninstallHooks();
+  process.exit(0);
+}
+
+// Default: start the server and open the browser
+process.env.NOCTRACE_NO_AUTOSTART = '1';
+const { startServer } = await import('../dist/server/server/index.js');
+const open = (await import('open')).default;
 const port = await startServer();
 const url = `http://localhost:${port}`;
 await open(url);