Invite a friend, get 1 month of Pro freeHow it works

How to use Crush: a step-by-step guide to Charm’s coding agent

How to use Crush, Charm’s terminal coding agent: install, pick a provider or local model, approve tools, use crush run, resume sessions and set up crushrc.

Solviera Teknoloji 7 min read

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+L switches the model; Ctrl+N starts a new session and Ctrl+S lists sessions.
  • @ mentions a file; Ctrl+F adds a file or image; Ctrl+V pastes an image.
  • Shift+Tab cycles the modes, including Plan mode, where Crush works out the steps before it edits.
  • Ctrl+O opens your editor for a long message; Ctrl+G shows help; Ctrl+C quits.

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)

OptionPriceNotes
CrushFreeBring your own keys or local models
Hyper pay-as-you-goFrom $5 prepaidCharm’s hosted open-weight models
Hyper monthly plans$10 to $200 a monthWeekly credits with a rolling 5-hour window
Your own keyYour provider’s priceAnthropic, 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. --yolo now blocks dangerous commands instead of asking; scripts that relied on the old behaviour may need -yy.
  • Commit trailers. Crush adds an Assisted-by trailer to commits by default. Change it with option attribution-trailer-style.
  • Clipboard on Linux. Copy and paste need wl-copy or xclip/xsel.
  • Where the logs are. crush logs --tail 50 shows what went wrong; logs live in the project’s .crush folder.

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 --json and 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.

Questions

Is Crush free?

Crush costs nothing to use: you bring your own API keys or a local model. Charm also sells Hyper, a hosted provider for open-weight models, with monthly plans from $10 to $200 or prepaid credit from $5 as of November 2026. Crush is under FSL-1.1-MIT, a source-available license whose versions turn into MIT later.

Does Crush work with local models?

Yes. Add an Ollama, LM Studio, llama.cpp or LiteLLM provider in crushrc, for example provider add ollama --type ollama --base-url "http://localhost:11434/v1/", and Crush discovers its models.

How do I resume a Crush session?

crush -C (or --continue) reopens the most recent session in the project, and crush -s <id> reopens a specific one. crush session list shows them, and Crush prints the resume command when you quit.

Does Crush read CLAUDE.md or AGENTS.md?

Both. Crush reads AGENTS.md, CRUSH.md, CLAUDE.md, GEMINI.md, .cursorrules and .github/copilot-instructions.md if they exist. Initialize Project in the command palette writes an AGENTS.md for you.

What does crush --yolo do?

It skips the approval prompts but still blocks commands Crush rates as dangerous. -yy (sysadmin mode) allows those too. Keep both for throwaway environments.

Bring your agents to one desk.

Download AgentVera for free; your installed CLIs are ready to go.

More posts