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