VS Code and Cursor reference

The v0.4.1 extension runs as a workspace extension and embeds the same loopback viewer in VS Code or Cursor webviews. It is distributed as beatricebm.dcmview through the VS Code Marketplace and Open VSX.

Supported bundled platforms

• Linux x64
• macOS x64
• macOS arm64
• Windows x64

Set dcmview.binaryPath on another platform or when testing a locally built binary.

Commands

Command	Purpose
dcmview: Open with dcmview	Open a selected file or directory.
dcmview: Open Workspace with dcmview	Open a selected workspace folder.
dcmview: Stop All dcmview Sessions	Stop extension-managed viewers.
dcmview: Show Bridge Status	Inspect the terminal-bridge state.

The extension also registers a read-only custom editor for *.dcm, *.dicom, and *.ima names. Extensionless DICOM objects and directories use the Explorer context command.

Settings

Setting	Type	Default	Behavior
dcmview.binaryPath	string	""	Absolute binary override.
dcmview.defaultRecursive	boolean	true	Recursively scan selected directories.
dcmview.extraArgs	string array	[]	Arguments inserted before selected paths, for example ["--mask"].
dcmview.startupTimeoutSeconds	number	20	Seconds to wait for a startup URL; minimum 1.
dcmview.terminalInterception.enabled	boolean	true	Route supported commands in new integrated terminals into webviews.

The normal launch shape is:

dcmview --no-browser --port 0 --host 127.0.0.1 --startup-json [extra args] <PATH>...

When default recursion is disabled, the extension also includes --no-recursive.

--unix-socket is not supported in dcmview.extraArgs. The extension needs an HTTP viewer URL, so a socket-only launch fails with an error that says Unix socket launches are not supported in VS Code.

Access token

The bundled viewer requires its access token on every API request. The extension passes the token to the viewer panel, so opening files and folders works as before.

• The extension reads the viewer’s origin (base_url) and token separately from the startup line, forwards the origin through VS Code, and attaches the token afterwards. The token therefore survives port forwarding, including Remote-SSH.
• Binaries older than v0.4.0 report only url; the extension falls back to it.
• The extension’s output channel shows the origin without credentials.
• Terminal and Python launches routed through the bridge receive the full local launch URL with its token fragment.
• A DCMVIEW_TOKEN set only in a terminal or notebook is not passed through the bridge. A viewer the extension manages inherits the extension host’s environment and otherwise generates its own token.

An extension older than v0.4.0 pointed at a v0.4.0 binary through dcmview.binaryPath can lose the token when VS Code forwards the port. Update the extension.

Masked sessions

With --mask in dcmview.extraArgs, the extension starts masked sessions and titles the viewer panel dcmview: masked session instead of the file name. Masking is a display aid, not de-identification, and it applies only inside the viewer page: VS Code’s Explorer, the tab of a file opened in the DICOM custom editor, and the viewer’s Directory view still show real folder and file names.

Theme

The viewer follows the editor’s color theme: light themes open it light, and dark and high-contrast themes open it dark. Switching themes updates open viewers without reloading them. The image area stays dark in every theme.

Binary resolution

The extension checks:

1. dcmview.binaryPath.
2. target/debug/dcmview or target/debug/dcmview.exe in a source checkout.
3. Its Marketplace-bundled resources/bin/<platform>-<arch>/ executable.
4. dcmview or dcmview.exe on PATH.

When interception is active but the extension cannot resolve a local executable, it may accept a trusted absolute client path supplied by the Python wrapper. On Unix that file must belong to the current user and must not be group- or world-writable; its filename must be dcmview or dcmview.exe.

Routing rule

The extension creates authenticated loopback bridge endpoints and short-lived registry records for open workspace folders. Every entry point, including dcmview, dcmview-py, python -m dcmview_py, and dcmview_py.view(), follows one rule that the dcmview binary applies:

• a process with the extension’s bridge environment, which new integrated terminals receive, opens in VS Code; and
• any other process opens in VS Code only when its working directory is inside a registered workspace folder.

Anywhere else the local viewer starts. DCMVIEW_VSCODE_BYPASS=1, or view(vscode_bridge=False) in Python, forces an ordinary local launch.

Terminal interception applies to integrated terminals created after activation. Before a launch, the binary probes each registry entry and removes one whose port now belongs to another service. The binary waits up to 120 seconds for a slow VS Code viewer to start. A launch that reached the bridge without confirmation exits instead of starting a second, local viewer.

The bridge URL and bearer token variables are extension-managed. Do not copy them into persistent shell configuration. Registry records expire after three hours and use permission checks on Unix. The binary no longer searches the registry locations used by extension builds older than 0.2.5.

See the VS Code and Cursor guide for the user workflow and troubleshooting for startup failures.