Crush: download, install and use the terminal coding agent

Introduction

Crush is a free open-source agentic coding tool by Charm. Like OpenCode, it lives in your terminal, reads and edits your files, runs shell commands and works through tasks step by step. Differences that matter: Crush is written in Go (single binary, no Node.js needed), understands LSP servers the way you do, keeps several work sessions per project, lets you switch models mid-session without losing context, and extends via MCP servers and Agent Skills. It runs on macOS, Linux, Windows (PowerShell and WSL), Android, FreeBSD, OpenBSD and NetBSD.

Download and install

With Homebrew (macOS and Linux)

brew install charmbracelet/tap/crush

With npm (any OS with Node.js)

npm install -g @charmland/crush

On Arch Linux

yay -S crush-bin

On FreeBSD

pkg install crush

On Windows: Winget

winget install charmbracelet.crush

On Windows: Scoop

scoop bucket add charm https://github.com/charmbracelet/scoop-bucket.git

scoop install crush

Debian and RPM packages plus binaries for every OS are on the releases page of the project repository.

With Go (any OS with a Go toolchain)

go install github.com/charmbracelet/crush@latest

Check it works:

crush --version

Connect a model

The quickest start is Hyper, the official Crush provider: it is subscription-based with a free tier, privacy focused with zero data retention. Pick a Hyper model in the model picker and follow the steps to authenticate.

To use any other provider, press ctrl+l to open the model picker, choose the provider and paste your API key. Supported keys include Anthropic, OpenAI, Gemini, OpenRouter and more — the same OpenRouter key from the OpenCode guide works here too. Keys can also come from environment variables:

• OPENROUTER_API_KEY — OpenRouter
• ANTHROPIC_API_KEY — Anthropic
• OPENAI_API_KEY — OpenAI
• GEMINI_API_KEY — Google Gemini
• HYPER_API_KEY — Charm Hyper

Local models work through Ollama, llama.cpp, LM Studio and similar: register the provider once, and Crush discovers its models itself.

Use Crush daily

Go to your project and start:

cd /path/to/project

crush

Let Crush learn the project: initialization analyzes the codebase and writes the findings to AGENTS.md — commit that file so every session starts with context. Project-specific rules that would confuse other tools go to CRUSH.md instead.

Core workflow:

• Sessions, not windows. Keep several work sessions per project and switch between them; two terminals on one directory share one workspace, so you can watch the same session live from both.
• Switch models mid-task. Open the model picker with ctrl+l any time — context is preserved, so start cheap and escalate to a strong model only for hard parts.
• Extra context on demand. Attach LSP servers for jump-accurate code context and MCP servers (stdio, http, sse) for tools, plus Agent Skills packages for reusable capabilities.
• Permissions with a safety valve. Crush asks before running tool calls; allow the safe ones forever and keep the rest confirmed. Full autopilot is one flag away — use it with care:

crush --yolo

Keep secrets out of the agent context with .crushignore (same syntax as .gitignore). Usage metrics are pseudonymous and can be switched off:

export CRUSH_DISABLE_METRICS=1

Configure with crushrc

Crush needs no configuration, but a crushrc customizes everything. It is Bash with Crush builtins, identical on all platforms. Project file ./.crushrc wins over the global ~/.config/crush/crushrc. Example:

provider add ollama --type ollama --base-url "http://localhost:11434/v1" permissions allow view edit mcp add github --type http --url "https://api.github.com/mcp/" option notifications disabled

The old JSON format still works but is deprecated. Note that crushrc is trusted code — never launch Crush in a directory whose config you have not reviewed.

Troubleshooting

• Command not found after install: restart the terminal (PATH update) or rerun the installer; with Go check that the Go bin dir is on PATH.
• No models listed: open the model picker with ctrl+l and connect a provider first; for Ollama confirm the server answers on http://localhost:11434.
• Clipboard copy and paste broken on Linux: install wl-copy and wl-paste for Wayland, or xclip / xsel for X11.
• Something behaves oddly: read the project log and rerun with debug output when needed:

crush logs --tail 500

crush --debug

Official sources:

• github.com/charmbracelet/crush
• hyper.charm.land
• charm.land/slack
• charm.land/discord

Article author: Andrei Olegovich