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 "lsp": {
143 "go": {
144 "command": "gopls"
145 },
146 "typescript": {
147 "command": "typescript-language-server",
148 "args": ["--stdio"]
149 },
150 "nix": {
151 "command": "nil"
152 }
153 }
154}
155```
156
157### MCPs
158
159Crush also supports Model Context Protocol (MCP) servers through three
160transport types: `stdio` for command-line servers, `http` for HTTP endpoints,
161and `sse` for Server-Sent Events. Environment variable expansion is supported
162using `$(echo $VAR)` syntax.
163
164```json
165{
166 "mcp": {
167 "filesystem": {
168 "type": "stdio",
169 "command": "node",
170 "args": ["/path/to/mcp-server.js"],
171 "env": {
172 "NODE_ENV": "production"
173 }
174 },
175 "github": {
176 "type": "http",
177 "url": "https://example.com/mcp/",
178 "headers": {
179 "Authorization": "$(echo Bearer $EXAMPLE_MCP_TOKEN)"
180 }
181 },
182 "streaming-service": {
183 "type": "sse",
184 "url": "https://example.com/mcp/sse",
185 "headers": {
186 "API-Key": "$(echo $API_KEY)"
187 }
188 }
189 }
190}
191```
192
193### Whitelisting Tools
194
195By default, Crush will ask you for permission before running tool calls. If
196you'd like, you can whitelist tools to be executed without prompting you for
197permissions. Use this with care.
198
199```json
200{
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 "providers": {
229 "deepseek": {
230 "type": "openai",
231 "base_url": "https://api.deepseek.com/v1",
232 "api_key": "$DEEPSEEK_API_KEY",
233 "models": [
234 {
235 "id": "deepseek-chat",
236 "name": "Deepseek V3",
237 "cost_per_1m_in": 0.27,
238 "cost_per_1m_out": 1.1,
239 "cost_per_1m_in_cached": 0.07,
240 "cost_per_1m_out_cached": 1.1,
241 "context_window": 64000,
242 "default_max_tokens": 5000
243 }
244 ]
245 }
246 }
247}
248```
249
250#### Anthropic-Compatible APIs
251
252Custom Anthropic-compatible providers follow this format:
253
254```json
255{
256 "providers": {
257 "custom-anthropic": {
258 "type": "anthropic",
259 "base_url": "https://api.anthropic.com/v1",
260 "api_key": "$ANTHROPIC_API_KEY",
261 "extra_headers": {
262 "anthropic-version": "2023-06-01"
263 },
264 "models": [
265 {
266 "id": "claude-sonnet-4-20250514",
267 "name": "Claude Sonnet 4",
268 "cost_per_1m_in": 3,
269 "cost_per_1m_out": 15,
270 "cost_per_1m_in_cached": 3.75,
271 "cost_per_1m_out_cached": 0.3,
272 "context_window": 200000,
273 "default_max_tokens": 50000,
274 "can_reason": true,
275 "supports_attachments": true
276 }
277 ]
278 }
279 }
280}
281```
282
283## Logging
284
285Sometimes you need to look at logs. Luckily, Crush logs all sorts of
286stuff. Logs are stored in `./.crush/logs/crush.log` relative to the project.
287
288The CLI also contains some helper commands to make perusing recent logs easier:
289
290```bash
291# Print the last 1000 lines
292crush logs
293
294# Print the last 500 lines
295crush logs --tail 500
296
297# Follow logs in real time
298crush logs --follow
299```
300
301Want more logging? Run `crush` with the `--debug` flag, or enable it in the
302config:
303
304```json
305{
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