1# Crush
2
3<p align="center">
4 <a href="https://stuff.charm.sh/crush/charm-crush.png"><img width="450" alt="Charm Crush Logo" src="https://github.com/user-attachments/assets/adc1a6f4-b284-4603-836c-59038caa2e8b" /></a><br />
5 <a href="https://github.com/charmbracelet/crush/releases"><img src="https://img.shields.io/github/release/charmbracelet/crush" alt="Latest Release"></a>
6 <a href="https://github.com/charmbracelet/crush/actions"><img src="https://github.com/charmbracelet/crush/workflows/build/badge.svg" alt="Build Status"></a>
7</p>
8
9<p align="center">Your new coding bestie, now available in your favourite terminal.<br />Your tools, your code, and your workflows, wired into your LLM of choice.</p>
10
11<p align="center"><img width="800" alt="Crush Demo" src="https://github.com/user-attachments/assets/58280caf-851b-470a-b6f7-d5c4ea8a1968" /></p>
12
13## Features
14
15- **Multi-Model:** choose from a wide range of LLMs or add your own via OpenAI- or Anthropic-compatible APIs
16- **Flexible:** switch LLMs mid-session while preserving context
17- **Session-Based:** maintain multiple work sessions and contexts per project
18- **LSP-Enhanced:** Crush uses LSPs for additional context, just like you do
19- **Extensible:** add capabilities via MCPs (`http`, `stdio`, and `sse`)
20- **Works Everywhere:** first-class support in every terminal on macOS, Linux, Windows (PowerShell and WSL), and FreeBSD
21
22## Installation
23
24Use a package manager:
25
26```bash
27# Homebrew
28brew install charmbracelet/tap/crush
29
30# NPM
31npm install -g @charmland/crush
32
33# Arch Linux (btw)
34yay -S crush-bin
35```
36
37<details>
38<summary><strong>Nix</strong></summary>
39
40Crush is available via [NUR](https://github.com/nix-community/NUR) in `nur.repos.charmbracelet.crush`.
41
42You can also try out Crush via `nix-shell`:
43
44```bash
45# Add the NUR channel.
46nix-channel --add https://github.com/nix-community/NUR/archive/main.tar.gz nur
47nix-channel --update
48
49# Get Crush in a Nix shell.
50nix-shell -p '(import <nur> { pkgs = import <nixpkgs> {}; }).repos.charmbracelet.crush'
51```
52
53</details>
54
55<details>
56<summary><strong>Debian/Ubuntu</strong></summary>
57
58```bash
59sudo mkdir -p /etc/apt/keyrings
60curl -fsSL https://repo.charm.sh/apt/gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/charm.gpg
61echo "deb [signed-by=/etc/apt/keyrings/charm.gpg] https://repo.charm.sh/apt/ * *" | sudo tee /etc/apt/sources.list.d/charm.list
62sudo apt update && sudo apt install crush
63```
64
65</details>
66
67<details>
68<summary><strong>Fedora/RHEL</strong></summary>
69
70```bash
71echo '[charm]
72name=Charm
73baseurl=https://repo.charm.sh/yum/
74enabled=1
75gpgcheck=1
76gpgkey=https://repo.charm.sh/yum/gpg.key' | sudo tee /etc/yum.repos.d/charm.repo
77sudo yum install crush
78```
79
80</details>
81
82Or, download it:
83
84- [Packages][releases] are available in Debian and RPM formats
85- [Binaries][releases] are available for Linux, macOS, Windows, FreeBSD, OpenBSD, and NetBSD
86
87[releases]: https://github.com/charmbracelet/crush/releases
88
89Or just install it with Go:
90
91```
92go install github.com/charmbracelet/crush@latest
93```
94
95> [!WARNING]
96> Productivity may increase when using Crush and you may find yourself nerd
97> sniped when first using the application. If the symptoms persist, join the
98> [Discord][discord] and nerd snipe the rest of us.
99
100## Getting Started
101
102The quickest way to get started is to grab an API key for your preferred
103provider such as Anthropic, OpenAI, Groq, or OpenRouter and just start
104Crush. You'll be prompted to enter your API key.
105
106That said, you can also set environment variables for preferred providers.
107
108| Environment Variable | Provider |
109| -------------------------- | -------------------------------------------------- |
110| `ANTHROPIC_API_KEY` | Anthropic |
111| `OPENAI_API_KEY` | OpenAI |
112| `GEMINI_API_KEY` | Google Gemini |
113| `VERTEXAI_PROJECT` | Google Cloud VertexAI (Gemini) |
114| `VERTEXAI_LOCATION` | Google Cloud VertexAI (Gemini) |
115| `GROQ_API_KEY` | Groq |
116| `AWS_ACCESS_KEY_ID` | AWS Bedrock (Claude) |
117| `AWS_SECRET_ACCESS_KEY` | AWS Bedrock (Claude) |
118| `AWS_REGION` | AWS Bedrock (Claude) |
119| `AZURE_OPENAI_ENDPOINT` | Azure OpenAI models |
120| `AZURE_OPENAI_API_KEY` | Azure OpenAI models (optional when using Entra ID) |
121| `AZURE_OPENAI_API_VERSION` | Azure OpenAI models |
122
123### By the Way
124
125Is there a provider you’d like to see in Crush? Is there an existing model that needs an update?
126
127Crush’s default model listing is managed in [Catwalk](https://github.com/charmbracelet/catwalk), an community-supported, open source repository of Crush-compatible models, and you’re welcome to contribute.
128
129<a href="https://github.com/charmbracelet/catwalk"><img width="174" height="174" alt="Catwalk Badge" src="https://github.com/user-attachments/assets/95b49515-fe82-4409-b10d-5beb0873787d" /></a>
130
131## Configuration
132
133Crush runs great with no configuration. That said, if you do need or want to
134customize Crush, configuration can be added either local to the project itself,
135or globally, with the following priority:
136
1371. `./.crush.json`
1382. `./crush.json`
1393. `$HOME/.config/crush/crush.json`
140
141Configuration itself is stored as a JSON object:
142
143```json
144{
145 "this-setting": { }
146 "that-setting": { }
147}
148```
149
150### LSPs
151
152Crush can use LSPs for additional context to help inform its decisions, just
153like you would. LSPs can be added manually like so:
154
155```json
156{
157 "$schema": "https://charm.land/crush.json",
158 "lsp": {
159 "go": {
160 "command": "gopls"
161 },
162 "typescript": {
163 "command": "typescript-language-server",
164 "args": ["--stdio"]
165 },
166 "nix": {
167 "command": "nil"
168 }
169 }
170}
171```
172
173### MCPs
174
175Crush also supports Model Context Protocol (MCP) servers through three
176transport types: `stdio` for command-line servers, `http` for HTTP endpoints,
177and `sse` for Server-Sent Events. Environment variable expansion is supported
178using `$(echo $VAR)` syntax.
179
180```json
181{
182 "$schema": "https://charm.land/crush.json",
183 "mcp": {
184 "filesystem": {
185 "type": "stdio",
186 "command": "node",
187 "args": ["/path/to/mcp-server.js"],
188 "env": {
189 "NODE_ENV": "production"
190 }
191 },
192 "github": {
193 "type": "http",
194 "url": "https://example.com/mcp/",
195 "headers": {
196 "Authorization": "$(echo Bearer $EXAMPLE_MCP_TOKEN)"
197 }
198 },
199 "streaming-service": {
200 "type": "sse",
201 "url": "https://example.com/mcp/sse",
202 "headers": {
203 "API-Key": "$(echo $API_KEY)"
204 }
205 }
206 }
207}
208```
209
210### Whitelisting Tools
211
212By default, Crush will ask you for permission before running tool calls. If
213you'd like, you can whitelist tools to be executed without prompting you for
214permissions. Use this with care.
215
216```json
217{
218 "$schema": "https://charm.land/crush.json",
219 "permissions": {
220 "allowed_tools": [
221 "view",
222 "ls",
223 "grep",
224 "edit",
225 "mcp_context7_get-library-doc"
226 ]
227 }
228}
229```
230
231You can also skip all permission prompts entirely by running Crush with the
232`--yolo` flag. Be very, very careful with this feature.
233
234### Custom Providers
235
236Crush supports custom provider configurations for both OpenAI-compatible and
237Anthropic-compatible APIs.
238
239#### OpenAI-Compatible APIs
240
241Here’s an example configuration for Deepseek, which uses an OpenAI-compatible
242API. Don't forget to set `DEEPSEEK_API_KEY` in your environment.
243
244```json
245{
246 "$schema": "https://charm.land/crush.json",
247 "providers": {
248 "deepseek": {
249 "type": "openai",
250 "base_url": "https://api.deepseek.com/v1",
251 "api_key": "$DEEPSEEK_API_KEY",
252 "models": [
253 {
254 "id": "deepseek-chat",
255 "name": "Deepseek V3",
256 "cost_per_1m_in": 0.27,
257 "cost_per_1m_out": 1.1,
258 "cost_per_1m_in_cached": 0.07,
259 "cost_per_1m_out_cached": 1.1,
260 "context_window": 64000,
261 "default_max_tokens": 5000
262 }
263 ]
264 }
265 }
266}
267```
268
269#### Anthropic-Compatible APIs
270
271Custom Anthropic-compatible providers follow this format:
272
273```json
274{
275 "$schema": "https://charm.land/crush.json",
276 "providers": {
277 "custom-anthropic": {
278 "type": "anthropic",
279 "base_url": "https://api.anthropic.com/v1",
280 "api_key": "$ANTHROPIC_API_KEY",
281 "extra_headers": {
282 "anthropic-version": "2023-06-01"
283 },
284 "models": [
285 {
286 "id": "claude-sonnet-4-20250514",
287 "name": "Claude Sonnet 4",
288 "cost_per_1m_in": 3,
289 "cost_per_1m_out": 15,
290 "cost_per_1m_in_cached": 3.75,
291 "cost_per_1m_out_cached": 0.3,
292 "context_window": 200000,
293 "default_max_tokens": 50000,
294 "can_reason": true,
295 "supports_attachments": true
296 }
297 ]
298 }
299 }
300}
301```
302
303## Logging
304
305Sometimes you need to look at logs. Luckily, Crush logs all sorts of
306stuff. Logs are stored in `./.crush/logs/crush.log` relative to the project.
307
308The CLI also contains some helper commands to make perusing recent logs easier:
309
310```bash
311# Print the last 1000 lines
312crush logs
313
314# Print the last 500 lines
315crush logs --tail 500
316
317# Follow logs in real time
318crush logs --follow
319```
320
321Want more logging? Run `crush` with the `--debug` flag, or enable it in the
322config:
323
324```json
325{
326 "$schema": "https://charm.land/crush.json",
327 "options": {
328 "debug": true,
329 "debug_lsp": true
330 }
331}
332```
333
334## Whatcha think?
335
336We’d love to hear your thoughts on this project. Need help? We gotchu. You can find us on:
337
338- [Twitter](https://twitter.com/charmcli)
339- [Discord][discord]
340- [Slack](https://charm.land/slack)
341- [The Fediverse](https://mastodon.social/@charmcli)
342
343[discord]: https://charm.land/discord
344
345## License
346
347[FSL-1.1-MIT](https://github.com/charmbracelet/crush/raw/main/LICENSE)
348
349---
350
351Part of [Charm](https://charm.land).
352
353<a href="https://charm.land/"><img alt="The Charm logo" width="400" src="https://stuff.charm.sh/charm-banner-next.jpg" /></a>
354
355<!--prettier-ignore-->
356Charm热爱开源 • Charm loves open source