# Reference

Generated from `extension/package.json`, MCP `registerTool` / `registerAppTool` calls, and the validation contracts. Do not edit this file by hand. Run `python3 tooling/docs/generate_reference.py`.

Product versions in this tree: extension `0.1.36`, plugin host `0.3.61`, VS Code engine `^1.106.0`. Development targets and Python minima: [versions](/local-setup.html#versions).

## Contents

- [Extension settings](#extension-settings)
- [Commands](#commands)
- [MCP tools](#mcp-tools)
- [tensorviz.toml](#tensorviztoml)
- [Source directives](#source-directives)

## Extension settings

18 keys under `contributes.configuration.properties`. `tensorviz.graphSurface` is deprecated. Save validation and execution caching are enabled by default.

| Setting | Type | Default | Scope | Notes |
| --- | --- | --- | --- | --- |
| `tensorviz.agent.claudeAcpPath` | string | `""` | machine | Absolute executable path for the optional ACP pipeline. Tested adapter: `@agentclientprotocol/claude-agent-acp@0.99.0`. Uses the existing signed-in agent; no... |
| `tensorviz.agent.claudePath` | string | `""` | machine | Optional absolute path to the Claude Code executable for Canvas chat. Empty uses the workspace host's PATH and standard installation locations. Sign in to th... |
| `tensorviz.agent.codexAcpPath` | string | `""` | machine | Absolute executable path for the optional ACP pipeline. Tested adapter: `@agentclientprotocol/codex-acp@2.3.0`. Uses the existing signed-in agent; no provide... |
| `tensorviz.agent.codexPath` | string | `""` | machine | Optional absolute path to the Codex executable for Canvas chat. Empty uses the workspace host's PATH and standard installation locations. Sign in to the inst... |
| `tensorviz.agent.pipeline` | string | `native` | machine | enum: `native`, `acp`. Canvas chat runtime. Native keeps the existing CLI bridge; ACP uses persistent Agent Client Protocol sessions. Set adapter paths and s... |
| `tensorviz.autoOpenCanvas` | boolean | `true` | window | Open the sidebar Canvas initially when a Python model or project is found. Only tensorViz IDE enables this implicitly; stock VS Code requires an explicit set... |
| `tensorviz.codeFocus` | object | `{"enabled":false,"scope":"node","references":"both","opacity":25}` | — | Dim code outside selected Canvas nodes. Configure **Model / class**, **Function**, or **Node / expression**, parameter declarations/uses, and opacity from **... |
| `tensorviz.devServerUrl` | string | `""` | machine-overridable | Load the canvas from this URL instead of the app bundled with the extension — for developing the frontend against a live `npm start`. When empty (the default... |
| `tensorviz.executionCache.maxSizeMB` | number | `96` | machine-overridable | Memory limit, in megabytes, for results kept by `#tensorviz.executionCache.mode#` in this window (at most 32 results, 16 MB each). The least recently used re... |
| `tensorviz.executionCache.mode` | string | `on` | machine-overridable | enum: `off`, `shadow`, `on`. Reuse of identical runs (on by default; set `off` to always run). A Run can reuse an earlier identical result only with the same... |
| `tensorviz.followEditor` | boolean | `true` | — | Move the project canvas to the file you open, and open its node. Turn this off to leave the camera where you put it; the canvas still follows when you click... |
| `tensorviz.graphSurface` | string | `sidebar` | window | enum: `sidebar`, `browser`, `editor`. Open as Graph always uses the persistent sidebar Canvas. Use **tensorViz: Open Canvas in Browser** for the selected mod... |
| `tensorviz.mcpPort` | integer | `0` | application | Local MCP port shared by all tensorViz windows. Zero automatically chooses an available port and reuses it while available. Set a number to require a fixed p... |
| `tensorviz.pythonPath` | string | `""` | machine-overridable | Absolute Python path offered in the environment picker and used for model execution when this workspace folder has no saved choice. Use tensorViz: Select Pyt... |
| `tensorviz.repoPath` | string | `""` | machine-overridable | **Developer override.** Absolute path to a canvas checkout, used as the backend source instead of the one tensorViz ships with. You do not need this: the bac... |
| `tensorviz.showGraphPrompt` | boolean | `true` | application | Show an Open as Graph notification when the active saved Python file contains a discovered PyTorch model. Each file is offered once per VS Code window sessio... |
| `tensorviz.traceOnSave` | boolean | `true` | resource | Validate the selected model after saving changed model code or a known Python dependency. Rapid saves are combined; validation uses the saved inputs, device... |
| `tensorviz.traceTier` | string | `real` | resource | enum: `real`, `fake`, `auto`. How the trace worker runs your model when it captures a graph without a saved profile. `real` (default) uses real tensors, so d... |

`tensorviz.mcpPort` allows 0 through 65535. Zero chooses an available port. `tensorviz.codeFocus.opacity` allows 10 through 60.

Saving relevant model or dependency changes schedules validation in the selected model environment. Changes invalidate the previous result first; rapid saves are coalesced and superseded runs are cancelled. Set `tensorviz.traceOnSave` to `false` to retain source refresh with manual execution. `tensorviz.traceTier` accepts only `real` and `fake`; automatic tier selection is unavailable.

`tensorviz.agent.pipeline` defaults to `native`, the existing CLI bridge. Select `acp` and configure an absolute adapter path with `tensorviz.agent.codexAcpPath` or `tensorviz.agent.claudeAcpPath` to use persistent ACP sessions. Start a new chat after switching. Adapter paths are restricted machine settings; Send never installs an adapter. The extension uses the signed-in agent account, and Canvas receives no provider key.

## Commands

Palette titles use the category `tensorViz` plus the title, for example **tensorViz: Open as Graph**. Two commands can share a title and differ by id.

| Command | Title | Category |
| --- | --- | --- |
| `tensorviz.signInToWebsite` | Sign in to tensorViz | tensorViz |
| `tensorviz.signOutOfWebsite` | Sign out of tensorViz | tensorViz |
| `tensorviz.connectMcp` | Connect coding agent (MCP) | tensorViz |
| `tensorviz.forwardMcp` | Forward MCP to This Desktop | tensorViz |
| `tensorviz.disconnectMcp` | Disconnect coding agents (MCP) | tensorViz |
| `tensorviz.applySourceProposal` | Apply source change | tensorViz |
| `tensorviz.discardSourceProposal` | Discard proposal | tensorViz |
| `tensorviz.inspectSourceCandidate` | Inspect candidate result | tensorViz |
| `tensorviz.cancelSourceCandidate` | Cancel candidate run | tensorViz |
| `tensorviz.runSourceCandidate` | Run reviewed candidate | tensorViz |
| `tensorviz.openCanvas` | Open Canvas | tensorViz |
| `tensorviz.openProject` | Open Project as Graph | tensorViz |
| `tensorviz.openProjectInBrowser` | Open Canvas in Browser (Legacy Alias) | — |
| `tensorviz.openAsGraph` | Open as Graph | tensorViz |
| `tensorviz.toggleCanvas` | Toggle Canvas | tensorViz |
| `tensorviz.repairRuntime` | Repair runtime | tensorViz |
| `tensorviz.getStarted` | Get Started | tensorViz |
| `tensorviz.selectEnvironment` | Select Python Environment | tensorViz |
| `tensorviz.checkEnvironment` | Check the Python environment | tensorViz |
| `tensorviz.openHuggingFace` | Open Hugging Face model | tensorViz |
| `tensorviz.newModelFromTemplate` | New model from template | tensorViz |
| `tensorviz.refreshModels` | Refresh models | tensorViz |
| `tensorviz.clearExecutionCache` | Clear Execution Cache | tensorViz |
| `tensorviz.compareWithHead` | Graph diff against HEAD | tensorViz |
| `tensorviz.graphDiffWorking` | Graph diff | tensorViz |
| `tensorviz.graphDiffStaged` | Graph diff | tensorViz |
| `tensorviz.showSidebarCanvas` | Show Canvas | tensorViz |
| `tensorviz.hideCanvas` | Hide Canvas | tensorViz |
| `tensorviz.openCanvasInBrowser` | Open Canvas in Browser | tensorViz |
| `tensorviz.openPullRequest` | Open PR | tensorViz |
| `tensorviz.graphDiffFromEditor` | Graph diff | tensorViz |
| `tensorviz.reviewGraphChanges` | Review model changes | tensorViz |

`tensorviz.openProjectInBrowser` is hidden from the command palette (`when: false`). `tensorviz.graphDiffWorking` and `tensorviz.graphDiffStaged` are shown from Source Control, not the palette.

## MCP tools

Names below are every `registerTool` and `registerAppTool` registration under `extension/src`, `packages/graph-host/src`, and `plugin/src`, excluding tests: 45 distinct names across the hosts. Shared toolsets show both **extension** and **plugin** where registered. **canvas agent** tools use only the private in-canvas agent endpoint: source review tools from `registerCanvasCodeTools`, permission explanation tools and reviewed project diagnostic tools. They are not exposed by the standalone plugin or the external extension MCP endpoint. `configure_graph_environment` is a shared setup tool; each host retains its own environment capabilities and approval flow. **plugin panel** tools with app visibility are the panel transport; the model-workflow skill tells the agent not to call those transport tools. Behavior and arguments: [MCP tools](/mcp-tools.html).

| Tool | Registered for | Source |
| --- | --- | --- |
| `analyze_computation_change` | extension, plugin | `packages/graph-host/src/mcpCaptures.ts` |
| `cancel_proposal_candidate` | extension | `extension/src/mcpProposals.ts` |
| `cancel_run` | extension, plugin | `packages/graph-host/src/mcpValidation.ts` |
| `close_graph_panel` | plugin panel | `plugin/src/graphPanel.ts` |
| `compare_runs` | extension, plugin | `packages/graph-host/src/mcpValidation.ts` |
| `configure_graph_environment` | extension, plugin | `packages/graph-host/src/mcpGraphSetup.ts` |
| `configure_graph_setup` | extension, plugin | `packages/graph-host/src/mcpGraphSetup.ts` |
| `detach_graph_panel` | plugin panel | `plugin/src/graphPanel.ts` |
| `find_computation` | extension, plugin | `packages/graph-host/src/mcpCaptures.ts` |
| `focus_view` | extension, plugin | `packages/graph-host/src/mcpViews.ts` |
| `get_execution_environment` | extension, plugin | `packages/graph-host/src/mcpOpenGraph.ts`, `plugin/src/main.ts` |
| `get_graph` | extension, plugin | `packages/graph-host/src/mcpGraph.ts` |
| `get_graph_setup` | extension, plugin | `packages/graph-host/src/mcpGraphSetup.ts` |
| `get_machine_info` | canvas agent | `extension/src/canvasAgentProjectTools.ts` |
| `get_model_context` | extension, plugin | `packages/graph-host/src/mcpCaptures.ts` |
| `get_pending_permission` | canvas agent | `extension/src/canvasAgentPermissionTools.ts` |
| `get_project_command` | canvas agent | `extension/src/canvasAgentProjectTools.ts` |
| `get_proposal` | extension | `extension/src/mcpProposals.ts` |
| `get_run` | extension, plugin | `packages/graph-host/src/mcpValidation.ts` |
| `get_selection` | extension, plugin | `packages/graph-host/src/mcpViews.ts` |
| `graph_panel_exchange` | plugin panel | `plugin/src/graphPanel.ts` |
| `graph_panel_read` | plugin panel | `plugin/src/graphPanel.ts` |
| `inspect_applied_proposal` | extension | `extension/src/mcpProposals.ts` |
| `inspect_capture` | extension, plugin | `packages/graph-host/src/mcpCaptures.ts` |
| `inspect_nodes` | extension, plugin | `packages/graph-host/src/mcpGraph.ts` |
| `inspect_proposal_candidate` | extension | `extension/src/mcpProposals.ts` |
| `inspect_run` | extension, plugin | `packages/graph-host/src/mcpValidation.ts` |
| `list_captures` | extension, plugin | `packages/graph-host/src/mcpCaptures.ts` |
| `list_models` | extension, plugin | `packages/graph-host/src/mcpGraph.ts`, `plugin/src/main.ts` |
| `list_proposal_candidates` | extension | `extension/src/mcpProposals.ts` |
| `open_graph` | extension, plugin | `packages/graph-host/src/mcpOpenGraph.ts`, `plugin/src/main.ts` |
| `open_graph_diff` | extension, plugin | `extension/src/mcpGraphDiff.ts`, `plugin/src/main.ts` |
| `open_graph_panel` | plugin panel | `plugin/src/graphPanel.ts` |
| `open_graph_view` | extension, plugin | `packages/graph-host/src/mcpGraphView.ts`, `plugin/src/main.ts` |
| `present_permission` | canvas agent | `extension/src/canvasAgentPermissionTools.ts` |
| `propose_edit` | extension | `extension/src/mcpProposals.ts` |
| `propose_source_set` | canvas agent | `extension/src/mcpProposals.ts` |
| `query_computation` | extension, plugin | `packages/graph-host/src/mcpCaptures.ts` |
| `query_source_context` | extension | `packages/graph-host/src/mcpSourceContext.ts` |
| `read_model_source` | canvas agent | `extension/src/mcpProposals.ts` |
| `read_project_file` | canvas agent | `extension/src/canvasAgentProjectTools.ts` |
| `request_project_command` | canvas agent | `extension/src/canvasAgentProjectTools.ts` |
| `run_proposal_candidate` | extension | `extension/src/mcpProposals.ts` |
| `suggest_graph_inputs` | extension, plugin | `packages/graph-host/src/mcpGraphSetup.ts` |
| `validate_model` | extension, plugin | `packages/graph-host/src/mcpValidation.ts` |

## tensorviz.toml

`ValidationConfig` in `backend/services/validation/contracts.py` is the file. `version` is `1`. `profiles` holds 1 to 64 named profiles. Each profile is a `model` or a `script`.

| Key | Applies to | Constraint |
| --- | --- | --- |
| `version` | file | `1` |
| `profiles` | file | 1 to 64 entries |
| `kind` | profile | `model` or `script` |
| `cwd` | profile | `"."` or a path. Default `"."` |
| `tracked_files` | profile | at most 256 paths |
| `limits.timeout_ms` | profile | 100 through 86,400,000. Default 60,000 |
| `limits.max_events` | profile | 1 through 100,000. Default 10,000 |
| `limits.max_tensors` | profile | 1 through 100,000. Default 10,000 |
| `limits.max_record_bytes` | profile | at least 1,024, at most the record cap. Default is the cap |
| `limits.max_capture_bytes` | profile | optional; 1,024 through 16,777,216 |
| `model` | model | `file:symbol` |
| `framework` | model | omit for PyTorch, or `jax` |
| `mode` | model | `train` or `eval` |
| `device` | model | execution device |
| `grad_enabled` | model | boolean |
| `deterministic` | model | boolean. Default true |
| `seed` | model | optional natural number |
| `init` | model | constructor binding. Exactly one of `init` or `factory` |
| `factory` | model | `file`, `callable`, optional `kwargs` |
| `inputs` | model | a binding, or a factory |
| `script` | script | path |
| `args` | script | at most 256 strings |
| `capture` | script | `model` symbol and positive `call` |

An example that matches `backend/tests/fixtures/model_profiles/valid.toml` is in [saved profiles](/model-validation-profiles.html).

Tensor bindings use `kind = "tensor"`, `shape`, `dtype`, and a tagged `generator`.
`requires_grad` defaults to `false`; set it to `true` only for floating tensors.
Graph setup reports invalid draft fields with short dotted paths and shows at
most five validation requirements at a time. A class whose local inheritance
proves it is outside PyTorch is rejected before signature discovery; tensorViz
captures PyTorch `nn.Module` and supported Flax/JAX models.

## Source directives

Comments in model source. A saved `tensorviz.toml` profile supplies an explicit
recipe and is used first. These comments apply when that recipe does not.

| Directive | Where it is read | What it does |
| --- | --- | --- |
| `# tensorviz: input=` | `backend/services/ingest/input_declarations.py` (`applicable`), used by `backend/services/ingest/service.py` and `backend/utils/code_parser.py` | Example forward input for one class. Only actual comments owned by the selected model class are used. Adjacent class declarations and supported inherited declarations follow the same rule in setup, source projection and capture; unrelated models and docstrings cannot supply inputs. The comma form `2,4` is a shape. `2,8;2,8` is two arguments; the torch-free reader takes the first argument's comma shape. The worker also accepts an expression such as `torch.randint(0, 50257, (1, 16))` through `parse_input_spec`. |
| `# tensorviz: init=` | `backend/utils/code_parser.py`, `backend/services/ingest/service.py`, `extension/src/initComment.ts` | How to construct the class when it cannot be called with no arguments. One call, keyword arguments only, literal values. A config object is one level deep: `cfg=ModelConfig(width=8)`. Place it on or above the class line. |
| `# tensorviz: out_shape=` | `backend/services/ingest/introspect.py` | Declared output of a class the trace did not measure. It must sit in that class body. `(2, 16)` is a numeric shape. `(B, D)` is recorded and is not turned into numbers. |

`input=` is used when the opening has no explicit execution recipe, tensor
inputs, or example input (`_input_from_comment` in `backend/services/ingest/service.py`).
During graph setup, a saved `tensorviz.toml` profile never reaches the resolver,
and a class-owned declaration overrides inputs inferred from repository example calls
(`backend/services/ide/graph_setup_resolution.py`). Complete calls can still supply
the constructor recipe. An explicit `input_shape` wins over the comment.