Beautiful reading experience for OpenSpec specification files and project documentation.
AI-assisted development generates specs, proposals, and designs faster than ever. But reviewing structured markdown in a terminal or a GitHub diff is painful. When specs are hard to read, they don't get read.
SpecReader gives your specifications a proper reading experience. Collapsible requirements, themed reading modes, and structured navigation make it natural to review proposals and specs, whether they're yours or someone else's.
npx @davevdveen/spec-reader@latestWorks on any project directory. Auto-detects OpenSpec folders and renders everything readable: specs, proposals, READMEs, configs, and more.
Try it on the OpenSpec framework itself:
git clone https://github.com/Fission-AI/OpenSpec && cd OpenSpec && npx @davevdveen/spec-reader@latestSpecReader includes a skill for AI coding agents (Claude Code, OpenCode) that opens the viewer for any PR or branch:
/read-specs # open specs for current branch
/read-specs 42 # checkout PR #42 and open its specs
/read-specs feature/xyz # checkout branch and open specs
Install the skill in your project:
npx @davevdveen/spec-reader@latest initThis auto-detects your agent (Claude Code, OpenCode, or both) and installs the skill in the right place.
| Scope | Shows |
|---|---|
| Specs | OpenSpec files |
| Docs | All markdown files |
| All | All readable files (.md, .yaml, .yml, .txt, extensionless) |
| Search | Filter across all files |
Four reading themes, each with light and dark variants:
| Theme | Font |
|---|---|
| Original | Sans-serif |
| Paper | Georgia serif |
| Calm | Serif, warm tones |
| Mono | Monospace |
Follows system light/dark preference with manual override.
spec-reader # serve current directory
spec-reader ~/projects/myapp # serve any project
spec-reader export openspec/ dist/ # export static site
spec-reader init # install AI agent skill
view-proposal add-dark-mode # open viewer on a proposal| Key | Action |
|---|---|
← → |
Previous / next page |
↑ ↓ |
Scroll content |
- |
Expand / collapse all sections in the document |
Cmd+Shift+R |
Toggle sidebar |
A single HTML file served by a shell script that walks your directory, generates a manifest, and starts Python's built-in HTTP server. Zero runtime dependencies beyond Python 3.
File changes are detected every 3 seconds. Edit a spec, see it update in the viewer.
- Python 3 (used to serve files locally)
- Node.js (for
npxinstallation only) - gh CLI (optional, for the
/read-specsskill to checkout PRs)
Works on macOS, Linux, and Windows (WSL). Tested in Safari, should work in any modern browser.
npm install -g @davevdveen/spec-reader
npx @davevdveen/spec-reader@latestMIT