Render .plan.md files as rich interactive plan views in VS Code — matching Cursor IDE's native plan experience.
Install from VS Code Marketplace
What is a
.plan.mdfile? It's a markdown file with YAML frontmatter that defines a plan: a name, overview, and a list of todos with statuses. Cursor IDE renders these as interactive plan views. This extension brings that same experience to VS Code.
The file must end with .plan.md — for example my-project.plan.md. Regular .md files are not affected by this extension.
Every .plan.md file must start with a valid YAML frontmatter block. The extension will not render without it.
---
name: "Short plan title"
overview: "One-line description of the plan"
todos:
- id: <uuid>
content: "Description of the task"
status: pending
isProject: false
---| Field | Type | Required | Description |
|---|---|---|---|
name |
string | Yes | Title shown at the top of the plan view |
overview |
string | No | Subtitle shown below the title |
todos |
array | Yes | List of task items (can be empty []) |
todos[].id |
string (UUID) | Yes | Unique identifier — must be a valid UUID |
todos[].content |
string | Yes | The task description |
todos[].status |
string | Yes | One of: pending, completed, in-progress, error |
isProject |
boolean | No | Shows a "Project" badge on the plan view |
Each todo requires a unique UUID. There are several ways to generate one:
Terminal (macOS / Linux):
uuidgen
# Example output: A1B2C3D4-0001-4000-8000-000000000001Node.js / JavaScript:
crypto.randomUUID()
// Example output: "a1b2c3d4-0001-4000-8000-000000000001"Python:
import uuid
str(uuid.uuid4())
# Example output: "a1b2c3d4-0001-4000-8000-000000000001"Online: uuidgenerator.net
Tip: You don't need to generate UUIDs manually — use the + New button in the Plan View to add tasks with auto-generated UUIDs.
Save the following as my-feature.plan.md:
---
name: "API Integration"
overview: "Integrate the payment gateway into the checkout flow"
todos:
- id: f47ac10b-58cc-4372-a567-0e02b2c3d479
content: "Read the Stripe API documentation"
status: completed
- id: 6ba7b810-9dad-11d1-80b4-00c04fd430c8
content: "Create a Stripe account and get API keys"
status: completed
- id: 6ba7b811-9dad-11d1-80b4-00c04fd430c8
content: "Implement the checkout session endpoint"
status: in-progress
- id: 6ba7b812-9dad-11d1-80b4-00c04fd430c8
content: "Add webhook handler for payment confirmation"
status: pending
- id: 6ba7b813-9dad-11d1-80b4-00c04fd430c8
content: "Write integration tests"
status: pending
isProject: false
---
## Notes
Add any context, links, or reference material here. This section renders as formatted markdown.
- [Stripe API Docs](https://stripe.com/docs/api)
- Webhook secret stored in `.env` as `STRIPE_WEBHOOK_SECRET`Click checkboxes to toggle todos between pending and completed. Changes write directly to the YAML frontmatter — integrated with VS Code's undo/redo (Cmd+Z / Ctrl+Z).
A progress bar at the bottom shows completion at a glance: 8 / 12 (67%).
Click any text to edit it in place:
- Plan title — click the heading to rename
- Overview — click to edit the description
- Todo content — click any task's text to rewrite it
- Markdown body — click anywhere in the rendered content to edit
No mode switching, no raw YAML — edit the rich view directly.
- + New button below the task list adds a new todo
- Hover any task to reveal the × delete button
Fenced code blocks render with syntax highlighting for TypeScript, JavaScript, JSON, YAML, Python, Bash, CSS, and HTML. Each block includes:
- Language label in the header
- Copy button — one click to copy the code
Adapts to VS Code's light, dark, and high-contrast themes using native CSS variables. Syntax highlighting colors match VS Code's default Dark+ and Light+ themes.
Everything below the YAML frontmatter renders as formatted markdown:
- Headings, paragraphs, and blockquotes
- Tables with proper alignment
- Ordered and unordered lists
- Task list checkboxes (clickable)
- Inline code and fenced code blocks
- Links and images
.plan.md files automatically open in Plan View — even if they were previously opened as raw text. To see the source, right-click the tab → Open With → Text Editor.
Hover over any task to reveal the ≡ drag handle. Grab it and drag to reorder tasks — the new order saves directly to the YAML frontmatter.
Filter your task list with pill buttons above the todos:
- All — show everything
- Pending — only uncompleted tasks
- Completed — only finished tasks
Filtering is instant (CSS-only, no re-render).
Scroll position is maintained across checkbox toggles, add/delete operations, and undo/redo. No more jumping back to the top after every interaction.
Click any task's status badge to cycle through statuses. The badge rotates: pending → in-progress → completed → pending. Faster than toggling the checkbox when you want to mark a task as in-progress rather than jumping straight to completed.
Press Enter to quickly add a new task. The new task appears at the bottom of the todo list with status pending and an auto-generated UUID — ready to edit immediately.
Open the command palette (Cmd+Shift+P) and run Plan View: New Plan File. A save dialog lets you choose a location and name. The file is created with valid YAML frontmatter and two placeholder tasks, then immediately opens in Plan View.
Press Ctrl+F / Cmd+F to open the search bar at the top of the plan view. As you type:
- Matching text is highlighted in both the todo list and the markdown body
- Non-matching todos are hidden so you can focus on relevant tasks
- A match count shows how many results were found
- Press Escape or click × to close search and clear highlights
Click the $(export) Export icon in the editor title bar, or run Plan View: Export Plan from the command palette. Three formats are available:
| Format | Output |
|---|---|
| HTML | Standalone .html file — opens in any browser, no VS Code required |
| Opens a print-ready page in your browser; use Cmd+P → Save as PDF | |
| Docx | Word-compatible .docx file — opens in Word and LibreOffice |
The exported file is saved next to the .plan.md source and revealed in Finder / Explorer.
The extension reads the YAML frontmatter format used by Cursor's plan feature:
---
name: "My Project Plan"
overview: "Short description of the plan"
todos:
- id: a1b2c3d4-0001-4000-8000-000000000001
content: "First task to complete"
status: pending
- id: a1b2c3d4-0001-4000-8000-000000000002
content: "Second task"
status: completed
- id: a1b2c3d4-0001-4000-8000-000000000003
content: "Third task in progress"
status: in-progress
isProject: false
---
# Notes
Any markdown content below the closing `---` renders as formatted text.| Value | Display |
|---|---|
pending |
Unchecked checkbox |
completed |
Checked with strikethrough |
in-progress |
Blue badge |
error |
Red badge |
- VS Code 1.85.0 or later
The extension registers a CustomTextEditorProvider for *.plan.md files. When you open a plan file:
- Parser extracts the YAML frontmatter (name, overview, todos) and markdown body
- HTML Builder renders a rich webview with interactive checkboxes, progress bar, and formatted markdown
- Webview JS handles clicks, inline editing, and sends messages back to the extension
- Serializer applies surgical regex updates to the YAML — only the changed field is modified, preserving all formatting
All changes integrate with VS Code's edit history. Undo, redo, and save work as expected.
- HTML-to-markdown conversion may lose some inline formatting on save
- No file watcher for external changes outside VS Code
- New Plan File — command palette action scaffolds a
.plan.mdwith correct frontmatter - Search — Ctrl+F / Cmd+F to search todos and markdown body with live highlights
- Export — export as HTML, PDF, or Docx from the editor title bar or command palette
- Status cycling — click the status badge to cycle through pending → in-progress → completed
- Keyboard shortcut — press Enter to quickly add a new task
- Test coverage — 43 tests (up from 28), covering all serializer functions
- Scroll position preserved across checkbox toggles, add/delete, and undo/redo
- Drag-and-drop todo reordering with drag handle
- Status filter bar (All / Pending / Completed)
Initial release.
- Rich plan view for
*.plan.mdfiles - Interactive checkboxes with undo/redo
- Inline editing of all fields
- Syntax-highlighted code blocks with copy button
- Add and delete tasks
- Progress bar and theme-aware styling
- Auto-redirect from text editor to plan view
- 28 unit tests (parser + serializer)
MIT