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## Logging
453
454Sometimes you need to look at logs. Luckily, Crush logs all sorts of
455stuff. Logs are stored in `./.crush/logs/crush.log` relative to the project.
456
457The CLI also contains some helper commands to make perusing recent logs easier:
458
459```bash
460# Print the last 1000 lines
461crush logs
462
463# Print the last 500 lines
464crush logs --tail 500
465
466# Follow logs in real time
467crush logs --follow
468```
469
470Want more logging? Run `crush` with the `--debug` flag, or enable it in the
471config:
472
473```json
474{
475  "$schema": "https://charm.land/crush.json",
476  "options": {
477    "debug": true,
478    "debug_lsp": true
479  }
480}
481```
482
483## Disabling Provider Auto-Updates
484
485By default, Crush automatically checks for the latest and greatest list of
486providers and models from [Catwalk](https://github.com/charmbracelet/catwalk),
487the open source Crush provider database. This means that when new providers and
488models are available, or when model metadata changes, Crush automatically
489updates your local configuration.
490
491For those with restricted internet access, or those who prefer to work in
492air-gapped environments, this might not be want you want, and this feature can
493be disabled.
494
495To disable automatic provider updates, set `disable_provider_auto_update` into
496your `crush.json` config:
497
498```json
499{
500  "$schema": "https://charm.land/crush.json",
501  "options": {
502    "disable_provider_auto_update": true
503  }
504}
505```
506
507Or set the `CRUSH_DISABLE_PROVIDER_AUTO_UPDATE` environment variable:
508
509```bash
510export CRUSH_DISABLE_PROVIDER_AUTO_UPDATE=1
511```
512
513### Manually updating providers
514
515Manually updating providers is possible with the `crush update-providers`
516command:
517
518```bash
519# Update providers remotely from Catwalk.
520crush update-providers
521
522# Update providers from a custom Catwalk base URL.
523crush update-providers https://example.com/
524
525# Update providers from a local file.
526crush update-providers /path/to/local-providers.json
527
528# Reset providers to the embedded version, embedded at crush at build time.
529crush update-providers embedded
530
531# For more info:
532crush update-providers --help
533```
534
535## A Note on Claude Max and GitHub Copilot
536
537Crush only supports model providers through official, compliant APIs. We do not
538support or endorse any methods that rely on personal Claude Max and GitHub
539Copilot accounts or OAuth workarounds, which violate Anthropic and
540Microsoft’s Terms of Service.
541
542We’re committed to building sustainable, trusted integrations with model
543providers. If you’re a provider interested in working with us,
544[reach out](mailto:vt100@charm.sh).
545
546## Contributing
547
548See the [contributing guide](https://github.com/charmbracelet/crush?tab=contributing-ov-file#contributing).
549
550## Whatcha think?
551
552We’d love to hear your thoughts on this project. Need help? We gotchu. You can find us on:
553
554- [Twitter](https://twitter.com/charmcli)
555- [Discord][discord]
556- [Slack](https://charm.land/slack)
557- [The Fediverse](https://mastodon.social/@charmcli)
558- [Bluesky](https://bsky.app/profile/charm.land)
559
560[discord]: https://charm.land/discord
561
562## License
563
564[FSL-1.1-MIT](https://github.com/charmbracelet/crush/raw/main/LICENSE.md)
565
566---
567
568Part of [Charm](https://charm.land).
569
570<a href="https://charm.land/"><img alt="The Charm logo" width="400" src="https://stuff.charm.sh/charm-banner-next.jpg" /></a>
571
572<!--prettier-ignore-->
573Charm热爱开源 • Charm loves open source