planview

A local web viewer for MDX plan files. Browse, read, comment, and export your plans from the browser — no database, no cloud, everything stays on disk.

Install & run

No cloning required. Use npx:

npx @vtripathi/planview --dir ./your-plans-directory

Then open http://localhost:3000.

Options

--dir <path>    Directory containing .mdx plan files (default: current directory)
--port <port>   Port to listen on (default: 3000)
-h, --help      Show help

Examples

# Plans are in a ./plans folder relative to where you run the command
npx @vtripathi/planview --dir ./plans

# Absolute path
npx @vtripathi/planview --dir /home/user/my-project/plans

# Different port
npx @vtripathi/planview --dir ./plans --port 4000

Plans directory structure

Place .mdx files directly inside the directory you pass to --dir:

plans/
  my-feature.mdx
  another-plan.mdx

Each file can have optional frontmatter:

---
title: My Feature Plan
---

# Content here

If no title is set in frontmatter, the first # heading is used. Comments are stored as <slug>.comments.json alongside the plan file, auto-created when you add the first comment.

Features

| Feature | Description | |---------|-------------| | Browse | Home page lists all .mdx files in the directory | | Read | Full MDX rendering with rich components, mermaid diagrams, and syntax highlighting | | Comment | Click any h2/h3 heading to add an inline note | | History | Side drawer shows git log for each plan file | | Export | "Export HTML" button — print or save as PDF from the browser |

Supported MDX components

Planview ships with built-in components you can use in your .mdx files:

Callout

<Callout type="info" title="Note">
  Something worth highlighting.
</Callout>

Types: info, warning, tip, danger

Tabs

<Tabs labels={["Option A", "Option B"]}>
  <Tab>Content for Option A</Tab>
  <Tab>Content for Option B</Tab>
</Tabs>

Steps

<Steps>
  <Step title="Install dependencies">Run `npm install`</Step>
  <Step title="Configure">Set your environment variables</Step>
  <Step title="Run">Execute `npm start`</Step>
</Steps>

Badge

<Badge variant="success">Completed</Badge>
<Badge variant="warning">In Progress</Badge>
<Badge variant="error">Blocked</Badge>
<Badge variant="info">Review</Badge>

CodeBlock

<CodeBlock language="typescript" title="example.ts">
const greet = (name: string) => `Hello, ${name}`
</CodeBlock>

Mermaid diagrams

Fenced code blocks tagged mermaid render as diagrams:

```mermaid
flowchart TD
  A[Start] --> B{Decision}
  B -->|Yes| C[Do it]
  B -->|No| D[Skip]
```

GFM task lists

- [x] Done
- [ ] Not done

Note: Raw markdown tables are not supported. Use a component instead.

Workflow with visual-plan

planview pairs with the visual-plan Claude Code skill. The skill authors structured MDX plan documents; planview displays them.

1. Run /visual-plan in Claude Code to author a plan — output is a .mdx file
2. Run npx @vtripathi/planview --dir ./plans to view it
3. Click headings to comment, use the side drawer for git history
4. Export HTML to share or save as PDF

Publishing / contributing

The package is published to npm at @vtripathi/planview.

To build and publish a new version:

npm run build        # builds Next.js standalone output + copies static assets
npm version patch    # bumps version
npm publish --access public