NoteStack
Inline annotation layer for VS Code — attach persistent, prioritized notes to any line in your codebase without modifying source files.
Features
| Feature |
Detail |
| Inline annotations |
Attach multi-line notes to any file/line position via gutter icon + highlight |
| Priority system |
Mark notes 🔴 High / 🟡 Medium / 🟢 Low / ✅ Completed — sorted and color-coded throughout the UI |
| Completed status |
Mark notes as done — filtered out of the default view, greyed out when shown |
| Notes Browser |
Full-panel webview listing every note across all workspaces with search and priority filtering |
| Global persistence |
Notes stored in VS Code's global storage — survive workspace deletion, visible across all instances |
| Cloud sync |
Point storage to Dropbox/iCloud/GDrive via settings for cross-machine sync |
| Local mirror |
.vscode/note-stack.json written in parallel so notes can be committed to git |
| Export to Markdown |
Export all notes across all workspaces to a single .md file |
| Clickable URLs |
http, https, ftp, mailto links in note text are clickable in the browser panel |
| Tree view |
Sidebar panel grouped by file, sorted by priority then line |
| Moveable notes |
Right-click any annotated line → Move Note, then right-click target line → Place Note Here |
| Time-aware tooltips |
Hover any annotated line to see the note, priority, and relative age (5m ago, 3d ago) |
Usage
Add / Edit a Note
Place cursor on the target line, then:
- Keyboard:
Ctrl+Shift+N / Cmd+Shift+N
- Right-click: context menu → Add Note
The note editor opens as a panel. Write your note, select a priority from the dropdown, then Ctrl+Enter to save or Escape to cancel. If a note already exists on that line, the editor opens pre-populated for editing.
Move a Note
Place cursor on the line with an existing note, then:
- Right-click: context menu → Move Note
Move the cursor to the target line, then:
- Right-click: context menu → Place Note Here
Works across files in the same workspace. Click Cancel in the notification to abort the move.
Notes Browser
Opens a full panel showing all notes across all workspaces with search and priority filter:
- Button: preview icon in the NoteStack tree view header bar
- Keyboard:
Ctrl+Shift+Alt+B / Cmd+Shift+Alt+B
- Command Palette:
NoteStack: Open Notes Browser
Each card shows workspace, file, line, timestamp, relative age, and full note body. Clicking a note title navigates directly to that file and line in the editor — including files from other workspaces. Clicking ↗ opens that workspace in a new window.
Priority
Set priority when saving a note via the dropdown:
| Priority |
Icon |
Use |
| High |
🔴 |
Blocking issues, critical paths |
| Medium |
🟡 |
Important but non-blocking |
| Low |
🟢 |
Nice-to-have, minor observations |
| Completed |
✅ |
Resolved — hidden from default view |
| No Priority |
⚪ |
General annotations |
Notes are sorted priority-first throughout the tree view, browser panel, and QuickPick lists. Completed notes are filtered out of the default All view and shown only when the Completed filter is selected.
Known Limitations
NoteStack anchors notes to specific line positions without modifying your source files. For frequently changing codebases, use NoteStack together with Git history or GitLens to more easily locate the original context and re-anchor notes manually when needed.
Line-shifting issue
When you add, remove, or rearrange code, note positions can become outdated, this is a common limitation of all external annotation tools that don't pollute your codebase. There is no perfect lightweight solution for this problem. NoteStack is deliberately kept simple rather than adding complex auto-tracking logic that is often unreliable.
Cloud Sync
NoteStack supports easy cloud synchronization by pointing the storage location to any folder that is synced by Dropbox, Google Drive, OneDrive, Syncthing, etc. Works with any cloud provider that syncs a local folder.
Edit your VS Code settings.json and add or modify the following setting:
{
"codeNotes.storageLocation": "/path/to/your/cloud/folder/"
}
Preferably create a dedicated subfolder (e.g. NoteStack) instead of putting notes in the root of your cloud folder.
Other Commands
| Command |
Keybind |
Action |
| Remove Note at Line |
Ctrl+Shift+D |
Removes note at cursor line |
| Show Notes in Current File |
— |
QuickPick list for the active file |
| Show All Notes in Workspace |
Ctrl+Shift+Alt+N |
QuickPick across all files |
| Export All Notes to Markdown |
— |
Saves all notes across all workspaces to .md |
| Clear All Notes in Workspace |
— |
Destructive wipe with confirmation |
Storage
Notes are written to two locations on every save:
# Primary — shared across all VS Code instances
<globalStorageUri>/note-stack-<appId>.json
# Secondary — per-workspace, git-trackable
<workspaceRoot>/.vscode/note-stack.json
The global store is keyed by workspace URI. On first launch with an existing .vscode/note-stack.json, notes are automatically migrated to global storage.
To commit notes to source control, add .vscode/note-stack.json to your repository. To exclude them, add it to .gitignore.
// note-stack-<appId>.json
{
"file:///home/user/projects/myapp": {
"src/server.ts": [
{
"line": 42,
"character": 0,
"note": "Race condition here under high load — see issue [#42](https://github.com/node42-dev/note-stack/issues/42)",
"timestamp": "4/2/2026, 4:42:00 AM",
"priority": "high",
"author": "Alex",
"machineId": "4b82d310...",
"private": false
}
]
}
}
priority is "high" | "medium" | "low" | "completed" or absent.
Build & Install
npm install
npm run compile
npm run package
npx @vscode/vsce package --no-dependencies --out dist/
code --install-extension "dist/note-stack-$(node -e "console.log(require('./package.json').version)").vsix"
Requirements
- VS Code
^1.74.0
- Node.js
^16 (build only)
License
MIT — see LICENSE.txt
Author
Alex Olsson
LinkedIn
