Comment Sidecar

Explain a line of code without touching the code.
Comments live in a .comment file beside your source, appear right on the line in your editor,
follow that line as the code moves, and can be read by AI agents.

Install · Quick start · How it works · For AI agents · Commands · Settings · FAQ

An editor showing app.tsx. Lines 4 and 5 are tinted blue and end with a dashed ring marker that reads “comment”. The pointer rests on line 4, and a card above it says: Comment on line 4 — Wait for session restoration before choosing a screen.

Why a sidecar?

Your source stays clean	Comments keep up	Agents can read them
Source files are never written. Notes about why a line exists stay out of the code and out of its diffs.	Each comment follows its line as code moves around it, and asks for a review when the line itself changes.	A CLI and an MCP server hand an agent the code and its comments in a single read.

Install

VS Code: install Comment Sidecar from the Marketplace, or run:

code --install-extension zainzafar90.comment-sidecar

Cursor and other VS Code–based editors: build the package, then use Extensions → … → Install from VSIX.

npm run release    # writes dist/comment-sidecar-0.3.0.vsix

Building needs Node.js 18.17+ and Python 3.9+; see DEVELOPMENT.md.

Quick start

Open a file and save it.
Put the cursor on a line and press Ctrl+Alt+; (Cmd+Alt+; on macOS).
A draft opens beside your code. Write why the line is the way it is, then save the draft.

The line now ends in ◌ comment. Hover it to read the note. Only the sidecar was written (app.tsx.comment for app.tsx); your source file is untouched.

Cloned this repository? Open the examples folder and hover lines 4 and 5 of app.tsx.


Follows its line. Add or remove code above a comment and it moves with its line.	Flags what changed. Edit the line itself and its comment turns amber until you confirm the note still holds.

How it works

The file app.tsx.comment. Numbered badges mark its parts: 1, a header with the format version and file names; 2, the line number, a stable ID and the comment's state; 3, fingerprints — hashes of the line and its neighbors, never a copy of the code; 4, the comment itself in plain text.

Every source file can have one sidecar: app.tsx → app.tsx.comment. For each comment it stores the line number and fingerprints (hashes of the line and the two lines on either side of it), never the code itself. When the source changes, the fingerprints decide where each comment belongs now:

Status	What happened	In the editor
Attached	The line is where it was.	`◌ comment`
Moved	Lines were added or removed above it, and it followed.	`◌ comment`
Needs review	The line itself was edited, or only the line (not its neighbors) still matches.	`◌ comment !` in amber
Ambiguous	Several lines match, so it won't guess.	A warning, no marker
Detached	The line was deleted, split or rewritten.	A warning, no marker

Resolve the last three with Mark Comment Reviewed or Reattach Comment to This Line. Attached means the position still matches, not that the note is still true.

Renaming a file in the editor renames its .comment file too. Renames made outside the editor aren't tracked; Check Workspace reports the orphaned sidecar. The file format is specified in FORMAT.md.

For AI agents

Agents don't see editor decorations, so give them a tool and tell them to use it.

Instructions. Run Comment Sidecar: Copy Agent Instructions and paste the result into your AGENTS.md or a Cursor rule. It explains how to read and write comments, and what a good one is: a non-obvious rule or reason, in one or two sentences, on the line that enforces it.
MCP server. Run Comment Sidecar: Copy Cursor MCP Configuration, pick read-only or read-and-write, and merge the entry into .cursor/mcp.json. For VS Code, start from integration/vscode-mcp.example.json.

Tool	What it does	Access
`comment_sidecar_read`	Returns source and comments together, with the original line numbers.	Read‑only
`comment_sidecar_check`	Lists comments that need review, are ambiguous, or are detached.	Read‑only
`comment_sidecar_write`	Adds, edits, reviews, reattaches or deletes comments, in `.comment` files only. Needs `--allow-write`.	Opt-in

Copied configurations point at the installed extension, so copy them again after an update. Comment text always reaches the agent as untrusted data, never as instructions.

Using the CLI directly

The copied instructions already contain the full path to the CLI on your machine. From a clone of this repository:

node src/cli.js read examples/app.tsx --start 1 --end 8                   # source and comments
node src/cli.js read examples/app.tsx --start 1 --end 8 --mode comments   # comments only
node src/cli.js check examples/app.tsx                                    # problems only
node src/cli.js --help                                                    # write commands

Pass --root /path/to/repo to work on another repository. read prints the original line numbers and two revision hashes. Every write needs both hashes from a fresh read, so an agent can't overwrite changes it hasn't seen; add and reanchor also need the exact text of the target line.

Commands

Everything lives in the Command Palette under Comment Sidecar:.

Command	What it does
Add Comment at Line	Opens a draft for the current line. Ctrl+Alt+; · Cmd+Alt+;
Edit Comment	Opens the comment on the current line as a draft.
Delete Comment	Deletes it after you confirm.
Mark Comment Reviewed	Confirms that a comment needing review still fits its line.
Reattach Comment to This Line	Moves a lost or misplaced comment to the current line.
List File Comments	Jumps to any comment in the file.
Open Annotated Preview	Shows the source with its comments inline.
Copy Annotated Selection	Copies source and comments with line numbers.
Open .comment Patch	Opens the raw sidecar file.
Check Workspace	Reports every comment that needs attention.
Copy Agent Instructions	See For AI agents.
Copy Cursor MCP Configuration	See For AI agents.

Settings

Setting	Default	Options
`commentSidecar.markerStyle`	`label`	`label` shows `◌ comment` · `icon` shows `◌` · `off` hides it
`commentSidecar.showMarkers`	`true`	`false` hides markers in every style
`commentSidecar.highlightStyle`	`line`	`line` (tint and left edge) · `underline` · `off`
`commentSidecar.showHoverMetadata`	`false`	`true` adds the comment's ID, status and reason to the hover

Colors

Every color is a theme token. Override any of them in your settings, for example:

{
  "workbench.colorCustomizations": {
    "commentSidecar.highlightBackground": "#4CA6FF12",
    "commentSidecar.highlightBorder": "#71B7FF88",
    "commentSidecar.reviewBackground": "#E6AF2E16",
    "commentSidecar.reviewBorder": "#E6AF2EA0",
    "commentSidecar.sidecarForeground": "#7F93B2"
  }
}

FAQ

Does it ever change my source files?

No. Only .comment files are written. A .comment file that can't be read is reported as an error; it is never treated as empty or overwritten.

Why won't my comment save?

Save the source file first, and its .comment file if it's open. A draft is refused when either one changed after the draft opened, so nothing you haven't seen gets overwritten. Adding and editing also need a trusted workspace; untrusted workspaces are read-only.

Should I commit .comment files?

Yes. They're plain text and belong with the code they describe, so they travel through branches and code review like everything else.

Can I hide .comment files?

By default each one is dimmed and nested, collapsed, under its source file in the Explorer. The extension does this by setting VS Code defaults:

{
  "explorer.fileNesting.enabled": true,
  "explorer.fileNesting.expand": false,
  "explorer.fileNesting.patterns": { "*": "${capture}.comment" }
}

These settings are VS Code-wide, so the built-in nesting (such as lockfiles under package.json) shows up too. Anything you set yourself wins; if you define explorer.fileNesting.patterns, add "*": "${capture}.comment" to it. To hide sidecars completely, add "files.exclude": { "**/*.comment": true }. Hovers, markers and agent tools keep working.

Which languages does it support?

Any UTF-8 text file. Comments attach to physical lines rather than symbols, so there's no parser or language server involved.

Does anything leave my machine?

No. There is no network access, telemetry or model call, and hovers are computed locally. An agent you connect may send the tool output to its model; that part is up to the agent. See SECURITY.md.

What are the limits?

Source and .comment files: up to 2 MiB each.
Up to 1,000 comments per file and 16,000 characters per comment.
Dependency, build and version-control folders (node_modules, dist, .git, …) are skipped.

Learn more

FORMAT.md: the .comment file format.
SECURITY.md: trust boundaries and what is not protected.
DEVELOPMENT.md: building, testing, releasing and the code layout.

_{MIT License · Comments next to code, not inside it.}

Zain Zafar