A lightweight, read-only viewer for OpenSpec content — browse specs, changes, and tasks with structure.

繁體中文

spek turns your local OpenSpec directory into a navigable, searchable interface. Instead of reading raw Markdown files in a text editor, spek provides structured browsing with BDD syntax highlighting, task progress tracking, and full-text search.

Live Demo — Try it instantly in your browser, no install needed.

Available in two forms:

• Web — Local Express + React app, accessible in any browser
• VS Code Extension — Integrated Webview Panel within your editor

Both are read-only and local-only. No server deployment, no authentication, no data leaves your machine.

• Dashboard — Overview of specs count, changes count, and task completion rates
• Specs Browser — Alphabetical listing with detail view and revision history
• Changes Timeline — Active and archived changes with tabbed views (Proposal / Design / Tasks / Specs)
• BDD Syntax Highlighting — Visual distinction for WHEN/GIVEN, THEN, AND, MUST/SHALL keywords
• Task Progress — Checkbox parsing with section-grouped progress bars
• Full-text Search — Cmd+K / Ctrl+K to search across all specs and changes
• Dark / Light Theme — Toggle between themes; dark by default
• Spec History — Git-based timestamp tracking for spec revisions
• Responsive Layout — Works on various screen sizes

Overview of specs count, changes count, and task completion rates.

Alphabetical listing of all spec topics with filter support.

Visual distinction for BDD keywords — WHEN/GIVEN (blue), THEN (green), AND (gray), MUST/SHALL (red).

Active and archived changes listed chronologically.

Tabbed view with Proposal, Design, Tasks, and Specs sections.

Cmd+K / Ctrl+K to search across all specs and changes.

git clone https://github.com/kewang/spek.git
cd spek
npm install
npm run dev

Open http://localhost:5173, enter a path to a repo containing an openspec/ directory, and start browsing.

Install from the Visual Studio Marketplace. The extension activates automatically when your workspace contains openspec/config.yaml.

Commands:

• spek: Open spek — Open the viewer panel
• spek: Search OpenSpec — Open search dialog

spek expects the following structure under your repository:

{repo}/openspec/
├── config.yaml
├── specs/
│   └── {topic}/
│       └── spec.md              # BDD-formatted specification
└── changes/
    ├── {active-change}/         # In-progress changes
    │   ├── .openspec.yaml
    │   ├── proposal.md
    │   ├── design.md
    │   ├── tasks.md
    │   └── specs/               # Delta specs for this change
    └── archive/
        └── {YYYY-MM-DD-desc}/   # Archived changes (same structure)

packages/
├── core/       # @spek/core — Pure logic (scanner, parser, types)
├── web/        # @spek/web — Express API + React SPA
└── vscode/     # spek-vscode — VS Code Extension

The frontend communicates through an ApiAdapter interface with two implementations:

• FetchAdapter — Web version, calls Express REST API over HTTP
• MessageAdapter — VS Code version, uses postMessage IPC with the extension host

This allows the same React UI to run in both environments without code changes.

npm install              # Install all workspace dependencies
npm run dev              # Start Vite (5173) + Express (3001)
npm run build            # Build core + web
npm run build:core       # Build @spek/core only
npm run build:webview    # Build webview assets for VS Code extension
npm run build:vscode     # Build VS Code extension
npm run type-check       # TypeScript type check

Requirements: Node.js 22+

This project was inspired by 龍哥（高見龍）'s articles on SDD (Spec Driven Development). spek was created because Spectra does not have a Linux version.

• SDD — Spec Driven Development
• Spectra with OpenSpec

MIT