Add invisible comments to your code that do not modify files and are hidden from version control.
Overview
Phantom Comments is a VS Code extension that allows you to annotate lines of code with personal or team notes without modifying the actual source files. These comments are stored separately and stay attached to their respective code blocks even as lines move during development.
Common use cases include:
Personal code notes during review or learning.
Debugging breadcrumbs that should not be committed.
Team collaboration without cluttering the source code.
TODOs and reminders that stay contextually linked.
Features
Core Functionality
Invisible Comments: Add annotations that do not appear in your source files or git history.
Smart Anchoring: Comments automatically track code changes, insertions, and deletions.
Fuzzy Recovery: Comments use context matching to relocate their correct positions after major edits.
Markdown Support: Full markdown capabilities with a live preview in the editor.
Comment Categories: Organize notes by type (Note, TODO, Question, Warning, Idea, or Bug).
Tagging System: Use custom tags for advanced filtering and organization.
Team Collaboration
Team Sharing: Share specific comments with teammates by toggling the shared status.
Decentralized Sync: Collaborative comments are stored in a .phantom-comments JSON file designed for Git.
Conflict Resolution: Intelligent merging and conflict detection for concurrent edits.
Mentions: Tag teammates using the @@username syntax to trigger notifications.
Real-time Updates: A file-watching system ensures changes from teammates appear instantly.
Navigation and Search
Search: Full-text search across all workspace comments.
Tag Filtering: Quickly narrow down comments based on specific tags.
Branch Awareness: Maintain separate sets of comments for different Git branches.
Explorer View: Browse all comments in a structured tree view in the sidebar.
Quick Start
Place your cursor on any line of code.
Press Cmd+Alt+C (Mac) or Ctrl+Alt+C (Windows/Linux).
Draft your comment using markdown.
Press Cmd+Enter to save.
Keyboard Shortcuts
Shortcut
Action
Cmd+Alt+C
Add comment at cursor
Cmd+Alt+Shift+C
Add comment to selection
Cmd+Alt+F
Search comments
Cmd+Alt+H
Toggle comment visibility
Cmd+Alt+E
Expand or collapse comment
Cmd+Alt+X
Export to markdown
Cmd+Alt+M
Enter move mode (drag and drop)
Alt+]
Navigate to next comment
Alt+[
Navigate to previous comment
Configuration
Setting
Default
Description
phantomComments.showGutterIcons
true
Show icons in the editor gutter.
phantomComments.showInlinePreviews
true
Show inline preview text next to code.
phantomComments.inlinePreviewMaxLength
50
Maximum characters for inline previews.
phantomComments.enableBranchAwareness
true
Enable branch-specific comment sets.
phantomComments.enableRealTimeSync
true
Enable real-time sync for team updates.
phantomComments.enableCodeLens
true
Show expand/collapse actions above code.
phantomComments.enableMentionNotifications
true
Receive notifications for @mentions.
phantomComments.issueBaseUrl
""
Base URL for issue linking (e.g., GitHub).
How It Works
Comments are stored in a .phantom-comments/comments.json file within your workspace root.
To keep comments private, add .phantom-comments/ to your .gitignore.
To share comments with a team, commit the .phantom-comments/ folder to your repository.
The extension uses a multi-layered anchoring system:
Content Hashing: Comments are primarily linked to the exact text of a line.
Contextual Fingerprinting: Surrounding lines are used to verify position.
Fuzzy Matching: Similarity algorithms recover positions even after code formatting or minor edits.
License
MIT License - see the LICENSE file for details.
Built for developers who require contextual notes without codebase clutter.
