Bosonic Quantum IDE for VS Code

Bosonic Quantum IDE brings distributed quantum circuit workflows into VS Code. Open OpenQASM or Qiskit Python circuits, compile them for distributed execution, simulate them locally, inspect connectivity, and review results from the Bosonic Activity Bar.

This 0.1.0 release is a preview build. It is intended for demos and early feedback while the production backend distribution model is finalized.

Quick Start

1. Install the extension from VSIX or the Marketplace pre-release listing.
2. Install Python >=3.10,<3.12.
3. Open a workspace containing a .qasm file or a Qiskit Python circuit.
4. Run Bosonic: Configure Run Settings.
5. Choose demo backend mode for the extension-managed local demo backend.
6. Run Bosonic: Start API Server.
7. Run Bosonic: Compile Current Circuit or Bosonic: Simulate Current Circuit.

For local demo use, these settings are usually enough:

{
  "bosonic.backendMode": "demo",
  "bosonic.demoPythonCommand": "python3.10"
}

Preview Notes

• Demo mode creates a private Python virtual environment in VS Code global extension storage.
• On first run, demo mode installs pinned packages from TestPyPI and PyPI, including bosonic-sdk[disqco], dqsim, fastapi, and uvicorn.
• Python-to-QASM conversion executes the active Python file locally so the extension can discover qiskit.QuantumCircuit objects.
• The demo backend listens only on 127.0.0.1 using the configured bosonic.apiPort.
• No source code, circuits, credentials, or simulation results are intentionally sent to Bosonic by this extension.
• TestPyPI is used for this preview backend. A stable Marketplace release should move to a production package distribution strategy.

Screenshots

Compile And Simulate From The Editor

Sidebar Controls

Results Overview

Current Capabilities

• Bosonic Activity Bar container with a Controls panel.
• Compile and simulate commands for .qasm and Python circuit files.
• Python-to-QASM conversion command for Qiskit files.
• Configurable run settings for nodes, qubits per node, shots, and distributor.
• Backend mode selection with bosonic.backendMode.
• Extension-managed demo backend bootstrap for pinned TestPyPI SDK packages.
• Local API startup through bosonic.apiCommand and bosonic.apiArgs.
• OpenQASM language registration, syntax highlighting, snippets, and editor behavior.
• Results webview with compile/simulation history, coupling map, gate-count bars, operation mix, probability bars, and run history.
• Compact internode connectivity visual in the sidebar.
• Problems panel diagnostics for compile, simulation, and Python conversion failures.
• Setup-focused error messages for missing tools, missing backend folders, unreachable API URLs, early backend exits, stale API versions, and structured API validation errors.
• VSIX packaging through @vscode/vsce.
• CI workflow that builds, checks, packages, and uploads the VSIX artifact.

Repository Layout

The extension lives inside the monorepo at apps/vscode-extension.

apps/vscode-extension/
  package.json                 Extension manifest, commands, settings, views, packaging config
  tsconfig.json                TypeScript config for the extension
  README.md                    Extension-focused developer and user guide
  CHANGELOG.md                 Extension release notes
  LICENSE.txt                  MIT license included in the VSIX
  language-configuration.json  QASM editor brackets/comments
  media/                       Activity Bar icon, sidebar brand asset, Marketplace icon
  python/demo_backend.py        Lightweight demo API shim launched by demo mode
  snippets/qasm.json           QASM snippets
  syntaxes/qasm.tmLanguage.json QASM TextMate grammar
  src/
    apiServer.ts               Starts and monitors local/demo FastAPI backends
    bosonicApi.ts              HTTP client for compile/simulate/Python conversion
    config.ts                  Reads `bosonic.*` VS Code settings
    controlsView.ts            Activity Bar Controls webview and connectivity preview
    extension.ts               Activation, command registration, command workflows
    resultsView.ts             Results webview charts/history
    types.ts                   API response types shared by the extension

Related files outside the extension:

.vscode/launch.json                    Launch config for Extension Development Host
.github/workflows/vscode-extension.yml CI build/check/package workflow
examples/distributed-ghz.qasm          QASM test circuit
examples/distributed_ghz.py            Qiskit Python test circuit
package.json                           Root workspace scripts
package-lock.json                      NPM lockfile

Prerequisites

Install the local development tools used by the monorepo:

• Node.js 20 or newer.
• npm, using the root package-lock.json.
• VS Code.
• uv, used by default to start the Python API.
• The backend dependencies for apps/api.

For demo backend mode only:

• Python >=3.10,<3.12.
• Internet access on the first run so the extension can install packages into its private demo environment.
• Access to TestPyPI and PyPI.

From the repository root, install Node dependencies:

npm install

If the backend has not been prepared yet, sync it from apps/api:

cd apps/api
uv sync

Then return to the repository root before running extension scripts.

Development Commands

Run these from the repository root.

npm run build:extension
npm run check:extension
npm run test:extension
npm run test:extension:demo-backend
npm run package:extension
npm run dev:api:extension

Command details:

• npm run build:extension: compiles extension TypeScript into apps/vscode-extension/out.
• npm run check:extension: runs TypeScript without emitting files.
• npm run test:extension: launches VS Code with @vscode/test-electron and runs the integration test suite.
• npm run test:extension:demo-backend: starts the bundled demo backend and smoke-tests package imports, /python/to-qasm, /compile, and /simulate.
• npm run package:extension: creates a local VSIX package with vsce package --no-dependencies.
• npm run dev:api:extension: starts the FastAPI backend on port 8742.

The extension uses port 8742 by default so it does not collide with the web/Tauri development API on 8741.

Running Locally

1. Open the monorepo root in VS Code.
2. Run npm install if dependencies are not already installed.
3. Run npm run build:extension.
4. Open the Run and Debug panel in VS Code.
5. Select Run Bosonic VS Code Extension.
6. Start debugging. If F5 does not work on macOS, click the green run button in the Run and Debug panel.
7. A new [Extension Development Host] VS Code window opens.
8. In that new window, open this repository or the examples/ folder.
9. Open examples/distributed-ghz.qasm or examples/distributed_ghz.py.
10. Use the Command Palette or Bosonic Activity Bar view to run Bosonic commands.

If the Extension Development Host opens with no folder, choose Open Folder and select the monorepo root or the examples/ directory.

Main User Workflows

Create a Sample Circuit

Run Bosonic: Create Sample Circuit from the Command Palette or the Bosonic sidebar.

When a workspace folder is open, the command creates sample files under:

bosonic-samples/

If no folder is open, it opens the sample as an untitled editor.

Configure Run Settings

Run Bosonic: Configure Run Settings to update:

• backend mode
• nodes
• qubits per node
• shots
• distributor

The values are stored in workspace settings. The status bar and sidebar update after configuration changes.

Compile a Circuit

Open a .qasm file or a Python file, then run:

Bosonic: Compile Current Circuit

For Python files, the extension first converts the Qiskit circuit to QASM through the API, then compiles the resulting QASM.

After a successful compile:

• the Output panel receives a compile summary,
• the Problems panel is cleared for that document,
• the Results panel updates if it is open,
• the sidebar connectivity visual updates to the latest coupling map.

Simulate a Circuit

Open a .qasm file or a Python file, then run:

Bosonic: Simulate Current Circuit

After a successful simulation:

• the Output panel receives a simulation summary,
• marginal probabilities appear in the Results panel,
• the run is added to the recent history table.

View Results

Run:

Bosonic: Show Last Results

The Results panel includes:

• latest compile metrics,
• latest simulation metrics,
• weighted coupling map,
• gate-count bars,
• operation mix,
• simulation marginal probability bars,
• recent compile and simulation history.

Use the Sidebar

Click the Bosonic icon in the Activity Bar. The Controls panel includes:

• active file,
• run settings,
• internode connectivity preview/latest compile visual,
• compile/simulate/convert buttons,
• settings/results/API/diagnostics buttons.

Before compile, the connectivity visual shows a dashed layout preview from the configured node count. After compile, it uses the latest coupling_map returned by the API.

Commands

The extension contributes these commands:

• Bosonic: Start API Server
• Bosonic: Compile Current Circuit
• Bosonic: Convert Python Circuit to QASM
• Bosonic: Simulate Current Circuit
• Bosonic: Create Sample Circuit
• Bosonic: Configure Run Settings
• Bosonic: Show Run Settings
• Bosonic: Cancel Simulation
• Bosonic: Clear Diagnostics
• Bosonic: Show Last Results

Most commands are available from the Command Palette. Compile, simulate, convert, and configure are also available from editor/explorer context menus where appropriate.

Settings

The extension contributes these bosonic.* settings.

{
  "bosonic.backendMode": "local",
  "bosonic.demoPythonCommand": "",
  "bosonic.apiUrl": "http://127.0.0.1:8742",
  "bosonic.apiPort": 8742,
  "bosonic.autoStartApi": true,
  "bosonic.apiCommand": "uv",
  "bosonic.apiArgs": [
    "run",
    "--directory",
    "${extensionRoot}/../api",
    "python",
    "main.py",
    "${port}"
  ],
  "bosonic.nodes": 4,
  "bosonic.qubitsPerNode": 4,
  "bosonic.shots": 100,
  "bosonic.distributor": "bosonic"
}

Supported backend modes:

• local: use a locally running or locally launched Bosonic API backend. This is the current working monorepo mode.
• demo: use the extension-managed Python demo backend. On first run, the extension creates a private virtual environment under VS Code global storage, installs pinned demo packages, and launches the bundled python/demo_backend.py API shim.

bosonic.demoPythonCommand is only used in demo mode. Leave it empty to auto-detect python3.11, python3.10, python3, or python. Set it to a specific executable path if your default Python is too old.

Supported substitutions in bosonic.apiArgs:

• ${extensionRoot}: path to apps/vscode-extension during local development.
• ${workspaceFolder}: first open workspace folder, or the extension path if no folder is open.
• ${port}: value of bosonic.apiPort.

For local monorepo development, the default command resolves to:

uv run --directory apps/api python main.py 8742

Demo Backend

The demo backend is designed for a fast VSIX demo without requiring the full monorepo backend checkout. It still runs locally on the user's machine and uses the same bosonic.apiPort/bosonic.apiUrl contract as local mode.

On first start in demo mode, the extension installs:

• fastapi>=0.115,<1
• uvicorn[standard]>=0.30,<1
• bosonic-sdk[disqco]==0.1.7
• dqsim==0.1.2
• pyzx>=0.9,<0.10

bosonic-sdk[disqco] pulls the SDK-side model, converter, QASM, Qiskit, and disqco dependencies needed for compile/distribution. dqsim is still installed separately because simulation uses simulate_distributed_shots. fastapi and uvicorn are installed because the VS Code extension talks to a local HTTP API rather than importing Python packages directly from Node.

The install command uses:

python -m pip install --index-url https://test.pypi.org/simple --extra-index-url https://pypi.org/simple ...

The private environment is stored in VS Code global extension storage, not inside the user's workspace. Delete that storage folder or bump the install version in src/apiServer.ts when you need a clean reinstall.

Important demo limitations:

• Python files are executed locally during Python-to-QASM conversion so the extension can discover qiskit.QuantumCircuit objects.
• TestPyPI packages are not a production supply-chain story. Before Marketplace release, decide whether to publish stable packages to PyPI, bundle wheels, use a hosted backend, or document a separate installer.
• The first run can take a while because it creates a venv and installs binary dependencies.

Backend Contract

The extension expects a Bosonic API with these routes:

• GET /health
• GET /openapi.json
• POST /compile
• POST /simulate
• POST /python/to-qasm
• POST /cancel

The extension uses /health to decide whether the backend is already running. It uses /openapi.json to detect stale API processes that do not expose newer routes such as /python/to-qasm.

The core response shapes are defined in src/types.ts and mirror apps/web/src/lib/types.ts.

Diagnostics and Error Handling

Compile, simulation, and Python conversion failures are written to the Problems panel as Bosonic diagnostics. Use Bosonic: Clear Diagnostics to remove them manually.

Common setup failures include action buttons to open the Bosonic output channel or extension settings. The extension detects and explains:

• missing API command, especially missing uv,
• configured command permission errors,
• missing local backend directory,
• missing or incompatible Python for demo backend mode,
• failed demo backend package installation,
• API auto-start disabled while no API is running,
• API process exiting before it becomes healthy,
• API URL or port not reachable,
• stale API process missing expected routes,
• structured FastAPI validation errors.

When debugging backend startup, open:

View > Output > Bosonic

or choose Show Bosonic Output from an error notification.

Packaging

Create a local VSIX package from the repository root:

npm run package:extension

The package is written to:

apps/vscode-extension/bosonic-vscode-extension-0.1.0.vsix

The extension manifest uses a files allowlist so the VSIX only includes the extension runtime files, media, grammar, snippets, README, changelog, and license.

To manually install the VSIX in VS Code:

1. Open VS Code.
2. Open the Extensions view.
3. Choose ....
4. Choose Install from VSIX....
5. Select apps/vscode-extension/bosonic-vscode-extension-0.1.0.vsix.

For a clean install test, use a separate VS Code window or profile.

CI

The workflow at .github/workflows/vscode-extension.yml runs on relevant pull requests and pushes to main.

It performs:

1. npm ci
2. npm run build:extension
3. npm run check:extension
4. xvfb-run -a npm run test:extension
5. npm run package:extension
6. Uploads the generated VSIX artifact

Tests

The extension test suite lives under:

apps/vscode-extension/src/test/

Run it from the repository root:

npm run test:extension

The test runner compiles the extension, launches a real VS Code Extension Development Host through @vscode/test-electron, opens a temporary workspace, and runs a small assertion-based integration suite inside the extension host.

Current coverage includes:

• extension activation,
• Bosonic command registration,
• QASM language contribution,
• default bosonic.* settings,
• Bosonic: Create Sample Circuit writing a QASM sample into the open workspace.

On Linux CI, tests run under xvfb-run because VS Code needs a display server.

The demo backend smoke test lives at:

apps/vscode-extension/scripts/smoke_demo_backend.py

Run it from the repository root with Python 3.10:

npm run test:extension:demo-backend

By default, the smoke test creates a temporary virtual environment, installs the pinned TestPyPI/PyPI demo packages, starts python/demo_backend.py, and verifies:

• package imports for bosonic_sdk, dqsim, fastapi, qiskit, and uvicorn,
• backend route discovery through /openapi.json,
• Python-to-QASM conversion for examples/distributed_ghz.py,
• compile for the generated QASM,
• simulation for the generated QASM.

To reuse an existing venv and avoid reinstalling packages on every run:

BOSONIC_DEMO_VENV=/tmp/bosonic-demo-smoke-1782247490 npm run test:extension:demo-backend

Marketplace Readiness

Before publishing, update the extension manifest in apps/vscode-extension/package.json.

Required decisions:

• final Marketplace publisher,
• support/contact URLs if desired,
• README screenshots or GIFs,
• production backend distribution model.

The current manifest is configured for a preview release:

• "publisher": "bosonic"
• "preview": true
• "license": "MIT"
• repository URL points to the current fork remote

Do not publish until the Marketplace publisher ID is confirmed.

Troubleshooting

Extension Development Host Opens With No Folder

Open the monorepo root or examples/ folder manually inside the Extension Development Host.

F5 Does Not Start Debugging On macOS

Open the Run and Debug panel and click the green run button for Run Bosonic VS Code Extension.

Command Says The API Is Not Running

Run Bosonic: Start API Server, or check that:

• bosonic.autoStartApi is enabled,
• bosonic.apiUrl points to the correct port,
• no stale backend process is occupying the port,
• uv is installed and available on PATH.

If bosonic.backendMode is demo, also check that Python >=3.10,<3.12 is installed or set bosonic.demoPythonCommand to a compatible Python executable.

Missing Backend Folder

The default local development command expects this structure:

apps/api
apps/vscode-extension

Open the monorepo root in VS Code. If you are testing the extension outside the monorepo, configure bosonic.apiUrl to point to a running API or update bosonic.apiCommand and bosonic.apiArgs.

Python Conversion Says The API Is Stale

The extension checks whether /python/to-qasm exists. If that route is missing, stop the old backend process and start the current one on the configured port.

No Status Bar Item

The status bar can be hidden in VS Code. Use the Command Palette or Bosonic Activity Bar Controls panel instead.

Results Panel Is Empty

Run compile or simulation first, then run Bosonic: Show Last Results.

Development Notes

• Keep extension code inside apps/vscode-extension/src.
• Keep shared API response types aligned with apps/web/src/lib/types.ts.
• Run npm run check:extension before pushing.
• Run npm run package:extension after manifest, README, grammar, snippet, or media changes.
• The generated VSIX is ignored by git.
• Do not commit out/ unless the team decides packaged JS should be tracked.
• The Activity Bar icon must be theme-aware SVG; the Marketplace icon must be PNG.

Next Steps

Recommended product and engineering follow-ups:

• Replace the temporary/approximate Bosonic logo with the official source asset.
• Add more extension tests for config update prompts, diagnostics, API startup errors, compile/simulate flows with a mocked API, and webview rendering.
• Harden the demo backend bootstrapper with mocked API tests, clearer reinstall/upgrade controls, and clean-profile install testing.
• Decide the production backend strategy: bundled local backend, hosted API, separate installer, or documented local setup.
• Improve the Results panel with export/download options for compile and simulation summaries.
• Add screenshots or a short GIF to the README before Marketplace release.
• Add command icons or clearer editor-title affordances where VS Code supports them.
• Decide whether results history should persist across VS Code reloads.
• Add a release workflow that publishes VSIX artifacts on tags.
• Add a Marketplace publish workflow after publisher, token, license, and privacy details are finalized.
• Audit and update publisher, repository, license, private, and version fields before publishing.
• Test installing the generated VSIX in a clean VS Code profile.
• Confirm the extension behavior on macOS, Windows, and Linux.