@@ -1,60 +1,101 @@
1−> [!WARNING]
2−> 🚧 This is a pre-release under heavy, active development. Things are still in flux but we’re excited to share early progress.
3−
41# Crush
52
63<p>
7− <img width="450" alt="Charm Crush Art" src="https://github.com/user-attachments/assets/9ab4c30c-9327-46b6-a722-3ad0e20f6976" /><br>
4+ <img width="450" alt="Charm Crush Art" src="https://github.com/user-attachments/assets/4cd517be-476b-4a78-971c-810a0b1af3f6" /><br>
85 <a href="https://github.com/charmbracelet/crush/releases"><img src="https://img.shields.io/github/release/charmbracelet/crush" alt="Latest Release"></a>
96 <a href="https://github.com/charmbracelet/crush/actions"><img src="https://github.com/charmbracelet/crush/workflows/build/badge.svg" alt="Build Status"></a>
107</p>
118
12−Crush is a tool for building software with AI.
9+Your new coding bestie, available in your favourite terminal. Your tools, your
10+code, and your workflows, wired into your LLM of choice.
11+
12+<img width="800" alt="Crush Demo" src="https://github.com/user-attachments/assets/a67e22a5-167f-4aa0-bcbf-4248740b6fd4" />
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
1322
1423## Installation
1524
16−Crush has first class support for macOS, Linux, and Windows.
25+Use a package manager:
1726
18−Nightly builds are available while Crush is in development.
27+```bash
28+# macOS or Linux
29+brew install charmbracelet/tap/crush
1930
20−- [Packages](https://github.com/charmbracelet/crush/releases/tag/nightly) are available in Debian, RPM, APK, and PKG formats
21−- [Binaries](https://github.com/charmbracelet/crush/releases/tag/nightly) are available for Linux, macOS and Windows
31+# NPM
32+npm install -g @charmland/crush
2233
23−You can also just install it with go:
34+# Arch Linux (btw)
35+yay -S crush-bin
2436
25−```
26−git clone git@github.com:charmbracelet/crush.git
27−cd crush
28−go install
37+# Windows (with Winget)
38+winget install charmbracelet.crush
39+
40+# Nix
41+nix-shell -p nur.repos.charmbracelet.crush
2942```
3043
3144<details>
32−<summary>Not a developer? Here’s a quick how-to.</summary>
45+<summary><strong>Debian/Ubuntu</strong></summary>
3346
34−Download the latest [nightly release](https://github.com/charmbracelet/crush/releases) for your system. The [macOS ARM64 one](https://github.com/charmbracelet/crush/releases/download/nightly/crush_0.1.0-nightly_Darwin_arm64.tar.gz) is most likely what you want.
47+```bash
48+sudo mkdir -p /etc/apt/keyrings
49+curl -fsSL https://repo.charm.sh/apt/gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/charm.gpg
50+echo "deb [signed-by=/etc/apt/keyrings/charm.gpg] https://repo.charm.sh/apt/ * *" | sudo tee /etc/apt/sources.list.d/charm.list
51+sudo apt update && sudo apt install crush
52+```
3553
36−Next, open a terminal and run the following commands:
54+</details>
55+
56+<details>
57+<summary><strong>Fedora/RHEL</strong></summary>
3758
3859```bash
39−cd ~/Downloads
40−tar -xvzf crush_0.1.0-nightly_Darwin_arm64.tar.gz -C crush
41−sudo mv ./crush/crush /usr/local/bin/crush
42−rm -rf ./crush
60+echo '[charm]
61+name=Charm
62+baseurl=https://repo.charm.sh/yum/
63+enabled=1
64+gpgcheck=1
65+gpgkey=https://repo.charm.sh/yum/gpg.key' | sudo tee /etc/yum.repos.d/charm.repo
66+sudo yum install crush
4367```
4468
45−Then, run Crush by typing `crush`.
69+</details>
4670
47−---
71+Or, download it:
4872
49−</details>
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+
78+Or just install it with go:
79+
80+```
81+go 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.
5088
5189## Getting Started
5290
53−The quickest way to get started to grab an API key for your preferred
54−provider such as Anthropic, OpenAI, or Groq, and just start Crush. You'll be
55−prompted to enter your API key.
91+The quickest way to get started is to grab an API key for your preferred
92+provider such as Anthropic, OpenAI, Groq, or OpenRouter and just start
93+Crush. You'll be prompted to enter your API key.
5694
57−That said, you can also set environment variables for preferred providers:
95+That said, you can also set environment variables for preferred providers.
96+
97+<details>
98+<summary><strong>Supported Environment Variables</strong></summary>
5899
59100| Environment Variable | Provider |
60101| -------------------------- | -------------------------------------------------- |
@@ -71,17 +112,31 @@ That said, you can also set environment variables for preferred providers:
71112| `AZURE_OPENAI_API_KEY` | Azure OpenAI models (optional when using Entra ID) |
72113| `AZURE_OPENAI_API_VERSION` | Azure OpenAI models |
73114
115+</details>
116+
74117## Configuration
75118
76−For many use cases, Crush can be run with no config. That said, if you do need config, it can be added either local to the project itself, or globally. Configuration has the following priority:
119+Crush runs great with no configuration. That said, if you do need or want to
120+customize Crush, configuration can be added either local to the project itself,
121+or globally, with the following priority:
77122
78−1. `.crush.json`
79−2. `crush.json`
123+1. `./.crush.json`
124+2. `./crush.json`
801253. `$HOME/.config/crush/crush.json`
81126
127+Configuration itself is stored as a JSON object:
128+
129+```json
130+{
131+ "this-setting": { }
132+ "that-setting": { }
133+}
134+```
135+
82136### LSPs
83137
84−Crush can use LSPs for additional context to help inform its decisions, just like you would. LSPs can be added manually like so:
138+Crush can use LSPs for additional context to help inform its decisions, just
139+like you would. LSPs can be added manually like so:
85140
86141```json
87142{
@@ -94,7 +149,7 @@ Crush can use LSPs for additional context to help inform its decisions, just lik
94149 "args": ["--stdio"]
95150 },
96151 "nix": {
97− "command": "alejandra"
152+ "command": "nil"
98153 }
99154 }
100155}
@@ -102,7 +157,10 @@ Crush can use LSPs for additional context to help inform its decisions, just lik
102157
103158### MCPs
104159
105−Crush supports Model Context Protocol (MCP) servers through three transport types: `stdio` for command-line servers, `http` for HTTP endpoints, and `sse` for Server-Sent Events. Environment variable expansion is supported using `$(echo $VAR)` syntax.
160+Crush also supports Model Context Protocol (MCP) servers through three
161+transport types: `stdio` for command-line servers, `http` for HTTP endpoints,
162+and `sse` for Server-Sent Events. Environment variable expansion is supported
163+using `$(echo $VAR)` syntax.
106164
107165```json
108166{
@@ -133,37 +191,11 @@ Crush supports Model Context Protocol (MCP) servers through three transport type
133191}
134192```
135193
136−### Logging
137−
138−Enable debug logging with the `-d` flag or in config. View logs with `crush logs`. Logs are stored in `.crush/logs/crush.log`.
139−```bash
140−# Run with debug logging
141−crush -d
142−
143−# View last 1000 lines
144−crush logs
194+### Whitelisting Tools
145195
146−# Follow logs in real-time
147−crush logs -f
148−
149−# Show last 500 lines
150−crush logs -t 500
151−```
152−
153−Add to your `crush.json` config file:
154−
155−```json
156−{
157− "options": {
158− "debug": true,
159− "debug_lsp": true
160− }
161−}
162−```
163−
164−### Configurable Default Permissions
165−
166−Crush includes a permission system to control which tools can be executed without prompting. You can configure allowed tools in your `crush.json` config file:
196+By default, Crush will ask you for permission before running tool calls. If
197+you'd like, you can whitelist tools to be executed without prompting you for
198+permissions. Use this with care.
167199
168200```json
169201{
@@ -172,27 +204,25 @@ Crush includes a permission system to control which tools can be executed withou
172204 "view",
173205 "ls",
174206 "grep",
175− "edit:write",
207+ "edit",
176208 "mcp_context7_get-library-doc"
177209 ]
178210 }
179211}
180212```
181213
182−The `allowed_tools` array accepts:
183−
184−- Tool names (e.g., `"view"`) - allows all actions for that tool
185−- Tool:action combinations (e.g., `"edit:write"`) - allows only specific actions
186−
187−You can also skip all permission prompts entirely by running Crush with the `--yolo` flag.
214+You can also skip all permission prompts entirely by running Crush with the
215+`--yolo` flag. Be very, very careful with this feature.
188216
189217### Custom Providers
190218
191−Crush supports custom provider configurations for both OpenAI-compatible and Anthropic-compatible APIs.
219+Crush supports custom provider configurations for both OpenAI-compatible and
220+Anthropic-compatible APIs.
192221
193222#### OpenAI-Compatible APIs
194223
195−Here's an example configuration for Deepseek, which uses an OpenAI-compatible API. Don't forget to set `DEEPSEEK_API_KEY` in your environment.
224+Here’s an example configuration for Deepseek, which uses an OpenAI-compatible
225+API. Don't forget to set `DEEPSEEK_API_KEY` in your environment.
196226
197227```json
198228{
@@ -220,7 +250,7 @@ Here's an example configuration for Deepseek, which uses an OpenAI-compatible AP
220250
221251#### Anthropic-Compatible APIs
222252
223−You can also configure custom Anthropic-compatible providers:
253+Custom Anthropic-compatible providers follow this format:
224254
225255```json
226256{
@@ -234,14 +264,15 @@ You can also configure custom Anthropic-compatible providers:
234264 },
235265 "models": [
236266 {
237− "id": "claude-3-sonnet",
238− "model": "Claude 3 Sonnet",
239− "cost_per_1m_in": 3000,
240− "cost_per_1m_out": 15000,
241− "cost_per_1m_in_cached": 300,
242− "cost_per_1m_out_cached": 15000,
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,
243273 "context_window": 200000,
244− "default_max_tokens": 4096,
274+ "default_max_tokens": 50000,
275+ "can_reason": true,
245276 "supports_attachments": true
246277 }
247278 ]
@@ -250,23 +281,56 @@ You can also configure custom Anthropic-compatible providers:
250281}
251282```
252283
284+## Logging
285+
286+Sometimes you need to look at logs. Luckily, Crush logs all sorts of
287+stuff. Logs are stored in `./.crush/logs/crush.log` relative to the project.
288+
289+The CLI also contains some helper commands to make perusing recent logs easier:
290+
291+```bash
292+# Print the last 1000 lines
293+crush logs
294+
295+# Print the last 500 lines
296+crush logs --tail 500
297+
298+# Follow logs in real time
299+crush logs --follow
300+```
301+
302+Want more logging? Run `crush` with the `--debug` flag, or enable it in the
303+config:
304+
305+```json
306+{
307+ "options": {
308+ "debug": true,
309+ "debug_lsp": true
310+ }
311+}
312+```
313+
253314## Whatcha think?
254315
255316We’d love to hear your thoughts on this project. Feel free to drop us a note!
256317
257318- [Twitter](https://twitter.com/charmcli)
319+- [Discord][discord]
320+- [Slack](https://charm.land/slack)
258321- [The Fediverse](https://mastodon.social/@charmcli)
259−- [Discord](https://charm.sh/chat)
322+
323+[discord]: https://charm.land/discord
260324
261325## License
262326
263−[MIT](https://github.com/charmbracelet/crush/raw/main/LICENSE)
327+[FSL-1.1-MIT](https://github.com/charmbracelet/crush/raw/main/LICENSE)
264328
265329---
266330
267331Part of [Charm](https://charm.land).
268332
269−<a href="https://charm.sh/"><img alt="The Charm logo" width="400" src="https://stuff.charm.sh/charm-banner-next.jpg" /></a>
333+<a href="https://charm.land/"><img alt="The Charm logo" width="400" src="https://stuff.charm.sh/charm-banner-next.jpg" /></a>
270334
271335<!--prettier-ignore-->
272336Charm热爱开源 • Charm loves open source