SpecViber for VS Code

This extension is the VS Code surface of SpecViber — a shared working layer for spec-driven AI development. The extension brings SpecViber's document-related features directly into your editor. It is not a standalone tool — you need an active SpecViber workspace to use it.

Vibe coding that actually holds together

AI gets you moving fast — until the work scatters. The agent forgets what you decided, "done" turns out not to be done, and every session starts with rebuilding context by hand.

SpecViber closes that gap by giving the developer and the AI agent one shared working layer for the work itself: planning, context, tasks, progress, relations and verification. Same documents. Same task objects. Same state. The agent stops working from a loose snapshot of the project and starts working against the same live reality as you.

It does this without taking over your setup. Your code stays in your repo, your markdown stays in your project, your git workflow and AI assistant stay where they are. SpecViber adds the working layer around them.

The full loop, on one shared layer

The core unit is the action spec — a living markdown document that carries the work from the first problem statement to a checked, documented delivery.

• Planning, in the document. The agent drafts problem, goal, context, related docs, plan and verification criteria. You steer with inline @comments where the decisions belong. The agent responds and sharpens the spec until it is ready to execute.
• Execution, with the spec as a live map. As work moves, the agent keeps the spec current: checkboxes change state (todo, in_progress, done, dropped, blocked, needs_research), blockers are flagged, missing steps appear. You follow it in real time — in the document, on the Kanban, or through the relation graph.
• Verification before close. Every action spec ends with explicit checks. The agent runs what it can itself (terminal, syntax, tests, API). A close-guard prevents the spec from being marked done while open steps or failed checks remain. Done means verified — not "the chat said so."

What makes the layer work

• Markdown that does the work. Ordinary .md files become structured work objects with status, progress, comments, relations, checkboxes and task connections — readable for you, actionable for the agent.
• Relations you can walk. depends_on, supersedes, references, part_of, conflicts — explicit and explorable in a relation graph. The agent loads the right context before acting; you stop tracking impact by hand.
• Kanban as a live cockpit. Tasks and action specs share one board. Assign work to the agent, follow the card, watch progress update as the work moves.
• MCP-native. Works with Copilot, Claude Code, Cursor and other MCP clients. No vendor lock-in.
• Privacy by design. Your code and markdown never leave your machine. Only the coordinating metadata lives in SpecViber.

SpecViber drops into an existing project — no greenfield required — and is built to keep working as the project grows.

Learn more at specviber.com.

SpecViber is a web app — this is its VS Code surface

The full SpecViber product is a web app: Kanban, relation graphs, workspace management, classification, audit, registration of new documents, AI MCP integration, the whole working method.

This extension makes SpecViber's document-related features available directly inside VS Code, so you do not have to switch to the browser every time you edit a tracked markdown file. It is a thin surface on top of the same SpecViber backend and the same workspace you already use on the web.

For board work, cross-workspace navigation, full relation graphs, onboarding and governance, use the web app.

What the extension brings into VS Code

Navigator Sidebar

Browse, search and open documents in your SpecViber workspace from a dedicated activity-bar view. Jump by document ID (#D123), filter by status or area, and open straight into the viewer or properties panel.

Document viewer

Open any tracked markdown as a SpecViber-aware document: rendered content, multi-state checkboxes, inline @comments, metadata and outline — all in one reading view. Switch to edit mode with instant preview and all tools available when needed.

Document Properties

Open the SpecViber properties panel for the current markdown file: status, type, areas, quality, summary, checklist, relations, comments, notes, and history — all in one panel next to your code.

What you can do without leaving the editor

• update document metadata while editing the source
• toggle multi-state checkboxes without losing your place in the file
• read and write inline @comments exactly where they belong in the document
• jump between related documents through the same relations your action specs use
• navigate large workspaces by ID, area, or search instead of by filesystem path

For board work, relation graphs, workspace administration and the broader SpecViber workflow, use the web app at specviber.com.

Requirements

• An active SpecViber SaaS account and workspace — start at specviber.com
• A local SpecViber SaaS client (ZIP downloaded from your SpecViber account, unpacked into a folder served by a local web server such as XAMPP)
• Node.js 18+ (for the bundled MCP server)
• VS Code 1.85+ with GitHub Copilot

The extension is a thin VS Code surface on top of the SaaS client. The client provides the local content API and the MCP server that the extension and Copilot talk to.

Getting Started

The extension works against any VS Code project once that project is connected to your SpecViber workspace through the local SaaS client.

1. Install the extension from the Marketplace.

2. Install the SaaS client — download the ZIP from your SpecViber account, unpack it to a path your local web server serves (for example C:/xampp/htdocs/specviber_saas_client/), then install MCP dependencies:

   cd path/to/specviber_saas_client/mcp-server
   npm install
   

3. Create a workspace in the SpecViber web UI, copy the generated API token and note the workspace ID.

4. Open your project in VS Code and create .vscode/mcp.json:

   {
     "servers": {
       "specviber": {
         "type": "stdio",
         "command": "node",
         "args": ["<absolute-path>/specviber_saas_client/mcp-server/index.js"],
         "env": {
           "SPEVI_API_URL": "https://app.specviber.com/api/docs",
           "SPEVI_CONTENT_URL": "http://localhost/<your-client-path>/api/docs/content",
           "SPEVI_API_TOKEN": "<your-token>",
           "SPEVI_DEFAULT_WORKSPACE": "<workspace-id>",
           "SPEVI_ALLOWED_WORKSPACES": "<workspace-id>"
         }
       }
     }
   }
   

   SPEVI_API_URL points at the SaaS metadata API. SPEVI_CONTENT_URL points at the local SaaS client — your .md files stay on disk and never leave your machine.

5. Configure the extension in VS Code Settings (klick the ⚙️): set spevi.apiUrl, spevi.contentUrl and spevi.workspaceId to the same values you used in mcp.json (or run SpecViber: Select Workspace).

6. Reload VS Code. In Copilot Chat, run spevi_dashboard to confirm the connection.

7. Open any tracked .md file and use Document Properties, Document Viewer or Edit with Preview from the editor title bar or right-click menu.

Need a self-hosted SpecViber instead of SaaS? Point SPEVI_API_URL / spevi.apiUrl at your own instance and omit SPEVI_CONTENT_URL / spevi.contentUrl to use single-mode. (This mode is currently not available. Contact Inducera AB to get an update...)

Configuration

Commands

• SpecViber: Document Properties — open the metadata and workflow panel for the current markdown file
• SpecViber: Document Viewer — open the rendered SpecViber-aware document view
• SpecViber: Edit with Preview — split editor with raw markdown and live SpecViber-aware preview
• SpecViber: Open Document by ID — jump straight to a specific SpecViber document by #D… ID
• SpecViber: Open Properties by ID — open the properties panel without first locating the file
• SpecViber: Select Workspace — switch workspace context from inside VS Code
• SpecViber: Reset Stored Credentials — clear locally stored credentials and re-authenticate

Learn more about SpecViber

The extension shows one slice of SpecViber — the document-editing slice. The full working method, the kanban, the relation graphs, the AI MCP integration, the onboarding, governance, and licensing all live in the web app:

• specviber.com — product overview, methodology, and access

Development

Project Structure

vscode-spevi/
├── src/
│   ├── extension.ts          # Entry point — command registration, auth, config
│   ├── api-client.ts         # HTTP client (http/https, Bearer auth, 15s timeout)
│   ├── doc-resolver.ts       # Maps file URI → SpeVi doc_id (cache with 5-min TTL)
│   ├── properties-panel.ts   # WebviewPanel — all message handlers + HTML template
│   └── webview/
│       ├── properties.js     # Webview UI logic (runs in webview context)
│       └── properties.css    # VS Code theme-aware styles (--vscode-* variables)
├── dist/                     # esbuild output (bundled, not committed in dev)
├── out/                      # tsc output (for dev/debug, not in .vsix)
├── resources/
│   ├── icon.svg              # Command icon
│   ├── marketplace-icon.png  # Marketplace listing icon (256x256)
│   └── preview-*.png         # README / marketplace preview images
├── .vscode/
│   ├── launch.json           # F5 → Extension Development Host
│   └── tasks.json            # Default build task (npm compile)
├── package.json              # Extension manifest
├── tsconfig.json             # TypeScript config (ES2020, commonjs)
├── .vscodeignore             # Files excluded from .vsix
├── CHANGELOG.md
└── README.md

Setup

cd vscode-spevi
npm install

Build Commands

Development Workflow

1. npm run compile — or just press F5 (launch.json uses preLaunchTask)
2. An Extension Development Host window opens
3. Open any .md file → right-click → SpeVi: Document Properties
4. After code changes: Ctrl+Shift+P → "Developer: Reload Window" in the host

Architecture Notes

• No runtime dependencies — only devDependencies. The extension uses Node.js built-in http/https modules.
• esbuild bundles all TypeScript into a single dist/extension.js (18 KB minified).
• Webview files (src/webview/) are plain JS/CSS, loaded at runtime via asWebviewUri() — not bundled by esbuild.
• Auth uses VS Code SecretStorage — password is prompted once, stored securely, reused across sessions.
• Doc resolver maps vscode.Uri → doc_id by extracting the repo-relative path and querying list.php. Results are cached for 5 minutes.

Installation

From a packaged VSIX

# Build the package
cd vscode-spevi
npm install
npm run package
# → produces vscode-spevi-X.Y.Z.vsix

# Install in VS Code
code --install-extension vscode-spevi-X.Y.Z.vsix

Or in VS Code: Ctrl+Shift+P → "Extensions: Install from VSIX..." → select the .vsix file.

From source (development)

cd vscode-spevi
npm install

Then press F5 to launch the Extension Development Host.

Packaging and Release

Local or team distribution

1. Build: npm run package → vscode-spevi-X.Y.Z.vsix
2. Share the .vsix file (email, shared drive, git release)
3. Recipients install via code --install-extension <file>.vsix

Version bumping

# Update version in package.json, then:
npm run package

Follow semver: patch (0.1.1) for fixes, minor (0.2.0) for features, major (1.0.0) for breaking changes.

Visual Studio Marketplace

Requires a publisher account at https://marketplace.visualstudio.com/manage.

# One-time: login
npx vsce login specviber

# Publish
npx vsce publish

Open VSX

npx ovsx publish vscode-spevi-X.Y.Z.vsix -p <token>

Updating

After installing a new .vsix version, the old version is automatically replaced. Reload VS Code to activate.

code --install-extension vscode-spevi-X.Y.Z.vsix
# Replaces the older installed version automatically

Uninstalling

code --uninstall-extension specviber.vscode-spevi

Or: Extensions sidebar → find SpecViber → Uninstall.