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), FreeBSD, OpenBSD, and NetBSD
 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# Nix
 37nix run github:numtide/nix-ai-tools#crush
 38```
 39
 40<details>
 41<summary><strong>Nix (NUR)</strong></summary>
 42
 43Crush is available via [NUR](https://github.com/nix-community/NUR) in `nur.repos.charmbracelet.crush`.
 44
 45You can also try out Crush via `nix-shell`:
 46
 47```bash
 48# Add the NUR channel.
 49nix-channel --add https://github.com/nix-community/NUR/archive/main.tar.gz nur
 50nix-channel --update
 51
 52# Get Crush in a Nix shell.
 53nix-shell -p '(import <nur> { pkgs = import <nixpkgs> {}; }).repos.charmbracelet.crush'
 54```
 55
 56</details>
 57
 58<details>
 59<summary><strong>Debian/Ubuntu</strong></summary>
 60
 61```bash
 62sudo mkdir -p /etc/apt/keyrings
 63curl -fsSL https://repo.charm.sh/apt/gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/charm.gpg
 64echo "deb [signed-by=/etc/apt/keyrings/charm.gpg] https://repo.charm.sh/apt/ * *" | sudo tee /etc/apt/sources.list.d/charm.list
 65sudo apt update && sudo apt install crush
 66```
 67
 68</details>
 69
 70<details>
 71<summary><strong>Fedora/RHEL</strong></summary>
 72
 73```bash
 74echo '[charm]
 75name=Charm
 76baseurl=https://repo.charm.sh/yum/
 77enabled=1
 78gpgcheck=1
 79gpgkey=https://repo.charm.sh/yum/gpg.key' | sudo tee /etc/yum.repos.d/charm.repo
 80sudo yum install crush
 81```
 82
 83</details>
 84
 85Or, download it:
 86
 87- [Packages][releases] are available in Debian and RPM formats
 88- [Binaries][releases] are available for Linux, macOS, Windows, FreeBSD, OpenBSD, and NetBSD
 89
 90[releases]: https://github.com/charmbracelet/crush/releases
 91
 92Or just install it with Go:
 93
 94```
 95go install github.com/charmbracelet/crush@latest
 96```
 97
 98> [!WARNING]
 99> Productivity may increase when using Crush and you may find yourself nerd
100> sniped when first using the application. If the symptoms persist, join the
101> [Discord][discord] and nerd snipe the rest of us.
102
103## Getting Started
104
105The quickest way to get started is to grab an API key for your preferred
106provider such as Anthropic, OpenAI, Groq, or OpenRouter and just start
107Crush. You'll be prompted to enter your API key.
108
109That said, you can also set environment variables for preferred providers.
110
111| Environment Variable       | Provider                                           |
112| -------------------------- | -------------------------------------------------- |
113| `ANTHROPIC_API_KEY`        | Anthropic                                          |
114| `OPENAI_API_KEY`           | OpenAI                                             |
115| `OPENROUTER_API_KEY`       | OpenRouter                                         |
116| `GEMINI_API_KEY`           | Google Gemini                                      |
117| `VERTEXAI_PROJECT`         | Google Cloud VertexAI (Gemini)                     |
118| `VERTEXAI_LOCATION`        | Google Cloud VertexAI (Gemini)                     |
119| `GROQ_API_KEY`             | Groq                                               |
120| `AWS_ACCESS_KEY_ID`        | AWS Bedrock (Claude)                               |
121| `AWS_SECRET_ACCESS_KEY`    | AWS Bedrock (Claude)                               |
122| `AWS_REGION`               | AWS Bedrock (Claude)                               |
123| `AZURE_OPENAI_ENDPOINT`    | Azure OpenAI models                                |
124| `AZURE_OPENAI_API_KEY`     | Azure OpenAI models (optional when using Entra ID) |
125| `AZURE_OPENAI_API_VERSION` | Azure OpenAI models                                |
126
127### By the Way
128
129Is there a provider you’d like to see in Crush? Is there an existing model that needs an update?
130
131Crush’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.
132
133<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>
134
135## Configuration
136
137Crush runs great with no configuration. That said, if you do need or want to
138customize Crush, configuration can be added either local to the project itself,
139or globally, with the following priority:
140
1411. `.crush.json`
1422. `crush.json`
1433. `$HOME/.config/crush/crush.json` (Windows: `%USERPROFILE%\AppData\Local\crush\crush.json`)
144
145Configuration itself is stored as a JSON object:
146
147```json
148{
149   "this-setting": {"this": "that"},
150   "that-setting": ["ceci", "cela"]
151}
152```
153
154As an additional note, Crush also stores ephemeral data, such as application state, in one additional location:
155
156```bash
157# Unix
158$HOME/.local/shared/crush/crush.json
159
160# Windows
161%LOCALAPPDATA%\crush\crush.json
162```
163
164### LSPs
165
166Crush can use LSPs for additional context to help inform its decisions, just
167like you would. LSPs can be added manually like so:
168
169```json
170{
171  "$schema": "https://charm.land/crush.json",
172  "lsp": {
173    "go": {
174      "command": "gopls"
175    },
176    "typescript": {
177      "command": "typescript-language-server",
178      "args": ["--stdio"]
179    },
180    "nix": {
181      "command": "nil"
182    }
183  }
184}
185```
186
187### MCPs
188
189Crush also supports Model Context Protocol (MCP) servers through three
190transport types: `stdio` for command-line servers, `http` for HTTP endpoints,
191and `sse` for Server-Sent Events. Environment variable expansion is supported
192using `$(echo $VAR)` syntax.
193
194```json
195{
196  "$schema": "https://charm.land/crush.json",
197  "mcp": {
198    "filesystem": {
199      "type": "stdio",
200      "command": "node",
201      "args": ["/path/to/mcp-server.js"],
202      "env": {
203        "NODE_ENV": "production"
204      }
205    },
206    "github": {
207      "type": "http",
208      "url": "https://example.com/mcp/",
209      "headers": {
210        "Authorization": "$(echo Bearer $EXAMPLE_MCP_TOKEN)"
211      }
212    },
213    "streaming-service": {
214      "type": "sse",
215      "url": "https://example.com/mcp/sse",
216      "headers": {
217        "API-Key": "$(echo $API_KEY)"
218      }
219    }
220  }
221}
222```
223
224### Ignoring Files
225
226Crush respects `.gitignore` files by default, but you can also create a
227`.crushignore` file to specify additional files and directories that Crush
228should ignore. This is useful for excluding files that you want in version
229control but don't want Crush to consider when providing context.
230
231The `.crushignore` file uses the same syntax as `.gitignore` and can be placed
232in the root of your project or in subdirectories.
233
234### Allowing Tools
235
236By default, Crush will ask you for permission before running tool calls. If
237you'd like, you can allow tools to be executed without prompting you for
238permissions. Use this with care.
239
240```json
241{
242  "$schema": "https://charm.land/crush.json",
243  "permissions": {
244    "allowed_tools": [
245      "view",
246      "ls",
247      "grep",
248      "edit",
249      "mcp_context7_get-library-doc"
250    ]
251  }
252}
253```
254
255You can also skip all permission prompts entirely by running Crush with the
256`--yolo` flag. Be very, very careful with this feature.
257
258### Local Models
259
260Local models can also be configured via OpenAI-compatible API. Here are two common examples:
261
262#### Ollama
263
264```json
265{
266  "providers": {
267    "ollama": {
268      "name": "Ollama",
269      "base_url": "http://localhost:11434/v1/",
270      "type": "openai",
271      "models": [
272        {
273          "name": "Qwen 3 30B",
274          "id": "qwen3:30b",
275          "context_window": 256000,
276          "default_max_tokens": 20000
277        }
278      ]
279    }
280}
281```
282
283#### LM Studio
284
285```json
286{
287  "providers": {
288    "lmstudio": {
289      "name": "LM Studio",
290      "base_url": "http://localhost:1234/v1/",
291      "type": "openai",
292      "models": [
293        {
294          "name": "Qwen 3 30B",
295          "id": "qwen/qwen3-30b-a3b-2507",
296          "context_window": 256000,
297          "default_max_tokens": 20000
298        }
299      ]
300    }
301  }
302}
303```
304
305### Custom Providers
306
307Crush supports custom provider configurations for both OpenAI-compatible and
308Anthropic-compatible APIs.
309
310#### OpenAI-Compatible APIs
311
312Here’s an example configuration for Deepseek, which uses an OpenAI-compatible
313API. Don't forget to set `DEEPSEEK_API_KEY` in your environment.
314
315```json
316{
317  "$schema": "https://charm.land/crush.json",
318  "providers": {
319    "deepseek": {
320      "type": "openai",
321      "base_url": "https://api.deepseek.com/v1",
322      "api_key": "$DEEPSEEK_API_KEY",
323      "models": [
324        {
325          "id": "deepseek-chat",
326          "name": "Deepseek V3",
327          "cost_per_1m_in": 0.27,
328          "cost_per_1m_out": 1.1,
329          "cost_per_1m_in_cached": 0.07,
330          "cost_per_1m_out_cached": 1.1,
331          "context_window": 64000,
332          "default_max_tokens": 5000
333        }
334      ]
335    }
336  }
337}
338```
339
340#### Anthropic-Compatible APIs
341
342Custom Anthropic-compatible providers follow this format:
343
344```json
345{
346  "$schema": "https://charm.land/crush.json",
347  "providers": {
348    "custom-anthropic": {
349      "type": "anthropic",
350      "base_url": "https://api.anthropic.com/v1",
351      "api_key": "$ANTHROPIC_API_KEY",
352      "extra_headers": {
353        "anthropic-version": "2023-06-01"
354      },
355      "models": [
356        {
357          "id": "claude-sonnet-4-20250514",
358          "name": "Claude Sonnet 4",
359          "cost_per_1m_in": 3,
360          "cost_per_1m_out": 15,
361          "cost_per_1m_in_cached": 3.75,
362          "cost_per_1m_out_cached": 0.3,
363          "context_window": 200000,
364          "default_max_tokens": 50000,
365          "can_reason": true,
366          "supports_attachments": true
367        }
368      ]
369    }
370  }
371}
372```
373
374### Amazon Bedrock
375
376Crush currently supports running Anthropic models through Bedrock, with caching disabled.
377
378* A Bedrock provider will appear once you have AWS configured, i.e. `aws configure`
379* Crush also expects the `AWS_REGION` or `AWS_DEFAULT_REGION` to be set
380* To use a specific AWS profile set `AWS_PROFILE` in your environment, i.e. `AWS_PROFILE=myprofile crush`
381
382### Vertex AI Platform
383
384Vertex AI will appear in the list of available providers when `VERTEXAI_PROJECT` and `VERTEXAI_LOCATION` are set. You will also need to be authenticated:
385
386```bash
387gcloud auth application-default login
388```
389
390To add specific models to the configuration, configure as such:
391
392```json
393{
394  "$schema": "https://charm.land/crush.json",
395  "providers": {
396    "vertexai": {
397      "models": [
398        {
399          "id": "claude-sonnet-4@20250514",
400          "name": "VertexAI Sonnet 4",
401          "cost_per_1m_in": 3,
402          "cost_per_1m_out": 15,
403          "cost_per_1m_in_cached": 3.75,
404          "cost_per_1m_out_cached": 0.3,
405          "context_window": 200000,
406          "default_max_tokens": 50000,
407          "can_reason": true,
408          "supports_attachments": true
409        }
410      ]
411    }
412  }
413}
414```
415
416## Logging
417
418Sometimes you need to look at logs. Luckily, Crush logs all sorts of
419stuff. Logs are stored in `./.crush/logs/crush.log` relative to the project.
420
421The CLI also contains some helper commands to make perusing recent logs easier:
422
423```bash
424# Print the last 1000 lines
425crush logs
426
427# Print the last 500 lines
428crush logs --tail 500
429
430# Follow logs in real time
431crush logs --follow
432```
433
434Want more logging? Run `crush` with the `--debug` flag, or enable it in the
435config:
436
437```json
438{
439  "$schema": "https://charm.land/crush.json",
440  "options": {
441    "debug": true,
442    "debug_lsp": true
443  }
444}
445```
446
447## Whatcha think?
448
449We’d love to hear your thoughts on this project. Need help? We gotchu. You can find us on:
450
451- [Twitter](https://twitter.com/charmcli)
452- [Discord][discord]
453- [Slack](https://charm.land/slack)
454- [The Fediverse](https://mastodon.social/@charmcli)
455
456[discord]: https://charm.land/discord
457
458## License
459
460[FSL-1.1-MIT](https://github.com/charmbracelet/crush/raw/main/LICENSE)
461
462---
463
464Part of [Charm](https://charm.land).
465
466<a href="https://charm.land/"><img alt="The Charm logo" width="400" src="https://stuff.charm.sh/charm-banner-next.jpg" /></a>
467
468<!--prettier-ignore-->
469Charm热爱开源 • Charm loves open source