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### Attribution Settings
274
275By default, Crush adds attribution information to Git commits and pull requests
276it creates. You can customize this behavior with the `attribution` option:
277
278```json
279{
280  "$schema": "https://charm.land/crush.json",
281  "options": {
282    "attribution": {
283      "co_authored_by": true,
284      "generated_with": true
285    }
286  }
287}
288```
289
290- `co_authored_by`: When true (default), adds `Co-Authored-By: Crush <crush@charm.land>` to commit messages
291- `generated_with`: When true (default), adds `💘 Generated with Crush` line to commit messages and PR descriptions
292
293### Local Models
294
295Local models can also be configured via OpenAI-compatible API. Here are two common examples:
296
297#### Ollama
298
299```json
300{
301  "providers": {
302    "ollama": {
303      "name": "Ollama",
304      "base_url": "http://localhost:11434/v1/",
305      "type": "openai",
306      "models": [
307        {
308          "name": "Qwen 3 30B",
309          "id": "qwen3:30b",
310          "context_window": 256000,
311          "default_max_tokens": 20000
312        }
313      ]
314    }
315  }
316}
317```
318
319#### LM Studio
320
321```json
322{
323  "providers": {
324    "lmstudio": {
325      "name": "LM Studio",
326      "base_url": "http://localhost:1234/v1/",
327      "type": "openai",
328      "models": [
329        {
330          "name": "Qwen 3 30B",
331          "id": "qwen/qwen3-30b-a3b-2507",
332          "context_window": 256000,
333          "default_max_tokens": 20000
334        }
335      ]
336    }
337  }
338}
339```
340
341### Custom Providers
342
343Crush supports custom provider configurations for both OpenAI-compatible and
344Anthropic-compatible APIs.
345
346#### OpenAI-Compatible APIs
347
348Here’s an example configuration for Deepseek, which uses an OpenAI-compatible
349API. Don't forget to set `DEEPSEEK_API_KEY` in your environment.
350
351```json
352{
353  "$schema": "https://charm.land/crush.json",
354  "providers": {
355    "deepseek": {
356      "type": "openai",
357      "base_url": "https://api.deepseek.com/v1",
358      "api_key": "$DEEPSEEK_API_KEY",
359      "models": [
360        {
361          "id": "deepseek-chat",
362          "name": "Deepseek V3",
363          "cost_per_1m_in": 0.27,
364          "cost_per_1m_out": 1.1,
365          "cost_per_1m_in_cached": 0.07,
366          "cost_per_1m_out_cached": 1.1,
367          "context_window": 64000,
368          "default_max_tokens": 5000
369        }
370      ]
371    }
372  }
373}
374```
375
376#### Anthropic-Compatible APIs
377
378Custom Anthropic-compatible providers follow this format:
379
380```json
381{
382  "$schema": "https://charm.land/crush.json",
383  "providers": {
384    "custom-anthropic": {
385      "type": "anthropic",
386      "base_url": "https://api.anthropic.com/v1",
387      "api_key": "$ANTHROPIC_API_KEY",
388      "extra_headers": {
389        "anthropic-version": "2023-06-01"
390      },
391      "models": [
392        {
393          "id": "claude-sonnet-4-20250514",
394          "name": "Claude Sonnet 4",
395          "cost_per_1m_in": 3,
396          "cost_per_1m_out": 15,
397          "cost_per_1m_in_cached": 3.75,
398          "cost_per_1m_out_cached": 0.3,
399          "context_window": 200000,
400          "default_max_tokens": 50000,
401          "can_reason": true,
402          "supports_attachments": true
403        }
404      ]
405    }
406  }
407}
408```
409
410### Amazon Bedrock
411
412Crush currently supports running Anthropic models through Bedrock, with caching disabled.
413
414- A Bedrock provider will appear once you have AWS configured, i.e. `aws configure`
415- Crush also expects the `AWS_REGION` or `AWS_DEFAULT_REGION` to be set
416- To use a specific AWS profile set `AWS_PROFILE` in your environment, i.e. `AWS_PROFILE=myprofile crush`
417
418### Vertex AI Platform
419
420Vertex AI will appear in the list of available providers when `VERTEXAI_PROJECT` and `VERTEXAI_LOCATION` are set. You will also need to be authenticated:
421
422```bash
423gcloud auth application-default login
424```
425
426To add specific models to the configuration, configure as such:
427
428```json
429{
430  "$schema": "https://charm.land/crush.json",
431  "providers": {
432    "vertexai": {
433      "models": [
434        {
435          "id": "claude-sonnet-4@20250514",
436          "name": "VertexAI Sonnet 4",
437          "cost_per_1m_in": 3,
438          "cost_per_1m_out": 15,
439          "cost_per_1m_in_cached": 3.75,
440          "cost_per_1m_out_cached": 0.3,
441          "context_window": 200000,
442          "default_max_tokens": 50000,
443          "can_reason": true,
444          "supports_attachments": true
445        }
446      ]
447    }
448  }
449}
450```
451
452## Custom Commands (a.k.a. Saved Prompts)
453
454Crush has first-class support for predefined prompts with variables that can be
455filled in when run. See [COMMANDS.md](COMMANDS.md) for more info.
456
457## Logging
458
459Sometimes you need to look at logs. Luckily, Crush logs all sorts of
460stuff. Logs are stored in `./.crush/logs/crush.log` relative to the project.
461
462The CLI also contains some helper commands to make perusing recent logs easier:
463
464```bash
465# Print the last 1000 lines
466crush logs
467
468# Print the last 500 lines
469crush logs --tail 500
470
471# Follow logs in real time
472crush logs --follow
473```
474
475Want more logging? Run `crush` with the `--debug` flag, or enable it in the
476config:
477
478```json
479{
480  "$schema": "https://charm.land/crush.json",
481  "options": {
482    "debug": true,
483    "debug_lsp": true
484  }
485}
486```
487
488## Disabling Provider Auto-Updates
489
490By default, Crush automatically checks for the latest and greatest list of
491providers and models from [Catwalk](https://github.com/charmbracelet/catwalk),
492the open source Crush provider database. This means that when new providers and
493models are available, or when model metadata changes, Crush automatically
494updates your local configuration.
495
496For those with restricted internet access, or those who prefer to work in
497air-gapped environments, this might not be want you want, and this feature can
498be disabled.
499
500To disable automatic provider updates, set `disable_provider_auto_update` into
501your `crush.json` config:
502
503```json
504{
505  "$schema": "https://charm.land/crush.json",
506  "options": {
507    "disable_provider_auto_update": true
508  }
509}
510```
511
512Or set the `CRUSH_DISABLE_PROVIDER_AUTO_UPDATE` environment variable:
513
514```bash
515export CRUSH_DISABLE_PROVIDER_AUTO_UPDATE=1
516```
517
518### Manually updating providers
519
520Manually updating providers is possible with the `crush update-providers`
521command:
522
523```bash
524# Update providers remotely from Catwalk.
525crush update-providers
526
527# Update providers from a custom Catwalk base URL.
528crush update-providers https://example.com/
529
530# Update providers from a local file.
531crush update-providers /path/to/local-providers.json
532
533# Reset providers to the embedded version, embedded at crush at build time.
534crush update-providers embedded
535
536# For more info:
537crush update-providers --help
538```
539
540## A Note on Claude Max and GitHub Copilot
541
542Crush only supports model providers through official, compliant APIs. We do not
543support or endorse any methods that rely on personal Claude Max and GitHub
544Copilot accounts or OAuth workarounds, which violate Anthropic and
545Microsoft’s Terms of Service.
546
547We’re committed to building sustainable, trusted integrations with model
548providers. If you’re a provider interested in working with us,
549[reach out](mailto:vt100@charm.sh).
550
551## Contributing
552
553See the [contributing guide](https://github.com/charmbracelet/crush?tab=contributing-ov-file#contributing).
554
555## Whatcha think?
556
557We’d love to hear your thoughts on this project. Need help? We gotchu. You can find us on:
558
559- [Twitter](https://twitter.com/charmcli)
560- [Discord][discord]
561- [Slack](https://charm.land/slack)
562- [The Fediverse](https://mastodon.social/@charmcli)
563- [Bluesky](https://bsky.app/profile/charm.land)
564
565[discord]: https://charm.land/discord
566
567## License
568
569[FSL-1.1-MIT](https://github.com/charmbracelet/crush/raw/main/LICENSE.md)
570
571---
572
573Part of [Charm](https://charm.land).
574
575<a href="https://charm.land/"><img alt="The Charm logo" width="400" src="https://stuff.charm.sh/charm-banner-next.jpg" /></a>
576
577<!--prettier-ignore-->
578Charm热爱开源 • Charm loves open source