CodeNotes — Native Code Memory for VS Code

A native, zero-friction note system that lives inside your editor — not on top of it.

Philosophy

Quick Start

1. Install dependencies

npm install
npm run compile

2. Set up Supabase (optional — works offline too)

1. Create a project at supabase.com
2. Run supabase-migration.sql in the SQL editor
3. Copy your Project URL and Anon key
4. In VS Code settings:
   • codenotes.supabaseUrl → your project URL
   • codenotes.supabaseAnonKey → your anon key

3. Press F5 to launch Extension Development Host

Usage

Creating a note

• Ctrl+Alt+N (Win/Linux) or Cmd+Alt+N (Mac) — instant input box on the current line
• Right-click any line → CodeNotes: Add Note Here
• Command Palette: CodeNotes: Add Note Here

Viewing notes

• Gutter icons — colored dots next to noted lines
• Hover over a noted line to preview the note
• CodeLens — click the inline label above the line
• Sidebar — Explorer panel → CodeNotes section

Searching

• Ctrl+Alt+F — fuzzy search across all notes
• Sidebar filter (type in the search box in the toolbar)
• Dashboard → filter by file, color, text

Dashboard

• Command: CodeNotes: Open Dashboard
• Opens to the side (doesn't replace your editor)
• Filter, search, manage workspaces, sign in/out

Architecture

extension.ts          ← entry point, wires everything
├── storage/
│   └── NoteStore.ts  ← in-memory cache + globalState persistence
├── providers/
│   ├── DecorationProvider.ts   ← gutter icons + line highlights
│   ├── NoteHoverProvider.ts    ← hover tooltips
│   ├── NoteCodeLensProvider.ts ← inline note count
│   └── NoteTreeProvider.ts     ← sidebar tree
├── commands/
│   └── index.ts      ← all command handlers
├── sync/
│   └── SyncEngine.ts ← Supabase background sync
└── webview/
    └── DashboardPanel.ts ← HTML dashboard (browse/manage only)

Data Model

interface Note {
  id: string;               // UUID
  text: string;             // Note content
  filePath: string;         // Absolute path
  fileRelativePath: string; // Relative to workspace
  line: number;             // 0-indexed
  lineText: string;         // Snapshot of line at creation
  workspaceId: string;      // VS Code workspace URI
  userId: string | null;    // Supabase user ID
  createdAt: string;        // ISO timestamp
  updatedAt: string;
  syncedAt: string | null;
  isDirty: boolean;         // Has unsynced changes
  isDeleted: boolean;       // Soft delete
  tags: string[];
  color: 'amber'|'blue'|'green'|'red'|'purple';
}

Sync Strategy

1. Write → saved immediately to globalState (local)
2. Debounce → 3 seconds after last change, push to Supabase
3. Pull → every 30 seconds, merge remote notes
4. Conflict → last-write-wins on updated_at
5. Offline → works fully offline, syncs when reconnected

VS Code APIs Used

Configuration

Performance Considerations

• No lag on file open: notes load from in-memory cache, not disk
• Decorations are incremental: only re-render visible editors
• Sync is debounced: rapid typing doesn't trigger network calls
• Webview is lazy: only created when user opens dashboard
• Tree view uses VS Code's virtual rendering: handles thousands of notes

Built to feel like breakpoints and hover-docs — not a separate app. "# lync"