Onboarding: node-inspector/node-inspector

Generated by RepoPilot · 2026-05-06 · Source

Agent protocol

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/node-inspector/node-inspector shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

Verdict

GO — Healthy across all four use cases

• 21+ active contributors
• BSD-2-Clause licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 8y ago
• ⚠ Concentrated ownership — top contributor handles 61% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

Verify before trusting

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live node-inspector/node-inspector repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/node-inspector/node-inspector.

What it runs against: a local clone of node-inspector/node-inspector — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in node-inspector/node-inspector | Confirms the artifact applies here, not a fork | | 2 | License is still BSD-2-Clause | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 3039 days ago | Catches sudden abandonment since generation |

<details> <summary><b>Run all checks</b> — paste this script from inside your clone of <code>node-inspector/node-inspector</code></summary>

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of node-inspector/node-inspector. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/node-inspector/node-inspector.git
#   cd node-inspector
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of node-inspector/node-inspector and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "node-inspector/node-inspector(\\.git)?\\b" \\
  && ok "origin remote is node-inspector/node-inspector" \\
  || miss "origin remote is not node-inspector/node-inspector (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(BSD-2-Clause)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"BSD-2-Clause\"" package.json 2>/dev/null) \\
  && ok "license is BSD-2-Clause" \\
  || miss "license drift — was BSD-2-Clause at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "bin/inspector.js" \\
  && ok "bin/inspector.js" \\
  || miss "missing critical file: bin/inspector.js"
test -f "bin/node-debug.js" \\
  && ok "bin/node-debug.js" \\
  || miss "missing critical file: bin/node-debug.js"
test -f "front-end-node/NodeInspectorOverrides.js" \\
  && ok "front-end-node/NodeInspectorOverrides.js" \\
  || miss "missing critical file: front-end-node/NodeInspectorOverrides.js"
test -f "front-end-node/protocol.json" \\
  && ok "front-end-node/protocol.json" \\
  || miss "missing critical file: front-end-node/protocol.json"
test -f "front-end-node/inspector.json" \\
  && ok "front-end-node/inspector.json" \\
  || miss "missing critical file: front-end-node/inspector.json"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 3039 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~3009d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/node-inspector/node-inspector"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

</details>

TL;DR

Node Inspector is a debugger interface for Node.js applications that embeds the Blink Developer Tools (Chrome DevTools) UI to provide source-level debugging, breakpoints, call stack inspection, and console access. It bridges Node.js processes with the Chrome/Opera DevTools protocol, allowing developers to debug server-side JavaScript using the familiar browser debugging interface. Dual-frontend architecture: /front-end contains the Blink DevTools base assets (CSS, images, JavaScript), while /front-end-node contains Node.js-specific overrides (NodeInspectorOverrides.js, module.json configuration) for console, sources, profiler, and network panels. /bin contains CLI entry points (node-debug.js, inspector.js), with the main debugger logic presumably in lib/ (not fully listed but implied by file structure).

Who it's for

Node.js backend developers who need to debug running applications and prefer the familiar Chrome DevTools experience over command-line debugging. It's particularly useful for developers debugging long-running servers, complex async code, and production issues before Node 6.3+ made built-in DevTools debugging standard.

Maturity & risk

Mature but largely superseded: the README explicitly notes that Node.js 6.3+ includes a built-in DevTools-based debugger developed by the V8/Chromium team. Node Inspector has CI setup (.travis.yml), substantial codebase (6MB JavaScript), and is production-tested, but is now considered a legacy tool for older Node versions or edge cases where the built-in debugger is unavailable.

High obsolescence risk: the maintainers acknowledge deprecation in the README itself. No recent commit data shown, but the reliance on Blink/WebKit DevTools frontend (in /front-end and /front-end-node directories) creates brittleness if Chrome DevTools protocol diverges from Node.js implementation. Single-maintainer risk is implied by MAINTAINERS.md presence and gitter chat dependency for support.

Active areas of work

No active development signals visible in the provided file list. The repository appears to be in maintenance-only mode given the README disclaimer about Node 6.3+ built-in debuggers. The presence of ChangeLog.md and CONTRIBUTING.md suggests historical activity but no specific PRs, milestones, or recent changes are indicated in the data provided.

Get running

Clone: git clone https://github.com/node-inspector/node-inspector.git && cd node-inspector. Install: npm install (or npm install -g for global CLI tool). Run: node-debug app.js where app.js is your target Node script, which automatically loads the debugger in Chrome.

Daily commands: Start the debugger against a Node script: node-debug app.js. Alternatively, start the inspector daemon manually: node bin/inspector.js then visit http://localhost:8080 in Chrome/Opera. The node-debug command is the standard entry point for developers.

Map of the codebase

• bin/inspector.js — Entry point for the Node Inspector server; initializes the debugger backend and WebSocket protocol handler.
• bin/node-debug.js — CLI wrapper that launches Node.js with debugging enabled and opens the inspector UI in the browser.
• front-end-node/NodeInspectorOverrides.js — Core integration layer that bridges Blink DevTools frontend with Node.js debugging protocol.
• front-end-node/protocol.json — Protocol definition mapping Node.js debugging capabilities to Chrome DevTools protocol for frontend communication.
• front-end-node/inspector.json — Configuration file defining enabled modules, overrides, and frontend behavior for Node.js-specific inspector UI.
• front-end-node/sources/SourcesOverrides.js — Customizations to the Sources panel for Node.js source code debugging and breakpoint management.
• docs/embedding.md — Documents how to embed Node Inspector programmatically into applications.

Components & responsibilities

• bin/inspector.js (Inspector Server) (Node.js, WebSocket, V8 Debug Protocol) — Bootstraps the debug server, establishes WebSocket listener, routes protocol messages between browser frontend and Node.js debugger, manages breakpoints and variable inspection.
  • Failure mode: If server crashes, debugging session terminates; frontend loses connection and cannot inspect target process state.
• bin/node-debug.js (CLI Launcher) (Node.js child_process, HTTP client) — Spawns target Node.js process with debugging enabled, starts inspector server, opens browser window pointing to inspector UI.
  • Failure mode: If launcher fails, target process may start without debugging enabled or browser may not open; user must manually start components.
• front-end-node/ (Frontend UI) (Blink DevTools, HTML/CSS/JavaScript, WebSocket client) — Renders Blink DevTools with Node.js-specific customizations; displays source code, call stacks, variables, console output; allows user to set breakpoints and step through code.
  • Failure mode: UI rendering issues prevent user from viewing debugger state or interacting with controls; WebSocket disconnection prevents live updates.
• Protocol Handler (front-end-node/protocol.json) (V8 Debug Protocol, Chrome DevTools Protocol) — Maps Node.js V8 debug protocol events and commands to Chrome DevTools protocol equivalents; translates between two protocol formats.
  • Failure mode: Incorrect mapping may cause UI to display stale or incorrect variable values, or breakpoints to be set at wrong locations.

Data flow

• Developer (Browser UI) → bin/inspector.js (WebSocket) — undefined

How to make changes

Add a Node.js debugging feature to the Frontend

1. Create an override module in front-end-node/{panel}/ (e.g., front-end-node/custom/) (front-end-node/custom/CustomOverrides.js)
2. Add a module.json to register the override with the inspector (front-end-node/custom/module.json)
3. Update the protocol.json to expose new Node.js-specific protocol methods if needed (front-end-node/protocol.json)
4. Register the module in the top-level inspector.json configuration (front-end-node/inspector.json)

Add a new CLI command or debugging mode

1. Create a new bin script following the pattern of inspector.js or node-debug.js (bin/my-command.js)
2. Implement the server initialization and protocol handling in the script (bin/my-command.js)
3. Add the command to npm scripts in package.json and export from bin directory (bin/my-command.js)

Customize the Sources or Network panel for Node.js

1. Create or edit the panel override file in front-end-node/{panel}/ (front-end-node/sources/SourcesOverrides.js)
2. Add Node-specific properties or behavior by extending the base Blink panel (front-end-node/sources/SourcesOverrides.js)
3. Ensure the override is registered in the corresponding module.json (front-end-node/sources/module.json)

Why these technologies

• Blink DevTools (Chrome DevTools) — Provides a mature, familiar debugging UI that developers already use in Chrome; reduces need to build a custom interface from scratch.
• WebSocket protocol — Enables real-time bidirectional communication between the Node.js backend server and the browser-based frontend for live debugging updates.
• Node.js Debug Protocol — Standard protocol for communicating with Node.js V8 debugger; allows Node Inspector to read stack frames, variables, and inject breakpoints.
• Node.js as runtime — Debugger target; Node Inspector runs as a separate Node process that proxies commands to the debugged application.

Trade-offs already made

• Use Blink DevTools frontend instead of building a custom UI

  • Why: Leverage existing, battle-tested debugging interface with minimal development overhead.
  • Consequence: Tight coupling to Blink DevTools codebase; harder to implement Node-specific features that don't map to Chrome DevTools paradigms.

• Separate server process (bin/inspector.js) rather than in-process debugging

  • Why: Avoids instrumenting the target Node process directly; server remains independent and can debug multiple processes.
  • Consequence: Additional network hop and potential latency; requires WebSocket communication overhead.

• Override-based architecture for Node-specific features

  • Why: Allows reuse of Blink DevTools modules while selectively customizing behavior for Node.js.
  • Consequence: Frontend complexity increases when features require deep overrides; maintainability risk if Blink DevTools structure changes.

Non-goals (don't propose these)

• Does not provide built-in profiling; relies on Node.js profiler APIs exposed via protocol.
• Does not replace Node's built-in debugger (as of Node.js 6.3+); Node Inspector is deprecated in favor of Node's native DevTools integration.
• Does not support remote debugging over the internet out-of-the-box; requires manual SSH tunneling or firewall configuration.
• Does not handle authentication or multi-user debugging sessions; assumes single developer per inspector instance.

Traps & gotchas

Chrome/Opera browser requirement: debugger UI only works in Chrome and Opera, not Firefox/Safari/IE (noted in README). DevTools protocol version matching: the front-end must match the Node.js version's debugging protocol support, which can break across Node.js versions. No indication of package.json in the file list, so npm dependency management details are hidden. Possible requirement for Node.js versions < 6.3 to avoid built-in debugger conflicts.

Architecture

Concepts to learn

• Chrome DevTools Protocol (CDP) — Node Inspector is entirely built on translating Node.js's debugging agent into CDP commands; understanding the protocol is essential to modifying how the debugger communicates.
• WebSocket bidirectional communication — Node Inspector uses WebSockets to maintain a persistent connection between the Node.js debugger agent and the browser DevTools UI; critical for real-time breakpoint and stack updates.
• Source mapping and transpilation — Node Inspector must handle source maps to display original TypeScript/ES6+ code when debugging minified or transpiled JavaScript; visible in the Sources panel override logic.
• V8 Inspector Protocol — Node.js exposes debugging via V8's inspector protocol; Node Inspector translates between V8 Inspector and Chrome DevTools Protocol to bridge the gap.
• Module and panel overrides pattern — Node Inspector extends Blink DevTools by selectively overriding specific modules (console, sources, profiler) defined in module.json; this pattern is crucial for adapting browser tools to Node.js.
• Blink rendering engine integration — The /front-end and /front-end-node directories contain Blink/Chromium DevTools UI assets; understanding Blink's module system and CSS architecture is needed to modify the debugger UI.

Related repos

• nodejs/node — The upstream Node.js project that now includes the built-in DevTools-based debugger that deprecates Node Inspector; Node Inspector patches against Node.js debugging protocol.
• node-forward/readable-stream — Likely used by Node Inspector's server code for handling WebSocket streams and protocol communication between Node and browser.
• ChromeDevTools/devtools-frontend — The upstream Blink DevTools repository from which Node Inspector's /front-end directory is derived and must track for UI updates.
• TooTallNate/node-gyp — May be used in Node Inspector's build chain if native C++ bindings are required for low-level Node.js introspection.
• thlorenz/docDiff — Alternative lightweight Node.js debugging tool in the Node ecosystem for comparison of similar debugging problems.

PR ideas

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for front-end-node protocol overrides

The front-end-node directory contains multiple protocol override files (NodeInspectorOverrides.js, ConsoleExtentions.js, SourcesOverrides.js, SaveOverrides.js, MainOverrides.js, NetworkPanel.js) but there is no visible test directory in the repo structure. These overrides are critical to the debugging experience and should have unit tests to prevent regressions when updating the Blink DevTools base.

• [ ] Create a test/ directory structure mirroring front-end-node/
• [ ] Add unit tests for front-end-node/NodeInspectorOverrides.js covering protocol message handling
• [ ] Add tests for front-end-node/console/ConsoleExtentions.js for console-specific functionality
• [ ] Add tests for front-end-node/sources/SourcesOverrides.js for source code debugging features
• [ ] Update .jshintignore and .npmignore to exclude test files appropriately
• [ ] Configure .travis.yml to run the new test suite

Create integration tests for bin/ executable scripts with various Node.js versions

The bin/ directory contains three entry points (inspector.js, node-debug.js, run-repl.js) that users directly interact with, but there's no evidence of integration tests validating they work across different Node.js versions. This is critical since the README mentions Node.js 6.3+ provides built-in debugging, so compatibility testing is essential.

• [ ] Create test/integration/ directory for end-to-end tests
• [ ] Add test script that spawns node-inspector via bin/inspector.js and verifies WebSocket server starts
• [ ] Add test script for bin/node-debug.js validating it launches a debugger session
• [ ] Add test script for bin/run-repl.js validating REPL initialization
• [ ] Update .travis.yml to test against multiple Node.js versions (0.10, 0.12, 4.x, 6.x, etc.)
• [ ] Document in CONTRIBUTING.md how to run integration tests locally

Add missing documentation for front-end customization and protocol.json structure

The front-end-node directory contains protocol.json and multiple module.json files (console/module.json, profiler/module.json, sources/module.json, etc.) but these configuration formats are not documented in docs/. New contributors cannot understand how to add new debugging panels or extend the UI without reverse-engineering the existing code.

• [ ] Create docs/front-end-architecture.md explaining the front-end-node directory structure
• [ ] Document the protocol.json schema with examples from front-end-node/protocol.json
• [ ] Document module.json format with examples from console/module.json, profiler/module.json, etc.
• [ ] Add section explaining how to add a new debugging panel (reference: front-end-node/network/NetworkPanel.js)
• [ ] Document the override system (NodeInspectorOverrides.js pattern) and when to use it
• [ ] Update CONTRIBUTING.md with a link to this new architecture documentation

Good first issues

• Add missing test suite for front-end-node/console/ConsoleExtentions.js: the file exists but no test files are visible in the file list, making it a good target for contribution of console feature regression tests.
• Document the DevTools protocol.json schema: front-end-node/protocol.json appears to be machine-readable but lacks inline comments or a companion markdown explaining which Node.js versions support which debugging features.
• Create Windows batch file equivalents for /bin scripts: the file list shows shell scripts (.js and .sh files) but no .bat or .cmd files, leaving Windows developers with PowerShell-only access to node-debug and inspector.

Top contributors

• @3y3 — 61 commits
• @hustxiaoc — 13 commits
• @bajtos — 5 commits
• @淘杰 — 2 commits
• @sparkleholic — 2 commits

Recent commits

• 79e01c0 — v1.1.2 (taojie.hjp)
• ff35e8a — fix: ui messed up (#1034) (hustxiaoc)
• fd4e852 — Allow "blob:" sources for scripts in Content-Security-Policy header (#1017) (andrew8er)
• af15e8d — Fixed typo: buit > built (#1018) (gknapp)
• 0ce3a01 — 1.1.1 (淘杰)
• 12cfcad — fix: press enter doesn't work in console (#1006) (hustxiaoc)
• 72b8653 — fix: make it work with mac (#1003) (hustxiaoc)
• 624e691 — 1.1.0 (淘杰)
• 339c4a5 — doc: add doc of how to debug remote machine (#1002) (hustxiaoc)
• e90da5b — Revert "Revert "Implement the remote debugging feature."" (#1001) (hustxiaoc)

Security observations

Node Inspector presents moderate to high security concerns primarily due to: (1) missing dependency analysis preventing identification of vulnerable npm packages, (2) inherent risks of exposing a debugging interface over the network without adequate security controls, (3) potential XSS vulnerabilities in frontend code processing untrusted data, (4) deprecated project status with likely limited security maintenance, and (5) absence of security documentation and responsible disclosure processes. The project requires immediate attention to authentication/authorization mechanisms for the debugger, comprehensive input validation across all components, dependency vulnerability scanning, and migration planning to Node.js built-in debugger. Recommend treating this as a deprecated tool and phasing it out in favor of maintained alternatives.

• High · Missing Dependency Information — package.json (not provided). The package.json or dependencies file was not provided for analysis. This prevents assessment of known vulnerable dependencies, outdated packages, and supply chain risks. Node Inspector relies on multiple npm dependencies that could contain security vulnerabilities. Fix: Provide package.json and run 'npm audit' to identify vulnerable dependencies. Implement automated dependency scanning in CI/CD pipeline using tools like Snyk or npm audit.
• Medium · Debugger Network Exposure Risk — bin/inspector.js, bin/node-debug.js. Node Inspector exposes a debugging interface over HTTP/WebSocket. The README indicates it provides a web-based debugger interface. Without proper authentication and network isolation, this could allow remote code execution if the debugger is exposed to untrusted networks. Fix: Implement strong authentication mechanisms, restrict debugger access to localhost by default, use TLS/SSL for all debugger communications, and document secure deployment practices. Never expose debugger ports to public networks.
• Medium · Frontend Code Injection Potential — front-end-node/*.js, front-end-node/*/*.js. The front-end contains multiple JavaScript override files (NodeInspectorOverrides.js, MainOverrides.js, SourcesOverrides.js, etc.) that manipulate the Developer Tools UI. If these files process user-supplied input or debug target data without proper sanitization, they could be vulnerable to XSS attacks. Fix: Ensure all user input and data from debug targets is properly sanitized before being rendered in the UI. Use Content Security Policy (CSP) headers, avoid dangerouslySetInnerHTML patterns, and implement input validation.
• Medium · Protocol Configuration Not Analyzed — front-end-node/protocol.json. The protocol.json file defines the debugging protocol. Without reviewing its contents, there's potential risk of implementing insecure protocol handlers, insufficient validation of protocol messages, or exposure of sensitive debugging information. Fix: Review protocol.json for security-sensitive operations. Implement strict validation of all protocol messages, implement rate limiting on debug commands, and ensure sensitive data (source code, memory contents) is handled securely.
• Low · Outdated Project Status — README.md. According to the README snippet, Node Inspector has been largely deprecated since Node.js 6.3 introduced built-in DevTools-based debugging. Using deprecated software increases security risks due to lack of security updates and patches. Fix: Consider migrating to Node.js built-in DevTools debugger. If continuing to use Node Inspector, ensure regular security audits and maintenance. Monitor for security advisories specific to this deprecated tool.
• Low · Missing Security Documentation — Repository root. No security policy, security.md, or SECURITY.txt file is visible in the repository structure. This makes it difficult for security researchers to report vulnerabilities responsibly. Fix: Create a SECURITY.md file documenting how to report security vulnerabilities responsibly. Include contact information and expected response timeframes for security issues.
• Low · Lack of Input Validation Documentation — bin/inspector.js, bin/node-debug.js, bin/run-repl.js. The binary entry points (inspector.js, node-debug.js, run-repl.js) accept command-line arguments and potentially process debug target input without visible validation documentation or security guidelines. Fix: Implement and document strict input validation for all entry points. Sanitize command-line arguments, file paths, and data from debug targets. Include security guidelines in documentation.

LLM-derived; treat as a starting point, not a security audit.

Where to read next

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

---

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.