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