Troubleshooting

When Vreko first loads it checks five preconditions. If any are unmet, the status bar shows an actionable message instead of 🦎. Click the status bar item to resolve each one.

$(warning) Install Vreko CLI The Vreko CLI is not installed or not on your PATH.

npm install -g @vreko/cli
vreko --version

Or click the status bar item - it opens a terminal and runs the install automatically.

$(sync~spin) Starting Vreko… The service is starting. This resolves on its own within a few seconds. If it persists, reload VS Code (⌘+Shift+P → Developer: Reload Window).

$(key) Sign in to Vreko You are not authenticated. Click the status bar item to open the sign-in flow in your browser, then return to VS Code.

$(folder) Initialize workspace This workspace has not been initialized. Click the status bar item or run:

vreko init

$(plug) Connect AI tool MCP is not configured for your AI assistant. Click the status bar item or run ⌘+Shift+P → Vreko: Configure MCP. Supported tools configure automatically - no manual editing needed.

Extension not installing:

# Close VS Code, clear cache, reinstall
rm -rf ~/.vscode/extensions/marcellelabs.vreko-*
code --install-extension MarcelleLabs.vreko-vscode

Requirements:

• VS Code 1.70+
• Node.js 14+ (for CLI)

Not creating snapshots:

1. Check status bar for 🦎 icon (green = active)
2. Save a file with Cmd+S / Ctrl+S
3. Check Vreko sidebar

Permission denied (EACCES):

chmod -R 755 .vreko/

AI tool not detected:

• Make a change with AI, then save
• Check status bar for AI detection badge

Force detection:

// .vrekorc
{
  "aiDetection": {
    "forceEnable": true,
    "tool": "cursor"
  }
}

Too many false positives:

{
  "autoDecisionEngine": {
    "riskThreshold": 70
  }
}

MCP not connecting:

⌘+Shift+P → Vreko: MCP Reconnect

Run diagnostics:

⌘+Shift+P → Vreko: MCP Diagnose

Verify CLI:

npm install -g @vreko/cli
vreko --version

snap_begin / snap_end sessions not linking:

If snap_begin creates a session but snap_end reports “No active session to close”, the MCP server is not connecting to your local service correctly.

1. Verify the service is running:

   ls ~/.vreko/service.sock
   vreko service status

2. Check what your MCP config is pointing at - it should use the local Vreko binary, not a remote endpoint. See Session Not Linking → for the full diagnostic.

3. Rebuild and restart the MCP server:

   pnpm --filter @vreko/cli build
   # Then reload your AI assistant

Sessions created in one workspace not visible in another:

Each workspace must have its own MCP server process with its specific workspace path. Sessions are workspace-scoped by design - this is expected behavior, not a bug.

Slow performance:

# Clean old snapshots
vreko cleanup --keep 30d

# Or via VS Code
⌘+Shift+P → Vreko: Clean Old Snapshots

Exclude large directories:

// .vrekoignore
{
  "exclude": ["**/node_modules/**", "**/dist/**"]
}