Annotated

Annotate a codebase with grouped, shareable Markdown annotations.

Annotated attaches grouped, Markdown annotations to ranges of code — or to whole files — for reviews, code tours, onboarding notes, or just thinking out loud. Annotations live as plain JSON under .annotations/ in your repo, so they're diffable, shareable (commit them), and readable by AI agents. Organize groups with tags, discuss them in comment threads, link a group to a Git ref, and resolve them when the work is done.

Quickstart

Open the Annotated view from the Activity Bar to browse, filter, and manage your annotation groups. The everyday actions also have commands and keybindings:

A few things that live in the UI rather than as keybindings:

• Detail view (secondary sidebar): edit an annotation's Markdown, copy its content or path:line reference, jump prev/next, and reply in comment threads.
• Whole-file annotations: an annotation can target a file as a whole instead of specific lines — use Create File Annotation, or tick whole file in the detail view's range editor to convert an existing one (and untick it to go back). They open the file when clicked, and never go stale from edits elsewhere in it.
• Local links: an annotation's Markdown can link to code with [label](https://github.com/EperezOk/vscode-annotated/blob/HEAD/src/foo.ts#L10-L20), or to a whole file with [label](https://github.com/EperezOk/vscode-annotated/blob/HEAD/src/foo.ts). Copy a target with Copy Location for Annotation Link, then paste it over selected text in the editor to wrap it as a link. Clicking a local link opens the file and highlights those lines (in a distinct colour) without leaving the annotation; ↩ Refocus code jumps back to the annotation's own lines.
• Bulk actions: hit Select in the sidebar to tag, set a Git ref, resolve/restore, or delete multiple groups at once.
• Delete: right-click a group or an annotation.

AI agent skill

skills/annotated/ is a skill that lets an AI agent take part in an annotated workspace — surf groups and comment threads, reply, create annotation groups/annotations, and manage the tag palette — by reading and writing the .annotations/ files directly, under its own distinct identity (kept separate from yours).

Install it with a skill manager:

# GitHub CLI (gh ≥ 2.93)
gh skill install EperezOk/vscode-annotated annotated

# …or skills.sh
npx skills add EperezOk/vscode-annotated

Then ask your agent to, e.g., "explain how X works with annotations" or "answer the questions I left in the annotations" — the groups it creates are navigable right alongside your own. See skills/annotated/README.md for the full operation set and rules.

Development

Requires Node ≥ 20.19. This is a web-compatible extension — no Node built-ins in src/: pure logic lives in src/shared + src/core, the thin VS Code layer in src/web, and the Svelte webviews in src/webview.

npm install
npm run compile   # bundle extension + webviews (esbuild)
npm start         # launch in web VS Code (Chromium, via @vscode/test-web)

npm run test:unit         # Vitest: pure logic + Svelte components
npm run test:integration  # @vscode/test-web: extension-host activation/commands
npm run test:e2e          # Playwright: UI smoke against web VS Code
npm test                  # type-check + all tiers

npx @vscode/vsce package --no-dependencies   # build an installable .vsix

Releasing: npm run release -- <patch|minor|major> (or an explicit X.Y.Z) bumps the version, scaffolds a CHANGELOG.md entry from the commits since the last tag (edit it, then re-run), runs the gate, commits, tags vX.Y.Z, builds the .vsix, and pushes the branch + tag to origin after a confirmation (--no-push to skip, --yes to skip the prompt, --dry-run to preview). See CHANGELOG.md for release notes.