Ghost Notes

Attach invisible, per-line notes to your code — stored externally so your source stays clean.

Ghost Notes lets you pin Markdown reminders to specific lines of a file without writing anything into the file itself. The notes live in a small JSON file under .vscode/, so your source — especially LaTeX — never fills up with % // TODO: comments that risk leaking into a build.

Features

• Invisible, external notes. Nothing is written into your source file. Notes are stored in .vscode/ghost-notes.json.
• Built for LaTeX. Replace throwaway % TODO comments in .tex files with notes that never reach the compiled PDF — but works in every language.
• Severity levels. Mark each note Information, Warning, or Error. Each shows a distinct icon in the CodeLens, hover, and overview ruler, and the icons are configurable.
• Problems panel integration. Optionally surface all notes as native diagnostics in the Problems panel — one navigable, severity-aware list, with no third-party extension and no markers written into your code.
• CodeLens markers. A Ghost Note CodeLens appears above any line that has a note. Click it to edit, change severity, or delete.
• Rich hovers. Hover a noted line to read the full note rendered as Markdown, with inline Edit / Delete actions.
• Automatic line tracking. Add, remove, or paste lines above a note and its anchor shifts with the surrounding text, so the note stays attached to the right block.
• Scrollbar hints. A subtle marker in the overview ruler shows where notes live in long files, coloured by severity.
• Native look. Uses VS Code Codicons throughout — no emoji.

Getting started

1. Open any file inside a workspace folder.
2. Put your cursor on a line and run Ghost Notes: Add / Edit Ghost Note on Current Line (Ctrl+Alt+N / Cmd+Alt+N), or right-click → Add / Edit Ghost Note.
3. Type your note (Markdown is supported), press Enter, then choose a severity (Information, Warning, or Error).

A Ghost Note CodeLens now sits above the line, and hovering the line shows the full note. Click the CodeLens to edit, change severity, or delete.

Try the bundled demo

This repository ships a ready-made example so you can see notes immediately:

• Open samples/demo.tex with the extension active.
• The notes in .vscode/ghost-notes.json light up as CodeLenses and hovers on lines 12, 20, and 26.
• Type a few lines at the top of the file and watch the notes follow their blocks.

Commands

How notes are stored

Notes are saved per workspace folder in .vscode/ghost-notes.json. Line numbers are 1-based (matching the editor gutter) and paths are workspace-relative, so the file is easy to read, diff, and commit:

{
  "version": 1,
  "notes": {
    "samples/demo.tex": [
      {
        "line": 20,
        "content": "TODO: double-check this derivation before submission.",
        "severity": "warning",
        "createdAt": "2026-07-18T09:00:00.000Z",
        "updatedAt": "2026-07-18T09:00:00.000Z",
      },
    ],
  },
}

severity is one of information, warning, or error (notes without it are treated as information). You can hand-edit this file; Ghost Notes watches it and reloads automatically. Commit it to share notes with your team, or add it to .gitignore to keep them private.

Extension settings

Note on the Problems panel and hovers. VS Code always echoes a diagnostic's message into the editor hover. So when ghostNotes.problems.enabled is on, each note appears both as a line in the diagnostics hover and in the rich Ghost Note hover — an unavoidable overlap. It's off by default for that reason; turn it on if you value the aggregated, navigable list more than a perfectly clean hover.

Working with Todo Tree

A common request is to make ghost notes appear in Todo Tree. That extension finds tags by scanning the raw text of your files, so the only way it can see a note is if a literal TODO: is written into the source — which is exactly what Ghost Notes exists to avoid (and would break LaTeX). Instead, enable ghostNotes.problems.enabled to get the same "one list of all my notes" experience natively in the Problems panel, with clickable, line-accurate, severity-aware entries and no edits to your source.

Requirements

• VS Code ^1.125.0.
• A workspace folder must be open (notes are scoped to .vscode/ within a folder).

Development

This project uses Bun for all package management and scripts — no npm/npx/yarn/pnpm.

bun install          # install dependencies
bun run check-types  # type-check with tsc
bun run lint         # eslint
bun run compile      # type-check, lint, and bundle with esbuild
bun run watch        # watch build (used by the "Run Extension" launch config)
bun run test         # compile + run the full test suite in a headless VS Code

Press F5 in VS Code to launch the Run Extension host and try your changes live.

Testing

The suite is split into three layers, all runnable with bun run test:

• Unit — src/test/lineShift.test.ts: the pure line-shifting math (insert/delete/replace above, below, and across a note).
• Integration — src/test/noteStore.test.ts: JSON persistence and CRUD against a real temp directory.
• End-to-end — src/test/extension.test.ts: activation, CodeLens, hover, and live line-shifting driven by real document edits in a VS Code host (against the test-workspace/ fixture).

Packaging & publishing

bun run vsce:package   # build a .vsix (bunx @vscode/vsce package)
bun run vsce:publish   # publish to the VS Code Marketplace
bun run ovsx:publish   # publish to Open VSX

Release notes

See the CHANGELOG.

License

MIT