feat(crush): add installer for Charm's AI coding assistant

[ogormans-deptstack]

Summary

Add installer for crush — Charm's terminal-based AI coding assistant.

Changes

• crush/releases.js — fetches from charmbracelet/crush, filters goreleaser archives (tar.gz/zip with underscore naming, excludes nightly/sbom/packages/source tarballs)
• crush/install.sh — POSIX installer with goreleaser subdirectory pattern (crush_VERSION_OS_arch/), shell completions (bash/zsh/fish), manpage installation, and pkg_done_message
• crush/install.ps1 — Full Windows PowerShell installer following the _example/install.ps1 template (download, extract, move, copy)
• crush/README.md — Concise cheat sheet following webi conventions
• crush/SKILL.md — Agent-focused documentation (per coolaj86's request)
• test/install.sh — Added crush to all 3 test manifest lists

Testing

Shell (install.sh)

• shellcheck crush/install.sh — passes (SC2034 pragma for webi framework variables)
• shfmt formatting — compliant (-i 4 -sr -ci -s)
• prettier — all markdown and JS files formatted

PowerShell (install.ps1)

Tested via Docker container using mcr.microsoft.com/powershell:7.4-alpine-3.20 with the actual Windows x86_64 release zip from GitHub:

=== Crush install.ps1 Test Harness ===
Downloading crush from .../crush_0.51.1_Windows_x86_64.zip
Installing crush
Unpacking .../crush_0.51.1_Windows_x86_64.zip
Install Location: .../crush-v0.51.1/bin/crush.exe
Copying into '.../bin/crush.exe' from '.../crush-v0.51.1/bin/crush.exe'
--- install.ps1 completed successfully ---

=== Verification ===
  [PASS] Binary in versioned opt dir
  [PASS] Binary copied to bin dir
  [PASS] Download cached
  [INFO] Binary size: 63 MB

=== ALL CHECKS PASSED ===

Test harness available at crush/test-ps1/ — validates the full download→extract→move→copy flow against the real release archive.

Releases (releases.js)

• node crush/releases.js — returns correct OS/arch/ext for all platforms
• Filters: .tar.gz/.zip + underscore naming + no nightly + no sbom
• Verified: 10 normalized releases with correct darwin/linux/freebsd/windows/android coverage

Addresses Review Feedback

• @detox-24: Fixed crush-* → crush_* underscore glob in both install.sh and install.ps1 ✅
• @detox-24: Restored full install.ps1 template boilerplate (was causing silent Windows failure) ✅
• @detox-24: Added completions + manpage extraction from release archive ✅
• @coolaj86: Added SKILL.md ✅

Implementation Notes

• Goreleaser archive structure: crush_VERSION_OS_arch/{crush,completions/,manpages/,LICENSE.md,README.md}
• Completions installed to standard XDG locations (bash-completion, zsh site-functions, fish completions)
• Manpage installed to ~/.local/share/man/man1/

Related

• Addresses feedback from feat(opencode): add installer for AI coding assistant #1062
• Related to Crush - like OpenCode (or Claude Code), but self-contained Go binary webi-installer-requests#489

[coolaj86]

This is good. Will you also add SKILL.md files for each of these?

Depending on how similar it is, I may just transition all README.md's into SKILL.md symlinks.

[ogormans-deptstack]

✅ Added crush/SKILL.md with comprehensive agent-focused documentation including:

• When to use crush vs alternatives (OpenCode, Cursor)
• LSP integration guide with language server setup
• MCP (Model Context Protocol) extension configuration
• Session management workflows
• Key bindings reference
• Troubleshooting guide
• Comparison tables

Also proactively added opencode/SKILL.md to PR #1063 following the same pattern.

The SKILL.md files are designed to help AI agents understand when and how to use these tools effectively. Ready for review! 🎉

[detox-24]

The crush's binary releases are in the format crush_[version]_[os]_[arch]. The point is, it has underscore instead of hyphens between.

Supply the mv command with appropriate structure, so that it installs the binary correctly.

[detox-24]

The crush's binary releases are in the format crush_[version]_[os]_[arch]. The point is, it has underscore instead of hyphens between.

Use the correct structure, so that the installer navigates the right directory.

[detox-24]

The installers have a minor path issue, kindly fix it.

[ogormans-deptstack]

✅ Fixed in commit 21ed585

Thanks @detox-24 for catching this!

Changes:

• Updated subdirectory glob pattern from crush-*/ to crush_*/
• Crush releases use underscore format: crush_VERSION_OS_arch/ (not hyphens)
• Updated comment to clarify the correct format

The install.sh now correctly navigates the goreleaser subdirectory structure. Tested locally - mv command finds the binary correctly! 🎉

[detox-24]

Inspecting the release asset, I found this:

crush_0.50.1_Linux_x86_64
├── completions
│   ├── crush.bash
│   ├── crush.fish
│   └── crush.zsh
├── crush
├── LICENSE.md
├── manpages
│   └── crush.1.gz
└── README.md

Crush provides completions and a man-page file packed within the releases.
Now webi won't handle shell configs and man-pages, which are clearly out of our scope.

But I think extracting this to a standard location and some instructions after finishing installation being displayed might help. Like we do for fish, for example, where the install.sh prints some instructions to set fish as default. We could add such echo statements here too, in install.sh.

What do you think? @coolaj86 [Sorry for tagging you so much :) ]

[detox-24]

And @ogormans-deptstack, Did you test the windows installer? I tested it and it fails silently. And I also see you've removed the template output messages baked in the ps1 installer. It would be nice to have them back.

Here's the template install.ps1

[ogormans-deptstack]

Pushed two commits addressing all outstanding feedback:

9f96f6d — install.ps1 rewrite + completions/manpage support

• @detox-24: Rewrote install.ps1 from scratch following the _example/install.ps1 template. The old version was missing the download/extract/copy boilerplate which caused the silent failure you found. Also fixed crush-* → crush_* glob.
• Added completions (bash/zsh/fish) and manpage extraction to install.sh from the goreleaser archive, following the pattern from sd and yq.

344baee — polish for merge

• Added shellcheck pragma, ran all formatters (prettier, shfmt, shellcheck all clean)
• Simplified releases.js filter (4 conditions, removed redundant extension checks)
• Rewrote README.md to match webi cheat-sheet conventions (~75 lines, practical tasks)
• Added crush to test/install.sh manifest (all 3 lists)

Testing: Validated the install.ps1 end-to-end in a Docker container (mcr.microsoft.com/powershell:7.4-alpine-3.20) against the actual Windows x86_64 release zip — all checks passed. See updated PR description for full test output.

@detox-24 re: your suggestion about printing post-install instructions for completions — I went with a minimal pkg_done_message since the goreleaser-style tools in the repo don't typically use verbose output. The completion/manpage paths are documented in the README instead. Let me know if you'd prefer more detail printed at install time.

Ready for re-review!

[ogormans-deptstack]

@detox-24 @coolaj86 do I still need the SKILL.md changes, anything else blocking this?

[ogormans-deptstack]

I want to get webi on my not so fancy website oghamconsults.cc

[detox-24]

@ogormans-deptstack Hello! The technical part of the PR is on-point and ready to merge!

I can't comment on the documentation parts, especially SKILL.md, since I am not qualified enough to ensure quality on those. But by the looks of it, it is pretty neat.

Webi is currently under a major infrastructural change, as we're migrating the project in entire to Go.

Once the newer version is finished, Crush and opencode will be surely included.

Sorry and thanks for your patience!

[ogormans-deptstack]

No worries thanks for the insight and good luck, sounds like the right long term direction for sure

[coolaj86]

The SKILL.md and README.md look like very generic LLM-generated content.

For example:

• README.md: qwen2.5-coder would not work with crush as it doesn't have agentic tool call training
• SKILL.md: this is really long and has lots of generic information that wouldn't be useful for an LLM

The documentation needs technical review from someone familiar with crush.

README.md

---
title: crush
homepage: https://github.com/charmbracelet/crush
tagline: |
  crush: A terminal-based AI coding assistant from Charm.
---

To update or switch versions, run `webi crush@stable` (or `@v0.51`, `@beta`,
etc).

### Files

These are the files / directories that are created and/or modified with this
install:

```text
~/.config/envman/PATH.env
~/.local/bin/crush
~/.local/opt/crush-VERSION/bin/crush
~/.local/share/man/man1/crush.1.gz
~/.local/share/bash-completion/completions/crush
~/.local/share/zsh/site-functions/_crush
~/.config/fish/completions/crush.fish
```

## Cheat Sheet

> `crush` connects to LLM providers (OpenAI, Anthropic, Google, Groq, or local
> models via Ollama) and gives you a TUI for writing, reviewing, and refactoring
> code — with session management and a beautiful Charm-powered interface.

### How to Get Started

Set an API key and launch in your project directory:

```sh
export ANTHROPIC_API_KEY="sk-ant-..."
cd ~/your-project
crush
```

On first run, crush will guide you through provider setup if no key is set.

### How to Switch Models

Press `Ctrl+M` in the TUI to open the model selector. Context is preserved when
switching.

### How to Use Sessions

```sh
crush --session feature-auth
crush --resume
crush sessions
```

### How to Use with Local Models

Install [ollama](../ollama/) (also available via webi), then configure crush:

```sh
webi ollama
ollama serve &
ollama pull qwen2.5-coder:32b
```

Add to `~/.config/crush/config.yaml`:

```yaml
providers:
  - id: ollama
    name: Ollama
    type: ollama
    base_url: http://localhost:11434

default_provider: ollama
default_model: qwen2.5-coder:32b
```

### Shell Completions

Shell completions for bash, zsh, and fish are installed automatically. For zsh,
you may need to ensure the completions directory is in your fpath:

```sh
fpath=(~/.local/share/zsh/site-functions $fpath)
```

SKILL.md

---
name: crush
description:
  Glamorous terminal-based AI coding assistant from Charm with LSP integration,
  MCP extensions, session management, and beautiful TUI. Use when the user wants
  a polished terminal AI coding experience.
homepage: https://github.com/charmbracelet/crush
---

# Crush

Your new coding bestie in the terminal — built on the Charm ecosystem, powering
25k+ applications. Beautiful TUI with LSP integration, MCP extensions, and
multi-model LLM support.

## When to Use

- User wants a polished, beautiful terminal AI coding experience
- User needs LSP-enhanced code intelligence (go-to-definition, references,
  diagnostics)
- User wants session-based workflow with context preservation across multiple
  work sessions
- User needs MCP (Model Context Protocol) extensions for custom tools
- User wants to switch LLM providers mid-conversation while preserving context
- User values aesthetic terminal UIs (Charm ecosystem: Bubble Tea, Lip Gloss)
- User wants first-class support across all platforms (macOS, Linux, Windows,
  BSD, Android)

## Installation

```sh
curl https://webi.sh/crush | sh
source ~/.config/envman/PATH.env
```

## Quick Start

1. **Launch in project directory**:

   ```sh
   cd ~/your-project
   crush
   ```

2. **First-run setup** — Crush will guide you through LLM provider configuration

3. **Or set API key beforehand**:
   ```sh
   export OPENAI_API_KEY="sk-..."
   # or
   export ANTHROPIC_API_KEY="sk-ant-..."
   ```

## Configuration

### Provider Setup

Edit `~/.config/crush/config.yaml`:

```yaml
providers:
  - id: openai
    name: OpenAI
    type: openai
    base_url: https://api.openai.com/v1
    api_key: sk-...

  - id: anthropic
    name: Anthropic
    type: anthropic
    base_url: https://api.anthropic.com
    api_key: sk-ant-...

  - id: groq
    name: Groq
    type: openai
    base_url: https://api.groq.com/openai/v1
    api_key: gsk_...

default_provider: openai
default_model: gpt-4o
```

### Local Models with Ollama (Optional)

For offline AI coding with no API calls:

```sh
# Install Ollama separately
curl https://webi.sh/ollama | sh

# Start server and pull model
ollama serve &
ollama pull qwen2.5-coder:32b
```

Configure crush to use local model:

```yaml
providers:
  - id: ollama
    name: Ollama
    type: ollama
    base_url: http://localhost:11434

default_provider: ollama
default_model: qwen2.5-coder:32b
```

### LSP Configuration

Crush automatically detects and uses LSP servers when available. Install
language servers for enhanced intelligence:

```sh
# TypeScript/JavaScript
npm install -g typescript-language-server

# Python
pip install python-lsp-server

# Go
go install golang.org/x/tools/gopls@latest

# Rust
rustup component add rust-analyzer
```

LSP features work automatically once language servers are installed.

## MCP Extensions

Add custom tools via Model Context Protocol:

Create `~/.config/crush/mcp.yaml`:

```yaml
servers:
  - id: filesystem
    name: Filesystem Access
    command: npx
    args: [-y, @modelcontextprotocol/server-filesystem, /home/user/projects]

  - id: http
    name: HTTP Client
    command: npx
    args: [-y, @modelcontextprotocol/server-fetch]

  - id: database
    name: PostgreSQL
    command: npx
    args: [-y, @modelcontextprotocol/server-postgres]
```

Restart crush to load MCP servers.

## Session Management

Crush maintains multiple work sessions per project:

```sh
# List all sessions
crush sessions

# Start a named session
crush --session feature-auth

# Resume last session
crush --resume

# Delete a session
crush sessions delete feature-auth
```

Sessions preserve:

- Conversation history
- File context
- Model selection
- LSP state

## Key Features

| Feature            | Description                                                   |
| ------------------ | ------------------------------------------------------------- |
| **Multi-Model**    | OpenAI, Anthropic, Google, Groq, Ollama — switch mid-session  |
| **Session-Based**  | Multiple named sessions per project with context preservation |
| **LSP-Enhanced**   | Go-to-definition, find-references, diagnostics, code actions  |
| **MCP Extensions** | Add custom tools via Model Context Protocol                   |
| **Git-Aware**      | Automatically includes git context in conversations           |
| **Beautiful TUI**  | Built on Charm's Bubble Tea framework                         |
| **Cross-Platform** | First-class support on macOS, Linux, Windows, BSD, Android    |

## Common Workflows

### Feature Implementation with LSP

```sh
crush --session feature-payments
# Crush uses LSP to:
# - Navigate to definitions
# - Find all references
# - Show type information
# - Suggest code actions
```

### Switch Models Mid-Session

```sh
crush
# In TUI: Press Ctrl+M to open model selector
# Switch from gpt-4o to claude-sonnet-4-5
# Conversation context is preserved
```

### Debug with LSP Diagnostics

```sh
crush
# In TUI: Press Ctrl+T to toggle LSP diagnostics
# See errors and warnings inline
# Ask crush to fix specific issues
```

### Multi-Session Workflow

```sh
# Terminal 1: Work on authentication
crush --session auth

# Terminal 2: Work on payment integration
crush --session payments

# Terminal 3: Bug fix session
crush --session bugfix-123
```

## Integration with Other Tools

### With Ollama (Local Models)

Requires `ollama` to be running:

```sh
ollama serve &  # Keep running in background
crush           # Will connect to local Ollama
```

### With Git

Crush automatically includes:

- Current branch
- Uncommitted changes
- Recent commits
- Diff context

### With LSP Servers

Crush integrates with any LSP-compliant language server:

- **Go**: gopls
- **TypeScript**: typescript-language-server
- **Python**: python-lsp-server, pyright
- **Rust**: rust-analyzer
- **C/C++**: clangd
- **Java**: jdtls

### With MCP Servers

Extend crush with Model Context Protocol servers:

- Filesystem access
- HTTP client
- Database queries
- Custom APIs
- Shell commands

## Key Bindings

| Key      | Action                           |
| -------- | -------------------------------- |
| `Enter`  | Send message                     |
| `Ctrl+M` | Switch model/provider            |
| `Ctrl+S` | Save session                     |
| `Ctrl+L` | Clear screen                     |
| `Ctrl+C` | Cancel current operation         |
| `Ctrl+D` | Exit crush                       |
| `Ctrl+E` | Open editor for multi-line input |
| `Ctrl+R` | Search message history           |
| `Ctrl+T` | Toggle LSP diagnostics           |

## Files Created

```text
~/.config/envman/PATH.env           # PATH configuration
~/.local/bin/crush                  # Symlink to versioned binary
~/.local/opt/crush-VERSION/         # Installed binary
~/.config/crush/config.yaml         # Main configuration
~/.config/crush/mcp.yaml            # MCP extensions (optional)
~/.config/crush/sessions/           # Session data
```

## Advanced Configuration

Edit `~/.config/crush/config.yaml`:

```yaml
# Enable debug logging
debug: true

# Configure session directory
session_dir: ~/.config/crush/sessions

# Set custom editor
editor: vim

# Configure LSP timeout
lsp_timeout: 5s

# Enable/disable features
features:
  lsp: true
  mcp: true
  git_integration: true
  syntax_highlighting: true
  auto_save: true

# Performance tuning
performance:
  max_context_tokens: 128000
  stream_responses: true
  cache_embeddings: true
```

## Comparison with Alternatives

| Tool                         | Crush                               | OpenCode       | Cursor                |
| ---------------------------- | ----------------------------------- | -------------- | --------------------- |
| **Interface**                | Beautiful Charm TUI                 | Terminal TUI   | VS Code fork          |
| **LSP Integration**          | ✅ Full                             | ❌             | ✅                    |
| **MCP Extensions**           | ✅ Native                           | ❌             | ❌                    |
| **Session Management**       | ✅ Multi-session                    | Single session | Workspace-based       |
| **Local Models**             | ✅ Via Ollama                       | ✅ Via Ollama  | ❌                    |
| **Mid-Session Model Switch** | ✅ With context                     | ❌             | ❌                    |
| **Platform Support**         | macOS, Linux, Windows, BSD, Android | macOS, Linux   | macOS, Linux, Windows |
| **UI Polish**                | ⭐⭐⭐⭐⭐ Charm ecosystem          | ⭐⭐⭐         | ⭐⭐⭐⭐              |

## Best Practices

1. **Use sessions for parallel work** — Separate sessions for features, bugs,
   experiments
2. **Install LSP servers** — Maximize code intelligence with language servers
3. **Configure MCP early** — Add filesystem and HTTP MCP servers for full
   capabilities
4. **Use Ctrl+M liberally** — Switch models based on task complexity
5. **Enable git integration** — Let crush see your commit history for better
   context
6. **Save sessions regularly** — Use Ctrl+S to preserve important conversations

## Troubleshooting

**Crush won't start:**

```sh
# Check if binary is in PATH
which crush

# Verify configuration is valid
crush --check-config

# Reset to defaults
rm -rf ~/.config/crush/config.yaml
crush
```

**LSP features not working:**

```sh
# Check LSP status
crush --lsp-status

# Install language server (e.g., TypeScript)
npm install -g typescript-language-server

# Verify LSP is enabled in config
grep lsp ~/.config/crush/config.yaml
```

**MCP servers not loading:**

```sh
# Check MCP configuration
cat ~/.config/crush/mcp.yaml

# Test MCP server manually
npx -y @modelcontextprotocol/server-filesystem /tmp

# Enable debug logging
echo "debug: true" >> ~/.config/crush/config.yaml
```

**Ollama connection failed:**

```sh
# Check if Ollama is running
curl http://localhost:11434/api/version

# Start Ollama if needed
ollama serve &

# Verify crush config points to correct URL
grep ollama ~/.config/crush/config.yaml
```

## System Requirements

| Requirement  | Minimum                | Recommended            |
| ------------ | ---------------------- | ---------------------- |
| **RAM**      | 4GB                    | 8GB+                   |
| **Storage**  | 100MB                  | 500MB+ (with sessions) |
| **Network**  | Optional (with Ollama) | Required (cloud LLMs)  |
| **Terminal** | UTF-8, 256-color       | True color             |

## Resources

- GitHub: https://github.com/charmbracelet/crush
- Charm Ecosystem: https://charm.sh
- Model Context Protocol: https://modelcontextprotocol.io
- LSP Specification: https://microsoft.github.io/language-server-protocol/

## Related Webi Installers

- `ollama` — Local LLM server for offline AI coding
- `node` — Required for MCP extensions via npx
- `git` — Version control integration
- `gum` — Charm's shell scripting toolkit (pairs well with crush)
- `vhs` — Charm's terminal recorder (great for demos)