Reset & Recovery

When things go wrong, these steps help you recover without losing data.

Soft Reset (Reload Window)

Fixes: UI glitches, stale state, rendering issues.

• Press Cmd+R to reload the renderer
• Or: Command Palette → "Reload Window"

This preserves all settings and open repos. Only the renderer restarts.

Clear State & Reload

Fixes: Corrupted localStorage, broken UI state, persistent blank screens.

• Settings → Reset → Clear State & Reload
• Or: Command Palette → "Clear State and Reload"

This clears:

• localStorage (open repos, sidebar order, panel sizes)
• Cached metrics and preferences

It does NOT clear:

• Settings file (main-settings.json)
• Forge tokens (stored in OS keychain)
• Repository data

After clearing, you'll need to re-open your repositories.

Reset Settings to Defaults

Fixes: Misconfigured settings causing unexpected behavior.

• Settings → Reset → Reset All Settings

This restores all preferences to their defaults. Forge tokens and repo data are preserved.

Reset Layout

Fixes: Panels in wrong positions, invisible views, broken splits.

• Settings → Reset → Reset Layout

Restores default panel sizes and activity bar order.

Restart Agent

Fixes: Agent in a bad state, operations timing out, stale connections.

• Health view → Restart Agent
• Or: Command Palette → "Restart Agent"

This kills and respawns the Rust sidecar. All pending operations fail, but the app recovers immediately.

Clear Chunk Cache

Fixes: Disk space issues, corrupted cache, stale previews.

• Settings → Cache → Clear Cache
• Or: Health view → Clear Cache

This removes all cached chunks from ~/.cache/crab/. Files will be re-downloaded from cloud storage on next access. Safe to do at any time.

Clean Staging Area

Fixes: Stuck push operations, orphaned staging data.

• Health view → Clean Staging

Removes chunks from .crab/staging/ that belong to failed or interrupted operations. Active staging data (from a recent crab add) is preserved.

Remove Orphaned Worktrees

Fixes: Stale manual worktrees consuming disk space.

Use the Worktrees view → right-click → Remove on stale entries, or inspect and remove them with standard Git commands:

git worktree list
git worktree remove --force <path>

Full Reset (Nuclear Option)

If nothing else works:

1. Quit the app completely
2. Delete the config directory:

   rm -rf ~/.config/crab-desktop/

3. Optionally clear the cache:

   rm -rf ~/.cache/crab/

4. Relaunch the app

This gives you a fresh-install experience. Your repositories and git history are untouched — only app preferences and cache are removed.

Recovering from a Corrupted Repository

If git operations fail with "corrupt object" or similar errors:

1. Run git fsck in the terminal to identify corruption
2. If the repo uses Crab, run crab fsck to verify chunk integrity
3. For severe corruption, re-clone from the remote

The desktop app never modifies .git/objects directly — corruption is typically caused by disk errors or interrupted operations at the OS level.

Getting Help

If none of the above resolves your issue:

1. Open the Health view
2. Click Copy Diagnostics
3. File a bug report with the diagnostics attached
4. Include steps to reproduce the issue