Troubleshooting Guide

Quick Fix: Restart VS Code and try again.

Detailed Solutions:

1. Ensure you’re using VS Code version 1.70+ (Help → About)
2. Check your internet connection
3. Clear extension cache:

   Copy# Close VS Code completely
   rm -rf ~/.vscode/extensions/marcellelabs.snapback-*
   # Restart VS Code and reinstall

4. Try manual install:

   Copycode --install-extension marcellelabs.snapback

Quick Fix: Check if SnapBack icon (🧢) is green in status bar. If red, click to activate.

Detailed Solutions:

1. Verify extension is enabled:

   • Open Extensions panel (⌘+Shift+X)
   • Search for “SnapBack”
   • Ensure it shows “Enabled”

2. Check Output panel for errors:

   CopyView → Output → Select "SnapBack" from dropdown

3. Verify file isn’t ignored:

   • Check .snapbackignore in your project root
   • Ensure file extension is protected

4. Test with a simple file:

   Copy// test-snapback.js
   console.log("Testing SnapBack");
   // Save this file (Cmd+S)
   // Check status bar for snapshot confirmation

Quick Fix: Check if .snapback directory exists and is writable.

Common on macOS/Linux:

Copy# Check directory permissions
ls -la .snapback/

# Fix permissions if needed
chmod -R 755 .snapback/

If issue persists:

• Change storage location in VS Code settings:

  Copy{
    "snapback.storagePath": "/Users/yourname/snapback-storage"
  }

Quick Fix: Make a change using your AI tool, then save. Check status bar for AI detection badge.

Supported AI Tools:

• 🔵 Cursor (auto-detected)
• 🟪 Copilot (auto-detected)
• 🟠 Claude Code (auto-detected)
• 🔷 Windsurf (auto-detected)

Manual Detection: If SnapBack doesn’t auto-detect your AI tool:

Copy// .snapbackrc
{
  "aiDetection": {
    "forceEnable": true,
    "tool": "your-ai-tool-name"
  }
}

Quick Fix: Run “SnapBack: MCP Reconnect” from Command Palette.

Common Symptom: Status bar shows SB·MCP ✓ (checkmark) but AI assistant can’t use MCP tools.

Why This Happens:

• All MCP server processes connect to one daemon socket
• If the daemon socket breaks, ALL AI assistants disconnect
• Status bar detects the MCP process is running (not the actual connection)

Solutions (in order of priority):

1. Force Reconnection (Recommended):

   CopyCommand Palette (⌘+Shift+P) → SnapBack: MCP Reconnect

   This fixes ALL workspaces and AI assistants at once.

2. Run Diagnostics:

   CopyCommand Palette → SnapBack: MCP Diagnose

   Shows actual connection state, circuit breaker status, and daemon health.

3. Verify CLI Installation:

   Copy# Check if CLI is installed
   npx @snapback/cli --version
   
   # If not installed:
   npm install -g @snapback/cli

4. Check Multi-Workspace Setup: If you have 3 Cursor windows open, you should see 3 MCP processes:

   Copyps aux | grep "snap mcp --stdio"

   Each should have a different --workspace path.

5. Validate Configuration Files:

   • Cursor: .cursor/mcp.json in your project
   • Qoder: .qoder-mcp-config.json or global config
   • Claude: ~/Library/Application Support/Claude/claude_desktop_config.json

6. Reset MCP Configuration:

   CopyCommand Palette → SnapBack: MCP Reset

   Then restart your AI assistant.

See Full MCP Troubleshooting: MCP Documentation →

Quick Fix: Adjust sensitivity in settings.

Lower AI Detection Sensitivity:

Copy// .snapbackrc
{
  "autoDecisionEngine": {
    "riskThreshold": 70,  // Default: 60 (higher = less sensitive)
    "notifyThreshold": 50  // Default: 40
  }
}

Ignore Specific Patterns:

Copy{
  "exclude": [
    "**/mock-data/**",
    "**/*.example.js",
    "**/*.test.ts"
  ]
}

Quick Fix: Clean up old snapshots.

Check Snapshot Count:

Copy# Count snapshots
ls -la .snapback/snapshots/ | wc -l

Clean Up Old Snapshots:

• Via VS Code: Command Palette (⌘+Shift+P) → “SnapBack: Clean Old Snapshots”
• Via CLI:

  Copysnapback cleanup --keep 30d

Exclude Large Directories:

Copy// .snapbackignore
{
  "exclude": [
    "**/node_modules/**",
    "**/dist/**",
    "**/.next/**",
    "*.log"
  ]
}