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