The VS Code extension

A MatterWave chat view in the VS Code side bar: your conversations, streaming answers, branches, and the editor's selection or file as context. It uses the same /api routes and the same conversations as the web app. The extension lives at clients/vscode.

Install

Until it is on the Marketplace and Open VSX, install the .vsix that CI builds:

code --install-extension matterwave-<version>.vsix

or Extensions → ⋯ → Install from VSIX....

Settings

Two. Everything else (which models you may use, your plan, your budget) comes from the server.

Setting	Default
matterwave.baseUrl	https://app.matterwave.dev	The deployment.
matterwave.caFile	empty	Path to a PEM file holding the certificate authority that signed the deployment's TLS certificate, trusted beside the system's authorities. For a deployment behind a private CA; ~/ is expanded.

{
  "matterwave.baseUrl": "https://matterwave.internal.example",
  "matterwave.caFile": "~/certs/internal-root-ca.pem"
}

The first time the extension activates with the default baseUrl in force it asks for the server URL, prefilled with the default; the answer goes to the user setting. Escape keeps the default and the question is not asked again.

The extension host's fetch has no per-request trust store, so without caFile a deployment behind a private CA is refused by TLS. The refusal is reported as The server's certificate is not trusted; set matterwave.caFile ... -- in the chat view, on the sign-in commands and in the status bar's offline state -- with OpenSSL's code in brackets. A caFile that cannot be read, or that is not a certificate, fails the request with the path and the reason rather than sending without it. The file is read once per path; changing the setting applies to the next request.

Sign in

From the command palette, either:

• MatterWave: Sign In with API Key: paste a key (mw_..., from Settings → API keys, with chat:read and chat:write), or
• MatterWave: Sign In (Device Code): the extension opens /device in your browser with the code filled in; approve it there. The flow is in device-login.md.

The credential is kept in VS Code's SecretStorage. All requests go from the extension host; the chat webview never receives a token. MatterWave: Sign Out clears it; a key the device flow minted is revoked on the server first (DELETE /api/keys/{id}), so it disappears from Settings → API keys, while a pasted key is yours and is only forgotten by the editor. If the revoke fails the editor still signs out and tells you to revoke the key in Settings. Revoking the key in Settings → API keys signs the editor out too.

Sign-in through VS Code's own accounts menu (PKCE against a native identity-provider client, with a vscode:// redirect) is designed but not built.

Commands

Command	Does
MatterWave: New Chat	opens an empty conversation in the chat view
MatterWave: Ask about Selection	sends the selection, fenced with its language and path, inline in your message; also on the editor's right-click menu
MatterWave: Ask about File	uploads the file as a text/plain attachment named after its path; past 32 000 characters the server cuts it and the part is marked truncated; also on the editor's right-click menu
MatterWave: Pick Model	the models from /api/models, grouped as on the web; a model outside your plan is shown locked and cannot be picked
MatterWave: Compact Conversation Now	summarises the older turns of a long conversation (compaction.md)
MatterWave: Copy Last Request ID	the id of the last failed request, for a support thread

The status bar shows the model, the context meter, who you are signed in as, and offline.

What it does not do

• No edits, no terminal, no tool execution. It is a chat client, not a coding agent. Tool calls the server runs show as parts in the transcript, as on the web.
• No images. No model served today accepts them, and the extension has no image attach.
• No local model configuration. The model list is the org's, from the server.
• No offline sending. Without a connection the composer is disabled and the draft is kept; Reconnect in the view (or any command that reaches the API) reopens it.

How it is built

The extension host bundles the TypeScript SDK (sdk/typescript) from source, the way the terminal client depends on the Python SDK by path: conversations, streamed turns with resume, typed frames and device login come from the SDK; the model list, the context meter, compaction with a picked model, attachment upload and key revocation are the extension's own.