NoteVs

Project notes and code annotations, right inside VS Code. Works fully offline — no account needed.

Features

• 📝 Multiple notes per project — each folder gets its own isolated notes list
• 💻 Local-first — works completely offline, no account or internet required
• 🔗 Code annotations — select any lines in a file and attach a note to them (Cmd+Shift+N)
• 📦 Export & Import — back up your notes to a .notevs/ folder in your repo; restore them anytime with full fidelity
• 🤖 AI agent support — Claude Code and Cursor can create, read, and annotate notes via MCP (auto-registered on install)
• 🎨 Custom backgrounds — 12 background colours for your note editor
• ⚡ Auto-save — notes save as you type
• 🔒 Project-scoped — notes in Project A never appear in Project B, even across multiple VS Code windows

Getting Started

1. Click the NoteVs icon in the Activity Bar (left sidebar)
2. Open any project folder — your notes list for that project appears automatically
3. Press + to create a note and start writing

Code Annotations

Select any lines in a file, then:

• Press Cmd+Shift+N (Mac) / Ctrl+Shift+N (Windows/Linux)
• Or right-click → NoteVs: Annotate Selection
• Or click the 📎 Annotate selection status bar button

Annotated lines show a blue gutter highlight. Hover over them to see the note preview.

Annotations are collapsible inside the note editor — click any annotation row to expand or collapse it.

Export & Import

Click the |→ button in the sidebar toolbar to open the Export / Import menu.

Exporting

Exporting creates a .notevs/ folder at your repo root:

your-project/
  .notevs/
    notes.json          ← all note metadata + links to .md files
    root/
      my-note-abc123.md ← plain text, freely editable
    packages/api/
      other-note.md

• Each .md file contains only the note text — clean, no frontmatter, editable in any editor
• notes.json holds all metadata: title, status, priority, tags, Notion/Obsidian export state, Todoist/Google Tasks reminders, and annotations
• In a monorepo, notes are grouped into sub-folders matching your package structure (e.g. .notevs/packages/api/). Single repos use .notevs/root/
• Commit .notevs/ to git so your notes travel with the repo

Importing

Importing reads .notevs/ from your current workspace root and restores all notes:

• Full fidelity — Notion export badges, Todoist/Google Tasks reminder badges, and code annotations all come back automatically, no re-linking needed
• Idempotent — notes that already exist are skipped; only new ones are added
• External edits — if you edited a .md file outside NoteVs, re-importing picks up the updated content
• Workspace validation — NoteVs checks that the export belongs to the current project before importing; warns you if it came from a different repo
• Monorepo aware — folderPath on each note is remapped automatically if the workspace has moved

Use cases

• Backup — export before wiping your machine; import on the new one
• Team sharing — commit .notevs/ so teammates can import project notes
• Editing outside VS Code — open the .md files in any editor, write freely, then re-import to sync the changes back into NoteVs

AI Agent Support (MCP)

NoteVs includes a local MCP server that lets Claude Code, Cursor, and other AI agents read and write your project notes directly.

Auto-registration

When NoteVs activates, it automatically registers itself with Claude Code, Cursor, and VS Code Copilot agent mode. Just restart your agent after installing NoteVs and the tools will be available — no manual setup needed.

Manual setup (if auto-registration didn't work)

First, find the path to the MCP bridge. In your terminal:

Mac/Linux:

ls ~/.vscode/extensions/meshemugles1.notevs-*/dist/mcp-bridge.cjs

Windows:

dir "$env:USERPROFILE\.vscode\extensions\meshemugles1.notevs-*\dist\mcp-bridge.cjs"

Then register it with your agent:

Claude Code:

claude mcp add-json notevs '{
  "type": "stdio",
  "command": "node",
  "args": ["BRIDGE_PATH"]
}' -s user

Cursor — add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "notevs": {
      "command": "node",
      "args": ["BRIDGE_PATH"]
    }
  }
}

VS Code Copilot — add to ~/.vscode/mcp.json:

{
  "mcpServers": {
    "notevs": {
      "command": "node",
      "args": ["BRIDGE_PATH"]
    }
  }
}

Replace BRIDGE_PATH with the path from the ls / dir command above.

Note: VS Code must be open with NoteVs active for the MCP tools to work. The bridge talks to the extension over localhost:37491.

Available tools

Once registered, you can talk to your notes naturally:

• "List my notes for this project"
• "Create a note called 'Auth bug', priority urgent, tag backend"
• "Search my notes for anything about the login flow"
• "Add an annotation to src/auth.ts lines 45–52"
• "Mark the 'Fix race condition' note as done"
• "Export the 'Sprint plan' note to Notion"
• "Save the 'API design' note to my Obsidian vault"
• "Set a reminder for the 'Fix login bug' note for tomorrow at 09:00"

Full tool reference

Requirements for export/reminder tools:

• notevs_export_to_notion — Notion token must be saved in Settings → Integrations → Exporting
• notevs_export_to_obsidian — Obsidian Local REST API key or vault folder must be configured in Settings → Integrations → Exporting
• notevs_set_reminder — Todoist API token or Google Tasks must be connected in Settings → Integrations → Tasks

Notes are always scoped to the repo the agent is running in.

Settings

Keyboard Shortcuts