To use Crush, Charm’s coding agent, you install it with brew install charmbracelet/tap/crush (or npm, winget and others), run crush inside a project, press Ctrl+L to choose a model and paste an API key or sign in, then describe the task. Crush asks before it runs tools, and since version 0.88 its settings live in a crushrc file rather than crush.json.
This guide covers Crush as of November 2026 (version 0.101): install, providers and local models, the interface, approvals, crush run, sessions, configuration, context files, MCP and costs.
What Crush is
Crush is a terminal coding agent from Charm, the team behind Bubble Tea and other terminal tools, and it shows: it is one of the most polished interfaces in the category. It works with almost any model: Anthropic, OpenAI, Gemini, OpenRouter, Groq, xAI, Bedrock, Vertex, Azure, local models and Charm’s own Hyper service. You can switch models in the middle of a session without losing the context.
Crush is still before version 1.0 and ships a minor version about once a week, with nightly builds in between. Its license is FSL-1.1-MIT: the source is public and each version becomes MIT-licensed later, but it is not an OSI open-source license today.
Step 1: install
brew install charmbracelet/tap/crush # macOS and Linux
npm install -g @charmland/crush # any platform with Node
winget install charmbracelet.crush # Windows
go install github.com/charmbracelet/crush@latest
There are also packages for Arch (yay -S crush), Nix, FreeBSD, Scoop, and apt and yum repositories at repo.charm.sh. Crush runs on macOS, Linux, Windows (PowerShell and WSL) and the BSDs.
Step 2: pick a model
cd my-project
crush
Press Ctrl+L to open the model picker, choose a provider and paste its key. Crush also reads keys from the environment, for example ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY or OPENROUTER_API_KEY. To use a subscription instead of a key, run crush login with copilot, openai (a ChatGPT plan), grok or hyper.
For a local model, add a provider in your config (Step 6):
provider add ollama --type ollama --base-url "http://localhost:11434/v1/"
Crush gets its model list from Catwalk, a community catalog that updates on its own; crush models shows what is available and crush update-providers refreshes it.
Step 3: work in a session
Describe the task in plain words. The keys worth learning first:
Ctrl+P(or/) opens the command palette: summarize the session, initialize the project, toggle MCP servers and skills, change the theme.Ctrl+Lswitches the model;Ctrl+Nstarts a new session andCtrl+Slists sessions.@mentions a file;Ctrl+Fadds a file or image;Ctrl+Vpastes an image.Shift+Tabcycles the modes, including Plan mode, where Crush works out the steps before it edits.Ctrl+Oopens your editor for a long message;Ctrl+Gshows help;Ctrl+Cquits.
Step 4: approvals and yolo mode
Crush asks before each tool call. In the dialog, a allows it once, s allows that tool for the rest of the session, d denies it and t shows the diff. Read-only commands such as ls or git status run without asking.
To stop being asked about tools you trust, allow them in your config; to hide a tool completely, deny it:
permissions allow view ls grep edit
permissions deny bash
crush --yolo (or -y, or Ctrl+Y in a session) skips the prompts but still blocks commands Crush rates as dangerous. -yy turns on sysadmin mode, which allows those as well. Keep both for containers and throwaway machines.
Step 5: crush run for one-off tasks
crush run "add a unit test for the price formatter"
git diff | crush run "review this diff for bugs"
cat README.md | crush run "tighten the wording" > README.new.md
-m picks the model (provider/model), -q hides the spinner, and -s <id> or -C continues a session. crush run has no JSON output option, so for structured results ask for the format in the prompt and check it.
Step 6: crushrc and configuration
Since version 0.88, Crush reads its settings from a crushrc file: a Bash script with Crush commands, run by Crush’s own interpreter so it behaves the same on Windows. It looks for .crushrc or crushrc in the project and ~/.config/crush/crushrc globally, and merges what it finds, with the project winning. A small example:
model large anthropic/claude-sonnet-5-5
model small anthropic/claude-haiku-5-5
permissions allow view ls grep
mcp add docs --type http --url https://example.com/mcp
lsp add go --command gopls
crush.json and .crush.json still work, but they are deprecated and get no new features. crush dirs shows where Crush keeps its config and data.
One warning: a crushrc is code. Anything inside $(...) runs when Crush starts, so read the file before you start Crush in a repository you don’t know.
Step 7: AGENTS.md, MCP and LSP
Context files. Crush reads AGENTS.md, CRUSH.md, CLAUDE.md, GEMINI.md, .cursorrules and .github/copilot-instructions.md without any setup, plus ~/.config/crush/CRUSH.md for every project. Initialize Project in the command palette writes an AGENTS.md by looking at the repository. Our guide to CLAUDE.md and AGENTS.md covers what to put in it.
MCP. Crush supports stdio, HTTP and SSE servers, including OAuth sign-in. Add them with mcp add in crushrc and turn them on or off from the palette.
LSP. Language servers give Crush the same diagnostics your editor sees. Add one with lsp add, or let option auto-lsp set them up.
What Crush costs (as of November 2026)
| Option | Price | Notes |
|---|---|---|
| Crush | Free | Bring your own keys or local models |
| Hyper pay-as-you-go | From $5 prepaid | Charm’s hosted open-weight models |
| Hyper monthly plans | $10 to $200 a month | Weekly credits with a rolling 5-hour window |
| Your own key | Your provider’s price | Anthropic, OpenAI, Gemini, OpenRouter and more |
Crush sends pseudonymous usage metrics by default; set CRUSH_DISABLE_METRICS=1 or DO_NOT_TRACK=1 to turn them off.
Common pitfalls
- Following crush.json guides. Most tutorials from before August 2026 show JSON only. It still works, but new options arrive in
crushrc. - Yolo changed in v0.100.
--yolonow blocks dangerous commands instead of asking; scripts that relied on the old behaviour may need-yy. - Commit trailers. Crush adds an
Assisted-bytrailer to commits by default. Change it withoption attribution-trailer-style. - Clipboard on Linux. Copy and paste need
wl-copyorxclip/xsel. - Where the logs are.
crush logs --tail 50shows what went wrong; logs live in the project’s.crushfolder.
Running Crush next to other CLIs in AgentVera
If Crush is the only agent you use, its own interface may be all you need. It gets harder when Crush runs next to Claude Code, Codex or Gemini CLI on the same project. AgentVera is a desktop app that runs these CLIs side by side in real terminals, with your own installs and keys. Crush support works like this:
- One session per agent. AgentVera finds the session Crush creates through
crush session list --jsonand reopens it with--session <id>on later launches, so the conversation survives an app restart. - An account per agent. Each Crush account in Settings → Accounts gets its own data folder and
crush login, and you can add Anthropic, OpenAI, OpenRouter or Gemini keys. - MCP and conflicts. Servers from AgentVera’s MCP manager reach Crush through its config, and AgentVera adds its own hook so it sees which files each agent touches.
- Panes and review. Run Crush in the workspace grid next to other agents and check their changes with code review.
The free plan runs 2 agents at once and includes MCP, Git, Docker, SSH, code review and token savings. Pro is $9.99 a month and has no agent limit; if you have never had a trial, your first sign-in to the app turns on Pro for 7 days with no card. To try it, download AgentVera.
Wrapping up
Crush takes two steps to start: install it and run crush, then pick a model with Ctrl+L. After that, the settings that matter are in crushrc: which tools may run without asking, which models to use for big and small tasks, and which MCP and language servers to load. Keep an AGENTS.md in the project and Crush, like most other agents, will follow it.
Sources: Crush on GitHub, configuration docs, releases, license, Hyper.