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