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