[Feature Request] `plannotator annotate <file.md>` - Annotate any markdown file

[theflysurfer]

Problem

Currently, Plannotator only works with plans from the ExitPlanMode hook. However, the annotation system (DELETION, INSERTION, REPLACEMENT, COMMENT) is powerful and could be useful for any markdown file in a repository.

Use Case

When working with Claude Code, I often want to:

1. Open a documentation file (README, CONTRIBUTING, etc.)
2. Visually annotate specific sections that need changes
3. Send structured feedback to Claude to apply corrections

This workflow is currently not possible without the ExitPlanMode hook trigger.

Proposed Solution

Add a new subcommand plannotator annotate <file.md> that:

1. Reads any markdown file from disk
2. Opens the existing plan UI for annotation
3. Outputs structured feedback to stdout (like the review command)

CLI usage:

plannotator annotate README.md

Slash command:

/plannotator-annotate docs/GUIDE.md

Implementation

I have a working implementation ready:

• New packages/server/annotate.ts (~100 lines, simplified version of plan server)
• CLI subcommand in apps/hook/server/index.ts (~40 lines)
• Slash command apps/hook/commands/plannotator-annotate.md

The implementation reuses the existing UI and exportDiff() function - minimal changes to core packages.

Branch with implementation: https://github.com/theflysurfer/plannotator/tree/feature/annotate-any-md

Would this be welcome?

I'd be happy to submit a PR if this aligns with the project's direction. Let me know if you'd like any changes to the approach.

[deviantony]

I'll tag along on that one as I was thinking about something similar today. I like the review UX of plannotator when reviewing a plan.

Part of my dev workflow, I usually build build a spec document first before digging into an implementation (where I'll be using plan mode and plannotator). It would be great to be able to review that spec document in a similar fashion to implementation plan review.

I understand that this kinda drifts off from the original purpose of the tool - which is implementation plan review - into a more generic claude output review tool. Keen to discuss this further if integrating the spec step as part of the tool before the planning or making it a more generic claude output review tool is interesting to you, I believe that this is basically where future IDEs will likely be going from a UX perspective.

[ChrisEdwards]

I want this too. Otherwise I am writing my own tool to do this. I prefer to use plannotator though.

[arieh]

I just opened the issues to suggest this exactly! I often want to go over plan files in our repo and iterate on them with plannotator

[theflysurfer]

I developped all of them in a local fork. Do you want me to pull requests ? *Julien Fernandez* *Un email envoyé à une personne consomme autant d’énergie qu’une **ampoule économique allumée pendant 2h* *Un email envoyé à 10 personnes en consomme 4 fois plus.* *Stocker un email inutile consomme de la place sur plusieurs disques durs inutilement, et donc de l’énergie.* *Soyez parcimonieux, le numérique consomme de l’énergie réelle !* Le sam. 31 janv. 2026 à 11:38, Arieh Glazer ***@***.***> a écrit :

…

*arieh* left a comment (backnotprop/plannotator#109) <#109 (comment)> I just opened the issues to suggest this exactly! I often want to go over plan files in our repo and iterate on them with plannotator — Reply to this email directly, view it on GitHub <#109 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACGSXL3RJE2UNPMO5M5WB4D4JSA2PAVCNFSM6AAAAACSYLOT4KVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTQMRYGEZDSNZWGY> . You are receiving this because you authored the thread.Message ID: ***@***.***>