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://api.githubcopilot.com/mcp/",
120      "headers": {
121        "Authorization": "$(echo Bearer $GH_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
139```bash
140# Run with debug logging
141crush -d
142
143# View last 1000 lines
144crush logs
145
146# Follow logs in real-time
147crush logs -f
148
149# Show last 500 lines
150crush logs -t 500
151```
152
153Add 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
166Crush includes a permission system to control which tools can be executed without prompting. You can configure allowed tools in your `crush.json` config file:
167
168```json
169{
170  "permissions": {
171    "allowed_tools": [
172      "view",
173      "ls",
174      "grep",
175      "edit:write",
176      "mcp_context7_get-library-doc"
177    ]
178  }
179}
180```
181
182The `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
187You can also skip all permission prompts entirely by running Crush with the `--yolo` flag.
188
189### OpenAI-Compatible APIs
190
191Crush supports all OpenAI-compatible APIs. Here's an example configuration for Deepseek, which uses an OpenAI-compatible API. Don't forget to set `DEEPSEEK_API_KEY` in your environment.
192
193```json
194{
195  "providers": {
196    "deepseek": {
197      "provider_type": "openai",
198      "base_url": "https://api.deepseek.com/v1",
199      "models": [
200        {
201          "id": "deepseek-chat",
202          "name": "Deepseek V3",
203          "cost_per_1m_in": 0.27,
204          "cost_per_1m_out": 1.1,
205          "cost_per_1m_in_cached": 0.07,
206          "cost_per_1m_out_cached": 1.1,
207          "context_window": 64000,
208          "default_max_tokens": 5000
209        }
210      ]
211    }
212  }
213}
214```
215
216## Whatcha think?
217
218We’d love to hear your thoughts on this project. Feel free to drop us a note!
219
220- [Twitter](https://twitter.com/charmcli)
221- [The Fediverse](https://mastodon.social/@charmcli)
222- [Discord](https://charm.sh/chat)
223
224## License
225
226[MIT](https://github.com/charmbracelet/crush/raw/main/LICENSE)
227
228---
229
230Part of [Charm](https://charm.land).
231
232<a href="https://charm.sh/"><img alt="The Charm logo" width="400" src="https://stuff.charm.sh/charm-banner-next.jpg" /></a>
233
234<!--prettier-ignore-->
235Charm热爱开源 • Charm loves open source