https://github.com/bzon/spec-viewer
Local markdown viewer for AI agent specs — syntax highlighting, TOC, themes, live reload, Cmd+K search. Claude Code plugin included.
https://github.com/bzon/spec-viewer
ai-agents claude-code claude-code-plugin cli developer-tools documentation golang live-reload markdown markdown-it markdown-viewer shiki spec-viewer syntax-highlighting
Last synced: 3 months ago
JSON representation
Local markdown viewer for AI agent specs — syntax highlighting, TOC, themes, live reload, Cmd+K search. Claude Code plugin included.
- Host: GitHub
- URL: https://github.com/bzon/spec-viewer
- Owner: bzon
- License: mit
- Created: 2026-04-02T05:36:50.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-04-02T08:34:18.000Z (3 months ago)
- Last Synced: 2026-04-03T15:52:16.221Z (3 months ago)
- Topics: ai-agents, claude-code, claude-code-plugin, cli, developer-tools, documentation, golang, live-reload, markdown, markdown-it, markdown-viewer, shiki, spec-viewer, syntax-highlighting
- Language: Go
- Size: 1010 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# spec-viewer
[](https://github.com/bzon/spec-viewer/actions/workflows/ci.yml)
[](https://github.com/bzon/spec-viewer/actions/workflows/release.yml)
[](https://goreportcard.com/report/github.com/bzon/spec-viewer)
[](https://opensource.org/licenses/MIT)
[](https://github.com/bzon/spec-viewer/releases/latest)
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:
```bash
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
```bash
brew install bzon/tap/spec-viewer
```
## Usage
```bash
# 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](https://github.com/obra/superpowers)) can invoke spec-viewer after writing a spec:
```bash
# 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:
```bash
# 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:
```bash
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`:
```yaml
theme: dracula
```
### Custom themes
Drop a `.css` file in `~/.config/spec-viewer/themes/`:
```bash
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:**
```bash
# 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):**
```bash
go install github.com/bzon/spec-viewer/cmd/spec-viewer@latest
```
### Manual `/view` command (without plugin)
```bash
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 Theme name (default: github-light)
--port Server port (default: random)
--host 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](https://github.com/markdown-it/markdown-it)
- Syntax highlighting for 25+ languages with [Shiki](https://shiki.style)
- "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