N|Solid plugin for AI coding agents

The N|Solid plugin adds NodeSource skills and MCP servers to AI coding agents such as Claude Code and Codex CLI. After you install it and sign in, your agent can pull live data from N|Solid Console, capture and analyze CPU profiles and heap snapshots, audit dependencies with NodeSource Certified Modules (NCM), and benchmark code. It does all of this from the terminal where you already work.

The plugin is open source: nodesource/nsolid-plugin on GitHub.

tip

Using Visual Studio Code? The N|Solid IDE extension sets up the same kind of skills and MCP servers for your workspace when you click Install Toolkit. Use the plugin for terminal-based agents.

What's included

• Skills: 18 step-by-step workflows for Node.js performance, memory, tracing, security, and dependency work. See Skills.

• Three MCP servers:

  MCP server	What it provides
  nsolid-console	Live data from your N|Solid Console: applications, processes, metrics, events, traces, assets, and vulnerabilities. Also used to capture new CPU profiles and heap snapshots. See N|Solid Console MCP integration.
  ns-benchmark	Runs Node.js benchmarks and compares results.
  ncm	NodeSource Certified Modules package data: vulnerabilities, quality, and version information.

• The nsolid-plugin CLI, which signs you in to NodeSource and installs, checks, and repairs the plugin.

Supported agents

Agent	How the plugin is installed	--harness value
Claude Code	Native plugin from the NodeSource marketplace	claude
Codex CLI	Native plugin from the NodeSource marketplace	codex
Antigravity CLI	Native plugin from the GitHub repository	antigravity
OpenCode	Installed directly by the nsolid-plugin CLI	opencode
Pi Agent	npm package nsolid-pi-plugin, plus an MCP adapter	pi

The nsolid-plugin CLI calls each supported agent a harness; the --harness option selects which one a command applies to.

Requirements

• Node.js 22.3.0 or later.
• The CLI for the agent you use.
• A NodeSource account with the owner or admin role (or a role with the people permission) in your N|Solid organization. Sign-in lists and creates organization service tokens. If you don't have an account, see Sign up.
• Network access to npm the first time you run setup.

Install the CLI

Install the nsolid-plugin CLI globally:

npm install -g nsolid-plugin

Or run any command without installing it, using npx:

npx -y nsolid-plugin setup --harness <harness>

The examples on this page use the global command. Replace nsolid-plugin with npx -y nsolid-plugin if you didn't install it.

Install the plugin

Installation has two steps: install the plugin into your agent, then run nsolid-plugin setup to sign in. Installing the plugin never opens a browser or signs you in; only setup and switch-org do.

Claude Code

claude plugin marketplace add NodeSource/nsolid-plugin
claude plugin install nsolid-plugin@nodesource
nsolid-plugin setup --harness claude

Codex CLI

codex plugin marketplace add NodeSource/nsolid-plugin
codex plugin add nsolid-plugin@nodesource
nsolid-plugin setup --harness codex

Antigravity CLI

agy plugin install https://github.com/NodeSource/nsolid-plugin.git
nsolid-plugin setup --harness antigravity

OpenCode

OpenCode doesn't use the native plugin. The setup command signs you in and installs everything in one step:

nsolid-plugin setup --harness opencode

Skills are copied to ~/.config/opencode/skills/, and the MCP servers are added under the mcp key in ~/.config/opencode/opencode.jsonc. To refresh that configuration later, run nsolid-plugin install --harness opencode.

Pi Agent

Pi Agent gets its skills from an npm package, and it needs an adapter to use MCP servers:

pi install npm:nsolid-pi-plugin
nsolid-plugin setup --harness pi
pi install npm:pi-mcp-adapter

setup writes the MCP configuration to ~/.pi/agent/mcp.json, which pi-mcp-adapter reads automatically.

note

The alternative @0xkobold/pi-mcp adapter reads a different file (~/.0xkobold/mcp.json) in a different format, so it doesn't pick up the N|Solid configuration. Use pi-mcp-adapter.

Sign in

nsolid-plugin setup --harness <harness> signs you in to NodeSource:

1. Your browser opens the NodeSource Accounts sign-in page. If you belong to more than one organization, choose the one to use.
2. The CLI receives your credentials on a local callback server on port 8765. If that port is in use, it tries ports 8766 to 8770.
3. The CLI saves your credentials and sets up the MCP connection for your organization.

If a browser can't open (for example, in a dev container or over SSH), the CLI prints the sign-in URL. Open it in any browser to finish. The URL doesn't contain any tokens.

The first setup also downloads a small MCP bridge runtime to ~/.agents/nsolid-plugin/runtime/, so your agent can start the MCP servers without calling npm later. Later runs reuse it and work offline.

You're signed in to one NodeSource organization at a time, and the sign-in is shared by every agent you install the plugin into.

Where credentials are stored

• Your NodeSource credentials, including a service token, are saved in ~/.agents/.nodesource-auth.json, readable only by your user.
• For OpenCode, Pi Agent, and installs done with nsolid-plugin install, the service token is also written in plain text into the agent's own MCP configuration file (for example, ~/.config/opencode/opencode.jsonc or ~/.pi/agent/mcp.json).

warning

Treat these files as secrets. Don't commit them or copy them into shared dotfiles repositories. nsolid-plugin logout removes only the shared credentials file. Tokens already copied into agent configuration files stay valid until they expire. To remove those copies, run nsolid-plugin uninstall --harness <harness>.

The nsolid-console MCP server uses the permissions of the NODESOURCE_EXTENSION service token that sign-in creates for your organization (or reuses if it already exists). The N|Solid IDE extension shares this token. To limit what agents can do, edit that token's permissions under Service Tokens in NodeSource Accounts. See Tools and required permissions.

Verify the installation

nsolid-plugin doctor --harness <harness>

doctor reports the status of your credentials, skills, MCP servers, and the MCP bridge runtime. Add --json for machine-readable output.

In Claude Code, Codex CLI, OpenCode, and Antigravity CLI, you can also run /skills and /mcp inside the agent and look for the N|Solid entries. In Pi Agent, run pi list and check that nsolid-pi-plugin and pi-mcp-adapter are listed.

Use the plugin

You don't need special syntax. Describe the problem, and the agent picks the matching skill. For example:

• "My checkout-service app's memory keeps growing. Find the leak."
• "Why is CPU high on the api processes right now?"
• "Analyze asset <asset-id>."
• "Audit this project's dependencies for vulnerabilities."
• "Upgrade express to the latest version and tell me what breaks."
• "Is this function faster after my change? Prove it with a benchmark."

Skills that capture new diagnostics, such as CPU profiles or heap snapshots, run against processes connected to your N|Solid Console. Skills that work with existing evidence reuse asset IDs, event payloads, or local files that you provide before capturing anything new.

Skills

Skill	What it does	MCP server
ns-cpu-spike-analysis	Diagnoses high CPU, slow endpoints, and event loop blocking, using existing profiles first or capturing a new CPU profile.	nsolid-console
ns-memory-spike-analysis	Triages memory growth, heap spikes, high RSS, and out-of-memory crashes by comparing baseline and peak heap data.	nsolid-console
ns-advanced-memory-leak-hunter	Runs a deeper leak hunt when standard memory analysis is inconclusive, isolating retained objects, closures, and retainer paths.	nsolid-console
ns-analyze-event	Investigates an N|Solid event (for example, a blocked process, an agent exit, or a new vulnerability) and correlates related evidence.	nsolid-console
ns-analyze-tracing	Analyzes distributed traces for request latency, HTTP errors, and slow downstream dependencies.	nsolid-console
ns-analyze-vulnerabilities	Reports the vulnerabilities actually loaded in your running processes.	nsolid-console
ns-analyze-asset	Summarizes and interprets an existing CPU profile, heap profile, heap sample, or heap snapshot.	nsolid-console
ns-generate-asset	Captures a new CPU profile, heap sample, or heap snapshot from a connected process.	nsolid-console
ns-download-asset	Downloads a raw asset to disk for use in other tools, such as Chrome DevTools.	nsolid-console
ns-audit-dependencies	Audits a local project's dependency tree for vulnerabilities and quality issues, with a remediation plan.	ncm
ns-upgrade-package	Plans an upgrade of one npm package, including breaking changes and peer dependency risk.	ncm
ns-replace-package	Finds and compares alternatives to a deprecated, abandoned, or risky npm package.	ncm
ns-node-upgrade	Plans a Node.js runtime upgrade, with LTS and end-of-life guidance and dependency compatibility checks.	ncm
ns-generate-sbom	Generates a software bill of materials (SBOM) for an application connected to your N|Solid Console.	nsolid-console
ns-benchmark-run	Benchmarks a single function and reports throughput statistics.	ns-benchmark
ns-validate-optimization	Proves or disproves a performance change with a controlled A/B benchmark.	ns-benchmark
ns-optimize-function	Proposes a behavior-preserving optimization of a function you choose, then validates it with benchmarks. Needs the function's source in your workspace.	ns-benchmark
ns-switch-org	Switches the NodeSource organization the plugin is signed in to.	—

ns-analyze-vulnerabilities looks at what's running in production. ns-audit-dependencies checks a project's declared dependencies, like npm audit.

Switch organizations

If your account belongs to more than one NodeSource organization, switch with:

nsolid-plugin switch-org --harness <harness>

This opens the NodeSource sign-in page again so you can pick a different organization. You can also ask your agent to switch organizations; it uses the ns-switch-org skill.

The new organization applies to every agent that has the plugin installed:

• The agent you pass to --harness is updated right away. For Claude Code, Codex CLI, and Antigravity CLI, reconnect the MCP servers (or restart the agent) to pick up the change.
• Other agents configured by the CLI (OpenCode, Pi Agent, and install fallback installs) pick up the new organization the next time you run setup or install for them.

CLI reference

Command	What it does
nsolid-plugin setup --harness <harness>	Signs in (opens a browser if needed) and prepares the MCP bridge runtime. For OpenCode, also writes the skills and MCP configuration. For Pi Agent, also writes the MCP configuration; skills come from nsolid-pi-plugin.
nsolid-plugin install --harness <harness>	Writes the skills and MCP configuration directly into an agent. Never opens a browser. Use it for OpenCode refreshes, or as a fallback or repair for the native plugin installs. Run setup first.
nsolid-plugin doctor --harness <harness>	Checks the installation. Add --json for machine-readable output.
nsolid-plugin switch-org --harness <harness>	Signs in again to choose a different organization.
nsolid-plugin restore --harness <harness>	Restores the agent's MCP configuration from the latest automatic backup. Add --list to list backups, or --backup <path> to restore a specific one.
nsolid-plugin uninstall --harness <harness>	Removes the N|Solid skills, MCP servers, native plugin, and marketplace registration from an agent. Stored credentials are deleted when no installs remain, unless you pass --keep-credentials.
nsolid-plugin logout	Deletes the stored NodeSource credentials. Doesn't remove installed skills or configuration.

Common options:

Option	Description
--harness <harness>	The agent to act on: claude, codex, opencode, antigravity, or pi. If you leave it out in an interactive terminal, the CLI asks.
--verbose	Writes detailed, timestamped logs to stderr. Tokens are redacted. You can also set NSOLID_PLUGIN_VERBOSE=1.
--quiet	Hides step-by-step progress output.
--yes	Skips confirmation prompts.
--no-color	Disables colored output.

Troubleshooting

Start with nsolid-plugin doctor --harness <harness>. It shows what's missing and usually the command that fixes it.

"Credentials are expired" or "MCP bridge runtime is not ready". Run the setup command printed in the message, for example npx -y nsolid-plugin@<version> setup --harness claude. It's pinned to the plugin version that printed it. If the message keeps appearing after you run the pinned command, run npx -y nsolid-plugin@latest setup --harness <harness> instead. If setup reports MCP runtime setup failed, npm couldn't download the runtime: fix network or registry access and run it again. Your credentials are kept.

Sign-in port is in use. The CLI tries ports 8765 to 8770. Close the application using those ports and run setup again.

Sign-in timed out or was canceled. Run setup again. Nothing needs to be cleaned up.

Permission denied writing the agent's configuration. Make sure your user owns the agent's configuration file. On macOS and Linux, for example: sudo chown $USER ~/.claude.json.

An update broke the MCP configuration. The CLI backs up an agent's MCP configuration before every change, under ~/.agents/.config-backup/<harness>/. Run nsolid-plugin restore --harness <harness> to restore the latest backup.

Pi Agent can't use the MCP tools. Pi Agent doesn't support MCP natively. Install the adapter with pi install npm:pi-mcp-adapter.

Data from the wrong organization. Run nsolid-plugin switch-org --harness <harness> and choose the correct organization.

Uninstall

nsolid-plugin uninstall --harness <harness>

This removes the plugin's skills, MCP servers, native plugin, and marketplace registration from that agent. When you uninstall from the last agent, the stored credentials are deleted too; pass --keep-credentials to keep them. For Pi Agent, also remove the package with Pi's own tools.