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