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<p align="center">你的新编程伙伴，现在就在你最爱的终端中。<br />你的工具、代码和工作流，都与您选择的 LLM 模型紧密相连。</p>
 11
 12<p align="center"><img width="800" alt="Crush Demo" src="https://github.com/user-attachments/assets/58280caf-851b-470a-b6f7-d5c4ea8a1968" /></p>
 13
 14## Features
 15
 16- **Multi-Model:** choose from a wide range of LLMs or add your own via OpenAI- or Anthropic-compatible APIs
 17- **Flexible:** switch LLMs mid-session while preserving context
 18- **Session-Based:** maintain multiple work sessions and contexts per project
 19- **LSP-Enhanced:** Crush uses LSPs for additional context, just like you do
 20- **Extensible:** add capabilities via MCPs (`http`, `stdio`, and `sse`)
 21- **[Hooks](./internal/hooks/HOOKS.md):** execute custom shell commands at lifecycle events
 22- **Works Everywhere:** first-class support in every terminal on macOS, Linux, Windows (PowerShell and WSL), FreeBSD, OpenBSD, and NetBSD
 23
 24## Installation
 25
 26Use a package manager:
 27
 28```bash
 29# Homebrew
 30brew install charmbracelet/tap/crush
 31
 32# NPM
 33npm install -g @charmland/crush
 34
 35# Arch Linux (btw)
 36yay -S crush-bin
 37
 38# Nix
 39nix run github:numtide/nix-ai-tools#crush
 40```
 41
 42Windows users:
 43
 44```bash
 45# Winget
 46winget install charmbracelet.crush
 47
 48# Scoop
 49scoop bucket add charm https://github.com/charmbracelet/scoop-bucket.git
 50scoop install crush
 51```
 52
 53<details>
 54<summary><strong>Nix (NUR)</strong></summary>
 55
 56Crush is available via [NUR](https://github.com/nix-community/NUR) in `nur.repos.charmbracelet.crush`.
 57
 58You can also try out Crush via `nix-shell`:
 59
 60```bash
 61# Add the NUR channel.
 62nix-channel --add https://github.com/nix-community/NUR/archive/main.tar.gz nur
 63nix-channel --update
 64
 65# Get Crush in a Nix shell.
 66nix-shell -p '(import <nur> { pkgs = import <nixpkgs> {}; }).repos.charmbracelet.crush'
 67```
 68
 69### NixOS & Home Manager Module Usage via NUR
 70
 71Crush provides NixOS and Home Manager modules via NUR.
 72You can use these modules directly in your flake by importing them from NUR. Since it auto detects whether its a home manager or nixos context you can use the import the exact same way :)
 73
 74```nix
 75{
 76  inputs = {
 77    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
 78    nur.url = "github:nix-community/NUR";
 79  };
 80
 81  outputs = { self, nixpkgs, nur, ... }: {
 82    nixosConfigurations.your-hostname = nixpkgs.lib.nixosSystem {
 83      system = "x86_64-linux";
 84      modules = [
 85        nur.modules.nixos.default
 86        nur.repos.charmbracelet.modules.crush
 87        {
 88          programs.crush = {
 89            enable = true;
 90            settings = {
 91              providers = {
 92                openai = {
 93                  id = "openai";
 94                  name = "OpenAI";
 95                  base_url = "https://api.openai.com/v1";
 96                  type = "openai";
 97                  api_key = "sk-fake123456789abcdef...";
 98                  models = [
 99                    {
100                      id = "gpt-4";
101                      name = "GPT-4";
102                    }
103                  ];
104                };
105              };
106              lsp = {
107                go = { command = "gopls"; enabled = true; };
108                nix = { command = "nil"; enabled = true; };
109              };
110              options = {
111                context_paths = [ "/etc/nixos/configuration.nix" ];
112                tui = { compact_mode = true; };
113                debug = false;
114              };
115            };
116          };
117        }
118      ];
119    };
120  };
121}
122```
123
124</details>
125
126<details>
127<summary><strong>Debian/Ubuntu</strong></summary>
128
129```bash
130sudo mkdir -p /etc/apt/keyrings
131curl -fsSL https://repo.charm.sh/apt/gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/charm.gpg
132echo "deb [signed-by=/etc/apt/keyrings/charm.gpg] https://repo.charm.sh/apt/ * *" | sudo tee /etc/apt/sources.list.d/charm.list
133sudo apt update && sudo apt install crush
134```
135
136</details>
137
138<details>
139<summary><strong>Fedora/RHEL</strong></summary>
140
141```bash
142echo '[charm]
143name=Charm
144baseurl=https://repo.charm.sh/yum/
145enabled=1
146gpgcheck=1
147gpgkey=https://repo.charm.sh/yum/gpg.key' | sudo tee /etc/yum.repos.d/charm.repo
148sudo yum install crush
149```
150
151</details>
152
153Or, download it:
154
155- [Packages][releases] are available in Debian and RPM formats
156- [Binaries][releases] are available for Linux, macOS, Windows, FreeBSD, OpenBSD, and NetBSD
157
158[releases]: https://github.com/charmbracelet/crush/releases
159
160Or just install it with Go:
161
162```
163go install github.com/charmbracelet/crush@latest
164```
165
166> [!WARNING]
167> Productivity may increase when using Crush and you may find yourself nerd
168> sniped when first using the application. If the symptoms persist, join the
169> [Discord][discord] and nerd snipe the rest of us.
170
171## Getting Started
172
173The quickest way to get started is to grab an API key for your preferred
174provider such as Anthropic, OpenAI, Groq, or OpenRouter and just start
175Crush. You'll be prompted to enter your API key.
176
177That said, you can also set environment variables for preferred providers.
178
179| Environment Variable        | Provider                                           |
180| --------------------------- | -------------------------------------------------- |
181| `ANTHROPIC_API_KEY`         | Anthropic                                          |
182| `OPENAI_API_KEY`            | OpenAI                                             |
183| `OPENROUTER_API_KEY`        | OpenRouter                                         |
184| `GEMINI_API_KEY`            | Google Gemini                                      |
185| `CEREBRAS_API_KEY`          | Cerebras                                           |
186| `HF_TOKEN`                  | Huggingface Inference                              |
187| `VERTEXAI_PROJECT`          | Google Cloud VertexAI (Gemini)                     |
188| `VERTEXAI_LOCATION`         | Google Cloud VertexAI (Gemini)                     |
189| `GROQ_API_KEY`              | Groq                                               |
190| `AWS_ACCESS_KEY_ID`         | AWS Bedrock (Claude)                               |
191| `AWS_SECRET_ACCESS_KEY`     | AWS Bedrock (Claude)                               |
192| `AWS_REGION`                | AWS Bedrock (Claude)                               |
193| `AWS_PROFILE`               | AWS Bedrock (Custom Profile)                       |
194| `AWS_BEARER_TOKEN_BEDROCK`  | AWS Bedrock                                        |
195| `AZURE_OPENAI_API_ENDPOINT` | Azure OpenAI models                                |
196| `AZURE_OPENAI_API_KEY`      | Azure OpenAI models (optional when using Entra ID) |
197| `AZURE_OPENAI_API_VERSION`  | Azure OpenAI models                                |
198
199### By the Way
200
201Is there a provider you’d like to see in Crush? Is there an existing model that needs an update?
202
203Crush’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.
204
205<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>
206
207## Configuration
208
209Crush runs great with no configuration. That said, if you do need or want to
210customize Crush, configuration can be added either local to the project itself,
211or globally, with the following priority:
212
2131. `.crush.json`
2142. `crush.json`
2153. `$HOME/.config/crush/crush.json` (Windows: `%USERPROFILE%\AppData\Local\crush\crush.json`)
216
217Configuration itself is stored as a JSON object:
218
219```json
220{
221  "this-setting": { "this": "that" },
222  "that-setting": ["ceci", "cela"]
223}
224```
225
226As an additional note, Crush also stores ephemeral data, such as application state, in one additional location:
227
228```bash
229# Unix
230$HOME/.local/share/crush/crush.json
231
232# Windows
233%LOCALAPPDATA%\crush\crush.json
234```
235
236### LSPs
237
238Crush can use LSPs for additional context to help inform its decisions, just
239like you would. LSPs can be added manually like so:
240
241```json
242{
243  "$schema": "https://charm.land/crush.json",
244  "lsp": {
245    "go": {
246      "command": "gopls",
247      "env": {
248        "GOTOOLCHAIN": "go1.24.5"
249      }
250    },
251    "typescript": {
252      "command": "typescript-language-server",
253      "args": ["--stdio"]
254    },
255    "nix": {
256      "command": "nil"
257    }
258  }
259}
260```
261
262### MCPs
263
264Crush also supports Model Context Protocol (MCP) servers through three
265transport types: `stdio` for command-line servers, `http` for HTTP endpoints,
266and `sse` for Server-Sent Events. Environment variable expansion is supported
267using `$(echo $VAR)` syntax.
268
269```json
270{
271  "$schema": "https://charm.land/crush.json",
272  "mcp": {
273    "filesystem": {
274      "type": "stdio",
275      "command": "node",
276      "args": ["/path/to/mcp-server.js"],
277      "timeout": 120,
278      "disabled": false,
279      "env": {
280        "NODE_ENV": "production"
281      }
282    },
283    "github": {
284      "type": "http",
285      "url": "https://example.com/mcp/",
286      "timeout": 120,
287      "disabled": false,
288      "headers": {
289        "Authorization": "$(echo Bearer $EXAMPLE_MCP_TOKEN)"
290      }
291    },
292    "streaming-service": {
293      "type": "sse",
294      "url": "https://example.com/mcp/sse",
295      "timeout": 120,
296      "disabled": false,
297      "headers": {
298        "API-Key": "$(echo $API_KEY)"
299      }
300    }
301  }
302}
303```
304
305### Ignoring Files
306
307Crush respects `.gitignore` files by default, but you can also create a
308`.crushignore` file to specify additional files and directories that Crush
309should ignore. This is useful for excluding files that you want in version
310control but don't want Crush to consider when providing context.
311
312The `.crushignore` file uses the same syntax as `.gitignore` and can be placed
313in the root of your project or in subdirectories.
314
315### Allowing Tools
316
317By default, Crush will ask you for permission before running tool calls. If
318you'd like, you can allow tools to be executed without prompting you for
319permissions. Use this with care.
320
321```json
322{
323  "$schema": "https://charm.land/crush.json",
324  "permissions": {
325    "allowed_tools": [
326      "view",
327      "ls",
328      "grep",
329      "edit",
330      "mcp_context7_get-library-doc"
331    ]
332  }
333}
334```
335
336You can also skip all permission prompts entirely by running Crush with the
337`--yolo` flag. Be very, very careful with this feature.
338
339### Attribution Settings
340
341By default, Crush adds attribution information to Git commits and pull requests
342it creates. You can customize this behavior with the `attribution` option:
343
344```json
345{
346  "$schema": "https://charm.land/crush.json",
347  "options": {
348    "attribution": {
349      "co_authored_by": true,
350      "generated_with": true
351    }
352  }
353}
354```
355
356- `co_authored_by`: When true (default), adds `Co-Authored-By: Crush <crush@charm.land>` to commit messages
357- `generated_with`: When true (default), adds `💘 Generated with Crush` line to commit messages and PR descriptions
358
359### Local Models
360
361Local models can also be configured via OpenAI-compatible API. Here are two common examples:
362
363#### Ollama
364
365```json
366{
367  "providers": {
368    "ollama": {
369      "name": "Ollama",
370      "base_url": "http://localhost:11434/v1/",
371      "type": "openai-compat",
372      "models": [
373        {
374          "name": "Qwen 3 30B",
375          "id": "qwen3:30b",
376          "context_window": 256000,
377          "default_max_tokens": 20000
378        }
379      ]
380    }
381  }
382}
383```
384
385#### LM Studio
386
387```json
388{
389  "providers": {
390    "lmstudio": {
391      "name": "LM Studio",
392      "base_url": "http://localhost:1234/v1/",
393      "type": "openai-compat",
394      "models": [
395        {
396          "name": "Qwen 3 30B",
397          "id": "qwen/qwen3-30b-a3b-2507",
398          "context_window": 256000,
399          "default_max_tokens": 20000
400        }
401      ]
402    }
403  }
404}
405```
406
407### Custom Providers
408
409Crush supports custom provider configurations for both OpenAI-compatible and
410Anthropic-compatible APIs.
411
412> [!NOTE]
413> Note that we support two "types" for OpenAI. Make sure to choose the right one
414> to ensure the best experience!
415> * `openai` should be used when proxying or routing requests through OpenAI.
416> * `openai-compat` should be used when using non-OpenAI providers that have OpenAI-compatible APIs.
417
418#### OpenAI-Compatible APIs
419
420Here’s an example configuration for Deepseek, which uses an OpenAI-compatible
421API. Don't forget to set `DEEPSEEK_API_KEY` in your environment.
422
423```json
424{
425  "$schema": "https://charm.land/crush.json",
426  "providers": {
427    "deepseek": {
428      "type": "openai-compat",
429      "base_url": "https://api.deepseek.com/v1",
430      "api_key": "$DEEPSEEK_API_KEY",
431      "models": [
432        {
433          "id": "deepseek-chat",
434          "name": "Deepseek V3",
435          "cost_per_1m_in": 0.27,
436          "cost_per_1m_out": 1.1,
437          "cost_per_1m_in_cached": 0.07,
438          "cost_per_1m_out_cached": 1.1,
439          "context_window": 64000,
440          "default_max_tokens": 5000
441        }
442      ]
443    }
444  }
445}
446```
447
448#### Anthropic-Compatible APIs
449
450Custom Anthropic-compatible providers follow this format:
451
452```json
453{
454  "$schema": "https://charm.land/crush.json",
455  "providers": {
456    "custom-anthropic": {
457      "type": "anthropic",
458      "base_url": "https://api.anthropic.com/v1",
459      "api_key": "$ANTHROPIC_API_KEY",
460      "extra_headers": {
461        "anthropic-version": "2023-06-01"
462      },
463      "models": [
464        {
465          "id": "claude-sonnet-4-20250514",
466          "name": "Claude Sonnet 4",
467          "cost_per_1m_in": 3,
468          "cost_per_1m_out": 15,
469          "cost_per_1m_in_cached": 3.75,
470          "cost_per_1m_out_cached": 0.3,
471          "context_window": 200000,
472          "default_max_tokens": 50000,
473          "can_reason": true,
474          "supports_attachments": true
475        }
476      ]
477    }
478  }
479}
480```
481
482### Amazon Bedrock
483
484Crush currently supports running Anthropic models through Bedrock, with caching disabled.
485
486- A Bedrock provider will appear once you have AWS configured, i.e. `aws configure`
487- Crush also expects the `AWS_REGION` or `AWS_DEFAULT_REGION` to be set
488- To use a specific AWS profile set `AWS_PROFILE` in your environment, i.e. `AWS_PROFILE=myprofile crush`
489- Alternatively to `aws configure`, you can also just set `AWS_BEARER_TOKEN_BEDROCK`
490
491### Vertex AI Platform
492
493Vertex AI will appear in the list of available providers when `VERTEXAI_PROJECT` and `VERTEXAI_LOCATION` are set. You will also need to be authenticated:
494
495```bash
496gcloud auth application-default login
497```
498
499To add specific models to the configuration, configure as such:
500
501```json
502{
503  "$schema": "https://charm.land/crush.json",
504  "providers": {
505    "vertexai": {
506      "models": [
507        {
508          "id": "claude-sonnet-4@20250514",
509          "name": "VertexAI Sonnet 4",
510          "cost_per_1m_in": 3,
511          "cost_per_1m_out": 15,
512          "cost_per_1m_in_cached": 3.75,
513          "cost_per_1m_out_cached": 0.3,
514          "context_window": 200000,
515          "default_max_tokens": 50000,
516          "can_reason": true,
517          "supports_attachments": true
518        }
519      ]
520    }
521  }
522}
523```
524
525## Logging
526
527Sometimes you need to look at logs. Luckily, Crush logs all sorts of
528stuff. Logs are stored in `./.crush/logs/crush.log` relative to the project.
529
530The CLI also contains some helper commands to make perusing recent logs easier:
531
532```bash
533# Print the last 1000 lines
534crush logs
535
536# Print the last 500 lines
537crush logs --tail 500
538
539# Follow logs in real time
540crush logs --follow
541```
542
543Want more logging? Run `crush` with the `--debug` flag, or enable it in the
544config:
545
546```json
547{
548  "$schema": "https://charm.land/crush.json",
549  "options": {
550    "debug": true,
551    "debug_lsp": true
552  }
553}
554```
555
556## Provider Auto-Updates
557
558By default, Crush automatically checks for the latest and greatest list of
559providers and models from [Catwalk](https://github.com/charmbracelet/catwalk),
560the open source Crush provider database. This means that when new providers and
561models are available, or when model metadata changes, Crush automatically
562updates your local configuration.
563
564### Disabling automatic provider updates
565
566For those with restricted internet access, or those who prefer to work in
567air-gapped environments, this might not be want you want, and this feature can
568be disabled.
569
570To disable automatic provider updates, set `disable_provider_auto_update` into
571your `crush.json` config:
572
573```json
574{
575  "$schema": "https://charm.land/crush.json",
576  "options": {
577    "disable_provider_auto_update": true
578  }
579}
580```
581
582Or set the `CRUSH_DISABLE_PROVIDER_AUTO_UPDATE` environment variable:
583
584```bash
585export CRUSH_DISABLE_PROVIDER_AUTO_UPDATE=1
586```
587
588### Manually updating providers
589
590Manually updating providers is possible with the `crush update-providers`
591command:
592
593```bash
594# Update providers remotely from Catwalk.
595crush update-providers
596
597# Update providers from a custom Catwalk base URL.
598crush update-providers https://example.com/
599
600# Update providers from a local file.
601crush update-providers /path/to/local-providers.json
602
603# Reset providers to the embedded version, embedded at crush at build time.
604crush update-providers embedded
605
606# For more info:
607crush update-providers --help
608```
609
610## Metrics
611
612Crush records pseudonymous usage metrics (tied to a device-specific hash),
613which maintainers rely on to inform development and support priorities. The
614metrics include solely usage metadata; prompts and responses are NEVER
615collected.
616
617Details on exactly what’s collected are in the source code ([here](https://github.com/charmbracelet/crush/tree/main/internal/event)
618and [here](https://github.com/charmbracelet/crush/blob/main/internal/llm/agent/event.go)).
619
620You can opt out of metrics collection at any time by setting the environment
621variable by setting the following in your environment:
622
623```bash
624export CRUSH_DISABLE_METRICS=1
625```
626
627Or by setting the following in your config:
628
629```json
630{
631  "options": {
632    "disable_metrics": true
633  }
634}
635```
636
637Crush also respects the [`DO_NOT_TRACK`](https://consoledonottrack.com)
638convention which can be enabled via `export DO_NOT_TRACK=1`.
639
640## A Note on Claude Max and GitHub Copilot
641
642Crush only supports model providers through official, compliant APIs. We do not
643support or endorse any methods that rely on personal Claude Max and GitHub
644Copilot accounts or OAuth workarounds, which violate Anthropic and
645Microsoft’s Terms of Service.
646
647We’re committed to building sustainable, trusted integrations with model
648providers. If you’re a provider interested in working with us,
649[reach out](mailto:vt100@charm.sh).
650
651## Contributing
652
653See the [contributing guide](https://github.com/charmbracelet/crush?tab=contributing-ov-file#contributing).
654
655## Whatcha think?
656
657We’d love to hear your thoughts on this project. Need help? We gotchu. You can find us on:
658
659- [Twitter](https://twitter.com/charmcli)
660- [Slack](https://charm.land/slack)
661- [Discord][discord]
662- [The Fediverse](https://mastodon.social/@charmcli)
663- [Bluesky](https://bsky.app/profile/charm.land)
664
665[discord]: https://charm.land/discord
666
667## License
668
669[FSL-1.1-MIT](https://github.com/charmbracelet/crush/raw/main/LICENSE.md)
670
671---
672
673Part of [Charm](https://charm.land).
674
675<a href="https://charm.land/"><img alt="The Charm logo" width="400" src="https://stuff.charm.sh/charm-banner-next.jpg" /></a>
676
677<!--prettier-ignore-->
678Charm热爱开源 • Charm loves open source