charmbracelet/crush

Crush – an LLM‑powered coding assistant for the terminal

What it is – Crush is a command‑line application that lets you talk to a large language model (LLM) directly from any terminal. It acts as a “coding bestie”: you can ask it to write, edit, or explain code, run tools, and interact with your project’s files while staying inside the shell you already use.

Why it matters – Most AI‑code assistants live in IDE plugins or web UIs. Crush brings the same capabilities to the terminal, making it useful for developers who spend most of their time in Vim/Emacs, remote shells, or CI pipelines. It also supports multiple LLM providers (OpenAI, Anthropic, Gemini, Bedrock, local Ollama, etc.) and lets you switch models on the fly without losing context.

Core features (as described in the README)

Multi‑model support – choose any OpenAI‑ or Anthropic‑compatible API, add custom providers, or run local models via Ollama.
Session‑based workflow – keep separate conversations per project; you can have many sessions open at once.
LSP integration – Crush can launch language‑server‑protocol servers (e.g., gopls, nil, typescript-language-server) to give the model deeper understanding of your code.
Extensible via MCP – Model Context Protocol servers can be added over stdio, http, or sse to provide custom tools, data, or live updates.
Cross‑platform – works on macOS, Linux, Windows (PowerShell/WSL), Android, and the BSD family.
Configurable with crushrc – a Bash‑style configuration file that can be placed per‑project or globally; you can add providers, models, LSPs, MCPs, permissions, and more.
Global context files – markdown files (CRUSH.md, AGENTS.md) are automatically injected into the system prompt for personal instructions.
Permission system – tools (e.g., ls, grep, GitHub actions) require explicit allow/deny, protecting against unwanted side‑effects.
Workspace sharing – multiple TUI clients pointed at the same working directory share the same session list, history, and tool state via SSE.

Getting started (quick‑start steps)

Install – use Homebrew, NPM, Arch’s AUR, Nix, Winget, Scoop, or download a binary/package for your OS. A go install also works for those with a Go toolchain.
Pick a model – press Ctrl + L** to open the model picker, select a provider (e.g., the built‑in Hyper service, OpenAI, Anthropic, etc.), and paste the API key or set the appropriate environment variable (OPENAI_API_KEY, ANTHROPIC_API_KEY, …).
Start a session – run crush in a project directory. The TUI will appear; you can type natural‑language prompts, ask for code generation, or request tool execution.
Configure (optional) – create a crushrc (Bash syntax) or a JSON config to add LSPs, MCP servers, or pre‑approved tools. Example snippets are provided in the README.

Configuration highlights

Provider definition – in crushrc or JSON you can add a provider with provider add <name> --type <type> --base-url <url> and then register models (model add …).
LSPs – lsp add go --command "gopls" --enabled true makes the Go language server available to the model.
MCP servers – add custom tool back‑ends, e.g., a local Node script (mcp add filesystem --command node …) or a GitHub‑based MCP (mcp add github --type http …).
Permissions – permissions allow view edit pre‑approves safe tools; permissions deny bash blocks risky ones.
Global context – place personal instruction markdown in ~/.config/crush/CRUSH.md (or custom paths via option global-context-path).
Environment overrides – set CRUSH_GLOBAL_CONFIG or CRUSH_GLOBAL_DATA to relocate config/state directories.

Who might use it

Developers who live in the terminal and want AI assistance without leaving the shell.
Teams that need a consistent, configurable AI assistant across many OSes and CI environments.
Users of self‑hosted LLMs (Ollama, local Hugging Face inference) who want a simple front‑end.
Anyone who wants to script or automate tool calls through an LLM while retaining fine‑grained permission control.

Links from the README

Release page – https://github.com/charmbracelet/crush/releases
Model catalog (Catwalk) – https://github.com/charmbracelet/catwalk
Official provider (Hyper) – https://hyper.charm.land
Community chat – Slack / Discord links (mentioned in the warning box)

Bottom line

Crush is a fully‑featured, terminal‑native LLM assistant that integrates with existing development tooling (LSPs, version control, custom MCP services) and works with virtually any LLM backend. It’s designed for developers who prefer the command line and need a configurable, permission‑aware AI partner.