A fast, beautiful web app for browsing, searching, and reading markdown plan files generated by AI coding agents.
AI coding agents like Claude Code, Cursor, Codex, and others generate markdown implementation plans during the planning phase of complex development tasks. Plan Viewer gives you a dedicated UI to browse, search, and read them — with rich markdown rendering, syntax highlighting, an interactive outline, and more.
Works out of the box with Claude Code plans (~/.claude/plans/), and you can open any folder containing .md files to view plans from any agent or project.
Browse all your plans sorted by modification time. Each plan displays its title (extracted from the first # heading), file size, and how recently it was modified. Plans are organized in collapsible folder groups with smooth slide animations. Reads from ~/.claude/plans/ by default, but works with any folder of markdown files.
Need to view plans from a different agent or project? Use the Open Folder button to add any directory containing .md files. Each folder appears as a separate accordion section in the sidebar.
Common plan file locations:
| Agent | Default Path |
|---|---|
| Claude Code | ~/.claude/plans/ |
| Cursor | ~/.cursor/plans/ |
| Superpowers plugin | docs/superpowers/plans/ and docs/superpowers/specs/ (in project root) |
| Any agent | Open any folder containing .md files via the folder picker |
A collapsible right-side table of contents that makes navigating long plans effortless:
- Heading extraction — automatically parses all headings (h1 through h6) from the markdown
- Scroll-spy — highlights the currently visible section as you scroll through the plan
- Smooth-scroll navigation — click any heading in the outline to scroll directly to that section
- Inline markdown — renders
`code`, bold, and italic formatting within heading text - Responsive width — adapts to your screen size (wider on larger displays)
- Persistent preference — remembers whether you prefer the outline open or closed across sessions
- Slide animation — smoothly slides in and out when toggling visibility
Full GitHub Flavored Markdown support:
- Syntax-highlighted code blocks in 150+ languages via highlight.js
- Tables with proper alignment and borders
- Task lists with checkboxes
- Blockquotes, horizontal rules, and nested lists
- Inline code, links with external indicators, bold, and italic text
Real-time search filters plans instantly by title or file path as you type. When you have completed plans you no longer need to see, toggle them off with the visibility button in the sidebar header.
Mark any plan as implemented with a single click on the checkbox in the plan header or by hovering over a plan in the sidebar. The "Implemented" badge animates in smoothly. Completed plans are grouped under a collapsible "Implemented" section within each folder. Your completion status persists in localStorage across sessions.
Switch between light and dark modes with the theme toggle in the sidebar. All colors transition smoothly — backgrounds, text, borders, and shadows animate over 300ms for a polished feel. Your preference is saved and restored on reload.
The viewer polls for content changes every 5 seconds. When your AI agent creates or modifies a plan, it appears in the viewer automatically — no manual refresh needed. Stale data is refreshed after 30 seconds.
git clone https://github.com/eltonvs/plan-viewer.git
cd plan-viewer
vp install
vp devOpen http://localhost:5173 in your browser.
To change the default plans directory, edit vite.config.ts:
plansApiPlugin({ plansDir: "/path/to/your/plans" });vp build
vp preview| Category | Technology |
|---|---|
| Framework | React 19 |
| Routing | TanStack Router |
| Data Fetching | TanStack Query |
| Styling | Tailwind CSS v4 with oklch color system |
| Components | shadcn/ui (Radix primitives) |
| Markdown | react-markdown + rehype-highlight |
| Toolchain | Vite+ (Vite, Vitest, Oxlint, Oxfmt) |
| Language | TypeScript 5.9 |
src/
components/
layout/ # AppShell, Sidebar
plan-list/ # PlanListItem, PlanSearch, FolderAccordion
plan-viewer/ # PlanViewer, PlanHeader, MarkdownRenderer, OutlinePanel
ui/ # shadcn components (Button, Badge, Tooltip, etc.)
hooks/ # usePlans, usePlanContent, useActiveHeading, useTheme
lib/ # API client, heading extraction, File System Access helpers
server/ # Vite plugin that serves the plans REST API
context/ # FolderContext provider for browser folder sources
types/ # Shared TypeScript interfaces
vp dev # Start dev server with hot reload
vp test # Run tests via Vitest
vp check # Type check + lint + format check
vp check --fix # Auto-fix formatting issues
vp build # Production build
vp preview # Preview the production build locallyContributions are welcome! Feel free to open an issue or submit a pull request.