# Crush | Artificialus

> For the complete content index, see [llms.txt](https://artificialus.com/llms.txt). Markdown versions of all pages are available by appending `.md` to any URL.

- Home
- /
- Agents
- /
- Crush

CR

# Crush

Glamourous agentic coding for your favorite terminal, powered by Charmbracelet's ecosystem.

Charmbracelet

Open source

Since 2025

Visit Website

Repository

Docs

Download

Share

X

Facebook

Reddit

Telegram

Bluesky

Email

Crush is a terminal-based AI coding assistant by Charmbracelet — a glamorous TUI agent that connects to any LLM, understands your codebase via LSPs, extends through MCP and agent skills, and manages multiple sessions with persistent history. Built on Charm's mature ecosystem (Bubble Tea, Lip Gloss, Glamour), it supports multi-model switching mid-session and runs on macOS, Linux, Windows, BSD, and Android.

##
+

Pros
- Beautiful, polished TUI built on Charmbracelet's mature ecosystem (Bubble Tea, Lip Gloss, Glamour, Bubbles)
- Multi-model switching without restarting sessions — swap between GPT-4, Claude, Gemini, Groq, Bedrock, and dozens more mid-conversation
- Excellent LSP integration for context-aware code understanding — automatic discovery and on-demand startup
- Wide platform support: macOS, Linux, Windows (PowerShell + WSL), FreeBSD, OpenBSD, NetBSD, and Android
- Extensible via MCP (stdio, HTTP, SSE) and the Agent Skills open standard with built-in skill discovery
- Session-based architecture with SQLite persistence, project-level context files (AGENTS.md), and session history navigation
- Battle-tested reliability — benefits from Charm's mature ecosystem powering 25k+ production applications
- Desktop notifications for permission prompts and agent turn completion

##
−

Cons
- Functional Source License (FSL-1.1-MIT) is not fully open-source by OSI standards — imposes some adoption restrictions
- Requires own API keys for each LLM provider — no built-in model access or subscription included
- Heavier than minimal alternatives (~22MB+ binary, Go runtime, SQLite dependency)
- TUI-only — no IDE extension or web UI (purely terminal-based experience)
- Rapid release pace (160+ releases in under a year) can make it hard to track breaking changes

##

Pricing

### Free

$0

Free and open source under FSL-1.1-MIT license (converts to MIT after 2 years). No paid tiers. Users bring their own LLM API keys.

## 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:
- Prompt mode (default) — asks before every tool execution
- Allowed tools — auto-approve specific tools via permissions.allowed_tools
- YOLO mode (--yolo or Ctrl+Y) — full autonomy (use with extreme care)
- 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:

## Version History

v0.73.0
May 26, 2026
AWS Bedrock Europe provider split (us-east-1 / eu-west-1), improved model change notification UI

v0.72.0
May 25, 2026
QoL release — skill command descriptions, Ctrl+Y to toggle YOLO mode, scrollbar in sessions list, auto-expanded TODO pills

v0.71.0
May 22, 2026
Scrollbar in model list, AWS Bedrock region enforcement, token cost estimation for non-reporting providers, permission prompt tightening for chained bash commands, user-invocable skills

Best for Developers who want a polished, beautiful TUI coding agent with multi-model support, LSP integration, and Charmbracelet-grade terminal UX

Capability Multi-model switching mid-session · LSP-enhanced context gathering · MCP protocol extensions · Session management with history · Four-mode permission system · AGENTS.md project initialization · Desktop notifications

Runs on Terminal TUI · macOS · Linux · Windows · FreeBSD · OpenBSD · NetBSD · Android

Signature Snippet

Copy

```
`# Install via Homebrew
brew install charmbracelet/tap/crush

# Or via npm
npm install -g @charmland/crush

# Or on Windows via Winget
winget install charmbracelet.crush

# Set your API key and launch
export ANTHROPIC_API_KEY="sk-ant-..."
crush

# Switch models mid-session without restarting
# Just press Ctrl+M and pick a different provider`
```

## More in this Space

SO

### Sourcery

Closed source

AI code review platform for the AI era. Automated code reviews, security scanning, and team analytics across GitHub, GitLab, VS Code, and JetBrains. Used by 300,000+ developers.

View profile

WT

### What The Diff

Closed source

AI-powered PR description generator and code review assistant. Automatically writes pull request descriptions, sends stakeholder notifications, creates changelogs, and provides inline code refactoring.

View profile

BA

### Blackbox AI

Closed source

Multi-agent AI coding platform with 12+ agents and 24+ models, featuring Chairman LLM for parallel multi-agent evaluation and end-to-end encrypted inference. Ships across six surfaces: CLI, IDE, Cloud, API, Mobile, and Builder.

View profile