VSCodeDiscuss

Code discussions that live with your code

A Visual Studio Code extension for creating persistent, threaded discussions anchored to specific code locations. Perfect for code reviews, architectural decisions, documentation questions, and asynchronous collaboration.

✨ Features

📍 Location-Anchored Discussions

• Select any code and start a discussion thread
• Discussions stay anchored to specific lines/ranges
• Navigate instantly from discussion to code location

Select code, right-click, and add your comment - it's that simple!

🌳 Threaded Comments

• Reply to discussions and individual comments
• Infinite nesting depth for complex conversations
• Visual tree structure with indentation and connecting lines
• Each comment shows author and timestamp

Build conversation threads with nested replies

🎨 Beautiful Sidebar Panel

• Dedicated discussions view in the activity bar
• See all discussions at a glance
• Active/Resolved status badges
• Comment counts and file paths
• Click any discussion to jump to code

Click any discussion to instantly jump to the code location

Browse and manage all discussions from the sidebar

Mark discussions as resolved or unresolve them when needed

💾 Git-Versioned Storage

• Discussions stored as JSON in .vscode-discuss/ folder
• Version controlled alongside your code
• Optional auto-commit on changes
• Automatic Git synchronization - Background pull/commit/push for team collaboration
• Merge conflict detection and resolution UI
• Works offline by default
• Status bar indicator showing sync status

⚡ Fast & Lightweight

• No external dependencies
• All data stored locally
• Instant search and navigation
• Auto-refresh on changes

🚀 Quick Start

Installation

From VSIX (Manual Install):

1. Download the .vsix file from releases
2. Open VS Code
3. Run Extensions: Install from VSIX... command
4. Select the downloaded file

From Source (Development):

git clone https://github.com/ApprenticeDave/VSCodeDiscuss.git
cd VSCodeDiscuss
npm install
npm run compile
# Press F5 to launch extension development host

First Discussion

1. Open the sidebar: Click the 💬 icon in the activity bar
2. Select some code: Highlight the lines you want to discuss
3. Create discussion:
   • Right-click → "Add Comment" OR
   • Command Palette → "VSCode Discuss: Create Discussion"
4. Type your comment and press Enter
5. View in sidebar: Your discussion appears in the panel

Reply to Discussions

1. From the sidebar panel:

   • Click "↩ Reply" on any discussion or comment
   • Type your reply in the input field
   • Press "Reply" button to submit

2. Threaded replies:

   • Reply to the main discussion (top-level)
   • Reply to specific comments (nested)
   • Build conversation trees

Navigate to Code

• Click any discussion card to jump to the code location
• Click replies to navigate to the same location
• Code selection is highlighted automatically

📖 Usage Guide

Managing Discussions

Resolve a Discussion:

• Click "Resolve" button on a discussion
• Resolved discussions appear with ✓ badge
• Still visible but marked as complete
• Can be unresolve if needed

Delete a Discussion:

• Click "Delete" button
• Confirmation dialog appears
• Permanently removes the discussion

Refresh View:

• Click refresh icon in panel header
• Auto-refreshes after any change
• Syncs with file system changes

Git Integration

Enable Auto-Commit:

{
  "vscodeDiscuss.git.autoCommit": true,
  "vscodeDiscuss.git.commitMessageTemplate": "Update discussions: {{action}}"
}

Automatic Git Synchronization (NEW):

Keep discussions synchronized across your team automatically:

{
  "vscodeDiscuss.sync.enabled": true,
  "vscodeDiscuss.sync.intervalMinutes": 5,
  "vscodeDiscuss.sync.autoCommit": true,
  "vscodeDiscuss.sync.syncOnStartup": true,
  "vscodeDiscuss.sync.requireManualConflictResolution": true
}

How Auto-Sync Works:

1. Background Sync: Automatically pulls, commits, and pushes discussions at configured intervals
2. Status Bar Indicator: Shows current sync status with visual feedback
3. Manual Sync: Click status bar or run "Sync Discussions Now" command
4. Conflict Detection: Detects merge conflicts and provides resolution workflow

Sync Status Indicators:

• $(cloud) Sync Idle - Waiting for next sync
• $(sync~spin) Syncing... - Sync in progress
• $(check) Synced X min ago - Last successful sync
• $(warning) Sync Conflict - Merge conflict detected
• $(error) Sync Error - Sync failed

Commands:

• Sync Discussions Now - Manually trigger sync
• Enable Auto-Sync - Turn on background sync
• Disable Auto-Sync - Turn off background sync

Merge Conflict Handling: When conflicts occur in discussions.json:

1. Extension detects the conflict automatically
2. Status bar shows warning indicator ($(warning) Sync Conflict)
3. Sync is paused until conflicts are resolved
4. Resolution Options:
   • Resolve conflicts manually in Git Source Control view
   • After resolving, run "Sync Discussions Now" to resume
   • Extension will detect resolved state automatically

Best Practices:

• Pull before creating/editing discussions
• Enable auto-commit for automatic versioning
• Review conflicts before pushing
• Set appropriate sync interval (5-15 minutes recommended)
• Use manual sync when making many rapid changes

Troubleshooting:

Comment Tree Structure

Discussions use a tree structure:

Discussion (root comment)
├── Reply 1
│   ├── Reply to Reply 1
│   └── Another reply
├── Reply 2
└── Reply 3
    └── Nested reply
        └── Deeply nested

• Visual indentation shows hierarchy
• Left border connects related comments
• Reply to any level in the tree
• Infinite nesting supported

⚙️ Configuration

All available settings for VSCodeDiscuss:

Example Settings

{
  // Enable Git auto-commit
  "vscodeDiscuss.git.autoCommit": true,

  // Custom commit message (use {action} placeholder)
  "vscodeDiscuss.git.commitMessageTemplate": "docs: {action} discussion",

  // Enable automatic sync
  "vscodeDiscuss.sync.enabled": true,
  "vscodeDiscuss.sync.intervalMinutes": 10,
  "vscodeDiscuss.sync.autoCommit": true,
  "vscodeDiscuss.sync.syncOnStartup": true
}

🗂️ Data Storage

Discussions are stored in .vscode-discuss/discussions.json:

{
  "version": "1.0.0",
  "discussions": [
    {
      "id": "uuid-here",
      "filePath": "src/app.ts",
      "range": {
        "start": { "line": 10, "character": 0 },
        "end": { "line": 15, "character": 30 }
      },
      "status": "active",
      "createdAt": "2025-11-20T10:00:00Z",
      "updatedAt": "2025-11-20T10:30:00Z",
      "author": {
        "name": "John Doe",
        "email": "john@example.com"
      },
      "comments": [
        {
          "id": "comment-uuid",
          "body": "Should we refactor this?",
          "author": { "name": "John Doe", "email": "john@example.com" },
          "createdAt": "2025-11-20T10:00:00Z",
          "updatedAt": "2025-11-20T10:00:00Z"
        },
        {
          "id": "comment-uuid-2",
          "body": "Yes, I think so.",
          "author": { "name": "Jane Smith", "email": "jane@example.com" },
          "parentId": "comment-uuid",
          "createdAt": "2025-11-20T10:30:00Z",
          "updatedAt": "2025-11-20T10:30:00Z"
        }
      ]
    }
  ]
}

Key Points:

• Human-readable JSON format
• File paths are relative to workspace root
• Line numbers are zero-indexed
• parentId creates comment threading
• Version field for future migrations

🎯 Use Cases

Code Review Discussions

• "Why did we choose this approach?"
• "This could be optimized..."
• "Security concern here"

Documentation & Onboarding

• "What does this function do?"
• "How do I use this API?"
• "Where is this used?"

Architecture Decisions

• "Should we refactor this module?"
• "Alternative design approaches?"
• "Technical debt to address"

Async Team Collaboration

• Leave questions for teammates in different timezones
• Document decisions without meetings
• Build institutional knowledge

🔧 Development

Project Structure

VSCodeDiscuss/
├── src/
│   ├── extension.ts          # Extension entry point
│   ├── controllers/           # VS Code comment controllers
│   ├── models/                # Data models & types
│   ├── services/              # Business logic
│   ├── providers/             # VS Code providers
│   ├── views/                 # Webview panel
│   └── utils/                 # Helper functions
├── .vscode-discuss/           # Sample discussions
├── package.json               # Extension manifest
└── README.md                  # This file

Building

npm install          # Install dependencies
npm run compile      # Compile TypeScript
npm run watch        # Watch mode for development
npm run test         # Run tests (94 passing)
npm run lint         # ESLint
npm run format       # Prettier

Testing

npm test
# ✓ 94 tests passing (100% success rate)
# - 33 model tests (Discussion, Comment, Author, Storage)
# - 14 storage service tests
# - 6 comment controller tests
# - 5 git user service tests
# - 9 git service tests
# - 4 discussion command tests
# - 6 sync command integration tests
# - 3 sync service tests
# - 2 sync status bar tests
# - 2 sync git integration tests
# - 10 extension integration tests

📝 Roadmap

✅ Completed (v0.1.0 & v0.2.0)

• [x] Phase 1: Foundation & data models
• [x] Phase 2: VS Code commenting API
• [x] Phase 3: Git integration & user detection
• [x] Webview sidebar panel with threaded UI
• [x] Threaded comment trees with infinite nesting
• [x] Automatic Git synchronization for team collaboration
• [x] Status bar sync indicator with visual feedback
• [x] Manual sync commands (Sync Now, Enable/Disable)
• [x] Comprehensive test suite (94 tests, 100% passing)
• [x] Performance optimizations (Git repository caching, debounced file watchers)
• [x] Enhanced error messaging with actionable guidance
• [x] Improved logging with contextual information

📋 Planned Features

• [ ] Markdown rendering in comments
• [ ] Edit existing comments
• [ ] Search & filter discussions
• [ ] Export discussions (markdown, PDF)
• [ ] Code lens integration
• [ ] Discussion templates
• [ ] @mentions support
• [ ] Emoji reactions
• [ ] GitHub integration
• [ ] Discussion analytics dashboard

🤝 Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Run npm test and npm run lint
6. Submit a pull request

📄 License

MIT License - see LICENSE file for details

🙏 Acknowledgments

• Built with VS Code Extension API
• Inspired by GitHub Discussions and code review tools
• Memory bank system from awesome-copilot

Questions? Open an issue on GitHub
Ideas? Start a discussion in our repository