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