https://github.com/ofershap/cursor-plan-preview
Visual plan preview and team sharing for Cursor's plan mode. CPR — X-ray your plans before you build.
https://github.com/ofershap/cursor-plan-preview
Last synced: 3 months ago
JSON representation
Visual plan preview and team sharing for Cursor's plan mode. CPR — X-ray your plans before you build.
- Host: GitHub
- URL: https://github.com/ofershap/cursor-plan-preview
- Owner: ofershap
- License: mit
- Created: 2026-03-19T09:53:30.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-03-19T17:44:25.000Z (3 months ago)
- Last Synced: 2026-03-20T03:19:38.914Z (3 months ago)
- Language: TypeScript
- Size: 892 KB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
cursor-plan-preview
Your agent writes a plan. But your team has no idea what it's about to build.
The bottleneck in agentic development isn't writing code anymore. It's getting the plan right.
A bad plan burns tokens, wastes hours, and ships the wrong thing. Team review before execution isn't optional.
Visual plan review for Cursor. Annotate inline, share with your team,
get feedback back to the agent. No backend, no accounts.
---
## Your Agent Plans in the Dark
Cursor's plan mode generates a detailed implementation plan - files to change, architecture decisions, task breakdown. You approve it, the agent starts building. Your teammates find out when the PR lands. Or when something breaks.
There's no review step. No "hey, before you build this, can you check if this makes sense?" moment.
CPR puts the plan in front of your team before a single line of code is written.
1. Agent creates a plan, you run `cursor-plan-preview plan-preview-and-share`
2. Plan opens in a browser UI — you annotate inline (delete, replace, comment, insert)
3. Click **Share Plan** → URL copied with everything encoded in the hash
4. Teammate opens the URL, adds their own annotations, shares back
5. You export the feedback, the agent reads it on the next prompt
No accounts. No backend. The URL contains everything.
## Quick Start
```bash
npx cursor-plan-preview --setup
```
This installs a Cursor rule and a `/plan-preview-and-share` slash command.
After the agent creates a plan, preview and share it — type `/plan-preview-and-share` in Cursor chat, or run in terminal:
```bash
npx cursor-plan-preview plan-preview-and-share
```
Auto-detects the latest plan from `~/.cursor/plans/` and opens it in your browser. To preview a specific file:
```bash
npx cursor-plan-preview plan-preview-and-share path/to/plan.md
```
## How It Works
```
Agent generates plan -> saved to ~/.cursor/plans/
|
You run: cursor-plan-preview plan-preview-and-share
|
Plan opens in browser UI
|
You annotate + click Share Plan -> URL copied
|
Teammate opens URL -> adds annotations
|
You click Export Feedback -> -feedback.md written
|
Agent reads feedback -> adjusts plan before building
```
## What You Can Annotate
Select any text in the plan to pick an annotation type:
| | |
| --------------------------- | ------------------------------------ |
| **Delete** (scissors) | Mark text for removal |
| **Replace** (arrows) | Suggest replacement text |
| **Comment** (speech bubble) | Add a note to specific text |
| **Insert** (plus) | Add new text at a point |
| **Global Note** | Add a note not tied to specific text |
Annotations show as color-coded highlights in the plan body. The sidebar lists all annotations with a count badge.
## Sharing
Plans under ~8KB compressed get encoded entirely in the URL hash. Nothing leaves the browser. Your teammate opens the link and everything decodes client-side.
For larger plans, run `cursor-plan-preview plan-preview-and-share` locally and share your screen, or copy the plan body into a Slack thread.
## The Feedback Loop
After teammates annotate and share back:
1. Open the annotated URL
2. Click **Export Feedback**
3. A `*-feedback.md` file appears in `~/.cursor/plans/`
4. The installed Cursor rule tells the agent to check for feedback before building
5. Agent summarizes annotations and asks if you want to incorporate them
## What Gets Installed
`npx cursor-plan-preview --setup` installs one file:
| File | What it does |
| -------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `~/.cursor/rules/plan-preview.mdc` | Agent rule: suggests `plan-preview-and-share` after every plan, checks for feedback |
| `~/.cursor/skills/plan-preview-and-share/SKILL.md` | `/plan-preview-and-share` slash command in Cursor chat |
To remove everything:
```bash
npx cursor-plan-preview --uninstall
```
## Commands
```bash
cursor-plan-preview plan-preview-and-share [file] # open latest (or specific) plan in preview UI
cursor-plan-preview list # show recent plans from ~/.cursor/plans/
cursor-plan-preview --setup # install Cursor rule
cursor-plan-preview --uninstall # remove Cursor rule + legacy hook entries
```
## Architecture
```
cursor-plan-preview/
├── src/
│ ├── cli.ts CLI entry (plan-preview-and-share, list, setup, uninstall)
│ ├── server.ts Local HTTP server (plan API + static files)
│ ├── parser.ts Plan file parser (YAML frontmatter + markdown)
│ └── utils.ts Shared utilities
├── ui/
│ └── src/
│ ├── App.tsx Review UI (React 19 + marked)
│ └── utils/
│ └── sharing.ts Deflate + base64 URL encoding
└── agent-config/
├── setup.mjs --setup handler
└── cursor/rules/ Cursor rule for feedback loop
```
## Tech Stack
| | |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| **Language** |  |
| **UI** |  |
| **Markdown** |  |
| **Bundler** |  +  |
| **Testing** |  |
| **CI** |  |
## Contributing
Contributions welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for setup and guidelines.
## Author
[](https://gitshow.dev/ofershap)
[](https://linkedin.com/in/ofershap)
[](https://github.com/ofershap)
---
If this helped you, [star the repo](https://github.com/ofershap/cursor-plan-preview), [open an issue](https://github.com/ofershap/cursor-plan-preview/issues) if something breaks.
## License
[MIT](LICENSE) © [Ofer Shapira](https://github.com/ofershap)