Crush

Introduction

Crush is Charmbracelet's terminal-based AI coding assistant — a glamorous, full-featured TUI agent that brings multi-model LLM access, LSP-powered code intelligence, and MCP extensibility into your favourite terminal. Launched in July 2025 and hosted on GitHub under the FSL-1.1-MIT license, Crush has rapidly grown to over 24,700 stars and 160 releases, becoming one of the most polished terminal-native coding agents available.

Unlike coding assistants tied to a single IDE or provider, Crush is built from the ground up on Charmbracelet's acclaimed Go ecosystem — Bubble Tea for the TUI, Lip Gloss for styling, Glamour for markdown rendering, Bubbles for reusable components, and Fantasy for cross-provider LLM abstraction. The result is an agent that feels as refined as a native desktop app, but lives entirely in your terminal.

Crush connects to dozens of LLM providers — Anthropic, OpenAI, Google Gemini, AWS Bedrock, Groq, OpenRouter, Azure, Vertex AI, Ollama, LM Studio, and many more — and lets you switch between them mid-session without losing context. It understands your codebase through LSP integration, extends itself through MCP servers and the Agent Skills standard, and manages multiple work sessions with full history persisted in SQLite.

Key Features

Multi-Model Architecture: Choose from dozens of LLM providers — Anthropic, OpenAI, Gemini, AWS Bedrock, Azure, Groq, OpenRouter, Vercel AI Gateway, Hugging Face, and many more. Add custom OpenAI-compatible or Anthropic-compatible providers for anything else.

Mid-Session Model Switching: Swap LLMs mid-conversation without losing context. Press Ctrl+M to open the model picker and switch from Claude to GPT to Gemini on the fly. Each session tracks token usage and cost per model.

LSP-Enhanced Context: Crush automatically discovers and starts Language Servers (gopls, typescript-language-server, nil, rust-analyzer, etc.) to gather rich code intelligence. LSPs run on-demand and provide definitions, references, diagnostics, and symbols as context for the model.

Session Management: SQLite-backed sessions with full message history, persistence across restarts, and a session picker to switch between active conversations. Sessions track token counts, cost estimates, and file touch history.

Four-Mode Permission System: Crush operates with four tool permission modes: prompt-before-each (default), allowed-tools list (auto-approve specific tools), YOLO mode (full autonomy with --yolo), and disabled-tools (completely block certain tools). Desktop notifications alert you when permission is needed.

AGENTS.md Initialization: crush init analyzes your project and generates an AGENTS.md context file with build commands, code patterns, and conventions that Crush references in future sessions. Customizable filename via initialize_as config.

MCP Protocol Extensions: Full Model Context Protocol support with three transport types — stdio, http, and sse. Shell-style value expansion ($VAR, ${VAR:-default}, $(command)) works in command args, URLs, env vars, and headers.

Agent Skills: Supports the Agent Skills open standard (SKILL.md format). Skills are auto-discovered from project directories (.agents/skills/, .crush/skills/) and global paths (~/.config/agents/skills/). Skills can be user-invocable via the command palette (Ctrl+P).

Desktop Notifications: Crush sends native desktop notifications when the model requests tool permissions and when an agent turn completes — but only when the terminal window isn't focused.

Wide Platform Support: First-class support on macOS, Linux, Windows (PowerShell and WSL), Android, FreeBSD, OpenBSD, and NetBSD. Available via Homebrew, npm, Winget, Scoop, APT, YUM, Nix, and direct binary download.

Architecture / How It Works

Multi-Model Provider System

Crush's provider architecture is built on Fantasy, Charmbracelet's LLM abstraction layer that normalises protocol differences between Anthropic, OpenAI, Google Gemini, AWS Bedrock, and other providers. Each provider is configured via environment variables (e.g., ANTHROPIC_API_KEY, OPENAI_API_KEY, VERTEXAI_PROJECT) or through the crush.json config file. The provider list is managed in Catwalk, a community-maintained open-source repository of Crush-compatible models that auto-updates in the background.

When you open Crush, it scans for configured providers and presents them in a searchable model picker. You can switch providers mid-session — Crush retains the conversation history and sends it to the new model, preserving all context. This is particularly useful when you want Claude's reasoning for architecture planning and GPT-5's speed for implementation in the same session.

LSP Integration

Crush integrates with Language Servers to provide code-aware context to the LLM. It auto-discovers LSPs based on project files (e.g., go.mod → gopls, tsconfig.json → typescript-language-server) and starts them on-demand when the model requests code analysis. LSPs provide:

This means the model can answer questions like "What functions in this file accept a context parameter?" or "Find all callers of this deprecated method" with compiler-grade accuracy.

• Definitions — jump-to-definition and type information
• References — find all references to a symbol
• Diagnostics — real-time error and warning information
• Symbols — document and workspace symbol search

Session-Based Architecture

Each Crush session is backed by a SQLite database that stores the full message history, token usage, cost estimates, and file touch tracking. Sessions are scoped to workspaces (groups of clients sharing the same working directory). You can run multiple sessions per project and switch between them via the session picker. Sessions survive terminal restarts.

The workspace model also supports a client-server architecture (CRUSH_CLIENT_SERVER=1) where multiple TUI clients can share a workspace, see each other's sessions, and even view live agent turns in real-time.

Permission System

Crush implements a granular permission model:

1. Prompt mode (default) — asks before every tool execution
2. Allowed tools — auto-approve specific tools via permissions.allowed_tools
3. YOLO mode (--yolo or Ctrl+Y) — full autonomy (use with extreme care)
4. Disabled tools — completely block tools via options.disabled_tools

MCP and Extensibility

Crush supports three MCP transport types:

• stdio — for command-line MCP servers
• http — for HTTP API endpoints
• sse — for Server-Sent Events endpoints

Configuration uses shell-style value expansion ($VAR, ${VAR:-default}, $(command)) in command args, URLs, headers, and environment variables. Security note: crush.json is treated as trusted code — any $(...) executes at load time with shell privileges.

Additionally, Crush follows the Agent Skills open standard, loading SKILL.md-based skill packages from project directories and global paths. Skills can add new capabilities, custom slash commands, and be marked as user-invocable (appearing in the Ctrl+P command palette).

Installation & Setup

Crush is available through multiple package managers and installation methods: