runtime-inspector 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Asaf Erdman
+
+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,278 @@
+<p align="center">
+  <img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen" alt="Node.js 18+" />
+  <img src="https://img.shields.io/badge/platform-macOS%20%7C%20Linux-blue" alt="macOS | Linux" />
+  <img src="https://img.shields.io/badge/license-MIT-green" alt="MIT License" />
+  <img src="https://img.shields.io/badge/status-coming%20soon-orange" alt="Coming Soon" />
+</p>
+
+<h1 align="center">RuntimeInspector</h1>
+
+<p align="center">
+  <strong>See what your AI agents are really doing.</strong><br/>
+  A local CLI tool that scans your processes, groups them into sessions,<br/>
+  and serves a real-time dashboard. Install from npm. Runs on localhost. No cloud.
+</p>
+
+<br/>
+
+<p align="center">
+  <img width="720" src="https://github.com/user-attachments/assets/placeholder-dashboard.png" alt="RuntimeInspector Dashboard" />
+</p>
+
+> **Note:** `runtime-inspector` is not yet published to npm. Star this repo to get notified when it drops.
+
+---
+
+## Why
+
+Modern dev workflows spawn dozens of invisible processes — AI agents, dev servers, Docker containers, test watchers. Without visibility, you're flying blind.
+
+```
+$ ps aux | grep node
+# 47 lines of mystery
+```
+
+RuntimeInspector replaces that chaos with a single, organized dashboard:
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  RuntimeInspector · localhost:7331          6 sessions   │
+├─────────────────────────────────────────────────────────┤
+│                                                         │
+│  ● Claude Code — Refactor auth          acme/web-app    │
+│    PID 48201 + 3 children · 18m · CPU 12% · 340 MB     │
+│    Spawned 3 child shells; editing 12 files in          │
+│    src/auth/. Dev server on :3000.                      │
+│                                                         │
+│  ● Codex — Generate API tests      acme/api-service     │
+│    PID 48305 + 8 children · 42m · CPU 68% · 1.2 GB     │
+│    ⚠ HIGH CPU — Jest watch mode, 23 suites in parallel  │
+│                                                         │
+│  ● Vite Dev Server              acme/dashboard-ui       │
+│    PID 47102 · 2h 14m · CPU 3% · 180 MB                │
+│    ⚠ LONG-RUNNING — No file changes in 47 min          │
+│                                                         │
+│  ● Express API — payments            acme/payments      │
+│    PID 44089 · 3h 02m · CPU 1% · 95 MB                 │
+│    ⚠ ORPHAN — Parent gone. Still bound to :4000.        │
+│                                                         │
+│  ● Docker — Postgres + Redis           acme/infra       │
+│    PID 43998 + 2 containers · 4h 50m · 520 MB          │
+│    postgres:16 on :5432, redis:7 on :6379. Healthy.     │
+│                                                         │
+│  ● Cursor Agent — Fix CI pipeline  acme/deploy-config   │
+│    PID 49120 · 7m · CPU 22% · 410 MB                   │
+│    Reading .github/workflows/. Modifying deploy.yml.    │
+│                                                         │
+└─────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Quick Start
+
+### 1. Install globally
+
+```bash
+npm install -g runtime-inspector
+```
+
+### 2. Add shell integration (optional)
+
+```bash
+runtime-inspector setup --yes
+```
+
+This installs lightweight `preexec`/`precmd` hooks into your shell (zsh, bash, or fish) for command-level tracking. Restart your terminal after setup.
+
+### 3. Start the dashboard
+
+```bash
+runtime-inspector start --open
+```
+
+Your browser opens `http://localhost:7331` with a live view of everything running on your machine — grouped, explained, and scored.
+
+### Bonus: wrap a command
+
+```bash
+runtime-inspector run -- npm run dev
+```
+
+Wraps any command for deeper output tracking and richer session metadata.
+
+---
+
+## How It Works
+
+```
+┌──────────────┐     ┌──────────────┐     ┌──────────────┐
+│   1. SCAN    │────▶│   2. GROUP   │────▶│  3. EXPLAIN  │
+│              │     │              │     │              │
+│ Read process │     │ Cluster by   │     │ Plain-English│
+│ tree: PIDs,  │     │ agent, repo, │     │ summaries +  │
+│ commands,    │     │ runtime into │     │ risk signals │
+│ ports, CPU   │     │ sessions     │     │ per session  │
+└──────────────┘     └──────────────┘     └──────────────┘
+```
+
+**Scan** — Reads your process tree to identify CLIs, agents, servers, and their children.
+
+**Group** — Clusters related processes by agent, repository, and runtime into coherent sessions.
+
+**Explain** — Each session gets a summary and risk signals: long-running, orphaned, duplicated, or resource-heavy.
+
+---
+
+## CLI Reference
+
+```
+runtime-inspector start [--open]        Start agent + dashboard
+runtime-inspector run -- <command>      Run a command with output tracking
+runtime-inspector init [--shell zsh]    Print shell hook script to stdout
+runtime-inspector setup [--yes]         Install shell integration into rc file
+runtime-inspector --help                Show help
+```
+
+### Setup options
+
+| Flag | Description |
+|---|---|
+| `--shell zsh\|bash` | Override shell detection |
+| `--rc <path>` | Override rc file path |
+| `--yes` | Skip confirmation prompt |
+| `--open`, `-o` | Open browser after starting |
+
+---
+
+## What Gets Detected
+
+### AI Agents & Coding Tools
+| Tool | Status |
+|---|---|
+| Claude Code | Supported |
+| OpenAI Codex CLI | Supported |
+| Cursor Agent | Supported |
+| Aider | Supported |
+| GitHub Copilot CLI | Supported |
+| Continue | Supported |
+
+### Frameworks & Runtimes
+| Runtime | Status |
+|---|---|
+| Node.js | Supported |
+| Vite / Next.js | Supported |
+| Docker | Supported |
+| Python | Supported |
+| Go | Supported |
+| Rust (cargo) | Supported |
+
+Detection is plugin-based — adding new tools takes minutes.
+
+---
+
+## Risk Signals
+
+RuntimeInspector automatically flags sessions that need attention:
+
+| Signal | Trigger | Default |
+|---|---|---|
+| **Long-running** | Session exceeds duration threshold | 30 min |
+| **High CPU** | CPU usage exceeds threshold | 80% |
+| **Orphan** | Parent process no longer exists | Immediate |
+| **Duplicate** | Multiple instances of the same agent/server | Immediate |
+
+All thresholds are configurable via YAML config.
+
+---
+
+## Privacy & Security
+
+RuntimeInspector is **local-first by design**:
+
+- Runs entirely on `localhost` — no cloud dependency
+- Reads **process metadata only** (PIDs, command names, ports, resource counters)
+- **No source code** or terminal output leaves your machine
+- No telemetry, no tracking, no accounts
+- Configurable allowlist for any outbound data
+
+---
+
+## Project Structure
+
+```
+runtime-inspector/
+├── bin/
+│   └── cli.js              # CLI entry point
+├── src/
+│   ├── agent/
+│   │   ├── index.js         # Express server + dashboard
+│   │   ├── scanner.js       # Process tree scanner
+│   │   ├── detector.js      # Agent/framework detection
+│   │   ├── grouper.js       # Session grouping logic
+│   │   ├── explainer.js     # Plain-English summaries
+│   │   ├── purposer.js      # Intent inference
+│   │   ├── stateInfer.js    # State detection
+│   │   ├── progressInfer.js # Progress tracking
+│   │   ├── attentionInfer.js# Attention signals
+│   │   ├── actions.js       # Suggested actions
+│   │   ├── dashboard.js     # Dashboard HTML renderer
+│   │   ├── shellEvents.js   # Shell event processing
+│   │   ├── shellMerge.js    # Shell session merging
+│   │   ├── repoActivity.js  # Repo activity tracking
+│   │   ├── tmux.js          # Tmux detection
+│   │   └── tmuxMerge.js     # Tmux session merging
+│   ├── shell/
+│   │   ├── hooks.js         # Shell hook script generator
+│   │   └── setup.js         # RC file installer
+│   └── wrapper/
+│       ├── runner.js        # Command wrapper
+│       └── buffer.js        # Output buffer
+├── runtimeinspector/        # Next.js landing page
+│   └── ...
+├── package.json
+└── README.md
+```
+
+---
+
+## Requirements
+
+- **Node.js 18** or later
+- **macOS** or **Linux** (Windows/WSL on the roadmap)
+
+---
+
+## Contributing
+
+Contributions are welcome! Feel free to open issues or submit PRs.
+
+```bash
+# Clone the repo
+git clone https://github.com/asaferdman23/runtime_inspector_landing.git
+cd runtime_inspector_landing
+
+# Install CLI dependencies
+npm install
+
+# Install landing page dependencies
+cd runtimeinspector && npm install
+
+# Run the CLI
+node bin/cli.js start --open
+
+# Run the landing page
+cd runtimeinspector && npm run dev
+```
+
+---
+
+## License
+
+[MIT](LICENSE) — Asaf Erdman
+
+---
+
+<p align="center">
+  <strong>Star this repo</strong> to get notified when <code>runtime-inspector</code> lands on npm.
+</p>

package/bin/cli.js

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+
+// RuntimeInspector CLI
+// Usage: runtime-inspector start [--open]
+//        runtime-inspector run -- <command> [args...]
+//        runtime-inspector init [--shell zsh|bash]
+//        runtime-inspector setup [--shell zsh|bash] [--rc <path>] [--yes]
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+function getFlag(name) {
+  const idx = args.indexOf(name);
+  if (idx === -1) return null;
+  return args[idx + 1] || null;
+}
+
+function hasFlag(name) {
+  return args.includes(name);
+}
+
+if (command === 'init') {
+  // Print shell hook script to stdout
+  const shell = getFlag('--shell') || 'zsh';
+  import('../src/shell/hooks.js').then(({ generateHookScript }) => {
+    process.stdout.write(generateHookScript(shell));
+  }).catch((err) => {
+    console.error('Failed to generate hook script:', err.message);
+    process.exit(1);
+  });
+
+} else if (command === 'setup') {
+  // Install integration into shell rc file
+  const shell = getFlag('--shell') || null;
+  const rc = getFlag('--rc') || null;
+  const yes = hasFlag('--yes');
+
+  import('../src/shell/setup.js').then(({ detectShell, installRcBlock }) => {
+    const { shell: detectedShell, rcPath } = detectShell(shell, rc);
+
+    if (!yes) {
+      console.log(`  RuntimeInspector Shell Integration`);
+      console.log(`  Shell:   ${detectedShell}`);
+      console.log(`  RC file: ${rcPath}`);
+      console.log('');
+      console.log('  This will append the RuntimeInspector integration block to your rc file.');
+      console.log('  A backup will be created before any changes.');
+      console.log('');
+      console.log('  Run with --yes to proceed, or:');
+      console.log(`    runtimeinspector setup --shell ${detectedShell} --yes`);
+      return;
+    }
+
+    const result = installRcBlock({ shell: detectedShell, rcPath, yes });
+
+    if (result.status === 'already') {
+      console.log(`  ${result.message}`);
+      console.log('  No changes made.');
+    } else if (result.status === 'installed') {
+      console.log(`  ${result.message}`);
+      console.log('');
+      console.log('  Next steps:');
+      console.log('    1. Restart your terminal (or run: source ' + rcPath + ')');
+      console.log('    2. Start the agent: runtimeinspector start');
+      console.log('    3. Open dashboard: http://localhost:7331');
+    } else {
+      console.error(`  Error: ${result.message}`);
+      process.exit(1);
+    }
+  }).catch((err) => {
+    console.error('Failed to run setup:', err.message);
+    process.exit(1);
+  });
+
+} else if (command === 'run') {
+  // Find the -- separator
+  const dashIndex = args.indexOf('--');
+  if (dashIndex === -1 || dashIndex === args.length - 1) {
+    console.error('Usage: runtime-inspector run -- <command> [args...]');
+    console.error('Example: runtime-inspector run -- npm run dev');
+    process.exit(1);
+  }
+  const cmdArgs = args.slice(dashIndex + 1);
+
+  import('../src/wrapper/runner.js').then(({ runWrapped }) => {
+    runWrapped(cmdArgs);
+  }).catch((err) => {
+    console.error('Failed to start wrapper:', err.message);
+    process.exit(1);
+  });
+
+} else if (!command || command === 'start') {
+  const shouldOpen = args.includes('--open') || args.includes('-o');
+
+  import('../src/agent/index.js').then(({ startServer }) => {
+    startServer({ open: shouldOpen });
+  }).catch((err) => {
+    console.error('Failed to start RuntimeInspector:', err.message);
+    process.exit(1);
+  });
+
+} else if (command === '--help' || command === '-h') {
+  console.log(`
+  RuntimeInspector — local runtime inspection tool
+
+  Usage:
+    runtime-inspector start [--open]        Start the agent + dashboard
+    runtime-inspector run -- <command>       Run a command through RuntimeInspector
+    runtime-inspector init [--shell zsh]     Print shell hook script to stdout
+    runtime-inspector setup [--yes]          Install shell integration into rc file
+    runtime-inspector --help                Show this help
+
+  Setup options:
+    --shell zsh|bash    Override shell detection
+    --rc <path>         Override rc file path
+    --yes               Skip confirmation prompt
+
+  Quick start:
+    runtimeinspector setup --yes
+    # restart terminal
+    runtimeinspector start --open
+
+  Dashboard: http://localhost:7331
+  `);
+} else {
+  console.error(`Unknown command: ${command}`);
+  console.error('Run "runtime-inspector --help" for usage.');
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "runtime-inspector",
+  "version": "0.1.0",
+  "description": "Local-first runtime inspection tool for developers. Scans processes, groups them into sessions, and serves a real-time dashboard on localhost.",
+  "type": "module",
+  "bin": {
+    "runtime-inspector": "./bin/cli.js"
+  },
+  "scripts": {
+    "start": "node bin/cli.js start"
+  },
+  "files": [
+    "bin/",
+    "src/agent/",
+    "src/shell/",
+    "src/wrapper/",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "cli",
+    "process",
+    "inspector",
+    "developer-tools",
+    "terminal",
+    "runtime",
+    "observability",
+    "ai-agents",
+    "dashboard",
+    "localhost"
+  ],
+  "author": "Asaf Erdman <asaf.erdman.dev@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/asaferdman23/runtime_inspector_landing.git"
+  },
+  "homepage": "https://github.com/asaferdman23/runtime_inspector_landing#readme",
+  "bugs": {
+    "url": "https://github.com/asaferdman23/runtime_inspector_landing/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "express": "^4.21.0",
+    "open": "^10.1.0"
+  }
+}

package/src/agent/actions.js

@@ -0,0 +1,157 @@
+// Context actions — safe OS-level actions triggered from the dashboard.
+// Only whitelisted actions. No arbitrary command execution.
+
+import { execSync, spawnSync } from 'child_process';
+
+/**
+ * Open a terminal window at the given directory path.
+ * macOS: uses osascript to open Terminal.app.
+ */
+function openTerminal(cwd) {
+  if (!cwd || typeof cwd !== 'string') throw new Error('No working directory available');
+  if (!cwd.startsWith('/')) throw new Error('Invalid path');
+
+  // AppleScript to open Terminal.app at a specific directory
+  const script = `tell application "Terminal"
+    do script "cd ${escapeAppleScript(cwd)}"
+    activate
+  end tell`;
+
+  execSync(`osascript -e '${script.replace(/'/g, "'\\''")}'`, { timeout: 5000 });
+}
+
+/**
+ * Open a folder in Finder (macOS file explorer).
+ */
+function openFolder(cwd) {
+  if (!cwd || typeof cwd !== 'string') throw new Error('No working directory available');
+  if (!cwd.startsWith('/')) throw new Error('Invalid path');
+
+  execSync(`open "${cwd}"`, { timeout: 5000 });
+}
+
+/**
+ * Escape a string for AppleScript.
+ */
+function escapeAppleScript(str) {
+  return str.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+
+/**
+ * Register action routes on the Express app.
+ * Requires a function to look up sessions by id.
+ */
+export function registerActions(app, getSession) {
+  app.use('/api/actions', (req, res, next) => {
+    // All action routes use JSON
+    if (req.method === 'POST') {
+      let body = '';
+      req.on('data', chunk => body += chunk);
+      req.on('end', () => {
+        try { req.body = JSON.parse(body); } catch { req.body = {}; }
+        next();
+      });
+    } else {
+      next();
+    }
+  });
+
+  // POST /api/actions/open-terminal  { sessionId }
+  app.post('/api/actions/open-terminal', (req, res) => {
+    try {
+      const session = getSession(req.body?.sessionId);
+      if (!session) return res.status(404).json({ error: 'Session not found' });
+      if (!session.cwd) return res.status(400).json({ error: 'No working directory for this session' });
+
+      openTerminal(session.cwd);
+      res.json({ ok: true, action: 'open-terminal', cwd: session.cwd });
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  // POST /api/actions/open-folder  { sessionId }
+  app.post('/api/actions/open-folder', (req, res) => {
+    try {
+      const session = getSession(req.body?.sessionId);
+      if (!session) return res.status(404).json({ error: 'Session not found' });
+      if (!session.cwd) return res.status(400).json({ error: 'No working directory for this session' });
+
+      openFolder(session.cwd);
+      res.json({ ok: true, action: 'open-folder', cwd: session.cwd });
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  // POST /api/actions/focus-terminal  { sessionId }
+  // Best-effort: activate Terminal.app and switch to the TTY tab
+  app.post('/api/actions/focus-terminal', (req, res) => {
+    try {
+      const session = getSession(req.body?.sessionId);
+      if (!session) return res.status(404).json({ error: 'Session not found' });
+
+      const cwd = session.cwd;
+      if (!cwd) return res.status(400).json({ error: 'No working directory for this session' });
+
+      // Best-effort: open Terminal.app at cwd. If the session has a tty, try to find that tab.
+      const script = `tell application "Terminal"
+    activate
+    do script "cd ${escapeAppleScript(cwd)}"
+  end tell`;
+      execSync(`osascript -e '${script.replace(/'/g, "'\\''")}'`, { timeout: 5000 });
+      res.json({ ok: true, action: 'focus-terminal', cwd });
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  // POST /api/actions/tmux-focus  { sessionId }
+  // Switch tmux client to the pane associated with this session
+  app.post('/api/actions/tmux-focus', (req, res) => {
+    try {
+      const session = getSession(req.body?.sessionId);
+      if (!session) return res.status(404).json({ error: 'Session not found' });
+      if (!session.tmux) return res.status(400).json({ error: 'Session has no tmux pane' });
+
+      const { paneId, sessionName } = session.tmux;
+
+      // Try: switch-client to session and select-pane
+      const r = spawnSync('tmux', ['switch-client', '-t', sessionName, ';', 'select-pane', '-t', paneId], {
+        timeout: 2000,
+        encoding: 'utf-8',
+        stdio: 'pipe',
+      });
+
+      if (r.status !== 0) {
+        // Fallback: just select-pane (works if already in that session)
+        const r2 = spawnSync('tmux', ['select-pane', '-t', paneId], {
+          timeout: 2000,
+          encoding: 'utf-8',
+          stdio: 'pipe',
+        });
+        if (r2.status !== 0) {
+          return res.json({ ok: false, error: 'Could not focus tmux pane — are you in tmux?' });
+        }
+      }
+
+      res.json({ ok: true, action: 'tmux-focus', paneId });
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  // POST /api/actions/copy-command  { sessionId }
+  // Returns the root process command so the frontend can copy it.
+  app.post('/api/actions/copy-command', (req, res) => {
+    try {
+      const session = getSession(req.body?.sessionId);
+      if (!session) return res.status(404).json({ error: 'Session not found' });
+
+      const rootCmd = session.processes[0]?.cmd || '';
+      res.json({ ok: true, action: 'copy-command', command: rootCmd });
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+}