charmbracelet/crush: An Open-Source Terminal Coding Agent That Takes Any Model but the License Has a Catch

charmbracelet/crush is a terminal coding agent started in May 2025 by Charm (the studio behind Bubble Tea and Hugo). It has 27,274 stars on GitHub (real-time, per GitHub), 2,143 forks, is written in Go, and its last push was today (2026-08-11). It is not archived, and 629 open issues say the community is actually using it. The README positions it plainly: "Your new coding bestie, now available in your favourite terminal. Your tools, your code, and your workflows, wired into your LLM of choice." The differentiator: Claude Code locks you into Anthropic models plus a subscription, Cursor is a closed-source IDE copilot, and crush goes "software is open, you pick the model" -- any OpenAI- or Anthropic-compatible API works, and you can even swap models mid-session without losing context. But the catch is right there too: its license is not the MIT you might assume, it is FSL-1.1-MIT, which restricts competitive use. This piece unpacks that and a few other pitfalls.

This article is based on charmbracelet/crush's GitHub README and LICENSE.md, accurate as of 2026-08-11; star counts move in real time. It complements but stands apart from this site's GLM Coding Plan upgrade hotspot, AI coding plan comparison, and AI coding context engineering SOP, and covers different ground from the cua resource and openclaw resource.

1. Positioning: a coding partner in the terminal, not another IDE

crush runs in the terminal: you talk to it on the command line, it reads code, edits files, runs commands, calls tools, and does the "help me write code" job. It is not a GUI copilot inside an editor like Cursor -- no multi-pane diffs, no file-tree clicking, no IDE-style visualization. The interface is a TUI, and Charm's house strength is exactly terminal UI (the Bubble Tea framework is theirs), so crush looks better than most command-line tools.

Why bet on the terminal? First, SSH-ability: servers, containers, and remote dev boxes without a GUI can still run it -- a real need for backend and ops. Second, it is light: no Electron hogging memory, one terminal window does it. Third, broad cross-platform: the README lists macOS, Linux, Windows (PowerShell and WSL), Android, FreeBSD, OpenBSD, NetBSD -- Android and the three BSDs all on the list, quite rare among coding agents, enabled by Go compilation plus a native Bash interpreter. The README marks it "Industrial Grade," on the grounds that the Charm ecosystem powers 25k+ applications; it is not an experiment.

But "terminal agent" turns some people away: anyone used to Cursor's "code on the left, chat on the right, highlight the changed line" flow will find plain-text terminal unfamiliar. crush's target user is someone who already lives in the terminal -- backend, DevOps, systems programmers, vim/tmux workflow geeks. If the command line gives you a headache, you can skip this one.

2. Core features: six cards

Multi-Model: you pick the model, no lock-in. The hardest differentiator. It natively supports OpenAI- and Anthropic-compatible APIs -- official OpenAI/Anthropic obviously, plus OpenRouter, Azure OpenAI, AWS Bedrock, and Google VertexAI all have built-in environment variables. The README explicitly says you can "add your own via OpenAI- or Anthropic-compatible APIs" -- your own self-hosted LLM works too. Charm also runs an official provider called Hyper (hyper.charm.land), subscription with a free tier, pitching zero data retention (ZDR) and GDPR compliance.

Flexible: swap models mid-session, keep the context. A valuable one. Use a cheap model for grunt work (reading code, searching symbols), switch to a strong model for hard problems, hit Ctrl+L to bring up the selector and switch on the spot, context preserved. Allocate compute by task difficulty instead of "pick one and ride it to the end."

Session-Based: multiple projects, multiple sessions in parallel. Each project gets its own session and context, switching back and forth does not bleed, good for juggling several repos.

LSP-Enhanced: pull context via LSP, just like you do. crush taps the Language Server Protocol for symbols, definitions, and references -- structured context, not just file reading. README verbatim: "Crush uses LSPs for additional context, just like you do." You can enable gopls (Go), nil (Nix), and others, so the agent reads code structure instead of treating files as plain text -- far more accurate than naive file reads.

Extensible: extend abilities via MCP. Supports all three MCP transports: http, stdio, sse. You can hook up databases, browsers, file systems, and internal APIs, growing it beyond a "write code" agent. There is also Catwalk -- a community-maintained repo of crush-compatible models; if a model is missing, add it there.

Works Everywhere + crushrc. Platform coverage was covered above. The config system deserves a mention: crush uses a crushrc file, essentially a Bash script with a few crush-specific builtins, just as .bashrc relates to a shell. Because crush ships a native Bash interpreter, this config behaves identically on every platform (including Windows). Adding local Ollama is two lines:

provider add ollama --type ollama --base-url "http://localhost:11434/v1"
model add ollama/llama3.3 --name "Llama 3.3" --context-window 128000

3. How it divides turf with Claude Code, Cursor, and openclaw

These get mixed up the most. Cursor lives inside the editor: its strengths are repo-level multi-file edits, visual diffs, and IDE-grade navigation; it is closed-source and subscription. Claude Code is Anthropic's command-line/desktop agent, strong at long-context reasoning and engineering collaboration, but closed-source, locked to Anthropic models, and about $20/month. crush is most like Claude Code (both are terminal coding agents), but with two core differences: first, no model lock-in -- crush takes any compatible model; second, license -- Claude Code is closed-source, crush's source is visible (FSL, not MIT -- see section 5).

openclaw is a different species entirely: a personal assistant that manages your email, calendar, and files -- life and office chores, strong at local automation, it does not write code. crush's turf is the code repo, openclaw's turf is the inbox and calendar. One line: crush is "a partner that writes code in your terminal," Claude Code is "an Anthropic-locked engineering-collaboration agent," Cursor is "an editor GUI copilot," and openclaw is "a personal assistant that handles your chores."

They are more complementary than substitutive. A common combo: Cursor for quick edits under a GUI, Claude Code for gnawing on long-context hard problems, crush for work on servers and remote environments (SSH-ready, model-agnostic). Before choosing, check this site's AI coding plan comparison to run the numbers.

4. Getting started: install, wire a model, go

Install. The two most common:

brew install charmbracelet/tap/crush   # Homebrew
npm install -g @charmland/crush         # npm, all platforms

On Windows you can also winget install charmbracelet.crush or scoop install crush, or even go install github.com/charmbracelet/crush@latest from source.

Wire a model. Fastest path: after install, hit Ctrl+L to bring up the model selector, pick a Hyper model and authenticate as prompted -- the free tier is enough to try. If you do not want Hyper, set environment variables; crush recognizes a long list: ANTHROPIC_API_KEY, OPENAI_API_KEY, ZAI_API_KEY (Z.ai/Zhipu), MINIMAX_API_KEY, MOONSHOT_API_KEY, GEMINI_API_KEY, OPENROUTER_API_KEY, and more.

Wire domestic or local models. This is key to crush being friendly to users in China. Z.ai (Zhipu), MiniMax, Moonshot, and Alibaba all have native environment variables -- no compatibility shim needed. DeepSeek has no dedicated variable, but its API is OpenAI-compatible, so add a custom provider in crushrc with two lines:

provider add deepseek --type openai --base-url "https://api.deepseek.com/v1"
model add deepseek/deepseek-chat --name "DeepSeek Chat" --context-window 64000

To zero out API costs, hook local Ollama (the two lines above). The whole getting-started: one install line, one key, Ctrl+L to pick a model, three steps and you are working.

5. The price of the pitfalls: five things you must know

Pitfall 1: the license is not MIT, it is FSL-1.1-MIT (the one to read). GitHub's SPDX detector returns NOASSERTION for crush. Open the repo's LICENSE.md and the header reads "Functional Source License, Version 1.1, MIT Future License," abbreviated FSL-1.1-MIT, copyright Charmbracelet, Inc. This differs from Charm's Bubble Tea and Hugo (both MIT) -- do not assume crush is MIT just because they share a home. The FSL core: you may use, modify, copy, build on, and redistribute it, but only for a "Permitted Purpose"; "Competing Use" is forbidden -- meaning taking crush to build a commercial product or service that replaces crush itself or Charm's other products, or offering substantially the same functionality. Internal use, non-commercial education/research, and providing professional services to crush licensees are all fine. There is also a "future license": two years after crush's release it automatically converts to MIT. The precise statement is "source visible plus competitive-use restricted" today, MIT in two years. Personal coding or internal company use is completely fine; forking it into a competing SaaS to sell will not work in the first two years. Before any commercial integration, read LICENSE.md yourself.

Pitfall 2: terminal is not an IDE, calibrate expectations. Anyone coming in looking for a "Cursor replacement" will find no visual diffs, no file-tree clicking, no multi-pane layout. crush is a TUI; all interaction is terminal text. For terminal natives that is an advantage (light, fast, SSH-able), for heavy IDE users it is a barrier. Try it for two days for feel before rushing a full migration.

Pitfall 3: model API is self-paid; model-agnostic is a double-edged sword. The software is free, but LLM calls burn your API quota. Free model choice lets you pick cheap ones (DeepSeek, MiniMax, local Ollama), but nobody manages cost for you -- long sessions silently inflate tokens and the bill is yours. The Hyper free tier buffers this but is limited. Advice: cheap model for grunt work, strong model for hard problems (exactly what the Flexible mid-session switch is for), do not run the most expensive one the whole way.

Pitfall 4: MCP config has a learning curve. Extended ability comes from MCP, and hooking external tools means writing config. crushrc is Bash syntax, natural for anyone who writes scripts, a learning curve for those who do not know Bash. The good news: crush has a built-in "self-configuration" skill -- most of the time you tell it in natural language "add an Ollama provider for me" and it edits crushrc itself.

Pitfall 5 (a sweet spot in disguise): China availability is actually friendly. model-agnostic means no forced foreign model: Z.ai (Zhipu), MiniMax, Moonshot, and Alibaba all have native environment variables, DeepSeek works via the OpenAI-compatible endpoint with two crushrc lines, and local Ollama runs fully offline. Compared to a closed-source agent locked to a single overseas model, crush is actually stronger for domestic use -- pick a cheap domestic model and both cost and speed beat forcing a foreign API. For model choice, see this site's GLM Coding Plan upgrade hotspot.

Suited for: backend/DevOps/systems developers who live in the terminal; people who want model freedom and refuse to lock into one vendor; anyone who needs to run a coding agent on servers and remote environments; Chinese developers who want to wire domestic models to control cost. Skip it if: you want a GUI IDE -- Cursor fits better; you want zero-config out of the box -- a Claude Code subscription is easier; you want someone to manage your mail and calendar -- openclaw is that species.

6. FAQ

Q: Is crush MIT-licensed? A: No. GitHub SPDX reports NOASSERTION; LICENSE.md is actually FSL-1.1-MIT (Functional Source License v1.1, MIT Future License). You may use, modify, and build on it, but not for "competitive use" (building a commercial product/service that replaces crush). It automatically converts to MIT two years after release. Personal and internal use is fine; read LICENSE.md yourself before any commercial integration.

Q: How is crush different from Claude Code? A: Both are terminal coding agents, with two core differences: first, models -- Claude Code only takes Anthropic, about $20/month subscription, while crush takes any compatible model, software is free, model costs are self-paid, and you can switch models mid-session; second, license -- Claude Code is closed-source, crush's source is visible (FSL-1.1-MIT).

Q: Can I use it in China? Which models does it take? A: Yes, and friendlier than agents locked to foreign models. Z.ai (Zhipu), MiniMax, Moonshot, and Alibaba all have native environment variables; DeepSeek works via the OpenAI-compatible endpoint with a two-line custom provider in crushrc; and you can hook local Ollama for fully offline use. Picking a cheap domestic model to control cost is entirely feasible.

Q: How do I install it, and does it cost money? A: The software is free. brew install charmbracelet/tap/crush or npm install -g @charmland/crush, or winget/scoop on Windows. After install, Ctrl+L to pick a model: Hyper has a free tier, or set environment variables for your own API key. Model calls burn your API quota; hook local Ollama for zero API cost.

Q: 27k stars -- is the project mature? A: Active but still iterating fast. Created 2025-05-21, pushed today, not archived, 629 open issues. The Charm ecosystem (Bubble Tea/Hugo) has solid engineering foundations, but crush's own interfaces and docs are still moving; before production integration, run your scenario yourself.

References

• charmbracelet/crush GitHub repo (27,274 stars / 2,143 forks, Go, FSL-1.1-MIT license): https://github.com/charmbracelet/crush
• crush official site (by Charm): https://stuff.charm.sh/crush
• LICENSE.md (FSL-1.1-MIT full text, including competitive-use clause and the two-year MIT conversion): https://github.com/charmbracelet/crush/blob/main/LICENSE.md
• Charm Hyper official provider (subscription with free tier, ZDR): https://hyper.charm.land
• Catwalk (community-maintained crush-compatible model repo): https://github.com/charmbracelet/catwalk
• This site: GLM Coding Plan upgrade hotspot | AI coding plan comparison | AI coding context engineering SOP | cua resource | openclaw resource