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), FreeBSD, OpenBSD, and NetBSD
21
22## Installation
23
24Use a package manager:
25
26```bash
27# Homebrew
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 run github:numtide/nix-ai-tools#crush
38```
39
40<details>
41<summary><strong>Nix (NUR)</strong></summary>
42
43Crush is available via [NUR](https://github.com/nix-community/NUR) in `nur.repos.charmbracelet.crush`.
44
45You can also try out Crush via `nix-shell`:
46
47```bash
48# Add the NUR channel.
49nix-channel --add https://github.com/nix-community/NUR/archive/main.tar.gz nur
50nix-channel --update
51
52# Get Crush in a Nix shell.
53nix-shell -p '(import <nur> { pkgs = import <nixpkgs> {}; }).repos.charmbracelet.crush'
54```
55
56</details>
57
58<details>
59<summary><strong>Debian/Ubuntu</strong></summary>
60
61```bash
62sudo mkdir -p /etc/apt/keyrings
63curl -fsSL https://repo.charm.sh/apt/gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/charm.gpg
64echo "deb [signed-by=/etc/apt/keyrings/charm.gpg] https://repo.charm.sh/apt/ * *" | sudo tee /etc/apt/sources.list.d/charm.list
65sudo apt update && sudo apt install crush
66```
67
68</details>
69
70<details>
71<summary><strong>Fedora/RHEL</strong></summary>
72
73```bash
74echo '[charm]
75name=Charm
76baseurl=https://repo.charm.sh/yum/
77enabled=1
78gpgcheck=1
79gpgkey=https://repo.charm.sh/yum/gpg.key' | sudo tee /etc/yum.repos.d/charm.repo
80sudo yum install crush
81```
82
83</details>
84
85Or, download it:
86
87- [Packages][releases] are available in Debian and RPM formats
88- [Binaries][releases] are available for Linux, macOS, Windows, FreeBSD, OpenBSD, and NetBSD
89
90[releases]: https://github.com/charmbracelet/crush/releases
91
92Or just install it with Go:
93
94```
95go install github.com/charmbracelet/crush@latest
96```
97
98> [!WARNING]
99> Productivity may increase when using Crush and you may find yourself nerd
100> sniped when first using the application. If the symptoms persist, join the
101> [Discord][discord] and nerd snipe the rest of us.
102
103## Getting Started
104
105The quickest way to get started is to grab an API key for your preferred
106provider such as Anthropic, OpenAI, Groq, or OpenRouter and just start
107Crush. You'll be prompted to enter your API key.
108
109That said, you can also set environment variables for preferred providers.
110
111| Environment Variable | Provider |
112| -------------------------- | -------------------------------------------------- |
113| `ANTHROPIC_API_KEY` | Anthropic |
114| `OPENAI_API_KEY` | OpenAI |
115| `OPENROUTER_API_KEY` | OpenRouter |
116| `GEMINI_API_KEY` | Google Gemini |
117| `VERTEXAI_PROJECT` | Google Cloud VertexAI (Gemini) |
118| `VERTEXAI_LOCATION` | Google Cloud VertexAI (Gemini) |
119| `GROQ_API_KEY` | Groq |
120| `AWS_ACCESS_KEY_ID` | AWS Bedrock (Claude) |
121| `AWS_SECRET_ACCESS_KEY` | AWS Bedrock (Claude) |
122| `AWS_REGION` | AWS Bedrock (Claude) |
123| `AZURE_OPENAI_ENDPOINT` | Azure OpenAI models |
124| `AZURE_OPENAI_API_KEY` | Azure OpenAI models (optional when using Entra ID) |
125| `AZURE_OPENAI_API_VERSION` | Azure OpenAI models |
126
127### By the Way
128
129Is there a provider you’d like to see in Crush? Is there an existing model that needs an update?
130
131Crush’s default model listing is managed in [Catwalk](https://github.com/charmbracelet/catwalk), an community-supported, open source repository of Crush-compatible models, and you’re welcome to contribute.
132
133<a href="https://github.com/charmbracelet/catwalk"><img width="174" height="174" alt="Catwalk Badge" src="https://github.com/user-attachments/assets/95b49515-fe82-4409-b10d-5beb0873787d" /></a>
134
135## Configuration
136
137Crush runs great with no configuration. That said, if you do need or want to
138customize Crush, configuration can be added either local to the project itself,
139or globally, with the following priority:
140
1411. `./.crush.json`
1422. `./crush.json`
1433. `$HOME/.config/crush/crush.json`
144
145Configuration itself is stored as a JSON object:
146
147```json
148{
149 "this-setting": { }
150 "that-setting": { }
151}
152```
153
154### LSPs
155
156Crush can use LSPs for additional context to help inform its decisions, just
157like you would. LSPs can be added manually like so:
158
159```json
160{
161 "$schema": "https://charm.land/crush.json",
162 "lsp": {
163 "go": {
164 "command": "gopls"
165 },
166 "typescript": {
167 "command": "typescript-language-server",
168 "args": ["--stdio"]
169 },
170 "nix": {
171 "command": "nil"
172 }
173 }
174}
175```
176
177### MCPs
178
179Crush also supports Model Context Protocol (MCP) servers through three
180transport types: `stdio` for command-line servers, `http` for HTTP endpoints,
181and `sse` for Server-Sent Events. Environment variable expansion is supported
182using `$(echo $VAR)` syntax.
183
184```json
185{
186 "$schema": "https://charm.land/crush.json",
187 "mcp": {
188 "filesystem": {
189 "type": "stdio",
190 "command": "node",
191 "args": ["/path/to/mcp-server.js"],
192 "env": {
193 "NODE_ENV": "production"
194 }
195 },
196 "github": {
197 "type": "http",
198 "url": "https://example.com/mcp/",
199 "headers": {
200 "Authorization": "$(echo Bearer $EXAMPLE_MCP_TOKEN)"
201 }
202 },
203 "streaming-service": {
204 "type": "sse",
205 "url": "https://example.com/mcp/sse",
206 "headers": {
207 "API-Key": "$(echo $API_KEY)"
208 }
209 }
210 }
211}
212```
213
214### Ignoring Files
215
216Crush respects `.gitignore` files by default, but you can also create a
217`.crushignore` file to specify additional files and directories that Crush
218should ignore. This is useful for excluding files that you want in version
219control but don't want Crush to consider when providing context.
220
221The `.crushignore` file uses the same syntax as `.gitignore` and can be placed
222in the root of your project or in subdirectories.
223
224### Whitelisting Tools
225
226By default, Crush will ask you for permission before running tool calls. If
227you'd like, you can whitelist tools to be executed without prompting you for
228permissions. Use this with care.
229
230```json
231{
232 "$schema": "https://charm.land/crush.json",
233 "permissions": {
234 "allowed_tools": [
235 "view",
236 "ls",
237 "grep",
238 "edit",
239 "mcp_context7_get-library-doc"
240 ]
241 }
242}
243```
244
245You can also skip all permission prompts entirely by running Crush with the
246`--yolo` flag. Be very, very careful with this feature.
247
248### Custom Providers
249
250Crush supports custom provider configurations for both OpenAI-compatible and
251Anthropic-compatible APIs.
252
253#### OpenAI-Compatible APIs
254
255Here’s an example configuration for Deepseek, which uses an OpenAI-compatible
256API. Don't forget to set `DEEPSEEK_API_KEY` in your environment.
257
258```json
259{
260 "$schema": "https://charm.land/crush.json",
261 "providers": {
262 "deepseek": {
263 "type": "openai",
264 "base_url": "https://api.deepseek.com/v1",
265 "api_key": "$DEEPSEEK_API_KEY",
266 "models": [
267 {
268 "id": "deepseek-chat",
269 "name": "Deepseek V3",
270 "cost_per_1m_in": 0.27,
271 "cost_per_1m_out": 1.1,
272 "cost_per_1m_in_cached": 0.07,
273 "cost_per_1m_out_cached": 1.1,
274 "context_window": 64000,
275 "default_max_tokens": 5000
276 }
277 ]
278 }
279 }
280}
281```
282
283#### Anthropic-Compatible APIs
284
285Custom Anthropic-compatible providers follow this format:
286
287```json
288{
289 "$schema": "https://charm.land/crush.json",
290 "providers": {
291 "custom-anthropic": {
292 "type": "anthropic",
293 "base_url": "https://api.anthropic.com/v1",
294 "api_key": "$ANTHROPIC_API_KEY",
295 "extra_headers": {
296 "anthropic-version": "2023-06-01"
297 },
298 "models": [
299 {
300 "id": "claude-sonnet-4-20250514",
301 "name": "Claude Sonnet 4",
302 "cost_per_1m_in": 3,
303 "cost_per_1m_out": 15,
304 "cost_per_1m_in_cached": 3.75,
305 "cost_per_1m_out_cached": 0.3,
306 "context_window": 200000,
307 "default_max_tokens": 50000,
308 "can_reason": true,
309 "supports_attachments": true
310 }
311 ]
312 }
313 }
314}
315```
316
317## Logging
318
319Sometimes you need to look at logs. Luckily, Crush logs all sorts of
320stuff. Logs are stored in `./.crush/logs/crush.log` relative to the project.
321
322The CLI also contains some helper commands to make perusing recent logs easier:
323
324```bash
325# Print the last 1000 lines
326crush logs
327
328# Print the last 500 lines
329crush logs --tail 500
330
331# Follow logs in real time
332crush logs --follow
333```
334
335Want more logging? Run `crush` with the `--debug` flag, or enable it in the
336config:
337
338```json
339{
340 "$schema": "https://charm.land/crush.json",
341 "options": {
342 "debug": true,
343 "debug_lsp": true
344 }
345}
346```
347
348## Whatcha think?
349
350We’d love to hear your thoughts on this project. Need help? We gotchu. You can find us on:
351
352- [Twitter](https://twitter.com/charmcli)
353- [Discord][discord]
354- [Slack](https://charm.land/slack)
355- [The Fediverse](https://mastodon.social/@charmcli)
356
357[discord]: https://charm.land/discord
358
359## License
360
361[FSL-1.1-MIT](https://github.com/charmbracelet/crush/raw/main/LICENSE)
362
363---
364
365Part of [Charm](https://charm.land).
366
367<a href="https://charm.land/"><img alt="The Charm logo" width="400" src="https://stuff.charm.sh/charm-banner-next.jpg" /></a>
368
369<!--prettier-ignore-->
370Charm热爱开源 • Charm loves open source