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