charmbracelet/crush

What is Crush?

Crush is a terminal‑based AI coding assistant from the Charm bracelet ecosystem. It lets you chat with a large language model (LLM) directly from your shell, while staying tightly integrated with the tools you already use – editors, language‑server‑protocol (LSP) servers, version‑control, and custom “Model Context Protocol” (MCP) services. In short, it turns your command line into an interactive coding partner that can run code, fetch information, and invoke external tools, all driven by the LLM you choose.

Core capabilities

Feature	What it does
Multi‑model support	Connect to any OpenAI‑compatible, Anthropic‑compatible, or other provider (e.g., OpenAI, Gemini, Claude, Ollama, Hyper) and switch models on the fly while keeping conversation context.
Session‑based workflow	Keep separate chat sessions per project, switch between them, and share sessions across multiple terminal windows.
LSP‑enhanced context	Load language‑server‑protocol servers (e.g., `gopls`, `nil`, `typescript-language-server`) so the assistant can see type information, diagnostics, and other language‑specific data.
Extensible via MCP	Add custom tool back‑ends through three transport types – `stdio`, `http`, and `sse` – allowing the assistant to call arbitrary services (GitHub, Linear, custom scripts, etc.).
Configurable with `crushrc`	A Bash‑style configuration file that can declare providers, models, LSPs, MCPs, permissions, and even run shell commands at startup.
Theming & UI	Built‑in TUI themes (e.g., Charmtone Pantera, Gruvbox Dark) that can be switched live or edited via a JSON theme file.
Cross‑platform	Pre‑built binaries for macOS, Linux, Windows (PowerShell/WSL), FreeBSD, OpenBSD, NetBSD, and even illumos/Solaris.
Workspace sharing	Multiple terminal instances pointed at the same working directory automatically join a shared workspace, synchronising sessions, history, and tool state.

Getting started (quick‑start)

Install – use your favourite package manager (Homebrew, NPM, Arch AUR, Nix, Debian/Ubuntu apt repo, Fedora/YUM, Winget, Scoop, etc.) or go install github.com/charmbracelet/crush@latest.
Pick a model – press Ctrl + L to open the model picker, choose a provider (e.g., the built‑in Hyper service or any OpenAI‑compatible API), and paste the API key (or set the corresponding environment variable, such as OPENAI_API_KEY).
Start a session – run crush in a project directory. The TUI opens; you can type natural‑language prompts, ask for code generation, ask the assistant to run commands, or invoke configured MCP tools.
Add extra context – optionally add LSP servers in a crushrc file (lsp add go --command "gopls") or register custom MCP services (mcp add github --type http --url https://api.github.com/mcp/).

Configuration highlights

crushrc – a Bash‑compatible script that can provider add …, model add …, lsp add …, mcp add …, and set permissions. It is loaded from the project directory (./.crushrc → ./crushrc → ~/.config/crush/crushrc) with the first existing file taking precedence.
Environment variables – you can pre‑populate API keys (OPENAI_API_KEY, ANTHROPIC_API_KEY, HYPER_API_KEY, etc.) so the model picker is pre‑filled.
Themes – change via the command palette (Ctrl + P → Themes) or by setting options.tui.active_theme in the JSON config.
Global prompts – two optional markdown files (~/.config/crush/CRUSH.md and ~/.config/AGENTS.md) are automatically injected into the system prompt, letting you define personal rules or shared instructions.

Who might benefit?

Developers who spend a lot of time in the terminal and want an AI assistant without leaving the shell.
Teams that need a consistent, configurable AI tool across macOS, Linux, and Windows workstations.
Power‑users who want to hook custom services (issue trackers, CI pipelines, code‑review bots) into their AI workflow via MCP.

Where to learn more?

Release page – binary downloads and changelog: https://github.com/charmbracelet/crush/releases
Model catalog – community‑maintained list of compatible models: https://github.com/charmbracelet/catwalk
Documentation – detailed config, hooks, and MCP guides live in the repo under docs/.
Community – join the Charm Slack or Discord (links in the README) for help and to share custom configurations.

TL;DR

Crush is a full‑featured, terminal‑native AI coding companion that works with any major LLM, integrates language‑server data, supports custom tool back‑ends, and can be shared across multiple terminal windows. Install it via your package manager, configure providers in a crushrc (or environment variables), and start chatting with your code directly from the command line.