Crush Developer Guide
Crush is an open-source coding agent from Charmbracelet built for terminal-native development workflows. This guide explains how Crush is shaped, how to think about it as a developer tool, and where to contribute once the runtime model is clear.
This guide is based on the official charmbracelet/crush repository and its primary project materials, checked on June 26, 2026.
In this section​
- Setup and first run
- Architecture and runtime
- Configuration and security
- Extending and contributing
- Simple user guide
1. What Crush is​
The shortest accurate description is:
Crush is a terminal-first coding agent designed for developers who want AI assistance inside a native command-line workflow.
That puts it in the same broad class as Codex CLI, Gemini CLI, Qwen Code, and Goose CLI, but with Charmbracelet's terminal-product sensibility.
2. The mental model​
Think of Crush as four cooperating parts:
| Layer | What it does |
|---|---|
| terminal experience | Main user-facing interface |
| coding-agent runtime | Reads, reasons, and acts on software tasks |
| model and tool wiring | Connects the agent to external intelligence and local actions |
| product polish | Makes the CLI feel deliberate rather than improvised |
3. Why developers would choose it​
- It is open source and terminal-native.
- It comes from Charmbracelet, a team known for polished terminal software.
- It is aimed at coding workflows, not generic office chat.
- It can appeal to developers who want strong CLI ergonomics as much as raw agent capability.
4. Where it fits best​
Crush makes the most sense when the team wants:
- AI support inside the terminal,
- a more productized CLI experience,
- and an open codebase they can inspect or adapt.
5. Recommended reading order​
- this overview,
- the repo install and usage guidance,
- configuration and runtime behavior,
- implementation structure once the usage loop is clear.