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

URL: https://agentvera.dev/en/blog/how-to-use-crush/ · Published: 2026-11-17

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.

**In short:**

- Install with brew install charmbracelet/tap/crush, npm install -g @charmland/crush or winget install charmbracelet.crush, run crush in a project, press Ctrl+L to pick a model and paste a key or sign in.
- Crush asks before tool calls and lets you allow a tool for the session. crush run handles one-off tasks and piped input; crush -C or crush -s <id> resumes a session.
- Since v0.88 the config is a crushrc file (Bash with Crush commands); crush.json still works but is deprecated. Crush reads AGENTS.md, CRUSH.md and CLAUDE.md on its own.

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](https://github.com/charmbracelet "Charm on GitHub"), 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

```bash
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

```bash
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):

```bash
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:

```bash
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

```bash
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:

```bash
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](/en/blog/claude-md-agents-md/ "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.** `--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](/en/ "AgentVera") is a desktop app that runs these CLIs side by side in real terminals, with your own installs and keys. [Crush support](/en/agents/crush/ "Crush in AgentVera") 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](/en/features/mcp-manager/ "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](/en/features/workspace/ "Workspace") grid next to other agents and check their changes with [code review](/en/features/code-review/ "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](/en/download/ "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](https://github.com/charmbracelet/crush "Crush README"), [configuration docs](https://github.com/charmbracelet/crush/tree/main/docs/config "Crush configuration"), [releases](https://github.com/charmbracelet/crush/releases "Crush releases"), [license](https://github.com/charmbracelet/crush/blob/main/LICENSE.md "Crush license"), [Hyper](https://hyper.charm.land "Hyper by Charm").

## Frequently asked 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.

---

**About AgentVera.** AgentVera is a desktop app for macOS, Windows and Linux, built by Solviera Teknoloji. It runs 18 AI coding agents (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) side by side, per project, in real terminals with the user's own CLI installs and logins. The free plan runs 2 agents at once. Download: https://agentvera.dev/en/download/ · Pricing: https://agentvera.dev/en/pricing/
