Plan Viewer

A fast, beautiful web app for browsing, searching, and reading markdown plan files generated by AI coding agents.

planviewer.dev

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.

Features

Plan Browser

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.

Multi-Folder Support

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:

Outline Panel

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

Rich Markdown Rendering

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

Search and Filter

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.

Completion Tracking

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.

Light and Dark Theme

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.

Live Updates

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.

Getting Started

Prerequisites

• Node.js 20+
• Vite+ (vp CLI) — or use npx vite-plus if not installed globally

Install and Run

git clone https://github.com/eltonvs/plan-viewer.git
cd plan-viewer
vp install
vp dev

Open http://localhost:5173 in your browser.

Configuration

To change the default plans directory, edit vite.config.ts:

plansApiPlugin({ plansDir: "/path/to/your/plans" });

Build for Production

vp build
vp preview

Tech Stack

Project Structure

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

Development

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 locally

Contributing

Contributions are welcome! Feel free to open an issue or submit a pull request.

License

MIT