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
vr --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:

vr 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)

No restore points being recorded:

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

Permission denied (EACCES):

chmod -R 755 .vreko/

AI tool not detected:

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

Detection is automatic - there is no .vrekorc key to force it. The daemon classifies a session as ai-assisted from file-event timing and velocity, not from a configured tool name. Slow, human-paced edits are classified as human; both are observed.

Too many files flagged as elevated risk? Set a less aggressive default in .vrekorc:

{
  "protection": { "defaultLevel": "watch", "autoProtectConfigs": false }
}

MCP not connecting:

⌘+Shift+P → Vreko: MCP Reconnect

Run diagnostics:

⌘+Shift+P → Vreko: MCP Diagnose

Verify CLI:

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

vreko / vreko_end sessions not linking:

If vreko opens a session but vreko_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
   vr status

2. Check what your MCP config is pointing at - it should use the local Vreko binary, not a remote endpoint.

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? The most effective fix is to stop Vreko from observing large or generated directories. Add a .vrekoignore at your project root - one glob per line, # for comments (same syntax as .gitignore):

# .vrekoignore
**/node_modules/**
**/dist/**
**/.next/**
*.mp4
*.zip

Old learnings are archived automatically per the learning.maxAgeDays setting in .vrekorc (default 90 days) - no manual cleanup command is required.