VS Code Extension Overview

The Mosayic VS Code extension (mosayic.vscode-mosayic on the Visual Studio Marketplace) is the bridge between your machine and the Mosayic dashboard. Without it installed and signed in, the dashboard can’t do anything that requires touching your local filesystem, terminal, or installed CLIs.

What it does

In one sentence: the extension is a remote-controlled shell for your VS Code workspace, restricted to commands the Mosayic backend sends to it for the user who is signed in.

More concretely:

Runs commands

When you click “Connect GitHub” or “Start dev server” in the dashboard, the extension is what actually runs gh auth login or npm start in your project folder.

Opens terminals

Long-running interactive commands (like eas build) get their own VS Code terminal. You can see them, type into them, and the dashboard sees the output too.

Manages dev servers

The Expo dev server, the API server, and the local Supabase stack are all managed via the extension. Live output streams to both your VS Code terminal and the dashboard.

Picks folders

When the dashboard needs you to choose a folder (e.g. for the project scaffold), the extension opens VS Code’s native folder picker.

What it doesn’t do

The extension is deliberately minimal:

• No custom views, panels, or tree views. The only UI is a status bar item and the standard VS Code Output channel.
• No webviews. The dashboard is a separate website you open in your browser; the extension doesn’t embed it.
• No code intelligence. It’s not a language server. It doesn’t analyse, lint, or modify your code on its own — only when the dashboard tells it to run a command.
• No telemetry. The extension doesn’t send anything to Mosayic on its own; it only relays messages between the backend and your shell.

How it talks to the backend

A single WebSocket to the Mosayic backend (wss://...mosayic-api.../ws), opened on activation and reconnected automatically on failure. The connection is authenticated with your Supabase JWT in the Authorization header.

The backend sends JSON messages like:

{
  "type": "command",
  "request_id": "abc-123",
  "command": "gh auth status"
}

The extension runs the command and replies:

{
  "type": "command_result",
  "request_id": "abc-123",
  "stdout": "✓ Logged in to github.com as your-username",
  "stderr": "",
  "exit_code": 0
}

For long-running commands, output is streamed via command_output messages while the command runs.

A ping/pong exchange keeps the connection alive every 30 seconds. If the connection drops, the extension reconnects with exponential backoff (1s, 2s, 5s, 10s, 30s, max 10 attempts).

Single connection per user

Only one VS Code window per Mosayic user can be connected at a time. If you open VS Code on a second machine, the second connection wins — the first machine’s WebSocket is closed with code 4001 and its status bar updates to “signed out”.

This is intentional: it makes the routing unambiguous. The dashboard always knows exactly one extension to send commands to.

Privacy

The extension stores nothing about you outside of standard VS Code mechanisms:

• Auth tokens in VS Code’s secret storage (OS keychain)
• Logs in the “Mosayic WebSocket” output channel (cleared when VS Code restarts)

It does not phone home, doesn’t send analytics, doesn’t crash-report.

For more on what permissions the extension has and what safeguards exist, see Security & Permissions.

Reading on

Installation & Sign In Step-by-step install.

Commands Every command the extension contributes to the Command Palette.

Settings The settings you can tune in VS Code preferences.

Security & Permissions What the extension can and can't do, and the safeguards in place.

Troubleshooting When the status bar says something isn't right.