NoteStack

Inline annotation layer for VS Code — attach persistent, drift-aware, prioritized notes to any line or selection in your codebase, across all your projects, without modifying source files.

Features

For the detailed feature reference, see docs/FEATURES.md.

Usage

Add / Edit a Note

Place cursor on the target line — or select a range of lines — then:

• Keyboard: Ctrl+Shift+N / Cmd+Shift+N
• Right-click: context menu → Add / Remove Note

The note editor opens as a panel. Write your note, select a priority, optionally attach a reference URL and mark as private, then Ctrl+Enter to save or Escape to cancel. If a note already exists on that line, the editor opens pre-populated for editing.

NoteStack supports basic formatting in the browser panel:

Selection Annotations

Select one or more lines before adding a note — the selection range is saved alongside the note. When you navigate to the note later, the original selection is restored and highlighted in the editor.

Move a Note

Place cursor on the line with an existing note — or make a selection to re-anchor the range — then:

• Right-click: context menu → Move Note

Move the cursor (or make a new selection) at the target position, then:

• Right-click: context menu → Place Note Here

Works across files in the same workspace. The moved note inherits the new line, character, and selection range. Click Cancel in the notification to abort.

Notes Browser

Opens a full panel showing all notes across all workspaces with search, sort 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

Note Cards

Each card shows workspace, file, line, author, machine, timestamp, relative age, and full note body.

• Click the location info in the top-right corner of the note card to preview a live code snippet around the annotated line.

• Click the note title to jump directly to the file and annotated line — including files from other workspaces.

• Click the workspace name to open the file in its own project in a new window.

Priority

Set priority when saving a note via the dropdown:

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.

Tags

You can organize notes using hashtags anywhere in the note text (e.g. #bug, #refactor, #work).

• Tags are automatically detected and shown as clickable pills in the Notes Browser.
• Click one or more tag pills to filter the list.
• Multiple tags can be selected (AND logic).

Example note: Fix race condition here #bug #performance N42-187

The note will appear under both #bug and #performance filters.

Cloud Sync & Collaboration

NoteStack supports cloud sync and lightweight team collaboration by pointing the storage location to any synced folder.

Edit your VS Code settings.json:

{
  "noteStack.storageLocation": "/path/to/your/cloud/folder/NoteStack",
  "noteStack.showSharedNotes": true
}

Each machine writes its own note-stack-<machineId>.json file — no write conflicts. When showSharedNotes is enabled, the browser panel merges notes from all machines in the folder. Private notes are only visible on the machine that created them.

Tested with Dropbox, OneDrive, iCloud Drive, and Syncthing. Create a dedicated subfolder rather than placing notes in the root of your cloud folder.

Ticket Linking

NoteStack automatically detects ticket references in note text and renders them as clickable links in the Notes Browser. Supports Jira, Linear, GitHub Issues, and any custom tracker.

Configure in settings.json:

"codeNotes.ticketTrackers": [
  { "prefixes": ["N42", "FEAT"], "system": "jira",    "baseUrl": "https://yourco.atlassian.net"     },
  { "prefixes": ["LIN"],         "system": "linear",  "baseUrl": "https://linear.app/yourworkspace" },
  { "prefixes": ["GH"],          "system": "github",  "baseUrl": "https://github.com/org/repo"      },
  { "prefixes": ["TASK"],        "system": "custom",  "baseUrl": "https://tracker.io/issues/{key}"  }
]

Any note containing a matching ticket ID — e.g. N42-123 or FEAT-123 — will render the ID as a direct link to that ticket in the browser panel. Multiple prefixes can point to the same tracker instance.

Known Limitations

NoteStack anchors notes to specific line positions without modifying your source files. When code is added, removed, or rearranged, note positions can become outdated — this is a common limitation of all external annotation tools that don't pollute your codebase.

The drift detection feature warns you when this happens. Use NoteStack together with Git history or GitLens to locate the original context and re-anchor notes manually when needed.

Settings

Storage

Notes are written to two locations on every save:

# Primary — per machine, shared across all VS Code instances
<globalStorageUri>/note-stack-<machineId>.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.

Data Format

// note-stack-<machineId>.json
{
  "file:///home/user/projects/myapp": {
    "src/server.ts": [
      {
        "id": "c9a41cf4-...",
        "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...",
        "hostName": "n42",
        "private": false,
        "anchor": "private init ...",
        "textSel": {
          "startLine": 42,
          "endLine": 45,
          "startChar": 0,
          "endChar": 3
        },
        "refUrl": "https://github.com/org/repo/issues/42",
        "commitHash": "fe8b06d5..."
      }
    ]
  }
}

Priority is categorized as high | medium | low | completed or absent.

Other Commands

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