Brainforge Knowledge

Reset a broken OpenCode install with the official uninstaller

3 min read

Reset a broken OpenCode install with the official uninstaller

Context

We spent time on manual tree deletion (rm -rf on ~/.opencode, ~/.local/share/opencode, ~/.config/opencode) plus re-downloading the CLI. That path is fragile: large trees take a long time to delete, worktree/ paths can stay busy while other dev servers hold open directory handles, and it is easy to end up with a half-removed state that still misbehaves.

What actually worked in practice on Brainforge machines was OpenCode’s built-in uninstall command: opencode uninstall. It removes the CLI install and related files in one supported flow, with explicit flags for dry-run, keeping config, keeping session data, and non-interactive use.

Separately, opencode export remained the best offline signal for “is the assistant persisting text parts?” — see knowledge/engineering/opencode-blank-assistant-turns.md. Uninstall/reinstall addresses local install corruption or stale merged state; it does not by itself prove Zen or a specific model is healthy.

Guidance

  1. Prefer opencode uninstall over ad-hoc rm -rf. Run opencode uninstall --help on your installed version and treat the help text as source of truth for defaults.

    opencode uninstall --dry-run    # see what would be removed
opencode uninstall --force      # non-interactive full uninstall (example)

  2. Choose what to keep deliberately (flags vary by version; confirm in --help):

    • Use keep-config / keep-data style flags when you only want to refresh the binary but preserve ~/.config/opencode/opencode.json or session stores under ~/.local/share/opencode/.
    • Omit those flags when you want a true reset (you will re-merge models/providers and re-auth providers afterward).

  3. Reinstall the CLI after uninstall using the official installer (typical):

    curl -fsSL https://opencode.ai/install | bash

  4. Treat Desktop as its own channel. The CLI uninstaller may not remove /Applications/OpenCode.app, an older Beta app name, or a Homebrew cask install. If the GUI still looks wrong after a clean CLI reinstall, reinstall or remove Desktop explicitly (for example brew reinstall --cask opencode-desktop when you manage the app via Homebrew).

  5. Back up secrets before a wipe. Copy ~/.local/share/opencode/auth.json and ~/.config/opencode/opencode.json to a non-repo backup folder if you want faster recovery than re-pasting every provider key.

Why this matters

  • Official uninstall tracks OpenCode’s evolving layout; manual deletes drift from what the app actually uses and can leave “ghost” state behind.
  • Half-deleted ~/.local/share/opencode (especially under worktree/) is a common footgun when other processes still reference paths under that tree.

When to apply

  • Any time someone says “OpenCode is insane, wipe it and start over” — start with opencode uninstall --dry-run, then the smallest real uninstall that matches the goal (keep data vs not).
  • After major plugin merges (e.g. Compound Engineering installer) or suspected DB migration weirdness, when you want a known-clean baseline before re-debugging models or MCP.

Examples

# Inspect only
opencode uninstall --dry-run
 
# Full non-interactive reset (then reinstall CLI)
opencode uninstall --force
curl -fsSL https://opencode.ai/install | bash

Graph View

Backlinks