Agent & CLI Troubleshooting

The Rust agent sidecar (crab-desktop-agent) handles all data operations. The Crab CLI is used for write operations (push, hydrate, dehydrate).

Agent Status

Check the Health view (HeartPulse icon) for:

• 🟢 OK — agent is running normally
• 🟡 Degraded — agent is running but reporting warnings
• 🔴 Error — agent has crashed or is unresponsive

Agent Crashes

Symptom: Operations fail with "agent exited before response" errors.

What happens automatically:

• The main process detects the crash
• All pending operations are rejected with an error
• The agent is restarted (max 1 auto-restart per 30 seconds)
• UI state is preserved (no data loss)

If crashes persist:

1. Check the Health view for the crash reason
2. Enable debug logging: Settings → Diagnostics → Agent Log Level → debug
3. Reproduce the issue and copy diagnostics from the Health view
4. File a bug report with the diagnostics

Agent Not Starting

Symptom: Health view shows 🔴 and "Agent not running".

Solutions:

1. Binary missing: The agent binary should be bundled with the app. Reinstall if missing.
2. Permission denied: On macOS, ensure the app has permission to execute binaries (System Preferences → Security)
3. Port/resource conflict: Another instance of the app may be running. Check Activity Monitor for crab-desktop-agent processes and kill stale ones.

CLI Not Found

Symptom: Health view shows "CLI: not installed". Push, hydrate, and dehydrate operations fail.

Solutions:

1. Install the CLI: cd crab && make install
2. Verify it's in your PATH: which crab should return ~/.cargo/bin/crab
3. Restart the app (PATH is resolved on startup)

CLI Version Mismatch

Symptom: Health view shows a warning about CLI version.

The desktop agent and CLI should be from compatible versions. If you see unexpected behavior after updating one but not the other:

1. Update both: cd crab && git pull && make install
2. Restart the app

Increasing Log Verbosity

For debugging agent issues:

1. Settings → Diagnostics → Agent Log Level
2. Set to debug or trace
3. Reproduce the issue
4. Copy diagnostics from the Health view (includes recent log lines)

The CRAB_DESKTOP_LOG environment variable also controls verbosity if set before launching the app:

CRAB_DESKTOP_LOG=trace open -a "Crab Desktop"

Manual Agent Restart

If the agent is in a bad state:

1. Health view → Restart Agent button
2. Or: Command Palette → "Restart Agent"

This kills the current agent process and spawns a fresh one. All pending operations will fail, but the app recovers immediately.