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