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