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### Nix
51
52Crush provides a Nix flake for easy installation and configuration management.
53
54#### Installation
55
56Install directly from the flake:
57
58```bash
59nix profile install github:charmbracelet/crush
60```
61
62Or run without installing:
63
64```bash
65nix run github:charmbracelet/crush
66```
67#### NixOS Module
68
69Add Crush to your NixOS configuration:
70
71```nix
72{
73 inputs = {
74 nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
75 crush.url = "github:charmbracelet/crush";
76 };
77
78 outputs = { nixpkgs, crush, ... }: {
79 nixosConfigurations.your-hostname = nixpkgs.lib.nixosSystem {
80 modules = [
81 crush.nixosModules.default
82 {
83 programs.crush = {
84 enable = true;
85 settings = {
86 providers = {
87 openai = {
88 name = "OpenAI";
89 provider_type = "openai";
90 api_key = "sk-fake123456789abcdef...";
91 };
92 };
93 lsp = {
94 go = { command = "gopls"; };
95 nix = { command = "nil"; };
96 };
97 };
98 };
99 }
100 ];
101 };
102 };
103}
104```
105
106#### Home Manager Module
107
108Home Manager configuration uses identical settings structure:
109
110```nix
111{
112 inputs = {
113 nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
114 home-manager.url = "github:nix-community/home-manager";
115 crush.url = "github:charmbracelet/crush";
116 };
117
118 outputs = { nixpkgs, home-manager, crush, ... }: {
119 homeConfigurations.your-username = home-manager.lib.homeManagerConfiguration {
120 modules = [
121 crush.homeManagerModules.default
122 { programs.crush.enable = true; }
123 ];
124 };
125 };
126}
127```
128
129## Getting Started
130
131The quickest way to get started to grab an API key for your preferred
132provider such as Anthropic, OpenAI, or Groq, and just start Crush. You'll be
133prompted to enter your API key.
134
135That said, you can also set environment variables for preferred providers:
136
137| Environment Variable | Provider |
138| -------------------------- | -------------------------------------------------- |
139| `ANTHROPIC_API_KEY` | Anthropic |
140| `OPENAI_API_KEY` | OpenAI |
141| `GEMINI_API_KEY` | Google Gemini |
142| `VERTEXAI_PROJECT` | Google Cloud VertexAI (Gemini) |
143| `VERTEXAI_LOCATION` | Google Cloud VertexAI (Gemini) |
144| `GROQ_API_KEY` | Groq |
145| `AWS_ACCESS_KEY_ID` | AWS Bedrock (Claude) |
146| `AWS_SECRET_ACCESS_KEY` | AWS Bedrock (Claude) |
147| `AWS_REGION` | AWS Bedrock (Claude) |
148| `AZURE_OPENAI_ENDPOINT` | Azure OpenAI models |
149| `AZURE_OPENAI_API_KEY` | Azure OpenAI models (optional when using Entra ID) |
150| `AZURE_OPENAI_API_VERSION` | Azure OpenAI models |
151
152## Configuration
153
154For 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:
155
1561. `.crush.json`
1572. `crush.json`
1583. `$HOME/.config/crush/crush.json`
159
160### LSPs
161
162Crush can use LSPs for additional context to help inform its decisions, just like you would. LSPs can be added manually like so:
163
164```json
165{
166 "lsp": {
167 "go": {
168 "command": "gopls"
169 },
170 "typescript": {
171 "command": "typescript-language-server",
172 "args": ["--stdio"]
173 },
174 "nix": {
175 "command": "alejandra"
176 }
177 }
178}
179```
180
181### MCPs
182
183Crush 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.
184
185```json
186{
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://api.githubcopilot.com/mcp/",
199 "headers": {
200 "Authorization": "$(echo Bearer $GH_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### Logging
215
216Enable debug logging with the `-d` flag or in config. View logs with `crush logs`. Logs are stored in `.crush/logs/crush.log`.
217
218```bash
219# Run with debug logging
220crush -d
221
222# View last 1000 lines
223crush logs
224
225# Follow logs in real-time
226crush logs -f
227
228# Show last 500 lines
229crush logs -t 500
230```
231
232Add to your `crush.json` config file:
233
234```json
235{
236 "options": {
237 "debug": true,
238 "debug_lsp": true
239 }
240}
241```
242
243### Configurable Default Permissions
244
245Crush includes a permission system to control which tools can be executed without prompting. You can configure allowed tools in your `crush.json` config file:
246
247```json
248{
249 "permissions": {
250 "allowed_tools": [
251 "view",
252 "ls",
253 "grep",
254 "edit:write",
255 "mcp_context7_get-library-doc"
256 ]
257 }
258}
259```
260
261The `allowed_tools` array accepts:
262
263- Tool names (e.g., `"view"`) - allows all actions for that tool
264- Tool:action combinations (e.g., `"edit:write"`) - allows only specific actions
265
266You can also skip all permission prompts entirely by running Crush with the `--yolo` flag.
267
268### OpenAI-Compatible APIs
269
270Crush 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.
271
272```json
273{
274 "providers": {
275 "deepseek": {
276 "provider_type": "openai",
277 "base_url": "https://api.deepseek.com/v1",
278 "models": [
279 {
280 "id": "deepseek-chat",
281 "name": "Deepseek V3",
282 "cost_per_1m_in": 0.27,
283 "cost_per_1m_out": 1.1,
284 "cost_per_1m_in_cached": 0.07,
285 "cost_per_1m_out_cached": 1.1,
286 "context_window": 64000,
287 "default_max_tokens": 5000
288 }
289 ]
290 }
291 }
292}
293```
294
295## Whatcha think?
296
297We’d love to hear your thoughts on this project. Feel free to drop us a note!
298
299- [Twitter](https://twitter.com/charmcli)
300- [The Fediverse](https://mastodon.social/@charmcli)
301- [Discord](https://charm.sh/chat)
302
303## License
304
305[MIT](https://github.com/charmbracelet/crush/raw/main/LICENSE)
306
307---
308
309Part of [Charm](https://charm.land).
310
311<a href="https://charm.sh/"><img alt="The Charm logo" width="400" src="https://stuff.charm.sh/charm-banner-next.jpg" /></a>
312
313<!--prettier-ignore-->
314Charm热爱开源 • Charm loves open source