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