noctrace 0.4.0 → 0.4.2

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

@@ -178,6 +178,7 @@ if (args.includes('--uninstall-hooks')) {
 }
 
 // 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();