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
4# Crush
5
6<p>
7 <img width="450" alt="Charm Crush Art" src="https://github.com/user-attachments/assets/9ab4c30c-9327-46b6-a722-3ad0e20f6976" /><br>
8 <a href="https://github.com/charmbracelet/crush/releases"><img src="https://img.shields.io/github/release/charmbracelet/crush" alt="Latest Release"></a>
9 <a href="https://github.com/charmbracelet/crush/actions"><img src="https://github.com/charmbracelet/crush/workflows/build/badge.svg" alt="Build Status"></a>
10</p>
11
12Crush is a tool for building software with AI.
13
14## Installation
15
16Crush has first class support for macOS, Linux, and Windows.
17
18Nightly builds are available while Crush is in development.
19
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
22
23You can also just install it with go:
24
25```
26git clone git@github.com:charmbracelet/crush.git
27cd crush
28go install
29```
30
31<details>
32<summary>Not a developer? Here’s a quick how-to.</summary>
33
34Download 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.
35
36Next, open a terminal and run the following commands:
37
38```bash
39cd ~/Downloads
40tar -xvzf crush_0.1.0-nightly_Darwin_arm64.tar.gz -C crush
41sudo mv ./crush/crush /usr/local/bin/crush
42rm -rf ./crush
43```
44
45Then, run Crush by typing `crush`.
46
47---
48
49</details>
50
51## Getting Started
52
53The quickest way to get started to grab an API key for your preferred
54provider such as Anthropic, OpenAI, or Groq, and just start Crush. You'll be
55prompted to enter your API key.
56
57That said, you can also set environment variables for preferred providers:
58
59| Environment Variable | Provider |
60| -------------------------- | -------------------------------------------------- |
61| `ANTHROPIC_API_KEY` | Anthropic |
62| `OPENAI_API_KEY` | OpenAI |
63| `GEMINI_API_KEY` | Google Gemini |
64| `VERTEXAI_PROJECT` | Google Cloud VertexAI (Gemini) |
65| `VERTEXAI_LOCATION` | Google Cloud VertexAI (Gemini) |
66| `GROQ_API_KEY` | Groq |
67| `AWS_ACCESS_KEY_ID` | AWS Bedrock (Claude) |
68| `AWS_SECRET_ACCESS_KEY` | AWS Bedrock (Claude) |
69| `AWS_REGION` | AWS Bedrock (Claude) |
70| `AZURE_OPENAI_ENDPOINT` | Azure OpenAI models |
71| `AZURE_OPENAI_API_KEY` | Azure OpenAI models (optional when using Entra ID) |
72| `AZURE_OPENAI_API_VERSION` | Azure OpenAI models |
73
74## Configuration
75
76For 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:
77
781. `.crush.json`
792. `crush.json`
803. `$HOME/.config/crush/crush.json`
81
82### LSPs
83
84Crush can use LSPs for additional context to help inform its decisions, just like you would. LSPs can be added manually like so:
85
86```json
87{
88 "$schema": "https://charm.land/crush.json",
89 "lsp": {
90 "go": {
91 "command": "gopls"
92 },
93 "typescript": {
94 "command": "typescript-language-server",
95 "args": ["--stdio"]
96 },
97 "nix": {
98 "command": "alejandra"
99 }
100 }
101}
102```
103
104### MCPs
105
106Crush 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.
107
108```json
109{
110 "$schema": "https://charm.land/crush.json",
111 "mcp": {
112 "filesystem": {
113 "type": "stdio",
114 "command": "node",
115 "args": ["/path/to/mcp-server.js"],
116 "env": {
117 "NODE_ENV": "production"
118 }
119 },
120 "github": {
121 "type": "http",
122 "url": "https://example.com/mcp/",
123 "headers": {
124 "Authorization": "$(echo Bearer $EXAMPLE_MCP_TOKEN)"
125 }
126 },
127 "streaming-service": {
128 "type": "sse",
129 "url": "https://example.com/mcp/sse",
130 "headers": {
131 "API-Key": "$(echo $API_KEY)"
132 }
133 }
134 }
135}
136```
137
138### Logging
139
140Enable debug logging with the `-d` flag or in config. View logs with `crush logs`. Logs are stored in `.crush/logs/crush.log`.
141
142```bash
143# Run with debug logging
144crush -d
145
146# View last 1000 lines
147crush logs
148
149# Follow logs in real-time
150crush logs -f
151
152# Show last 500 lines
153crush logs -t 500
154```
155
156Add to your `crush.json` config file:
157
158```json
159{
160 "$schema": "https://charm.land/crush.json",
161 "options": {
162 "debug": true,
163 "debug_lsp": true
164 }
165}
166```
167
168### Configurable Default Permissions
169
170Crush includes a permission system to control which tools can be executed without prompting. You can configure allowed tools in your `crush.json` config file:
171
172```json
173{
174 "$schema": "https://charm.land/crush.json",
175 "permissions": {
176 "allowed_tools": [
177 "view",
178 "ls",
179 "grep",
180 "edit:write",
181 "mcp_context7_get-library-doc"
182 ]
183 }
184}
185```
186
187The `allowed_tools` array accepts:
188
189- Tool names (e.g., `"view"`) - allows all actions for that tool
190- Tool:action combinations (e.g., `"edit:write"`) - allows only specific actions
191
192You can also skip all permission prompts entirely by running Crush with the `--yolo` flag.
193
194### Custom Providers
195
196Crush supports custom provider configurations for both OpenAI-compatible and Anthropic-compatible APIs.
197
198#### OpenAI-Compatible APIs
199
200Here's an example configuration for Deepseek, which uses an OpenAI-compatible API. Don't forget to set `DEEPSEEK_API_KEY` in your environment.
201
202```json
203{
204 "$schema": "https://charm.land/crush.json",
205 "providers": {
206 "deepseek": {
207 "type": "openai",
208 "base_url": "https://api.deepseek.com/v1",
209 "api_key": "$DEEPSEEK_API_KEY",
210 "models": [
211 {
212 "id": "deepseek-chat",
213 "name": "Deepseek V3",
214 "cost_per_1m_in": 0.27,
215 "cost_per_1m_out": 1.1,
216 "cost_per_1m_in_cached": 0.07,
217 "cost_per_1m_out_cached": 1.1,
218 "context_window": 64000,
219 "default_max_tokens": 5000
220 }
221 ]
222 }
223 }
224}
225```
226
227#### Anthropic-Compatible APIs
228
229You can also configure custom Anthropic-compatible providers:
230
231```json
232{
233 "$schema": "https://charm.land/crush.json",
234 "providers": {
235 "custom-anthropic": {
236 "type": "anthropic",
237 "base_url": "https://api.anthropic.com/v1",
238 "api_key": "$ANTHROPIC_API_KEY",
239 "extra_headers": {
240 "anthropic-version": "2023-06-01"
241 },
242 "models": [
243 {
244 "id": "claude-3-sonnet",
245 "model": "Claude 3 Sonnet",
246 "cost_per_1m_in": 3000,
247 "cost_per_1m_out": 15000,
248 "cost_per_1m_in_cached": 300,
249 "cost_per_1m_out_cached": 15000,
250 "context_window": 200000,
251 "default_max_tokens": 4096,
252 "supports_attachments": true
253 }
254 ]
255 }
256 }
257}
258```
259
260## Whatcha think?
261
262We’d love to hear your thoughts on this project. Feel free to drop us a note!
263
264- [Twitter](https://twitter.com/charmcli)
265- [The Fediverse](https://mastodon.social/@charmcli)
266- [Discord](https://charm.sh/chat)
267
268## License
269
270[MIT](https://github.com/charmbracelet/crush/raw/main/LICENSE)
271
272---
273
274Part of [Charm](https://charm.land).
275
276<a href="https://charm.sh/"><img alt="The Charm logo" width="400" src="https://stuff.charm.sh/charm-banner-next.jpg" /></a>
277
278<!--prettier-ignore-->
279Charm热爱开源 • Charm loves open source