spec-viewer

A local markdown viewer for reading specs, plans, and documentation generated by AI coding agents. Renders markdown in the browser with syntax highlighting, table of contents, configurable themes, live reload, and cross-file search.

Quick Install

Claude Code (recommended)

Two commands — the binary auto-installs on first session:

claude plugin marketplace add bzon/spec-viewer
claude plugin install spec-viewer

Then use /spec-viewer:view in any Claude Code session:

/spec-viewer:view docs/specs/my-design.md
/spec-viewer:view docs/

Homebrew

brew install bzon/tap/spec-viewer

Usage

# View a single file
spec-viewer README.md

# View a directory of markdown files
spec-viewer docs/

# Use a specific theme
spec-viewer --theme dracula docs/

Search

Press Cmd+K (macOS) or Ctrl+K to open the search palette. Searches headings, filenames, and full-text content across all files.

Instance reuse

If spec-viewer is already running, subsequent calls send the file to the existing instance instead of starting a new server.

Use with AI Agents

spec-viewer is designed for agent-driven development workflows where agents generate markdown specs and plans.

How agents use it

Any agent or plugin (like Superpowers) can invoke spec-viewer after writing a spec:

# Agent writes a spec, then opens it for the user to review
spec-viewer docs/specs/2026-04-01-feature-design.md

The viewer opens automatically in the browser. If a server is already running, the file is sent to the existing instance — no duplicate servers.

Example workflow with Superpowers

When using the brainstorming or writing-plans skills, add a /spec-viewer:view call after the spec is written:

# After brainstorming produces a spec:
/spec-viewer:view docs/superpowers/specs/2026-04-01-invoice-review-design.md

# After writing-plans produces an implementation plan:
/spec-viewer:view docs/superpowers/plans/2026-04-01-invoice-review.md

Building your own integration

Agents can call spec-viewer directly via shell:

# Start server and open file (first call)
spec-viewer /path/to/spec.md
# Output: spec-viewer: serving /path at http://localhost:XXXXX

# Send file to existing server (subsequent calls)
spec-viewer /path/to/another-spec.md
# Output: spec-viewer: sent /path/to/another-spec.md to existing instance on port XXXXX

Or use the HTTP API on a running instance:

curl -X POST http://localhost:PORT/api/open \
  -H 'Content-Type: application/json' \
  -d '{"path": "/absolute/path/to/spec.md"}'

Themes

Five built-in themes: github-light (default), github-dark, dracula, nord, solarized.

Set a default theme

Create ~/.config/spec-viewer/config.yaml:

theme: dracula

Custom themes

Drop a .css file in ~/.config/spec-viewer/themes/:

spec-viewer --print-theme-template > ~/.config/spec-viewer/themes/my-theme.css
# Edit the file, then use: spec-viewer --theme my-theme

Manual Install

If not using the Claude Code plugin or Homebrew:

Download binary:

# macOS (Apple Silicon)
curl -sL https://github.com/bzon/spec-viewer/releases/latest/download/spec-viewer_darwin_arm64.tar.gz | tar xz
sudo mv spec-viewer /usr/local/bin/

# macOS (Intel)
curl -sL https://github.com/bzon/spec-viewer/releases/latest/download/spec-viewer_darwin_amd64.tar.gz | tar xz
sudo mv spec-viewer /usr/local/bin/

# Linux (amd64)
curl -sL https://github.com/bzon/spec-viewer/releases/latest/download/spec-viewer_linux_amd64.tar.gz | tar xz
sudo mv spec-viewer /usr/local/bin/

From source (requires Go):

go install github.com/bzon/spec-viewer/cmd/spec-viewer@latest

Manual /view command (without plugin)

mkdir -p ~/.claude/commands
curl -o ~/.claude/commands/view.md \
  https://raw.githubusercontent.com/bzon/spec-viewer/main/.claude/commands/view.md

CLI Reference

spec-viewer [flags] [path]

Arguments:
  path                     Markdown file or directory (default: current dir)

Flags:
  --theme <name>           Theme name (default: github-light)
  --port <number>          Server port (default: random)
  --host <addr>            Bind address (default: 127.0.0.1)
  --no-open                Don't auto-open the browser
  --print-theme-template   Print CSS custom properties template
  --version                Print version

Features

• Markdown rendering with markdown-it
• Syntax highlighting for 25+ languages with Shiki
• "On this page" TOC with active section tracking
• Live reload on file save
• Tree-grouped file list for directories
• Cmd+K search across headings, filenames, and content
• 5 built-in themes + custom theme support
• Single instance reuse (no duplicate servers)
• Inter + JetBrains Mono fonts embedded
• Keyboard accessible

License

MIT