How to Install Crush and Use It as Your Terminal AI Coder
Crush is a terminal AI coding agent from Charm, the makers of the Gum and Bubble Tea libraries. It lives in your shell, reads your project, and edits files with your approval. You install it with a package manager, set an API key for your provider, and start it inside a repo. It is free software; you pay only for the model you connect.
If you spend your day in a terminal and dislike switching to an editor panel to talk to an AI, this is built for you.
What is Crush?
Crush is a command-line coding assistant. It runs a session in your terminal, understands the project it sits in, and can read files, suggest edits, and run commands when you confirm them.
It supports multiple model providers, so you can point it at a hosted API or a local model depending on your budget and privacy needs.
Is Crush free?
The tool is free and open source. Model usage is not free unless you run a local model.
With a hosted key you pay per token through that provider. With a local model through a tool like Ollama, your only cost is hardware. There is no separate Crush subscription.
How do you install and start it?
- Install via a package manager — brew install on macOS, or the provided script for Linux.
- Run crush from inside your project directory so it picks up the repo context.
- Set your provider and API key in its configuration file.
- Type a request in plain language, such as “add input validation to the signup handler.”
- Review each proposed file change and accept or reject it.
The first session may prompt for configuration. A few lines of JSON name your provider and model; after that it remembers.
What can it actually do?
| Capability | Notes |
|---|---|
| Read project files | Builds context from the repo |
| Propose edits | You approve before writing |
| Run shell commands | With confirmation |
| Multiple providers | Hosted APIs or local models |
How should you prompt it?
Be concrete about files and intent. “Refactor utils/date.ts to remove the deprecated format function and update callers” gets a cleaner result than “clean up the code.”
Work in small steps. One change per request keeps the diffs reviewable and makes it easy to spot when Crush misunderstands your intent.
Where does a terminal agent fall short?
No visual diff viewer — you read changes as terminal output, which is harder for large edits than a side-by-side pane. And it depends on your model’s context window; large files can get truncated, so split work when a file is huge.
It also asks for confirmation a lot, which is correct for safety but slows fast iteration. Adjust that only once you trust it in a given repo.
Who should use Crush?
Terminal-first developers who want AI help without leaving the shell, and anyone who values an open-source tool they can inspect. If you prefer a rich GUI with inline diffs and integrated previews, an editor-based assistant will feel more natural. Crush is for the command line, unapologetically.
Quick Summary
- Crush is a free, open-source terminal AI coding agent from Charm.
- Install via a package manager, configure a provider, and run it inside your repo.
- It reads files, proposes edits, and runs commands, all with your approval.
- It supports hosted and local models — you pay only for model usage, if any.
