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/workflows/build/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
 40<details>
 41<summary><strong>Nix (NUR)</strong></summary>
 42
 43Crush is available via [NUR](https://github.com/nix-community/NUR) in `nur.repos.charmbracelet.crush`.
 44
 45You can also try out Crush via `nix-shell`:
 46
 47```bash
 48# Add the NUR channel.
 49nix-channel --add https://github.com/nix-community/NUR/archive/main.tar.gz nur
 50nix-channel --update
 51
 52# Get Crush in a Nix shell.
 53nix-shell -p '(import <nur> { pkgs = import <nixpkgs> {}; }).repos.charmbracelet.crush'
 54```
 55
 56</details>
 57
 58<details>
 59<summary><strong>Debian/Ubuntu</strong></summary>
 60
 61```bash
 62sudo mkdir -p /etc/apt/keyrings
 63curl -fsSL https://repo.charm.sh/apt/gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/charm.gpg
 64echo "deb [signed-by=/etc/apt/keyrings/charm.gpg] https://repo.charm.sh/apt/ * *" | sudo tee /etc/apt/sources.list.d/charm.list
 65sudo apt update && sudo apt install crush
 66```
 67
 68</details>
 69
 70<details>
 71<summary><strong>Fedora/RHEL</strong></summary>
 72
 73```bash
 74echo '[charm]
 75name=Charm
 76baseurl=https://repo.charm.sh/yum/
 77enabled=1
 78gpgcheck=1
 79gpgkey=https://repo.charm.sh/yum/gpg.key' | sudo tee /etc/yum.repos.d/charm.repo
 80sudo yum install crush
 81```
 82
 83</details>
 84
 85Or, download it:
 86
 87- [Packages][releases] are available in Debian and RPM formats
 88- [Binaries][releases] are available for Linux, macOS, Windows, FreeBSD, OpenBSD, and NetBSD
 89
 90[releases]: https://github.com/charmbracelet/crush/releases
 91
 92Or just install it with Go:
 93
 94```
 95go install github.com/charmbracelet/crush@latest
 96```
 97
 98> [!WARNING]
 99> Productivity may increase when using Crush and you may find yourself nerd
100> sniped when first using the application. If the symptoms persist, join the
101> [Discord][discord] and nerd snipe the rest of us.
102
103## Getting Started
104
105The quickest way to get started is to grab an API key for your preferred
106provider such as Anthropic, OpenAI, Groq, or OpenRouter and just start
107Crush. You'll be prompted to enter your API key.
108
109That said, you can also set environment variables for preferred providers.
110
111| Environment Variable       | Provider                                           |
112| -------------------------- | -------------------------------------------------- |
113| `ANTHROPIC_API_KEY`        | Anthropic                                          |
114| `OPENAI_API_KEY`           | OpenAI                                             |
115| `OPENROUTER_API_KEY`       | OpenRouter                                         |
116| `GEMINI_API_KEY`           | Google Gemini                                      |
117| `VERTEXAI_PROJECT`         | Google Cloud VertexAI (Gemini)                     |
118| `VERTEXAI_LOCATION`        | Google Cloud VertexAI (Gemini)                     |
119| `GROQ_API_KEY`             | Groq                                               |
120| `AWS_ACCESS_KEY_ID`        | AWS Bedrock (Claude)                               |
121| `AWS_SECRET_ACCESS_KEY`    | AWS Bedrock (Claude)                               |
122| `AWS_REGION`               | AWS Bedrock (Claude)                               |
123| `AZURE_OPENAI_ENDPOINT`    | Azure OpenAI models                                |
124| `AZURE_OPENAI_API_KEY`     | Azure OpenAI models (optional when using Entra ID) |
125| `AZURE_OPENAI_API_VERSION` | Azure OpenAI models                                |
126
127### By the Way
128
129Is there a provider you’d like to see in Crush? Is there an existing model that needs an update?
130
131Crush’s default model listing is managed in [Catwalk](https://github.com/charmbracelet/catwalk), an community-supported, open source repository of Crush-compatible models, and you’re welcome to contribute.
132
133<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>
134
135## Configuration
136
137Crush runs great with no configuration. That said, if you do need or want to
138customize Crush, configuration can be added either local to the project itself,
139or globally, with the following priority:
140
1411. `.crush.json`
1422. `crush.json`
1433. `$HOME/.config/crush/crush.json` (Windows: `%USERPROFILE%\AppData\Local\crush\crush.json`)
144
145Configuration itself is stored as a JSON object:
146
147```json
148{
149   "this-setting": {"this": "that"},
150   "that-setting": ["ceci", "cela"]
151}
152```
153
154As an additional note, Crush also stores ephemeral data, such as application state, in one additional location:
155
156```bash
157# Unix
158$HOME/.local/shared/crush/crush.json
159
160# Windows
161%LOCALAPPDATA%\crush\crush.json
162```
163
164### LSPs
165
166Crush can use LSPs for additional context to help inform its decisions, just
167like you would. LSPs can be added manually like so:
168
169```json
170{
171  "$schema": "https://charm.land/crush.json",
172  "lsp": {
173    "go": {
174      "command": "gopls"
175    },
176    "typescript": {
177      "command": "typescript-language-server",
178      "args": ["--stdio"]
179    },
180    "nix": {
181      "command": "nil"
182    }
183  }
184}
185```
186
187### MCPs
188
189Crush also supports Model Context Protocol (MCP) servers through three
190transport types: `stdio` for command-line servers, `http` for HTTP endpoints,
191and `sse` for Server-Sent Events. Environment variable expansion is supported
192using `$(echo $VAR)` syntax.
193
194```json
195{
196  "$schema": "https://charm.land/crush.json",
197  "mcp": {
198    "filesystem": {
199      "type": "stdio",
200      "command": "node",
201      "args": ["/path/to/mcp-server.js"],
202      "env": {
203        "NODE_ENV": "production"
204      }
205    },
206    "github": {
207      "type": "http",
208      "url": "https://example.com/mcp/",
209      "headers": {
210        "Authorization": "$(echo Bearer $EXAMPLE_MCP_TOKEN)"
211      }
212    },
213    "streaming-service": {
214      "type": "sse",
215      "url": "https://example.com/mcp/sse",
216      "headers": {
217        "API-Key": "$(echo $API_KEY)"
218      }
219    }
220  }
221}
222```
223
224### Ignoring Files
225
226Crush respects `.gitignore` files by default, but you can also create a
227`.crushignore` file to specify additional files and directories that Crush
228should ignore. This is useful for excluding files that you want in version
229control but don't want Crush to consider when providing context.
230
231The `.crushignore` file uses the same syntax as `.gitignore` and can be placed
232in the root of your project or in subdirectories.
233
234### Allowing Tools
235
236By default, Crush will ask you for permission before running tool calls. If
237you'd like, you can allow tools to be executed without prompting you for
238permissions. Use this with care.
239
240```json
241{
242  "$schema": "https://charm.land/crush.json",
243  "permissions": {
244    "allowed_tools": [
245      "view",
246      "ls",
247      "grep",
248      "edit",
249      "mcp_context7_get-library-doc"
250    ]
251  }
252}
253```
254
255You can also skip all permission prompts entirely by running Crush with the
256`--yolo` flag. Be very, very careful with this feature.
257
258### Local Models
259
260Local models can also be configured via OpenAI-compatible API. Here are two common examples:
261
262#### Ollama
263
264```json
265{
266  "providers": {
267    "ollama": {
268      "name": "Ollama",
269      "base_url": "http://localhost:11434/v1/",
270      "type": "openai",
271      "models": [
272        {
273          "name": "Qwen 3 30B",
274          "id": "qwen3:30b",
275          "context_window": 256000,
276          "default_max_tokens": 20000
277        }
278      ]
279    }
280}
281```
282
283#### LM Studio
284
285```json
286{
287  "providers": {
288    "lmstudio": {
289      "name": "LM Studio",
290      "base_url": "http://localhost:1234/v1/",
291      "type": "openai",
292      "models": [
293        {
294          "name": "Qwen 3 30B",
295          "id": "qwen/qwen3-30b-a3b-2507",
296          "context_window": 256000,
297          "default_max_tokens": 20000
298        }
299      ]
300    }
301  }
302}
303```
304
305### Custom Providers
306
307Crush supports custom provider configurations for both OpenAI-compatible and
308Anthropic-compatible APIs.
309
310#### OpenAI-Compatible APIs
311
312Here’s an example configuration for Deepseek, which uses an OpenAI-compatible
313API. Don't forget to set `DEEPSEEK_API_KEY` in your environment.
314
315```json
316{
317  "$schema": "https://charm.land/crush.json",
318  "providers": {
319    "deepseek": {
320      "type": "openai",
321      "base_url": "https://api.deepseek.com/v1",
322      "api_key": "$DEEPSEEK_API_KEY",
323      "models": [
324        {
325          "id": "deepseek-chat",
326          "name": "Deepseek V3",
327          "cost_per_1m_in": 0.27,
328          "cost_per_1m_out": 1.1,
329          "cost_per_1m_in_cached": 0.07,
330          "cost_per_1m_out_cached": 1.1,
331          "context_window": 64000,
332          "default_max_tokens": 5000
333        }
334      ]
335    }
336  }
337}
338```
339
340#### Anthropic-Compatible APIs
341
342Custom Anthropic-compatible providers follow this format:
343
344```json
345{
346  "$schema": "https://charm.land/crush.json",
347  "providers": {
348    "custom-anthropic": {
349      "type": "anthropic",
350      "base_url": "https://api.anthropic.com/v1",
351      "api_key": "$ANTHROPIC_API_KEY",
352      "extra_headers": {
353        "anthropic-version": "2023-06-01"
354      },
355      "models": [
356        {
357          "id": "claude-sonnet-4-20250514",
358          "name": "Claude Sonnet 4",
359          "cost_per_1m_in": 3,
360          "cost_per_1m_out": 15,
361          "cost_per_1m_in_cached": 3.75,
362          "cost_per_1m_out_cached": 0.3,
363          "context_window": 200000,
364          "default_max_tokens": 50000,
365          "can_reason": true,
366          "supports_attachments": true
367        }
368      ]
369    }
370  }
371}
372```
373
374## Logging
375
376Sometimes you need to look at logs. Luckily, Crush logs all sorts of
377stuff. Logs are stored in `./.crush/logs/crush.log` relative to the project.
378
379The CLI also contains some helper commands to make perusing recent logs easier:
380
381```bash
382# Print the last 1000 lines
383crush logs
384
385# Print the last 500 lines
386crush logs --tail 500
387
388# Follow logs in real time
389crush logs --follow
390```
391
392Want more logging? Run `crush` with the `--debug` flag, or enable it in the
393config:
394
395```json
396{
397  "$schema": "https://charm.land/crush.json",
398  "options": {
399    "debug": true,
400    "debug_lsp": true
401  }
402}
403```
404
405## Whatcha think?
406
407We’d love to hear your thoughts on this project. Need help? We gotchu. You can find us on:
408
409- [Twitter](https://twitter.com/charmcli)
410- [Discord][discord]
411- [Slack](https://charm.land/slack)
412- [The Fediverse](https://mastodon.social/@charmcli)
413
414[discord]: https://charm.land/discord
415
416## License
417
418[FSL-1.1-MIT](https://github.com/charmbracelet/crush/raw/main/LICENSE)
419
420---
421
422Part of [Charm](https://charm.land).
423
424<a href="https://charm.land/"><img alt="The Charm logo" width="400" src="https://stuff.charm.sh/charm-banner-next.jpg" /></a>
425
426<!--prettier-ignore-->
427Charm热爱开源 • Charm loves open source