Skip to content

VS Code extension

Install MySpec for VS Code (or Cursor, Windsurf, VSCodium), sign in with your MySpec account and link a project.

Updated View as Markdown

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 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

  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, or from a terminal:

code --install-extension myspec.myspec-vscode

These editors install extensions from Open VSX. Open the Extensions view, search for MySpec and select Install.

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

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 or the JetBrains plugin on this machine, you are signed in already: skip to Link a project.

Otherwise the view shows two buttons. Pick one.

Sign in with your browser

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).

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.

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.

Done

VS Code shows Signed in to MySpec as your email and organization, and asks you to 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.

Create a token

In MySpec, 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 for details.

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.

With Remote Development (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

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 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.
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, 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.
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.

Navigation

Type to search…

↑↓ navigate↵ selectEsc close