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