Crush: Charm's terminal coding agent, and what it actually commits to

The problem Crush solves is provider lock-in, not code completion

Most coding agents ship as a hosted product with one vendor's models behind it. Crush inverts that. The README describes it as "Your tools, your code, and your workflows, wired into your LLM of choice", and the feature list backs the claim: multi-model support, OpenAI- or Anthropic-compatible APIs for models the project does not ship, and the ability to switch LLMs mid-session while preserving context.

The audience is narrower than the tagline suggests. Crush assumes you are comfortable in a terminal, that you have API keys or a subscription, and that you will edit a JSON config rather than click through settings screens. If your team's workflow is a browser tab and a pull request review, the session model here has nothing to offer you.

The second audience is tooling people. Because Crush reads LSP servers and MCP servers from config, it is a way to give an agent the same language-server context a human editor gets, without writing a plugin for each editor.

Sessions, LSP context and MCP servers: the machinery under the TUI

The repository layout tells you more than the feature list. There is an internal/ tree for the application code, a docs/ directory, a schema.json, a crush.json at the top level, and a go.mod that reads like a list of Charm's own libraries: bubbletea for the terminal UI, lipgloss for styling, glamour for rendering, catwalk and fantasy for the model and provider layer.

Three mechanisms matter.

Sessions. Crush is session-based, and the README says sessions keep multiple work sessions and contexts per project. The practical consequence is that a session is a unit you can leave and return to, and that switching models mid-session preserves the context already built up. That is a real design choice: the conversation is not bound to the model that started it.

LSP enhancement. Crush starts language servers and uses them for additional context. In the NixOS example in the README, that looks like lsp = { go = { command = "gopls"; enabled = true; }; }. The agent is not guessing at symbols; it is asking the same server your editor asks.

MCP. Capabilities are added through MCPs over http, stdio and sse transports. This is the extension point. Anything you can express as an MCP server becomes something the agent can call, which is a wider surface than a fixed tool list but also a wider surface to secure.

The data flow is therefore: terminal UI in front, a provider adapter behind (OpenAI-compatible, Anthropic-compatible, or Charm's own Hyper), a local database for session state, and two side channels, LSP for code intelligence and MCP for tools. The go.mod includes go-git, goquery and html-to-markdown, which suggests the agent also reads repository history and web content, though the README does not spell out those paths.

Installing Crush and getting to a first session

Crush ships through a long list of package managers. Pick the one your machine already trusts; the README lists Homebrew, npm, Arch, Nix, FreeBSD, Winget and Scoop, plus Debian and Fedora repositories.

brew install charmbracelet/tap/crush

Node users can take the same binary through npm, and Go users can build from source. The Go path is the one that also covers illumos and Solaris, with a build tag for the latter.

go install github.com/charmbracelet/crush@latest

On Oracle Solaris the README asks for a build tag so the local database uses dot-file locking. That is the only platform-specific build instruction the README gives.

go install -tags sqlite3_dotlk github.com/charmbracelet/crush@latest

Once installed, the README's quickest route is the model picker: choose a Hyper model, follow the authentication steps, and start working. Hyper is Charm's own provider, described as subscription-based with a free tier, zero data retention and GDPR-oriented design. If you would rather use your own keys, press ctrl+l to open the model picker, choose a provider such as Anthropic, OpenAI, Gemini or OpenRouter, and paste the key. The README also names environment variables for preferred providers, listing HYPER_API_KEY for Charm Hyper.

Configuration lives in crush.json, and schema.json at the repository root is the schema for it. The NixOS module example in the README shows the shape: a providers object keyed by provider id with base_url, type, api_key and a models array, an lsp object mapping language names to command and enabled, and an options object with context_paths, a tui.compact_mode flag and a debug flag. If you are not on Nix, the same structure is what you write into crush.json, and the schema is what your editor should validate against.

The licence is marked NOASSERTION, and that is a real blocker for some teams

GitHub reports the licence as NOASSERTION, which means the repository's licence file did not match a recognised template. The top-level entries include LICENSE.md and CLA.md. A contributor licence agreement alongside an unrecognised licence is a combination that legal review will want to read rather than classify from a badge.

This is not a reason to avoid Crush for personal use. It is a reason not to assume Crush is MIT or Apache-2.0 because it comes from a project whose other tools often are. Read LICENSE.md. I am not going to tell you what it permits; I have not read it and this is not legal advice.

The second cost is upstream. Crush is a fast-moving project: the release list shows v0.94.2 on 2026-09-14, v0.94.1 on 2026-09-12, and a nightly build on 2026-09-15, with the last push to main on 2026-09-15. A version number below 1.0 plus nightly builds means the config schema and the provider layer can move between releases. Treat crush.json as a file under version control, and read the release notes before bumping. The README does not document a rollback path for a config written against a newer schema.

Where Crush is the wrong tool

Crush is a terminal application. The README's platform list is about terminals and shells on macOS, Linux, Windows via PowerShell and WSL, Android, FreeBSD, OpenBSD and NetBSD. There is no web interface and no IDE extension described. If your team needs a shared, auditable surface where a reviewer can see what the agent did without opening a terminal scrollback, Crush does not give you that.

The LSP dependency is a second limit. Crush uses language servers for context, and the config expects a command per language (gopls for Go, nil for Nix in the example). If your language has no working language server, or your project's build genuinely cannot start one, you are paying the configuration cost for a feature you will not get. The README does not describe a degraded mode for that case.

MCP is a third. Adding capabilities over http, stdio and sse is powerful and also means the agent's reach is defined by servers you configure. An MCP server that can write files or reach the network widens what a mistaken agent action can touch. The README does not describe a permission prompt per MCP tool, so do not assume one exists.

Finally, the model picker is a dependency on providers you do not control. Mid-session switching preserves context, but a provider outage or a rate limit still interrupts the session.

Alternatives: what changes if you pick a different shape

The closest comparison in the README is Charm's own Hyper provider, which is not an alternative agent but an alternative sourcing decision. Hyper is subscription-based with a free tier, zero data retention and GDPR-oriented design, and the README calls it the official Crush provider optimized for Crush. Choosing it means less configuration and one vendor relationship; choosing your own Anthropic or OpenAI key means more control and more setup. Both run inside the same Crush binary, so this is a billing and data-handling choice, not an architecture choice.

For a genuinely different approach, consider editor-integrated agents, where the model runs inside the editor and inherits its LSP and file context automatically rather than through a config file. The trade-off is the opposite of Crush's: you get context for free but you are tied to that editor, and you cannot move the agent to a headless machine or an SSH session. Crush's whole pitch is that it runs where your shell runs, including Android and the BSDs.

A third shape is a plain CLI wrapper around a provider API with no session state. That is smaller and easier to audit, and it loses the two things Crush adds: persistent sessions per project and language-server context. If you never resume a session and never needed symbol-level context, the wrapper is the better tool.

Editorial conclusion

Adopt Crush if you already live in a terminal, want to point a coding agent at your own provider keys, and are willing to treat crush.json as a file you version and review. Skip it if you need a documented stability promise, a web UI, or a licence you can read off the repository page in one line. Before rolling it out, verify three things yourself: which provider and model the model picker offers for your API key, whether your LSP servers start cleanly under the configured command, and what your organisation's policy says about a NOASSERTION licence plus an external subscription provider.

Frequently asked questions

Official sources

1. charmbracelet/crush on GitHub
2. Issues
3. README
4. Releases