Michael Ramos
5bc57fc5bd
* feat(ui): shortcut registry foundation Salvages the foundation of #380 by @gjermundgaraba — the original PR sat 6 weeks waiting for review and was closed by the author. This lands the engine, scope data, and auto-generated marketing docs page, deferring per-component handler migration to follow-up PRs. Layout: - packages/ui/shortcuts/{core,runtime,index}.ts — engine + barrel - packages/ui/shortcuts/plan-review/* — scopes for plan editor surfaces - packages/ui/shortcuts/code-review/* — scopes for review editor surfaces - packages/{editor,review-editor}/shortcuts.ts — per-app surface composition - apps/marketing/src/{components,lib} — auto-generated docs page App behavior is unchanged: existing ad-hoc keydown handlers keep running. The registry is plumbing waiting for migration PRs to wire to it. Co-authored-by: Gjermund Garaba <gjermund@garaba.net> * feat(ui): add missing shortcuts; warn on hold-binding gap Addresses code review on #652. Adds five live shortcuts that were missing from the registry, so the auto-generated /docs/reference/keyboard-shortcuts page is no longer incomplete: - Mod+P (print plan) — plan review + annotate - Mod+B (toggle file tree) — code review (new "Layout" section) - Mod+. (toggle review sidebar) — code review - Mod+Shift+T (toggle demo tour, dev-only) — code review - Mod+Shift+F (focus PR comments search) — new code-review/prComments scope Also whitelists `.` as a valid normalized binding token in the registry validator (keeps catching typos like Cmd/Ctrl while allowing legitimate punctuation keys). Hold-binding gap: the registry's `Alt hold` advertises a shortcut that `useShortcutScope` cannot dispatch. Today this is harmless because the existing `useInputMethodSwitch` hook handles it bespoke. Added warning comments at the binding declaration and next to `useDoubleTapShortcuts` so future migrators don't fall in. A `useHoldShortcuts` hook is the proper fix and will land with the App.tsx migration that needs it. * feat(ui): comprehensive shortcut registry coverage Two-Sonnet inventory audit found 19 more user-facing shortcuts not in the registry, on top of the 5 added in the previous commit. Adding all of them so the auto-generated /docs/reference/keyboard-shortcuts page ships honest and the in-app help modal (once migrated to read from the registry) is comprehensive. Plan / annotate surface (4 added): - Escape closes image lightbox (Viewer) - Mod+Enter saves annotation edit (AnnotationPanel) - Escape cancels annotation edit (AnnotationPanel) - Enter confirms image name (ImageAnnotator name field) Code review surface (15 added): - v / a in single-file diff mode (toggle viewed / stage) - v, a, x, z, c, [, ] in all-files (new AllFilesDiff scope) - Mod+Enter / Escape / Tab (new SuggestionModal scope) - Mod+Enter / Escape (new AI Assistant scope: AITab + AskAIInput) - Escape closes tour dialog (new TourDialog scope) Engine: extended NAMED_TOKENS with `[` and `]` for the all-files navigation bindings. Tests updated for the new section ordering. App behavior unchanged — this is pure declarative metadata. The existing ad-hoc keydown handlers keep running; the registry is plumbing for the migration follow-up PRs. * fix(ui): suggestion modal scope advertised non-existent submit shortcut Self-review caught: SuggestionModal.tsx only has Escape (close) and Tab (indent) handlers — no Mod+Enter. The Mod+Enter the inventory agent referenced lives in AnnotationToolbar's suggested-code textarea, which is already covered by reviewAnnotationToolbarShortcuts.submitComment. Removed the bogus submit action from the scope. Renamed cancel→close since the modal preserves suggestion state on Escape (it's not a discard). * fix(review): remove broken Cmd+Shift+C copy-diff shortcut The handler at App.tsx:695 checked `e.key === 'c'` but Shift forces `e.key` to uppercase `'C'`, so the shortcut never fired. The in-app help modal also advertised it incorrectly as "Toggle comment mode". Removing the broken shortcut entirely rather than fixing the case mismatch — the toolbar's Copy button already does the same thing, and there's no evidence anyone was relying on the keyboard shortcut. Three deletions: - packages/review-editor/App.tsx — handler block - packages/review-editor/shortcuts.ts — copyDiff registry action - packages/ui/components/KeyboardShortcuts.tsx — help modal entry * chore(ui): address review nits - F3: refresh AGENTS.md scope inventory (added scopes were missing) - F5: getShortcutPlatform() now delegates to packages/ui/utils/platform isMac instead of duplicating the regex+SSR guard - F7: drop the stand-alone imageAnnotator.confirmName entry; the behaviour is folded into the existing save action's hint so the marketing docs page no longer renders two Enter rows with different descriptions - F8: remove the unused listenerOptions parameter from useShortcutScope (no callers; inline objects in the dep array would have caused re-render loops if anyone tried to use it) TODOs left for the migration follow-up: - F2: cross-scope arbitration — dispatchShortcutEvent should bail on event.defaultPrevented; needs preventDefault to be claimed consistently across scopes first - F6: matchesKeyToken doesn't actually match the Space token; needs a special case before any scope binds Space App behaviour unchanged. --------- Co-authored-by: Gjermund Garaba <gjermund@garaba.net>
Plannotator
Interactive Plan & Code Review for AI Coding Agents. Mark up and refine your plans or code diffs using a visual UI, share for team collaboration, and seamlessly integrate with Claude Code, Copilot CLI, Gemini CLI, OpenCode, Pi, and Codex.
Plan Mode Demos:
Claude Code
|
OpenCode
|
Annotate: Plans, specs, folders, files, urls. send feedback directly to agents.
New: Code Review
- send your feedback to agents
- built-in:
- ask ai
- agent code reviews
Features
| Visual Plan Review | Built-in hook | Approve or deny agent plans with inline annotations |
| Plan Diff | Automatic | See what changed when the agent revises a plan |
| Code Review | /plannotator-review | View git diffs or remote PRs. Package annotations and ask AI about the code as you review. |
| Annotate Any File | /plannotator-annotate <file|folder|url> | Annotate markdown, HTML, URLs, or folders and send feedback to your agent |
| Annotate Last Message | /plannotator-last | Annotate the agent's last response and send structured feedback |
Sharing Plans
Plannotator lets you privately share plans, annotations, and feedback with colleagues. For example, a colleague can annotate a shared plan, and you can import their feedback to send directly back to the coding agent.
Small plans are encoded entirely in the URL hash. No server involved, nothing stored anywhere.
Large plans use a short link service with end-to-end encryption. Your plan is encrypted with AES-256-GCM in your browser before upload. The server stores only ciphertext it cannot read. The decryption key lives only in the URL you share. Pastes auto-delete after 7 days.
- Zero-knowledge storage, similar to PrivateBin
- Fully open source and self-hostable (see docs)
Install
Install for Claude Code
Install the plannotator command:
macOS / Linux / WSL:
curl -fsSL https://plannotator.ai/install.sh | bash
Windows PowerShell:
irm https://plannotator.ai/install.ps1 | iex
Then in Claude Code:
/plugin marketplace add backnotprop/plannotator
Restart Claude Code after plugin install.
Pin a specific version or verify provenance
curl -fsSL https://plannotator.ai/install.sh | bash -s -- --version vX.Y.Z
& ([scriptblock]::Create((irm https://plannotator.ai/install.ps1))) -Version vX.Y.Z
Every released binary ships with a SHA256 sidecar (verified automatically). SLSA provenance verification is supported from v0.17.2 onwards — see the installation docs for details.
See apps/hook/README.md for detailed installation instructions including a manual hook approach.
Install for Copilot CLI
Install the plannotator command:
macOS / Linux / WSL:
curl -fsSL https://plannotator.ai/install.sh | bash
Windows PowerShell:
irm https://plannotator.ai/install.ps1 | iex
Then in Copilot CLI:
/plugin marketplace add backnotprop/plannotator
/plugin install plannotator-copilot@plannotator
Restart Copilot CLI after plugin install. Plan review activates automatically when you use plan mode (Shift+Tab to enter plan mode).
See apps/copilot/README.md for details.
Install for Gemini CLI
Install the plannotator command:
macOS / Linux / WSL:
curl -fsSL https://plannotator.ai/install.sh | bash
Windows PowerShell:
irm https://plannotator.ai/install.ps1 | iex
The installer auto-detects Gemini CLI (checks for ~/.gemini) and configures the plan review hook and policy. It also installs /plannotator-review and /plannotator-annotate slash commands.
Then in Gemini CLI:
/plan # Enter plan mode — plans open in your browser
/plannotator-review # Code review for current changes
/plannotator-review <pr-url> # Review a GitHub pull request
/plannotator-annotate <file.md> # Annotate a markdown file
Requires Gemini CLI 0.36.0 or later.
See apps/gemini/README.md for details.
Install for OpenCode
Add to your opencode.json:
{
"plugin": ["@plannotator/opencode@latest"]
}
Run the install script to get /plannotator-review:
curl -fsSL https://plannotator.ai/install.sh | bash
Windows:
irm https://plannotator.ai/install.ps1 | iex
This also clears any cached plugin versions. Then restart OpenCode.
Install for Pi
pi install npm:@plannotator/pi-extension
Then start Pi with --plan to enter plan mode, or toggle it during a session with /plannotator.
See apps/pi-extension/README.md for full usage details, commands, and flags.
Install for Codex
Install the plannotator command:
macOS / Linux / WSL:
curl -fsSL https://plannotator.ai/install.sh | bash
The installer also enables Codex Stop hooks when Codex is installed or ~/.codex already exists. Restart Codex Desktop
after installing or changing hooks.
Windows PowerShell:
irm https://plannotator.ai/install.ps1 | iex
Codex plan review is automatic on macOS, Linux, and WSL. Codex hooks are currently disabled on Windows in the official Codex docs, so the Windows installer does not enable them automatically; the direct !plannotator commands still work.
Then in Codex — feedback flows back into the agent loop automatically:
$plannotator-review # Code review skill for current changes
$plannotator-annotate # Annotate a markdown file, URL, or folder
$plannotator-last # Annotate the last agent message
!plannotator review # Code review for current changes
!plannotator review <pr-url> # Review a GitHub pull request
!plannotator annotate file.md # Annotate a markdown file
!plannotator last # Annotate the last agent message
Plan review uses Codex's experimental Stop hook on macOS, Linux, and WSL.
See apps/codex/README.md for details.
How It Works
When your AI agent finishes planning, Plannotator:
- Opens the Plannotator UI in your browser
- Lets you annotate the plan visually (delete, insert, replace, comment)
- Approve → Agent proceeds with implementation
- Request changes → Your annotations are sent back as structured feedback
(Similar flow for code review, except you can also comment on specific lines of code diffs)
License
Copyright 2025-2026 backnotprop
This project is licensed under either of
- Apache License, Version 2.0 (http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (http://opensource.org/licenses/MIT)
at your option.
Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this project by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.