{"id":47777230,"url":"https://github.com/bzon/spec-viewer","last_synced_at":"2026-04-08T10:00:43.103Z","repository":{"id":348653247,"uuid":"1199175814","full_name":"bzon/spec-viewer","owner":"bzon","description":"Local markdown viewer for AI agent specs — syntax highlighting, TOC, themes, live reload, Cmd+K search. Claude Code plugin included.","archived":false,"fork":false,"pushed_at":"2026-04-02T08:34:18.000Z","size":1037,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-03T15:52:16.221Z","etag":null,"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"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bzon.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-02T05:36:50.000Z","updated_at":"2026-04-02T08:34:21.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/bzon/spec-viewer","commit_stats":null,"previous_names":["bzon/spec-viewer"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/bzon/spec-viewer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bzon%2Fspec-viewer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bzon%2Fspec-viewer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bzon%2Fspec-viewer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bzon%2Fspec-viewer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bzon","download_url":"https://codeload.github.com/bzon/spec-viewer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bzon%2Fspec-viewer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31549900,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T16:28:08.000Z","status":"online","status_checked_at":"2026-04-08T02:00:06.127Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","claude-code","claude-code-plugin","cli","developer-tools","documentation","golang","live-reload","markdown","markdown-it","markdown-viewer","shiki","spec-viewer","syntax-highlighting"],"created_at":"2026-04-03T12:05:49.501Z","updated_at":"2026-04-08T10:00:43.093Z","avatar_url":"https://github.com/bzon.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# spec-viewer\n\n[![CI](https://github.com/bzon/spec-viewer/actions/workflows/ci.yml/badge.svg)](https://github.com/bzon/spec-viewer/actions/workflows/ci.yml)\n[![Release](https://github.com/bzon/spec-viewer/actions/workflows/release.yml/badge.svg)](https://github.com/bzon/spec-viewer/actions/workflows/release.yml)\n[![Go Report Card](https://goreportcard.com/badge/github.com/bzon/spec-viewer)](https://goreportcard.com/report/github.com/bzon/spec-viewer)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n[![GitHub release](https://img.shields.io/github/v/release/bzon/spec-viewer)](https://github.com/bzon/spec-viewer/releases/latest)\n\nA 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.\n\n![spec-viewer-screenshot](./spec-viewer.png)\n\n## Quick Install\n\n### Claude Code (recommended)\n\nTwo commands — the binary auto-installs on first session:\n\n```bash\nclaude plugin marketplace add bzon/spec-viewer\nclaude plugin install spec-viewer\n```\n\nThen use `/spec-viewer:view` in any Claude Code session:\n\n```\n/spec-viewer:view docs/specs/my-design.md\n/spec-viewer:view docs/\n```\n\n### Homebrew\n\n```bash\nbrew install bzon/tap/spec-viewer\n```\n\n## Usage\n\n```bash\n# View a single file\nspec-viewer README.md\n\n# View a directory of markdown files\nspec-viewer docs/\n\n# Use a specific theme\nspec-viewer --theme dracula docs/\n```\n\n### Search\n\nPress **Cmd+K** (macOS) or **Ctrl+K** to open the search palette. Searches headings, filenames, and full-text content across all files.\n\n### Instance reuse\n\nIf spec-viewer is already running, subsequent calls send the file to the existing instance instead of starting a new server.\n\n## Use with AI Agents\n\nspec-viewer is designed for agent-driven development workflows where agents generate markdown specs and plans.\n\n### How agents use it\n\nAny agent or plugin (like [Superpowers](https://github.com/obra/superpowers)) can invoke spec-viewer after writing a spec:\n\n```bash\n# Agent writes a spec, then opens it for the user to review\nspec-viewer docs/specs/2026-04-01-feature-design.md\n```\n\nThe viewer opens automatically in the browser. If a server is already running, the file is sent to the existing instance — no duplicate servers.\n\n### Example workflow with Superpowers\n\nWhen using the brainstorming or writing-plans skills, add a `/spec-viewer:view` call after the spec is written:\n\n```\n# After brainstorming produces a spec:\n/spec-viewer:view docs/superpowers/specs/2026-04-01-invoice-review-design.md\n\n# After writing-plans produces an implementation plan:\n/spec-viewer:view docs/superpowers/plans/2026-04-01-invoice-review.md\n```\n\n### Building your own integration\n\nAgents can call `spec-viewer` directly via shell:\n\n```bash\n# Start server and open file (first call)\nspec-viewer /path/to/spec.md\n# Output: spec-viewer: serving /path at http://localhost:XXXXX\n\n# Send file to existing server (subsequent calls)\nspec-viewer /path/to/another-spec.md\n# Output: spec-viewer: sent /path/to/another-spec.md to existing instance on port XXXXX\n```\n\nOr use the HTTP API on a running instance:\n\n```bash\ncurl -X POST http://localhost:PORT/api/open \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"path\": \"/absolute/path/to/spec.md\"}'\n```\n\n## Themes\n\nFive built-in themes: `github-light` (default), `github-dark`, `dracula`, `nord`, `solarized`.\n\n### Set a default theme\n\nCreate `~/.config/spec-viewer/config.yaml`:\n\n```yaml\ntheme: dracula\n```\n\n### Custom themes\n\nDrop a `.css` file in `~/.config/spec-viewer/themes/`:\n\n```bash\nspec-viewer --print-theme-template \u003e ~/.config/spec-viewer/themes/my-theme.css\n# Edit the file, then use: spec-viewer --theme my-theme\n```\n\n## Manual Install\n\nIf not using the Claude Code plugin or Homebrew:\n\n**Download binary:**\n\n```bash\n# macOS (Apple Silicon)\ncurl -sL https://github.com/bzon/spec-viewer/releases/latest/download/spec-viewer_darwin_arm64.tar.gz | tar xz\nsudo mv spec-viewer /usr/local/bin/\n\n# macOS (Intel)\ncurl -sL https://github.com/bzon/spec-viewer/releases/latest/download/spec-viewer_darwin_amd64.tar.gz | tar xz\nsudo mv spec-viewer /usr/local/bin/\n\n# Linux (amd64)\ncurl -sL https://github.com/bzon/spec-viewer/releases/latest/download/spec-viewer_linux_amd64.tar.gz | tar xz\nsudo mv spec-viewer /usr/local/bin/\n```\n\n**From source (requires Go):**\n\n```bash\ngo install github.com/bzon/spec-viewer/cmd/spec-viewer@latest\n```\n\n### Manual `/view` command (without plugin)\n\n```bash\nmkdir -p ~/.claude/commands\ncurl -o ~/.claude/commands/view.md \\\n  https://raw.githubusercontent.com/bzon/spec-viewer/main/.claude/commands/view.md\n```\n\n## CLI Reference\n\n```\nspec-viewer [flags] [path]\n\nArguments:\n  path                     Markdown file or directory (default: current dir)\n\nFlags:\n  --theme \u003cname\u003e           Theme name (default: github-light)\n  --port \u003cnumber\u003e          Server port (default: random)\n  --host \u003caddr\u003e            Bind address (default: 127.0.0.1)\n  --no-open                Don't auto-open the browser\n  --print-theme-template   Print CSS custom properties template\n  --version                Print version\n```\n\n## Features\n\n- Markdown rendering with [markdown-it](https://github.com/markdown-it/markdown-it)\n- Syntax highlighting for 25+ languages with [Shiki](https://shiki.style)\n- \"On this page\" TOC with active section tracking\n- Live reload on file save\n- Tree-grouped file list for directories\n- Cmd+K search across headings, filenames, and content\n- 5 built-in themes + custom theme support\n- Single instance reuse (no duplicate servers)\n- Inter + JetBrains Mono fonts embedded\n- Keyboard accessible\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbzon%2Fspec-viewer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbzon%2Fspec-viewer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbzon%2Fspec-viewer/lists"}