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