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), and FreeBSD
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
37<details>
38<summary><strong>Nix</strong></summary>
39
40Crush is available via [NUR](https://github.com/nix-community/NUR) in `nur.repos.charmbracelet.crush`.
41
42You can also try out Crush via `nix-shell`:
43
44```bash
45# Add the NUR channel.
46nix-channel --add https://github.com/nix-community/NUR/archive/main.tar.gz nur
47nix-channel --update
48
49# Get Crush in a Nix shell.
50nix-shell -p '(import <nur> { pkgs = import <nixpkgs> {}; }).repos.charmbracelet.crush'
51```
52
53</details>
54
55<details>
56<summary><strong>Debian/Ubuntu</strong></summary>
57
58```bash
59sudo mkdir -p /etc/apt/keyrings
60curl -fsSL https://repo.charm.sh/apt/gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/charm.gpg
61echo "deb [signed-by=/etc/apt/keyrings/charm.gpg] https://repo.charm.sh/apt/ * *" | sudo tee /etc/apt/sources.list.d/charm.list
62sudo apt update && sudo apt install crush
63```
64
65</details>
66
67<details>
68<summary><strong>Fedora/RHEL</strong></summary>
69
70```bash
71echo '[charm]
72name=Charm
73baseurl=https://repo.charm.sh/yum/
74enabled=1
75gpgcheck=1
76gpgkey=https://repo.charm.sh/yum/gpg.key' | sudo tee /etc/yum.repos.d/charm.repo
77sudo yum install crush
78```
79
80</details>
81
82Or, download it:
83
84- [Packages][releases] are available in Debian and RPM formats
85- [Binaries][releases] are available for Linux, macOS, Windows, FreeBSD, OpenBSD, and NetBSD
86
87[releases]: https://github.com/charmbracelet/crush/releases
88
89Or just install it with Go:
90
91```
92go install github.com/charmbracelet/crush@latest
93```
94
95> [!WARNING]
96> Productivity may increase when using Crush and you may find yourself nerd
97> sniped when first using the application. If the symptoms persist, join the
98> [Discord][discord] and nerd snipe the rest of us.
99
100## Getting Started
101
102The quickest way to get started is to grab an API key for your preferred
103provider such as Anthropic, OpenAI, Groq, or OpenRouter and just start
104Crush. You'll be prompted to enter your API key.
105
106That said, you can also set environment variables for preferred providers.
107
108<details>
109<summary><strong>Supported Environment Variables</strong></summary>
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</details>
127
128### By the Way
129
130Is there a provider you’d like to see in Crush? Is there an existing model that needs an update?
131
132Crush’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.
133
134<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>
135
136## Configuration
137
138Crush runs great with no configuration. That said, if you do need or want to
139customize Crush, configuration can be added either local to the project itself,
140or globally, with the following priority:
141
1421. `./.crush.json`
1432. `./crush.json`
1443. `$HOME/.config/crush/crush.json`
145
146Configuration itself is stored as a JSON object:
147
148```json
149{
150 "this-setting": { }
151 "that-setting": { }
152}
153```
154
155### LSPs
156
157Crush can use LSPs for additional context to help inform its decisions, just
158like you would. LSPs can be added manually like so:
159
160```json
161{
162 "$schema": "https://charm.land/crush.json",
163 "lsp": {
164 "go": {
165 "command": "gopls"
166 },
167 "typescript": {
168 "command": "typescript-language-server",
169 "args": ["--stdio"]
170 },
171 "nix": {
172 "command": "nil"
173 }
174 }
175}
176```
177
178### MCPs
179
180Crush also supports Model Context Protocol (MCP) servers through three
181transport types: `stdio` for command-line servers, `http` for HTTP endpoints,
182and `sse` for Server-Sent Events. Environment variable expansion is supported
183using `$(echo $VAR)` syntax.
184
185```json
186{
187 "$schema": "https://charm.land/crush.json",
188 "mcp": {
189 "filesystem": {
190 "type": "stdio",
191 "command": "node",
192 "args": ["/path/to/mcp-server.js"],
193 "env": {
194 "NODE_ENV": "production"
195 }
196 },
197 "github": {
198 "type": "http",
199 "url": "https://example.com/mcp/",
200 "headers": {
201 "Authorization": "$(echo Bearer $EXAMPLE_MCP_TOKEN)"
202 }
203 },
204 "streaming-service": {
205 "type": "sse",
206 "url": "https://example.com/mcp/sse",
207 "headers": {
208 "API-Key": "$(echo $API_KEY)"
209 }
210 }
211 }
212}
213```
214
215### Whitelisting Tools
216
217By default, Crush will ask you for permission before running tool calls. If
218you'd like, you can whitelist tools to be executed without prompting you for
219permissions. Use this with care.
220
221```json
222{
223 "$schema": "https://charm.land/crush.json",
224 "permissions": {
225 "allowed_tools": [
226 "view",
227 "ls",
228 "grep",
229 "edit",
230 "mcp_context7_get-library-doc"
231 ]
232 }
233}
234```
235
236You can also skip all permission prompts entirely by running Crush with the
237`--yolo` flag. Be very, very careful with this feature.
238
239### Custom Providers
240
241Crush supports custom provider configurations for both OpenAI-compatible and
242Anthropic-compatible APIs.
243
244#### OpenAI-Compatible APIs
245
246Here’s an example configuration for Deepseek, which uses an OpenAI-compatible
247API. Don't forget to set `DEEPSEEK_API_KEY` in your environment.
248
249```json
250{
251 "$schema": "https://charm.land/crush.json",
252 "providers": {
253 "deepseek": {
254 "type": "openai",
255 "base_url": "https://api.deepseek.com/v1",
256 "api_key": "$DEEPSEEK_API_KEY",
257 "models": [
258 {
259 "id": "deepseek-chat",
260 "name": "Deepseek V3",
261 "cost_per_1m_in": 0.27,
262 "cost_per_1m_out": 1.1,
263 "cost_per_1m_in_cached": 0.07,
264 "cost_per_1m_out_cached": 1.1,
265 "context_window": 64000,
266 "default_max_tokens": 5000
267 }
268 ]
269 }
270 }
271}
272```
273
274#### Anthropic-Compatible APIs
275
276Custom Anthropic-compatible providers follow this format:
277
278```json
279{
280 "$schema": "https://charm.land/crush.json",
281 "providers": {
282 "custom-anthropic": {
283 "type": "anthropic",
284 "base_url": "https://api.anthropic.com/v1",
285 "api_key": "$ANTHROPIC_API_KEY",
286 "extra_headers": {
287 "anthropic-version": "2023-06-01"
288 },
289 "models": [
290 {
291 "id": "claude-sonnet-4-20250514",
292 "name": "Claude Sonnet 4",
293 "cost_per_1m_in": 3,
294 "cost_per_1m_out": 15,
295 "cost_per_1m_in_cached": 3.75,
296 "cost_per_1m_out_cached": 0.3,
297 "context_window": 200000,
298 "default_max_tokens": 50000,
299 "can_reason": true,
300 "supports_attachments": true
301 }
302 ]
303 }
304 }
305}
306```
307
308## Logging
309
310Sometimes you need to look at logs. Luckily, Crush logs all sorts of
311stuff. Logs are stored in `./.crush/logs/crush.log` relative to the project.
312
313The CLI also contains some helper commands to make perusing recent logs easier:
314
315```bash
316# Print the last 1000 lines
317crush logs
318
319# Print the last 500 lines
320crush logs --tail 500
321
322# Follow logs in real time
323crush logs --follow
324```
325
326Want more logging? Run `crush` with the `--debug` flag, or enable it in the
327config:
328
329```json
330{
331 "$schema": "https://charm.land/crush.json",
332 "options": {
333 "debug": true,
334 "debug_lsp": true
335 }
336}
337```
338
339## Whatcha think?
340
341We’d love to hear your thoughts on this project. Need help? We gotchu. You can find us on:
342
343- [Twitter](https://twitter.com/charmcli)
344- [Discord][discord]
345- [Slack](https://charm.land/slack)
346- [The Fediverse](https://mastodon.social/@charmcli)
347
348[discord]: https://charm.land/discord
349
350## License
351
352[FSL-1.1-MIT](https://github.com/charmbracelet/crush/raw/main/LICENSE)
353
354---
355
356Part of [Charm](https://charm.land).
357
358<a href="https://charm.land/"><img alt="The Charm logo" width="400" src="https://stuff.charm.sh/charm-banner-next.jpg" /></a>
359
360<!--prettier-ignore-->
361Charm热爱开源 • Charm loves open source