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