---
title: "VS Code extension"
description: "Install MySpec for VS Code (or Cursor, Windsurf, VSCodium), sign in with your MySpec account and link a project."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.myspec.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# VS Code extension

MySpec for VS Code shows a project's spec files, attachments, tasks and
discussions in a **MySpec** view in the activity bar. See
[MySpec in your IDE](https://docs.myspec.dev/ide/) for what it can do and how sign-in works.

**Requirements:** VS Code 1.95 or later, or a recent Cursor, Windsurf or
VSCodium. A MySpec account in at least one organization.

## Install

### VS Code

1. Open the **Extensions** view (`Ctrl+Shift+X`, or `Cmd+Shift+X` on macOS).
2. Search for **MySpec**.
3. Select **MySpec** by publisher **MySpec**, then **Install**.

Or install it from the
[Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=myspec.myspec-vscode),
or from a terminal:

```bash
code --install-extension myspec.myspec-vscode
```

### Cursor, Windsurf, VSCodium

These editors install extensions from
[Open VSX](https://open-vsx.org/extension/myspec/myspec-vscode). Open the
**Extensions** view, search for **MySpec** and select **Install**.

From a terminal, use the editor's own command:

```bash
cursor --install-extension myspec.myspec-vscode
windsurf --install-extension myspec.myspec-vscode
codium --install-extension myspec.myspec-vscode
```

A **MySpec** icon appears in the activity bar. Updates install automatically,
like any other extension.

## Sign in

Open the **MySpec** view from the activity bar. If you already signed in with
the [local MCP server](https://docs.myspec.dev/mcp/local-server/) or the JetBrains plugin on this
machine, you are signed in already: skip to [Link a project](#link-a-project).

Otherwise the view shows two buttons. Pick one.

### Sign in with your browser

1. **Start the sign-in**

   Select **Sign in with browser** in the MySpec view, or run
   **MySpec: Sign in with browser** from the Command Palette
   (`Ctrl+Shift+P`, or `Cmd+Shift+P` on macOS).
2. **Sign in to MySpec in your browser**

   Your browser opens the MySpec sign-in page. Sign in the way you usually do
   and approve the request. VS Code shows **Waiting for the MySpec sign-in in your browser…**
   until you finish.
3. **Choose your organization**

   If you belong to more than one organization, VS Code may ask
   **Which MySpec organization should VS Code use?** Pick one. You can switch
   later.
4. **Done**

   VS Code shows **Signed in to MySpec as** your email and organization, and
   asks you to [link a project](#link-a-project).

This sign-in is shared with the MySpec MCP server and JetBrains IDEs on this
machine. If the MCP server is already signed in to a different MySpec
environment, VS Code warns you first, because signing in here replaces that
sign-in too.

### Sign in with an API token

Use this on a shared machine, or when you want read-only access.

1. **Create a token**

   In [MySpec](https://app.myspec.dev), open the avatar menu and choose
   **API tokens**, then **Create token**. Choose the organization and the
   access (**Read only** or **Read and write**), then copy the token. See
   [API tokens](https://docs.myspec.dev/mcp/api-tokens/#create-a-token) for details.
2. **Enter it in VS Code**

   Select **Use an API token** in the MySpec view, or run
   **MySpec: Sign in with API token**. Paste the token (`msp_pat_…`) and press
   Enter. VS Code checks it with MySpec before saving it.

The token is kept in VS Code's secret storage and used only by VS Code. It is
never written to `~/.myspec/`, so it does not change what the MCP server signs
in as. While a token is saved in VS Code, VS Code uses it instead of the
browser sign-in.

### Sign in on a remote machine or another device

When VS Code cannot hand the sign-in back from your browser (for example in a
remote session, or when the browser is on another device), use the paste
option:

1. Start **Sign in with browser**. VS Code asks
   **Browser did not return to VS Code?** (or, if it cannot open a browser,
   offers **Copy sign-in link** straight away).
   - To sign in on another device, select **Copy sign-in link**.
   - If the page opened here but VS Code never received the sign-in, select
     **Paste token**.
2. Open the link in a browser, if it is not open already, and sign in.
3. The page shows a value like `<code>.<state>`. Copy **the whole value,
   including the dot**, and paste it into VS Code straight away: it expires a
   minute after you finish signing in.

> **Only open the sign-in link on a machine you trust**
>
> The sign-in page hands a one-time code to a program listening on the machine
> where the browser runs. Anything else running there could take the code and
> act as you until you sign out.

With [Remote Development](https://code.visualstudio.com/docs/remote/remote-overview)
(SSH, containers, WSL), the extension runs on your local machine by default, so
it uses your local sign-in and the normal browser flow works.

## Check who you are signed in as

The status bar shows your email and organization, with a lock icon for a
read-only token. Hover over it for the environment and which credential is in
use, or click it (or run **MySpec: Show account**) to open the account menu:

- **Switch organization** (browser sign-in only)
- **Switch project**
- **Sign out**
- **Settings**

## Link a project

The extension needs to know which MySpec project belongs to the folder you have
open.

1. Select **Link a project** in the MySpec view, or run
   **MySpec: Link a project to this folder**. (After your first sign-in, VS Code
   asks on its own.)
2. Pick a project from the list. Type to filter it.

The **Spec files**, **Attachments**, **Tasks** and **Discussions** views fill
in. VS Code remembers the link for this folder, so the project is there when
you reopen it. Use **MySpec: Switch project** to link another one, or
**MySpec: Unlink project from this folder** to remove the link.

If no folder is open, you can still pick a project, but it is not remembered.

## Use it

- **Spec files**: open a file to read it (Markdown preview works). Expand it
  to see its revisions; right-click a revision to **Compare with current** or
  **Compare with previous revision**.
- **Comments**: select text in a spec file, select the **+** in the editor
  gutter, write your comment and choose **Add comment**. Threads show in the gutter and in the
  **Discussions** view. Set `myspec.comments.showResolved` to also show
  resolved threads in the editor.
- **Tasks**: the view shows tasks assigned to you; use the filter buttons to
  see all, unassigned or someone else's. Right-click a task for
  **Set status…** and **Edit planning…**, then **Submit task changes** in the
  view's toolbar to send them. Unsent changes show as `● unsubmitted` and stay
  on this machine for up to 14 days.
- **Copy prompt for AI agent**: right-click tasks or a tasks file. Add `.specs/`
  to `.gitignore` if you do not want to commit the saved spec files.
- **Download…** is on the right-click menu of spec files, revisions and
  attachments (**Download folder…** on folders). **Open in MySpec** is on almost
  everything, including tasks and threads.

Views refresh when you come back to the window. Use **Refresh** in a view's
toolbar for an immediate reload.

## Sign out

Run **MySpec: Sign out**, or use the account menu.

- **Browser sign-in**: this also signs out the MySpec MCP server and JetBrains
  IDEs on this machine. VS Code asks you to confirm.
- **API token saved in VS Code**: the token is removed from VS Code. To stop it
  working everywhere, [revoke it](https://docs.myspec.dev/mcp/api-tokens/#revoke-a-token) in MySpec.
- **API token in `~/.myspec/oauth_creds.json`**: signing out keeps it. Delete
  its `apiToken` field to remove it.
- **`MYSPEC_API_TOKEN`**: unset the variable and restart VS Code.

## Settings

Open **Settings** and search for **MySpec**.

| Setting | Default | What it does |
|---|---|---|
| `myspec.environment` | `auto` | `auto` uses the same MySpec environment as the MCP server's sign-in on this machine, otherwise MySpec itself. You normally leave it as is. |
| `myspec.comments.showResolved` | `false` | Show resolved threads in the editor. The **Discussions** view always lists them. |

The extension logs to **Output → MySpec**. Tokens are never written to the log.

## Troubleshooting

| Problem | What to do |
|---|---|
| Nothing happens after you sign in in the browser | Select **Paste token** and paste the value the sign-in page shows. See [Sign in on a remote machine](#sign-in-on-a-remote-machine-or-another-device). |
| The pasted token is refused | Copy the whole `<code>.<state>` value, including the dot, not the `code=` part of the address. If more than a minute passed, sign in again. |
| "You do not belong to any organization yet" | Create a workspace in [MySpec](https://app.myspec.dev), then sign in again. |
| "No organization was chosen" | Run **MySpec: Switch organization** and pick one. |
| "The project linked to this folder belongs to another organization" | Select **Switch organization**, or **Pick another project**. |
| "The project linked to this folder is not available" | It was deleted, or you lost access. Select **Pick another project**. |
| "Could not reach MySpec" | Check your connection, then select **Try again**. |
| The API token is rejected | It expired, was revoked, or you left its organization. [Create a new token](https://docs.myspec.dev/mcp/api-tokens/#create-a-token). |
| You cannot comment or change tasks | You are using a **Read only** token. Sign in with your browser, or use a **Read and write** token. |
| "Tasks aren't available for this organization" | The task board is not turned on for your organization. |
| "Refusing to load credentials … file mode is too permissive" | Run `chmod 600 ~/.myspec/oauth_creds.json`, then run **MySpec: Refresh** from the Command Palette. |
| You appear signed out, and the **MySpec: Sign in** status bar tooltip says the MCP server is signed in to another environment | The MCP server on this machine is signed in to a different MySpec environment. Sign in again here, or set `myspec.environment` back to `auto`. |

For anything else, open **Output → MySpec** and see [Help](https://docs.myspec.dev/help/).

Source: https://docs.myspec.dev/ide/vscode/index.mdx
