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 it creates. You can customize this behavior with the `attribution` option:
179
180```json
181{
182  "$schema": "https://charm.land/crush.json",
183  "options": {
184    "attribution": {
185      "co_authored_by": true,
186      "generated_with": true
187    }
188  }
189}
190```
191
192- `co_authored_by`: When true (default), adds `Co-Authored-By: Crush <crush@charm.land>` to commit messages
193- `generated_with`: When true (default), adds `💘 Generated with Crush` line to commit messages and PR descriptions
194
195To disable all attribution, set both options to false:
196
197```json
198{
199  "$schema": "https://charm.land/crush.json",
200  "options": {
201    "attribution": {
202      "co_authored_by": false,
203      "generated_with": false
204    }
205  }
206}
207```
208
209### LSPs
210
211Crush can use LSPs for additional context to help inform its decisions, just
212like you would. LSPs can be added manually like so:
213
214```json
215{
216  "$schema": "https://charm.land/crush.json",
217  "lsp": {
218    "go": {
219      "command": "gopls",
220      "env": {
221        "GOTOOLCHAIN": "go1.24.5"
222      }
223    },
224    "typescript": {
225      "command": "typescript-language-server",
226      "args": ["--stdio"]
227    },
228    "nix": {
229      "command": "nil"
230    }
231  }
232}
233```
234
235### MCPs
236
237Crush also supports Model Context Protocol (MCP) servers through three
238transport types: `stdio` for command-line servers, `http` for HTTP endpoints,
239and `sse` for Server-Sent Events. Environment variable expansion is supported
240using `$(echo $VAR)` syntax.
241
242```json
243{
244  "$schema": "https://charm.land/crush.json",
245  "mcp": {
246    "filesystem": {
247      "type": "stdio",
248      "command": "node",
249      "args": ["/path/to/mcp-server.js"],
250      "env": {
251        "NODE_ENV": "production"
252      }
253    },
254    "github": {
255      "type": "http",
256      "url": "https://example.com/mcp/",
257      "headers": {
258        "Authorization": "$(echo Bearer $EXAMPLE_MCP_TOKEN)"
259      }
260    },
261    "streaming-service": {
262      "type": "sse",
263      "url": "https://example.com/mcp/sse",
264      "headers": {
265        "API-Key": "$(echo $API_KEY)"
266      }
267    }
268  }
269}
270```
271
272### Ignoring Files
273
274Crush respects `.gitignore` files by default, but you can also create a
275`.crushignore` file to specify additional files and directories that Crush
276should ignore. This is useful for excluding files that you want in version
277control but don't want Crush to consider when providing context.
278
279The `.crushignore` file uses the same syntax as `.gitignore` and can be placed
280in the root of your project or in subdirectories.
281
282### Allowing Tools
283
284By default, Crush will ask you for permission before running tool calls. If
285you'd like, you can allow tools to be executed without prompting you for
286permissions. Use this with care.
287
288```json
289{
290  "$schema": "https://charm.land/crush.json",
291  "permissions": {
292    "allowed_tools": [
293      "view",
294      "ls",
295      "grep",
296      "edit",
297      "mcp_context7_get-library-doc"
298    ]
299  }
300}
301```
302
303You can also skip all permission prompts entirely by running Crush with the
304`--yolo` flag. Be very, very careful with this feature.
305
306### Local Models
307
308Local models can also be configured via OpenAI-compatible API. Here are two common examples:
309
310#### Ollama
311
312```json
313{
314  "providers": {
315    "ollama": {
316      "name": "Ollama",
317      "base_url": "http://localhost:11434/v1/",
318      "type": "openai",
319      "models": [
320        {
321          "name": "Qwen 3 30B",
322          "id": "qwen3:30b",
323          "context_window": 256000,
324          "default_max_tokens": 20000
325        }
326      ]
327    }
328  }
329}
330```
331
332#### LM Studio
333
334```json
335{
336  "providers": {
337    "lmstudio": {
338      "name": "LM Studio",
339      "base_url": "http://localhost:1234/v1/",
340      "type": "openai",
341      "models": [
342        {
343          "name": "Qwen 3 30B",
344          "id": "qwen/qwen3-30b-a3b-2507",
345          "context_window": 256000,
346          "default_max_tokens": 20000
347        }
348      ]
349    }
350  }
351}
352```
353
354### Custom Providers
355
356Crush supports custom provider configurations for both OpenAI-compatible and
357Anthropic-compatible APIs.
358
359#### OpenAI-Compatible APIs
360
361Here’s an example configuration for Deepseek, which uses an OpenAI-compatible
362API. Don't forget to set `DEEPSEEK_API_KEY` in your environment.
363
364```json
365{
366  "$schema": "https://charm.land/crush.json",
367  "providers": {
368    "deepseek": {
369      "type": "openai",
370      "base_url": "https://api.deepseek.com/v1",
371      "api_key": "$DEEPSEEK_API_KEY",
372      "models": [
373        {
374          "id": "deepseek-chat",
375          "name": "Deepseek V3",
376          "cost_per_1m_in": 0.27,
377          "cost_per_1m_out": 1.1,
378          "cost_per_1m_in_cached": 0.07,
379          "cost_per_1m_out_cached": 1.1,
380          "context_window": 64000,
381          "default_max_tokens": 5000
382        }
383      ]
384    }
385  }
386}
387```
388
389#### Anthropic-Compatible APIs
390
391Custom Anthropic-compatible providers follow this format:
392
393```json
394{
395  "$schema": "https://charm.land/crush.json",
396  "providers": {
397    "custom-anthropic": {
398      "type": "anthropic",
399      "base_url": "https://api.anthropic.com/v1",
400      "api_key": "$ANTHROPIC_API_KEY",
401      "extra_headers": {
402        "anthropic-version": "2023-06-01"
403      },
404      "models": [
405        {
406          "id": "claude-sonnet-4-20250514",
407          "name": "Claude Sonnet 4",
408          "cost_per_1m_in": 3,
409          "cost_per_1m_out": 15,
410          "cost_per_1m_in_cached": 3.75,
411          "cost_per_1m_out_cached": 0.3,
412          "context_window": 200000,
413          "default_max_tokens": 50000,
414          "can_reason": true,
415          "supports_attachments": true
416        }
417      ]
418    }
419  }
420}
421```
422
423### Amazon Bedrock
424
425Crush currently supports running Anthropic models through Bedrock, with caching disabled.
426
427- A Bedrock provider will appear once you have AWS configured, i.e. `aws configure`
428- Crush also expects the `AWS_REGION` or `AWS_DEFAULT_REGION` to be set
429- To use a specific AWS profile set `AWS_PROFILE` in your environment, i.e. `AWS_PROFILE=myprofile crush`
430
431### Vertex AI Platform
432
433Vertex AI will appear in the list of available providers when `VERTEXAI_PROJECT` and `VERTEXAI_LOCATION` are set. You will also need to be authenticated:
434
435```bash
436gcloud auth application-default login
437```
438
439To add specific models to the configuration, configure as such:
440
441```json
442{
443  "$schema": "https://charm.land/crush.json",
444  "providers": {
445    "vertexai": {
446      "models": [
447        {
448          "id": "claude-sonnet-4@20250514",
449          "name": "VertexAI Sonnet 4",
450          "cost_per_1m_in": 3,
451          "cost_per_1m_out": 15,
452          "cost_per_1m_in_cached": 3.75,
453          "cost_per_1m_out_cached": 0.3,
454          "context_window": 200000,
455          "default_max_tokens": 50000,
456          "can_reason": true,
457          "supports_attachments": true
458        }
459      ]
460    }
461  }
462}
463```
464
465## Logging
466
467Sometimes you need to look at logs. Luckily, Crush logs all sorts of
468stuff. Logs are stored in `./.crush/logs/crush.log` relative to the project.
469
470The CLI also contains some helper commands to make perusing recent logs easier:
471
472```bash
473# Print the last 1000 lines
474crush logs
475
476# Print the last 500 lines
477crush logs --tail 500
478
479# Follow logs in real time
480crush logs --follow
481```
482
483Want more logging? Run `crush` with the `--debug` flag, or enable it in the
484config:
485
486```json
487{
488  "$schema": "https://charm.land/crush.json",
489  "options": {
490    "debug": true,
491    "debug_lsp": true
492  }
493}
494```
495
496## Disabling Provider Auto-Updates
497
498By default, Crush automatically checks for the latest and greatest list of
499providers and models from [Catwalk](https://github.com/charmbracelet/catwalk),
500the open source Crush provider database. This means that when new providers and
501models are available, or when model metadata changes, Crush automatically
502updates your local configuration.
503
504For those with restricted internet access, or those who prefer to work in
505air-gapped environments, this might not be want you want, and this feature can
506be disabled.
507
508To disable automatic provider updates, set `disable_provider_auto_update` into
509your `crush.json` config:
510
511```json
512{
513  "$schema": "https://charm.land/crush.json",
514  "options": {
515    "disable_provider_auto_update": true
516  }
517}
518```
519
520Or set the `CRUSH_DISABLE_PROVIDER_AUTO_UPDATE` environment variable:
521
522```bash
523export CRUSH_DISABLE_PROVIDER_AUTO_UPDATE=1
524```
525
526### Manually updating providers
527
528Manually updating providers is possible with the `crush update-providers`
529command:
530
531```bash
532# Update providers remotely from Catwalk.
533crush update-providers
534
535# Update providers from a custom Catwalk base URL.
536crush update-providers https://example.com/
537
538# Update providers from a local file.
539crush update-providers /path/to/local-providers.json
540
541# Reset providers to the embedded version, embedded at crush at build time.
542crush update-providers embedded
543
544# For more info:
545crush update-providers --help
546```
547
548## A Note on Claude Max and GitHub Copilot
549
550Crush only supports model providers through official, compliant APIs. We do not
551support or endorse any methods that rely on personal Claude Max and GitHub
552Copilot accounts or OAuth workarounds, which violate Anthropic and
553Microsoft’s Terms of Service.
554
555We’re committed to building sustainable, trusted integrations with model
556providers. If you’re a provider interested in working with us,
557[reach out](mailto:vt100@charm.sh).
558
559## Contributing
560
561See the [contributing guide](https://github.com/charmbracelet/crush?tab=contributing-ov-file#contributing).
562
563## Whatcha think?
564
565We’d love to hear your thoughts on this project. Need help? We gotchu. You can find us on:
566
567- [Twitter](https://twitter.com/charmcli)
568- [Discord][discord]
569- [Slack](https://charm.land/slack)
570- [The Fediverse](https://mastodon.social/@charmcli)
571- [Bluesky](https://bsky.app/profile/charm.land)
572
573[discord]: https://charm.land/discord
574
575## License
576
577[FSL-1.1-MIT](https://github.com/charmbracelet/crush/raw/main/LICENSE.md)
578
579---
580
581Part of [Charm](https://charm.land).
582
583<a href="https://charm.land/"><img alt="The Charm logo" width="400" src="https://stuff.charm.sh/charm-banner-next.jpg" /></a>
584
585<!--prettier-ignore-->
586Charm热爱开源 • Charm loves open source