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### Whitelisting Tools
214
215By default, Crush will ask you for permission before running tool calls. If
216you'd like, you can whitelist tools to be executed without prompting you for
217permissions. Use this with care.
218
219```json
220{
221 "$schema": "https://charm.land/crush.json",
222 "permissions": {
223 "allowed_tools": [
224 "view",
225 "ls",
226 "grep",
227 "edit",
228 "mcp_context7_get-library-doc"
229 ]
230 }
231}
232```
233
234You can also skip all permission prompts entirely by running Crush with the
235`--yolo` flag. Be very, very careful with this feature.
236
237### Custom Providers
238
239Crush supports custom provider configurations for both OpenAI-compatible and
240Anthropic-compatible APIs.
241
242#### OpenAI-Compatible APIs
243
244Here’s an example configuration for Deepseek, which uses an OpenAI-compatible
245API. Don't forget to set `DEEPSEEK_API_KEY` in your environment.
246
247```json
248{
249 "$schema": "https://charm.land/crush.json",
250 "providers": {
251 "deepseek": {
252 "type": "openai",
253 "base_url": "https://api.deepseek.com/v1",
254 "api_key": "$DEEPSEEK_API_KEY",
255 "models": [
256 {
257 "id": "deepseek-chat",
258 "name": "Deepseek V3",
259 "cost_per_1m_in": 0.27,
260 "cost_per_1m_out": 1.1,
261 "cost_per_1m_in_cached": 0.07,
262 "cost_per_1m_out_cached": 1.1,
263 "context_window": 64000,
264 "default_max_tokens": 5000
265 }
266 ]
267 }
268 }
269}
270```
271
272#### Anthropic-Compatible APIs
273
274Custom Anthropic-compatible providers follow this format:
275
276```json
277{
278 "$schema": "https://charm.land/crush.json",
279 "providers": {
280 "custom-anthropic": {
281 "type": "anthropic",
282 "base_url": "https://api.anthropic.com/v1",
283 "api_key": "$ANTHROPIC_API_KEY",
284 "extra_headers": {
285 "anthropic-version": "2023-06-01"
286 },
287 "models": [
288 {
289 "id": "claude-sonnet-4-20250514",
290 "name": "Claude Sonnet 4",
291 "cost_per_1m_in": 3,
292 "cost_per_1m_out": 15,
293 "cost_per_1m_in_cached": 3.75,
294 "cost_per_1m_out_cached": 0.3,
295 "context_window": 200000,
296 "default_max_tokens": 50000,
297 "can_reason": true,
298 "supports_attachments": true
299 }
300 ]
301 }
302 }
303}
304```
305
306## Logging
307
308Sometimes you need to look at logs. Luckily, Crush logs all sorts of
309stuff. Logs are stored in `./.crush/logs/crush.log` relative to the project.
310
311The CLI also contains some helper commands to make perusing recent logs easier:
312
313```bash
314# Print the last 1000 lines
315crush logs
316
317# Print the last 500 lines
318crush logs --tail 500
319
320# Follow logs in real time
321crush logs --follow
322```
323
324Want more logging? Run `crush` with the `--debug` flag, or enable it in the
325config:
326
327```json
328{
329 "$schema": "https://charm.land/crush.json",
330 "options": {
331 "debug": true,
332 "debug_lsp": true
333 }
334}
335```
336
337## Whatcha think?
338
339We’d love to hear your thoughts on this project. Need help? We gotchu. You can find us on:
340
341- [Twitter](https://twitter.com/charmcli)
342- [Discord][discord]
343- [Slack](https://charm.land/slack)
344- [The Fediverse](https://mastodon.social/@charmcli)
345
346[discord]: https://charm.land/discord
347
348## License
349
350[FSL-1.1-MIT](https://github.com/charmbracelet/crush/raw/main/LICENSE)
351
352---
353
354Part of [Charm](https://charm.land).
355
356<a href="https://charm.land/"><img alt="The Charm logo" width="400" src="https://stuff.charm.sh/charm-banner-next.jpg" /></a>
357
358<!--prettier-ignore-->
359Charm热爱开源 • Charm loves open source