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

npm install -g runtime-inspector

2. Add shell integration (optional)

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

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

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.

# 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 — Asaf Erdman