# Crush Migration (OpenCode → Charm)

## Why

`opencode-ai/opencode` archived Sep 2025. Successor: `charmbracelet/crush` (25.3k ⭐, actively maintained, 3,500+ commits). Crush v0.77.0+ vs opencode final v1.17.4.

## Install Crush

```bash
curl -sL "https://api.github.com/repos/charmbracelet/crush/releases/latest" \
  | python3 -c "import json,sys; d=json.load(sys.stdin); print([a['browser_download_url'] for a in d['assets'] if 'Linux_x86_64' in a['name'] and a['name'].endswith('.tar.gz')][0])" \
  | xargs curl -sL -o /tmp/crush.tar.gz
tar -xzf /tmp/crush.tar.gz -C /tmp/crush
sudo cp /tmp/crush/crush*/crush /usr/local/bin/
```

## CLI Comparison

| | OpenCode | Crush |
|---|---|---|
| Interactive | `opencode` | `crush` |
| One-shot | `opencode run "msg"` | `crush run "msg"` |
| Server | `opencode serve --port 4096` | `crush server` |
| Web UI | `opencode web` | **None** (headless only) |
| Config | `~/.config/opencode/opencode.json` | `crush.json` (local) |
| Auth | `opencode providers login` | `crush login` |
| Models | `opencode models` | `crush models` |

## Web UI Gap

Crush intentionally has no web UI — it's terminal-first (bubbletea TUI). If you need browser-based access, keep the old opencode server running on a port for the SPA while switching to Crush for actual agent work.

## Embedded Web UI Version Mismatch

The npm package `opencode-ai@1.17.4` ships with **v1.17.3 web assets** embedded in the Go binary. The web UI's error page says `Version: 1.17.3` even when the CLI reports `1.17.4`. The web assets were never rebuilt for 1.17.4 — the CLI binary version was bumped without recompiling the React frontend. This means the Settings context bug (v1.17.3) persists in v1.17.4 with no fix available.

## Config Migration

Crush reads `crush.json` from the current directory (or `--cwd`). The format is different from opencode. To see the expected schema:

```bash
crush --help  # includes EXAMPLES section with config patterns
```

## Key Facts

- Latest stable: v0.76.0 (Jun 5 2026), nightly: v0.77.0 (Jun 13 2026)
- Written in Go, single binary, no runtime deps
- Same agent patterns, different branding/UX