Use the VS Code extension

This page lets you install the Spectrace editor extension, sign in, and use it to pick a requirement, track acceptance criteria, link the files you touch, and hand the requirement's context to an AI coding agent.

The extension is published as spectrace.spectrace-vscode and runs in VS Code 1.85 or later. It is available on every Spectrace plan, including free.

Prerequisites

A Spectrace account and at least one project with requirements in it. See Quick start.
VS Code 1.85+, or a compatible editor: Cursor, Windsurf, and VSCodium install extensions from Open VSX.
A browser — signing in opens a browser tab and returns to the editor through a vscode:// (or cursor://, windsurf://) callback.

Install

Search for Spectrace in the Extensions view, or install from the command line:

bash

code --install-extension spectrace.spectrace-vscode

Marketplace listing: https://marketplace.visualstudio.com/items?itemName=spectrace.spectrace-vscode.

These editors read from Open VSX. Search for Spectrace in the editor's Extensions view, or open https://open-vsx.org/extension/spectrace/spectrace-vscode and install from there.

After installation a Spectrace icon appears in the activity bar. Clicking it opens the Requirements view.

Start the sign-in
Click Sign in with Spectrace on the sidebar's welcome screen, or run Spectrace: Sign In to Spectrace from the command palette. The extension opens your browser at the Spectrace login page.
Log in to Spectrace in the browser
Use whichever method your account uses (email and password, Google, or GitHub). When the login completes, Spectrace mints a one-time authorization code and redirects the browser to the editor's callback URL.
Return to the editor
The editor exchanges the code for a session. The sidebar switches from the welcome screen to the project picker.

The authorization code is single use and expires after 120 seconds; if the browser sits on the redirect for longer than that, sign in again. Tokens are stored in the editor's secret storage, not in settings or on disk in plain text, and are refreshed in the background. Spectrace: Sign Out of Spectrace clears them.

If you have no account, the welcome screen also offers Try the demo · no account needed, which loads a fixed sample project so you can see the sidebar without signing in.

At the top of the Requirements view is a project picker. Under it, four tabs group the project's requirements by workflow stage: Backlog, In dev, In review, and Done. A search box filters the list, and a quick-add box creates a new requirement in the selected project from a one-line description.

Selecting a requirement opens its detail view and makes it the active requirement. The detail view has two tabs:

Spec — the requirement's acceptance criteria with checkboxes, the files linked to it (click one to open it), and its subtasks. You can add subtasks and link the current file from here.
Test — the test cases generated in Spectrace, with a count of how many are approved. Test generation itself happens in the web app; the tab links there when there are none yet.

The Spec tab has two actions:

Start with SpecAI fetches the requirement's implementation context from Spectrace (user story, criteria, subtasks, linked and likely files, related code, and stubs for the generated tests), stamps the requirement as in development, and hands the prompt to your AI agent. Once any criterion or subtask is complete the button reads Continue with SpecAI; while a session is live it reads SpecAI in progress. Which agent receives the prompt is controlled by the spectrace.aiAgent setting below.
Create PR & Submit for Review appears once every acceptance criterion and subtask is complete on a project that has a GitHub repository. It commits and pushes your branch, creates the pull request through a GitHub account connected to your workspace, and moves the requirement to review. On a project without a repository the same button reads Mark Complete and only moves the stage.

The status bar shows the active requirement's reference and criteria progress; clicking it focuses the sidebar. CodeLens lines at the top of any file linked to a requirement show that requirement and its criteria progress, with three shortcuts: Start with SpecAI, Tests (generates Playwright test code for the requirement and opens it in a new editor tab), and Open (opens the requirement in the web app). Opening a file linked to exactly one requirement makes that requirement active.

Automatic file linking

While a requirement is active, the extension watches the workspace on disk and links every file you create or change to that requirement as a traceability link — a stored link between a requirement and a file path that PR verification reads as a fallback match and to detect drift. Because it watches the filesystem rather than editor saves, files written by a terminal agent such as Claude Code are linked too. Linking is silent; the linked files appear in the Spec tab and are returned by spectrace_requirements_get_context to a connected agent, and PR verification reads them on its next run. The web app has no linked-files view today.

Not every change is linked:

Paths containing node_modules, .git, dist, build, out, .next, coverage, vendor, target, .spectrace, and similar dependency, VCS, and build directories are ignored.
Only files under a recognisable source directory (src, lib, app, packages, apps, tests, components, api, and others of that kind) with a source, style, markup, config, or markdown extension are considered.
A burst of more than eight file events inside two seconds — a git checkout, a package install, a build — is dropped rather than linked.

You can also link the current file by hand with Spectrace: Link Current File to Requirement (Cmd+Shift+L). The Unlink Current File from Requirement command is a placeholder that does nothing yet, and the web app has no unlink control; to remove a link, send an authenticated DELETE /api/v1/requirements/{requirementId}/linked-files/{linkId} request as described on Spec drift. When a changed file's path matches a subtask's wording, the extension offers to mark that subtask done; the suggestion is a dismissible notification.

Commands

All commands live under the Spectrace category in the command palette. Windows and Linux use Ctrl in place of Cmd.

Command	Shortcut	What it does
Open Spectrace Sidebar	`Cmd+Shift+R`	Focuses the Requirements view.
Sign In to Spectrace / Sign Out of Spectrace	—	Starts the browser sign-in; clears stored tokens.
Select Active Requirement	`Cmd+Shift+E`	Quick-pick to change the active requirement.
Start with SpecAI	—	Builds the context prompt and hands it to your agent.
End AI Coding Session	—	Ends a live SpecAI session.
Create Branch for Requirement	—	Suggests `feat/<ref>-<slug>` (for example `feat/sss-050-webhook-consolidation`), lets you edit it, then creates and checks out the branch.
Generate Commit Message	`Cmd+Shift+M`	Generates a message scoped to the active requirement and puts it in the Source Control input (and on the clipboard).
Link Current File to Requirement	`Cmd+Shift+L`	Adds a traceability link for the open file. (Unlink Current File from Requirement is registered but is a placeholder that does nothing yet.)
Mark Acceptance Criterion Complete	`Cmd+Shift+C`	Marks one criterion complete. It is driven by the CodeLens criterion lines and the sidebar checkboxes, which pass the criterion in; run bare from the palette it has nothing to act on and warns.
Complete Requirement	—	Same as the detail view's Create PR / Mark Complete button.
Copy Requirement Reference	—	Copies the active requirement's reference (for example `sss-050`).
Open Requirement in Browser	—	Opens the requirement in the web app.
Refresh Data	—	Re-fetches the selected project's requirements now (still a conditional request; the sidebar's refresh button is the one that bypasses the ETag cache).

Branch names in the feat/<ref>-… form matter beyond the editor: PR verification reads the requirement reference from the branch name to link the pull request. See Linking a PR to a requirement.

Settings

Setting	Default	What it does
`spectrace.apiUrl`	`https://spectrace.io`	Base URL of the Spectrace instance the extension talks to.
`spectrace.aiAgent`	`auto`	Which agent Start with SpecAI targets: `auto`, `copilot`, `cursor`, `windsurf`, `claude-code`, or `clipboard`. `auto` picks Cursor or Windsurf when you are in that editor, else an installed chat extension (Copilot, Cline, or Roo Code), else the Claude Code CLI if installed, else the clipboard.
`spectrace.autoSync`	`true`	Poll Spectrace in the background. Idle polls are conditional requests and cost nothing when nothing changed.
`spectrace.syncInterval`	`30`	Seconds between polls. Values under 10 are raised to 10.
`spectrace.showCodeLens`	`true`	Show the CodeLens lines on linked files.
`spectrace.showStatusBar`	`true`	Show the active requirement in the status bar.

How each agent receives the prompt differs. Copilot Chat and the Claude Code CLI (in the integrated terminal) receive it directly. Cursor and Windsurf open their chat with the prompt staged on the clipboard for you to paste. clipboard copies the prompt and opens the generated context file.

Limits

The extension does not show PR verification results. Those live on the pull request itself and on the requirement's PR verification tab in the web app. See Reading a verification result.
Gherkin test cases are generated and reviewed in the web app; the Test tab is read-only. The CodeLens Tests action generates Playwright code from the requirement into an unsaved editor tab; it consumes one ai_test_generation credit and stores nothing in Spectrace.
Automatic linking only runs while a requirement is active and only inside a workspace folder. Files outside the recognised directories or extensions above are never linked automatically; use Cmd+Shift+L for those.
Create PR & Submit for Review needs a GitHub account connected to the workspace under Settings → Integrations; without one, the request fails with an error shown in the detail view.

What done looks like

You are signed in, the sidebar lists your project's requirements under the four tabs, and selecting one shows its criteria in the detail view and its reference in the status bar. Editing a file under src/ while that requirement is active adds it to the Spec tab's file list within a few seconds.

If the sidebar stays on the welcome screen after the browser reports success, the callback did not reach the editor: check that the browser opened the editor's URL scheme (allow it if prompted), then run Spectrace: Sign In to Spectrace again. If the list is empty, check the project picker and the tab: new requirements start under Backlog.