Annotaat - Code Annotations
Code annotations that stay out of your code.
Select any code, write a note — stored outside source, scoped per branch, exportable to Markdown.
Select code, press Cmd+Opt+A, write your note.
Annotated code ranges highlighted in the editor.
All annotations visible in the sidebar, grouped by file.
Quick Start
- Open a workspace folder in VS Code (Annotaat needs a workspace root)
- Select code in the editor
- Press
Cmd+Opt+A (Mac) or Ctrl+Alt+A (Windows/Linux)
- Write your note in the input field at the top of the Annotaat sidebar
- Done — annotation appears in the sidebar with a highlighted range in the editor
Click any annotation card to jump to its code location.
Features
- Annotation sidebar — Dedicated webview panel showing all annotations grouped by file
- Editor highlights — Inline colored decoration on annotated code ranges
- Per-branch storage — Annotations isolated by git branch; switch branches and annotations follow
- Markdown export — Generate full report (file or clipboard) for PRs, reviews, documentation
- Filter by file — Narrow sidebar to one file's annotations
- Search — Filter annotations by file name, note text, or code snippet
- Soft-remove / restore — Mark annotations as removed instead of deleting permanently
- Edit annotation text — Modify note content after creation
- Copy as Markdown — Copy a single annotation's Markdown to clipboard
- Broken anchor detection — When annotated code moves or is deleted, the annotation is flagged
- Branch auto-reload — Detects git branch switches automatically via
.git/HEAD watcher
- Configurable decoration colors — Separate base colors for dark and light themes
- Activity bar icon — One-click access from VS Code activity bar
- Editor context menu — Right-click any selection → "Annotaat: Annotate selection"
Use Cases
| Use case |
Description |
| Code review |
Leave review notes without touching source files. Export Markdown for PR descriptions. |
| AI-assisted development |
Annotate AI-generated code for review before committing. |
| Personal notes |
Sticky notes for your workspace. Gitignore .vscode/annotations/ for private use. |
| Team documentation |
Share annotations by committing the .vscode/annotations/ folder. |
Keyboard Shortcuts
| Shortcut |
Action |
Cmd+Opt+A (Mac) |
Annotate selection |
Ctrl+Alt+A (Win/Linux) |
Annotate selection |
Settings
| Setting |
Default |
Description |
annotaat.annotations.showFileName |
true |
Show file name under annotation |
annotaat.annotations.showTimeStampForNoteCreation |
false |
Show created timestamp under annotation |
annotaat.annotations.annotationBG.enableDecoration |
true |
Enable editor highlights for annotated ranges |
annotaat.annotations.annotationBG.color.dark |
#FFFFFF |
Base hex color for annotation highlights in dark themes |
annotaat.annotations.annotationBG.color.light |
#000000 |
Base hex color for annotation highlights in light themes |
annotaat.annotations.annotationBG.showBorder |
true |
Show a 1px border around annotation highlights |
annotaat.clickBehavior |
"goto" |
Action when clicking annotation card (deprecated) |
annotaat.debug |
false |
Enable detailed debug logging to Annotaat output channel |
Commands Reference
All commands are accessible from the Annotaat sidebar view title bar or item context menus.
| Command |
ID |
Description |
| Annotate |
annotaat.annotations.annotate |
Annotate selected code |
| Refresh |
annotaat.annotations.refreshEntry |
Reload annotations from disk |
| Filter by file |
annotaat.annotations.filterByFile |
Pick a file to filter annotations |
| Clear file filter |
annotaat.annotations.clearFilter |
Remove active file filter |
| Export as Markdown |
annotaat.annotations.generateReport |
Generate full Markdown report |
| Export to Clipboard |
annotaat.annotations.exportToClipboard |
Copy full report to clipboard |
| Remove Annotation |
annotaat.annotations.removeAnnotation |
Soft-remove an annotation |
| Restore Annotation |
annotaat.annotations.restoreAnnotation |
Restore a soft-removed annotation |
| Clear Annotations |
annotaat.annotations.clearAnnotations |
Remove all annotations |
| Open Annotation |
annotaat.annotations.openNote |
Jump to annotated code |
| Copy Annotation |
annotaat.annotations.copyNote |
Copy annotation as Markdown |
| Edit Annotation |
annotaat.annotations.editNote |
Modify annotation text |
Storage
Annotations stored in .vscode/annotations/{branch}.json at workspace root. Each git branch gets its own JSON file. Commit the folder for team sharing or add to .gitignore for private notes.
Development
make build # compile + package dist/annotaat.vsix
make test # run tests
make watch # compile on changes
make clean # remove dist/
make format # format all source files
See docs/architecture.md for source layout and design details.
Debug logs: View → Output → Annotaat. Enable with "annotaat.debug": true.
License
CC BY-NC-ND 4.0 — Copyright (c) 2026 Avre Barra.
