avrebarra / Annotaat

a vscode annotation plugin for the AI era

Stop reviewing AI output one by one.

Still fixing bugs one by one? With Annotaat, reviewing 60—even hundreds—of mistakes is fast and batch-processed. State and mark all your concerns, export it, send it to AI to fix everything at once. Skip the one-by-one. Grab coffee.

Are you directing your AI or being directed by it?

Don’t be your agent’s babysitter. Mark what needs fixing at the exact line, export your checklist, and ask AI to fix everything. Submit all mistakes in one precise pass.

15 prompts per file. Seriously?

Fix one bug, break three others, repeat. That loop? Amateur hour. Minimize your review cycle with Annotaat—mark everything, throw one fix at your AI. Coffee stays hot.

60 AI mistakes. One pass.

Scan and review your AI’s output, mark every issue with Cmd+Opt+A, when done paste it all to your agent and let AI fix everything at once. From 15 prompts to 1. Hot coffee.

Review like a thesis advisor.

You’re not a babysitter. You’re the advisor. Annotaat is your red pen for marking up AI’s thesis. Correct the code, hand it back, grab coffee. Don’t do the work yourself.

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

Used to be me. Now it’s bliss.

Waited 15 prompts. One fix at a time.

without-annotaat
> the login check is wrong, fix the null guard in auth.ts
+ Thought: 3.2s
→Read src/auth.ts (42 lines)
+ Thought: 1.1s
→Edit src/auth.ts — add null guard at line 42
Fixed! Added null check on line 42.
> now logout() throws TypeError
+ Thought: 4.5s
→Read src/auth.ts (48 lines)
+ Thought: 2.8s
*Grep "TypeError" in src/ (3 matches)
+ Thought: 6.1s
→Edit src/auth.ts — fix type at line 87
→Edit src/auth.ts — fix type at line 112
Sorry about that. Fixed the type issue.
> login is broken again… you reverted your own fix
+ Thought: 1.5s
→Read src/auth.ts (52 lines)
+ Thought: 8.3s
*Grep "login" in src/ (7 matches)
+ Thought: 2.2s
→Edit src/auth.ts — revert and redo null guard
My apologies. Let me look at the full picture.
> session refresh is also broken now, line 87 and 112
+ Thought: 5.7s
→Read src/session.ts (35 lines)
+ Thought: 3.4s
→Edit src/session.ts — fix refresh at line 23
→Edit src/session.ts — fix refresh at line 45
Fixed all three. I’m confident this time.
> nope, auth check is back to being wrong
+ Thought: 1.8s
→Read src/auth.ts (55 lines)
+ Thought: 9.1s
→Edit src/auth.ts — retry null guard approach
I apologize. Let me revert and try a different approach…
> forget it. i’ll write it myself.
# Result
15 prompts. 45 min. Cold coffee.

Throw 60 concerns for AI to work on. One pass.

with-annotaat
> fix all these review comments [160 lines copied]
+ Thought: 1.2s
→Read annotaat/annotations.json (60 items)
→Read src/auth.ts (42 lines)
→Read src/session.ts (35 lines)
→Read src/utils.ts (28 lines)
+ Thought: 15.3s
→Edit src/auth.ts — fix items [1–40]
→Edit src/session.ts — fix items [41–50]
→Edit src/utils.ts — fix items [51–60]
*Grep "regression" in src/ (0 matches)
Done. 60 items fixed, 0 regressions.
# Result
One prompt. 2 min. Coffee’s still hot.

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 350 KB. No setup wizard. No onboarding. Fully offline.

Three moves. That’s it.

1

Check and review AI output.
Critique what’s wrong.

2

Cmd+Opt+A on every issue.
Pinpoint exact lines.

3

Export as markdown. Send it all to AI for fixing.
Grab coffee.

Also works for PR prep, personal bookmarks, team documentation — annotations are just structured notes outside your source files.

What people say

FAQ

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.”

Why not just use TODO comments?
TODOs work for many things. But if you want structured notes that others can read without digging through code — or you just want quick, personal marks to revisit later — annotations fill that gap. TODO is useful. Annotations are useful too.
Will this reduce AI hallucination?
Not directly. But it guards against it — by giving AI exact locations and context, you avoid expanding the context window unnecessarily just to investigate one issue. Targeted annotations keep the AI focused.
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 350 KB — you’d need 40 copies to match a typical theme extension.
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.
Is my code safe?
Yes. Annotaat works entirely offline. No telemetry, no network calls, no data leaves your machine. Annotations are local JSON files in your project.
I don’t use AI agents. Is this still useful?
Absolutely. Annotaat is a general-purpose annotation tool. Mark issues, leave notes, bookmark lines for later — all without touching your source code. The AI integration is optional.
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 much does it cost?
It’s free. No premium tier, no paywall. Download it and use it.
Can I use it for commercial projects?
Yes. Personal, commercial, team — no restrictions. Use it however you want.

Under 350 KB. Zero config. Offline.

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

Install on VSCode