tensorViz coding-agent plugin — reference

For the short walkthrough, see the user guide. This page covers locally built source-development archives. Published plugin installation is in the user guide.

Contents

• Requirements
• Install
• Permissions
• Model graph panel
• What the plugin runs
• Build

The plugin lets Claude Code, Codex, or Cursor open a local PyTorch model, capture one forward pass, and read the graph. It is the same product as the VS Code extension, in a different host. Current versions: extension 0.1.36, plugin host 0.3.61.

Package	Source	What you install
Coding-agent plugin	plugin/ and plugins/tensorviz/	A local archive built from this repo, or the plugin directory after that build
VS Code extension	extension/	A VSIX. See the quickstart

Both display as tensorViz. The plugin id used by the Codex installer is tensorviz@tensorviz-standalone. The extension id is tensorviz.tensorviz-vscode. Those ids are stable. Renaming one would install a second copy.

Use one TensorViz host per agent. The plugin has its own stdio MCP server. The extension has a separate loopback HTTP endpoint, documented in MCP. Do not point the same agent at both.

The VS Code extension is optional. It is not required to run the plugin, and the plugin does not install the extension.

Requirements

• Node.js on the agent's PATH. The version is in the versions table.
• A Python that meets the tool-service minimum in that same table. Capture uses a project environment you select, with that model's dependencies.
• A local model project. tensorViz does not ask for its own provider API key. Your coding client's account still applies.

Build the host before you install it. This repository does not publish a compiled runtime or a marketplace release. See Plugin build.

Install

For Codex, use the built tensorviz-<version>.tar.gz source-development archive:

1. Check the archive against its .sha256 file.
2. Extract it into a directory you will keep. Keep the previous extract if you want a rollback copy.
3. From your model checkout, run the archive's installer:

sh /path/to/tensorviz/plugins/tensorviz/scripts/install.sh

Without an interactive terminal, applying changes requires an explicit host choice:

sh /path/to/tensorviz/plugins/tensorviz/scripts/install.sh --apply --host plugin

To keep a current connection instead, use --apply --host existing --connection NAME, using a connection name from the preflight report.

Source-built managed tool-service and CPU environments use the pinned runtimes for macOS arm64, Linux x64, and Windows x64. Capture availability follows those pins even when you select an existing model Python, because capture also needs the managed tool service. Intel macOS (darwin-x64) and Linux arm64 are unsupported for capture. These pins describe runtime availability, not verified end-to-end support: live Windows and macOS runs remain untested for these changes.

Source-package MCP manifests invoke node scripts/launch.cjs directly, without a Unix shell. On Windows, run the installer with node "C:\path to\tensorviz\plugins\tensorviz\scripts\install.cjs" --apply --host plugin. Node.js 22+ must be on the coding client's PATH. The published compiled preview uses a separate Darwin-arm64-only launcher (plugin/integration/launch.sh); it does not provide Windows, Linux, or Intel macOS capture.

The installer needs the Node.js version in the versions table. It refuses to run against a bare git checkout that has not been packaged, because the packaged host is not in plugins/tensorviz/ until you build. A preflight without changes:

node /path/to/tensorviz/plugins/tensorviz/scripts/install.cjs

Installation is for that agent's user profile on this machine, not inside the model repo. Start a new chat afterward. An existing chat keeps the tools it already loaded.

The guided installer configures Codex only. For Claude Code, register the extracted archive root and install the plugin explicitly:

claude plugin marketplace add /absolute/path/to/extracted-archive
claude plugin install tensorviz@tensorviz-standalone --scope user

The plugin folder alone is not the marketplace catalog.

If an older TensorViz connection is already enabled, choose Use the tensorViz plugin in the guided installer. It disables matching user-owned connections and keeps a recovery receipt. A manual entry named exactly tensorviz is moved to a disabled name such as tensorviz-previous, because Codex can hide plugin tools while that exact name exists. Unrelated connections are left alone. Project-owned MCP settings are reported, not overwritten.

Cursor local archive

The Cursor archive cannot use the Codex guided installer. Verify its checksum, then extract tensorviz-cursor-<version>.tar.gz into a directory you will keep:

tar -xzf tensorviz-cursor-<version>.tar.gz -C /absolute/path/to/install

Add this entry to Cursor's MCP configuration (~/.cursor/mcp.json), merging it with any existing servers:

{
  "mcpServers": {
    "tensorviz": {
      "command": "node",
      "args": ["/absolute/path/to/install/tensorviz-cursor-<version>/plugins/tensorviz/scripts/launch.cjs"]
    }
  }
}

Use the actual extracted directory and version. This absolute path replaces ${CURSOR_PLUGIN_ROOT} in the archive's plugins/tensorviz/mcp.json; that placeholder denotes the plugins/tensorviz directory when Cursor loads a plugin and is not automatically available in a manual MCP entry. Node.js 22+ must be on Cursor's PATH. Restart Cursor and check that TensorViz tools appear. Keep one TensorViz host enabled. The archive README includes the same steps.

For a local archive, use this MCP configuration; cursor-agent plugin marketplace add <path> treats the path as a git remote. Cursor can also use the source-built editor VSIX and Connect coding agent (MCP); see plugin build.

Permissions

The installer asks once. Accepting covers local project reads, Python inspection, model and setup execution, saving tensorviz.toml, and installing reviewed dependencies into the selected environment. It applies to this OS user, across projects. Model code runs with your user permissions. Graph text returned to the agent can become part of that client's conversation.

The Codex setting the installer writes is only:

[plugins."tensorviz@tensorviz-standalone".mcp_servers.tensorviz]
default_tools_approval_mode = "approve"

Other plugins, global approval settings, and per-tool overrides stay as they were. Organization policy still wins. The installer reports a policy it cannot change.

Status and revocation, from the installed plugin:

node /path/to/tensorviz/plugins/tensorviz/scripts/permissions.cjs --status
node /path/to/tensorviz/plugins/tensorviz/scripts/permissions.cjs --revoke

Revoke stops later execution and setup. It does not kill a worker that is already running. Read-only views of a graph you already captured stay available. A declined decision is remembered, so the plugin stops instead of asking on every call. open_graph can return action: request_permission; that asks again, and it cannot grant permission by itself.

The consent file is permissions/standalone.json under the user data directory from applicationData() in plugin/src/environment.ts:

Platform	Directory
macOS	~/Library/Application Support/TensorViz/standalone
Windows	%LOCALAPPDATA%\TensorViz\standalone
Linux	$XDG_DATA_HOME/tensorviz/standalone, or ~/.local/share/tensorviz/standalone when XDG_DATA_HOME is unset

It is separate from the project and from the plugin install. Uninstalling the plugin does not delete the consent file. Revoke it explicitly.

Unknown inputs and interpreter choices still need an answer when the project does not resolve them. Consent does not start a model on its own, and it does not replace an installed Torch or CUDA build.

Model graph panel

After the plugin is connected, ask the agent to open the Model graph panel with open_graph_panel, or use the client's plugin view if it has one. An empty panel does not start Python. Ask the agent to open_graph on the model you want. The panel shows the same canvas as the plugin browser: shapes, inputs, refresh, and local graph review.

open_graph_panel returning does not prove the panel drew the graph. A current view from list_models, after the canvas reports a render, is what shows that the panel is up. Clients without that panel use open_graph_view and a local browser page.

Closing the panel does not cancel a capture or edit source. Reopen Model graph if the panel disconnects; the capture is kept. Up to eight panels can attach to one plugin process. A panel with no traffic expires after five minutes.

The panel and the browser talk to the local Node host. They do not receive the loopback credential, and they cannot grant execution permission.

What the plugin runs

The plugin service is backend/standalone_server.py. It binds 127.0.0.1 on a free port, requires a launch token, and does not bind 0.0.0.0. The browser only accepts that loopback host. The shared backend (start.sh, backend/server_v2.py) also defaults to 127.0.0.1 and refuses a non-loopback bind unless TENSORVIZ_LOCAL_TOKEN is set. AUTH_DISABLED does not allow that bind. See service bind.

Capture uses the project Python you select. The tool service can use a separate interpreter. Changing the capture environment does not restart the service. See environment recovery.

Saved tensorviz.toml recipes are reused. Missing setup is asked for, or the agent can fill it through open_graph. Inspect source only does not execute the model. After you save a source edit, refresh the graph to capture again.

Build

npm run build --prefix plugin
npm run build:browser --prefix plugin
npm run build:panel --prefix plugin
npm run package:source-development --prefix plugin

npm run package:source-development --prefix plugin writes plugin/dist/tensorviz-<version>.tar.gz and plugin/dist/tensorviz-cursor-<version>.tar.gz, each with a .sha256 file. Details, including the tldraw key and what this repo does not publish, are in Plugin build.