Install the VS Code Extension

Everything from this point forward needs the extension. The dashboard can’t scaffold a folder it can’t reach, and it can’t reach your machine without the extension.

Install

1. Open VS Code. If you don’t have it, download from code.visualstudio.com. You need version 1.96 or newer.

2. Open the Extensions panel — Cmd/Ctrl + Shift + X, or click the squares icon in the Activity Bar on the left.

3. Search for Mosayic. The one you want is published by mosayic and the extension ID is mosayic.vscode-mosayic.

4. Click Install. The extension activates automatically when VS Code finishes loading — no restart needed.

Sign in

1. Open the Command Palette — Cmd/Ctrl + Shift + P.

2. Run Mosayic: Sign In. A browser tab opens and walks you through Google OAuth.

3. Use the same Google account you used to sign in to the dashboard. If they don’t match, the dashboard will detect the mismatch and refuse to send commands to the extension.

4. Wait for the redirect. When Google finishes, you’ll be sent back to VS Code through the vscode:// protocol. The browser tab can be closed.

5. Check the status bar. The bottom-left corner of VS Code now shows “Mosayic: connected” with a checkmark. That’s your green light.

The access token is stored in VS Code’s OS-level secret storage:

• macOS — Keychain
• Windows — Credential Manager
• Linux — libsecret (gnome-keyring, kwallet, etc.)

Tokens are refreshed automatically before they expire.

Open a workspace folder

The extension runs every command in the first folder of your VS Code workspace. If no folder is open, it falls back to your home directory.

You don’t need a real project folder yet — the Configure Your Project step will create one for you. But you do need some folder open. If you only have the welcome tab, click File → Open Folder… and pick anywhere temporarily (your Documents folder, for example).

Verify the connection in the dashboard

Switch back to the dashboard. Within a couple of seconds it should detect the extension and show:

✅ Extension connected — reporting macOS

(or Linux/Windows depending on your machine.)

If it still says “Waiting for extension…” after a few seconds:

• Click the Mosayic status bar item in VS Code and choose Show Logs to see what’s happening.
• Make sure the workspace folder is open in VS Code (the extension may not have anywhere to run commands).
• Check the troubleshooting page.

Why does my browser open every time I sign in?

Mosayic uses a standard OAuth PKCE flow because that’s what Google supports. The browser handoff is one round-trip — once you’re in, the extension stores the token securely and won’t re-prompt unless:

• You explicitly sign out (Mosayic: Sign Out)
• The refresh token is rejected (e.g., your Google session expired in a way that invalidates it)
• You uninstall and reinstall the extension

Tip

You can install Mosayic on multiple machines, but only one can be actively connected at a time. The most recently connected machine wins; the previous WebSocket is closed with code 4001. If you’re switching laptops, just open VS Code on the new one — the dashboard re-routes automatically.

Next

Now that the extension is online, the rest of the guide unlocks. Continue to Set Up Your Machine.

VS Code Extension reference Full reference for everything the extension does, including commands, settings, and security model.