avrebarra / Annotaat

Annotate code without polluting them.

Your thoughts on code shouldn’t live as // TODO litter that your teammates discover in PRs. Keep them private. Resolve them on your own time. Ship without the noise.

Install on VSCode
Floating annotation input in VS Code
VS Code command palette showing Annotaat commands
Annotaat sidebar with branch tab — annotations grouped by file
Exported Annotaat Markdown with line references and notes
Annotation copied to clipboard notification

What it does

Annotate without polluting

Select code, press Cmd+Opt+A, annotate. Stored in separate locations, but never in your source files.

Your AI review queue

Annotate AI-generated code, point to exact lines, work through the sidebar like a checklist. State concern → ask AI to fix → ship.

Survives refactors

Annotations don’t break when you move code around. They reattach automatically.

Branch-scoped

Every git branch gets its own annotation set. Switch branches — your notes switch too.

Zero config

Under 250 KB. No setup wizard. No onboarding. Fully offline.

FAQ

Does Annotaat modify my source code?
Never. Annotations live entirely in .vscode/annotations/ as JSON files. Your source files are untouched — no comments injected, no markers added. The highlights you see in the editor are VS Code decorations, not code changes.
How do annotations survive refactors?
Three-tier reattachment: exact text match → surrounding context match → smart fallback. Move code or rename things — annotations follow. When code gets deleted, the annotation is flagged as broken and surfaced at the top of the sidebar.
What happens when I switch git branches?
Annotaat watches .git/HEAD directly and auto-reloads annotations for the new branch. Works with CLI git, VS Code’s built-in git, and GUI tools. Each branch gets its own annotation file in .vscode/annotations/.
Can I share annotations with my team?
Yes — commit the .vscode/annotations/ folder. Teammates see the same annotations on that branch. Or .gitignore it for private notes. You can also point an AI agent at the JSON file and it’ll process each annotation at the exact location.
How do I use this with AI agents?

Annotate points across your codebase — exact file, line range, snippet, and what needs to change. Then ask your AI agent: “process all annotations and implement each one.” The agent reads the annotations file and makes precise changes at each location. No more vague comments. No more “somewhere in auth.ts there’s a bug.”

I don’t use AI. Is this still for me?

Absolutely. Annotaat is a utility extension — people use it for code review prep, personal bookmarks, onboarding notes, meeting prep, and delegating changes with precise locations. AI review is just one workflow among many.

Does it slow down VS Code?
No. Flat JSON, loaded on startup. Updates debounced at 500ms with atomic writes. Decorations use native VS Code APIs. The entire extension is under 250 KB — you’d need 40 copies to match a typical theme extension.
Where is my data? Is it safe?
Local JSON in .vscode/annotations/. No cloud. No accounts. Entirely offline. Commit the folder to share, or .gitignore it for private notes. Your choice.

Get started

Install, open a file, and hit ⌘ Cmd + ⌥ Opt + A — you’re annotating in seconds. No onboarding. No config.

< 250 KB installed offline
Install on VSCode