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| `GEMINI_API_KEY` | Google Gemini |
116| `VERTEXAI_PROJECT` | Google Cloud VertexAI (Gemini) |
117| `VERTEXAI_LOCATION` | Google Cloud VertexAI (Gemini) |
118| `GROQ_API_KEY` | Groq |
119| `AWS_ACCESS_KEY_ID` | AWS Bedrock (Claude) |
120| `AWS_SECRET_ACCESS_KEY` | AWS Bedrock (Claude) |
121| `AWS_REGION` | AWS Bedrock (Claude) |
122| `AZURE_OPENAI_ENDPOINT` | Azure OpenAI models |
123| `AZURE_OPENAI_API_KEY` | Azure OpenAI models (optional when using Entra ID) |
124| `AZURE_OPENAI_API_VERSION` | Azure OpenAI models |
125
126### By the Way
127
128Is there a provider you’d like to see in Crush? Is there an existing model that needs an update?
129
130Crush’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.
131
132<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>
133
134## Configuration
135
136Crush runs great with no configuration. That said, if you do need or want to
137customize Crush, configuration can be added either local to the project itself,
138or globally, with the following priority:
139
1401. `./.crush.json`
1412. `./crush.json`
1423. `$HOME/.config/crush/crush.json`
143
144Configuration itself is stored as a JSON object:
145
146```json
147{
148 "this-setting": { }
149 "that-setting": { }
150}
151```
152
153### LSPs
154
155Crush can use LSPs for additional context to help inform its decisions, just
156like you would. LSPs can be added manually like so:
157
158```json
159{
160 "$schema": "https://charm.land/crush.json",
161 "lsp": {
162 "go": {
163 "command": "gopls"
164 },
165 "typescript": {
166 "command": "typescript-language-server",
167 "args": ["--stdio"]
168 },
169 "nix": {
170 "command": "nil"
171 }
172 }
173}
174```
175
176### MCPs
177
178Crush also supports Model Context Protocol (MCP) servers through three
179transport types: `stdio` for command-line servers, `http` for HTTP endpoints,
180and `sse` for Server-Sent Events. Environment variable expansion is supported
181using `$(echo $VAR)` syntax.
182
183```json
184{
185 "$schema": "https://charm.land/crush.json",
186 "mcp": {
187 "filesystem": {
188 "type": "stdio",
189 "command": "node",
190 "args": ["/path/to/mcp-server.js"],
191 "env": {
192 "NODE_ENV": "production"
193 }
194 },
195 "github": {
196 "type": "http",
197 "url": "https://example.com/mcp/",
198 "headers": {
199 "Authorization": "$(echo Bearer $EXAMPLE_MCP_TOKEN)"
200 }
201 },
202 "streaming-service": {
203 "type": "sse",
204 "url": "https://example.com/mcp/sse",
205 "headers": {
206 "API-Key": "$(echo $API_KEY)"
207 }
208 }
209 }
210}
211```
212
213### Ignoring Files
214
215Crush respects `.gitignore` files by default, but you can also create a
216`.crushignore` file to specify additional files and directories that Crush
217should ignore. This is useful for excluding files that you want in version
218control but don't want Crush to consider when providing context.
219
220The `.crushignore` file uses the same syntax as `.gitignore` and can be placed
221in the root of your project or in subdirectories.
222
223### Whitelisting Tools
224
225By default, Crush will ask you for permission before running tool calls. If
226you'd like, you can whitelist tools to be executed without prompting you for
227permissions. Use this with care.
228
229```json
230{
231 "$schema": "https://charm.land/crush.json",
232 "permissions": {
233 "allowed_tools": [
234 "view",
235 "ls",
236 "grep",
237 "edit",
238 "mcp_context7_get-library-doc"
239 ]
240 }
241}
242```
243
244You can also skip all permission prompts entirely by running Crush with the
245`--yolo` flag. Be very, very careful with this feature.
246
247### Custom Providers
248
249Crush supports custom provider configurations for both OpenAI-compatible and
250Anthropic-compatible APIs.
251
252#### OpenAI-Compatible APIs
253
254Here’s an example configuration for Deepseek, which uses an OpenAI-compatible
255API. Don't forget to set `DEEPSEEK_API_KEY` in your environment.
256
257```json
258{
259 "$schema": "https://charm.land/crush.json",
260 "providers": {
261 "deepseek": {
262 "type": "openai",
263 "base_url": "https://api.deepseek.com/v1",
264 "api_key": "$DEEPSEEK_API_KEY",
265 "models": [
266 {
267 "id": "deepseek-chat",
268 "name": "Deepseek V3",
269 "cost_per_1m_in": 0.27,
270 "cost_per_1m_out": 1.1,
271 "cost_per_1m_in_cached": 0.07,
272 "cost_per_1m_out_cached": 1.1,
273 "context_window": 64000,
274 "default_max_tokens": 5000
275 }
276 ]
277 }
278 }
279}
280```
281
282#### Anthropic-Compatible APIs
283
284Custom Anthropic-compatible providers follow this format:
285
286```json
287{
288 "$schema": "https://charm.land/crush.json",
289 "providers": {
290 "custom-anthropic": {
291 "type": "anthropic",
292 "base_url": "https://api.anthropic.com/v1",
293 "api_key": "$ANTHROPIC_API_KEY",
294 "extra_headers": {
295 "anthropic-version": "2023-06-01"
296 },
297 "models": [
298 {
299 "id": "claude-sonnet-4-20250514",
300 "name": "Claude Sonnet 4",
301 "cost_per_1m_in": 3,
302 "cost_per_1m_out": 15,
303 "cost_per_1m_in_cached": 3.75,
304 "cost_per_1m_out_cached": 0.3,
305 "context_window": 200000,
306 "default_max_tokens": 50000,
307 "can_reason": true,
308 "supports_attachments": true
309 }
310 ]
311 }
312 }
313}
314```
315
316## Logging
317
318Sometimes you need to look at logs. Luckily, Crush logs all sorts of
319stuff. Logs are stored in `./.crush/logs/crush.log` relative to the project.
320
321The CLI also contains some helper commands to make perusing recent logs easier:
322
323```bash
324# Print the last 1000 lines
325crush logs
326
327# Print the last 500 lines
328crush logs --tail 500
329
330# Follow logs in real time
331crush logs --follow
332```
333
334Want more logging? Run `crush` with the `--debug` flag, or enable it in the
335config:
336
337```json
338{
339 "$schema": "https://charm.land/crush.json",
340 "options": {
341 "debug": true,
342 "debug_lsp": true
343 }
344}
345```
346
347## Whatcha think?
348
349We’d love to hear your thoughts on this project. Need help? We gotchu. You can find us on:
350
351- [Twitter](https://twitter.com/charmcli)
352- [Discord][discord]
353- [Slack](https://charm.land/slack)
354- [The Fediverse](https://mastodon.social/@charmcli)
355
356[discord]: https://charm.land/discord
357
358## License
359
360[FSL-1.1-MIT](https://github.com/charmbracelet/crush/raw/main/LICENSE)
361
362---
363
364Part of [Charm](https://charm.land).
365
366<a href="https://charm.land/"><img alt="The Charm logo" width="400" src="https://stuff.charm.sh/charm-banner-next.jpg" /></a>
367
368<!--prettier-ignore-->
369Charm热爱开源 • Charm loves open source