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