README.md · crush · git.iko.soy

git.iko.soy/crush

crush/README.md

485 lines 14 kB history raw

1# Crush

3

4 <a href="https://stuff.charm.sh/crush/charm-crush.png"><img width="450" alt="Charm Crush Logo" src="https://github.com/user-attachments/assets/adc1a6f4-b284-4603-836c-59038caa2e8b" /></a>

5 <a href="https://github.com/charmbracelet/crush/releases"><img src="https://img.shields.io/github/release/charmbracelet/crush" alt="Latest Release"></a>

6 <a href="https://github.com/charmbracelet/crush/actions"><img src="https://github.com/charmbracelet/crush/workflows/build/badge.svg" alt="Build Status"></a>

7

9Your new coding bestie, now available in your favourite terminal. Your tools, your code, and your workflows, wired into your LLM of choice.

11<img width="800" alt="Crush Demo" src="https://github.com/user-attachments/assets/58280caf-851b-470a-b6f7-d5c4ea8a1968" />

13## Features

15- **Multi-Model:** choose from a wide range of LLMs or add your own via OpenAI- or Anthropic-compatible APIs

16- **Flexible:** switch LLMs mid-session while preserving context

17- **Session-Based:** maintain multiple work sessions and contexts per project

18- **LSP-Enhanced:** Crush uses LSPs for additional context, just like you do

19- **Extensible:** add capabilities via MCPs (`http`, `stdio`, and `sse`)

20- **Works Everywhere:** first-class support in every terminal on macOS, Linux, Windows (PowerShell and WSL), FreeBSD, OpenBSD, and NetBSD

22## Installation

24Use a package manager:

26```bash

27# Homebrew

28brew install charmbracelet/tap/crush

30# NPM

31npm install -g @charmland/crush

33# Arch Linux (btw)

34yay -S crush-bin

36# Nix

37nix run github:numtide/nix-ai-tools#crush

39# Scoop

40scoop bucket add charm https://github.com/charmbracelet/scoop-bucket.git

41scoop install crush

42```

44<details>

45<summary>Nix (NUR)</summary>

47Crush is available via [NUR](https://github.com/nix-community/NUR) in `nur.repos.charmbracelet.crush`.

49You can also try out Crush via `nix-shell`:

51```bash

52# Add the NUR channel.

53nix-channel --add https://github.com/nix-community/NUR/archive/main.tar.gz nur

54nix-channel --update

56# Get Crush in a Nix shell.

57nix-shell -p '(import <nur> { pkgs = import <nixpkgs> {}; }).repos.charmbracelet.crush'

58```

60</details>

62<details>

63<summary>Debian/Ubuntu</summary>

65```bash

66sudo mkdir -p /etc/apt/keyrings

67curl -fsSL https://repo.charm.sh/apt/gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/charm.gpg

68echo "deb [signed-by=/etc/apt/keyrings/charm.gpg] https://repo.charm.sh/apt/ * *" | sudo tee /etc/apt/sources.list.d/charm.list

69sudo apt update && sudo apt install crush

70```

72</details>

74<details>

75<summary>Fedora/RHEL</summary>

77```bash

78echo '[charm]

79name=Charm

80baseurl=https://repo.charm.sh/yum/

81enabled=1

82gpgcheck=1

83gpgkey=https://repo.charm.sh/yum/gpg.key' | sudo tee /etc/yum.repos.d/charm.repo

84sudo yum install crush

85```

87</details>

89Or, download it:

91- [Packages][releases] are available in Debian and RPM formats

92- [Binaries][releases] are available for Linux, macOS, Windows, FreeBSD, OpenBSD, and NetBSD

94[releases]: https://github.com/charmbracelet/crush/releases

96Or just install it with Go:

98```

99go install github.com/charmbracelet/crush@latest

100```

101

102> [!WARNING]

103> Productivity may increase when using Crush and you may find yourself nerd

104> sniped when first using the application. If the symptoms persist, join the

105> [Discord][discord] and nerd snipe the rest of us.

106

107## Getting Started

108

109The quickest way to get started is to grab an API key for your preferred

110provider such as Anthropic, OpenAI, Groq, or OpenRouter and just start

111Crush. You'll be prompted to enter your API key.

112

113That said, you can also set environment variables for preferred providers.

114

115| Environment Variable | Provider |

116| -------------------------- | -------------------------------------------------- |

117| `ANTHROPIC_API_KEY` | Anthropic |

118| `OPENAI_API_KEY` | OpenAI |

119| `OPENROUTER_API_KEY` | OpenRouter |

120| `GEMINI_API_KEY` | Google Gemini |

121| `VERTEXAI_PROJECT` | Google Cloud VertexAI (Gemini) |

122| `VERTEXAI_LOCATION` | Google Cloud VertexAI (Gemini) |

123| `GROQ_API_KEY` | Groq |

124| `AWS_ACCESS_KEY_ID` | AWS Bedrock (Claude) |

125| `AWS_SECRET_ACCESS_KEY` | AWS Bedrock (Claude) |

126| `AWS_REGION` | AWS Bedrock (Claude) |

127| `AZURE_OPENAI_ENDPOINT` | Azure OpenAI models |

128| `AZURE_OPENAI_API_KEY` | Azure OpenAI models (optional when using Entra ID) |

129| `AZURE_OPENAI_API_VERSION` | Azure OpenAI models |

130

131### By the Way

132

133Is there a provider you’d like to see in Crush? Is there an existing model that needs an update?

134

135Crush’s default model listing is managed in [Catwalk](https://github.com/charmbracelet/catwalk), an community-supported, open source repository of Crush-compatible models, and you’re welcome to contribute.

136

137<a href="https://github.com/charmbracelet/catwalk"><img width="174" height="174" alt="Catwalk Badge" src="https://github.com/user-attachments/assets/95b49515-fe82-4409-b10d-5beb0873787d" /></a>

138

139## Configuration

140

141Crush runs great with no configuration. That said, if you do need or want to

142customize Crush, configuration can be added either local to the project itself,

143or globally, with the following priority:

144

1451. `.crush.json`

1462. `crush.json`

1473. `$HOME/.config/crush/crush.json` (Windows: `%USERPROFILE%\AppData\Local\crush\crush.json`)

148

149Configuration itself is stored as a JSON object:

150

151```json

152{

153 "this-setting": {"this": "that"},

154 "that-setting": ["ceci", "cela"]

155}

156```

157

158As an additional note, Crush also stores ephemeral data, such as application state, in one additional location:

159

160```bash

161# Unix

162$HOME/.local/share/crush/crush.json

163

164# Windows

165%LOCALAPPDATA%\crush\crush.json

166```

167

168### LSPs

169

170Crush can use LSPs for additional context to help inform its decisions, just

171like you would. LSPs can be added manually like so:

172

173```json

174{

175 "$schema": "https://charm.land/crush.json",

176 "lsp": {

177 "go": {

178 "command": "gopls"

179 },

180 "typescript": {

181 "command": "typescript-language-server",

182 "args": ["--stdio"]

183 },

184 "nix": {

185 "command": "nil"

186 }

187 }

188}

189```

190

191### MCPs

192

193Crush also supports Model Context Protocol (MCP) servers through three

194transport types: `stdio` for command-line servers, `http` for HTTP endpoints,

195and `sse` for Server-Sent Events. Environment variable expansion is supported

196using `$(echo $VAR)` syntax.

197

198```json

199{

200 "$schema": "https://charm.land/crush.json",

201 "mcp": {

202 "filesystem": {

203 "type": "stdio",

204 "command": "node",

205 "args": ["/path/to/mcp-server.js"],

206 "env": {

207 "NODE_ENV": "production"

208 }

209 },

210 "github": {

211 "type": "http",

212 "url": "https://example.com/mcp/",

213 "headers": {

214 "Authorization": "$(echo Bearer $EXAMPLE_MCP_TOKEN)"

215 }

216 },

217 "streaming-service": {

218 "type": "sse",

219 "url": "https://example.com/mcp/sse",

220 "headers": {

221 "API-Key": "$(echo $API_KEY)"

222 }

223 }

224 }

225}

226```

227

228### Ignoring Files

229

230Crush respects `.gitignore` files by default, but you can also create a

231`.crushignore` file to specify additional files and directories that Crush

232should ignore. This is useful for excluding files that you want in version

233control but don't want Crush to consider when providing context.

234

235The `.crushignore` file uses the same syntax as `.gitignore` and can be placed

236in the root of your project or in subdirectories.

237

238### Allowing Tools

239

240By default, Crush will ask you for permission before running tool calls. If

241you'd like, you can allow tools to be executed without prompting you for

242permissions. Use this with care.

243

244```json

245{

246 "$schema": "https://charm.land/crush.json",

247 "permissions": {

248 "allowed_tools": [

249 "view",

250 "ls",

251 "grep",

252 "edit",

253 "mcp_context7_get-library-doc"

254 ]

255 }

256}

257```

258

259You can also skip all permission prompts entirely by running Crush with the

260`--yolo` flag. Be very, very careful with this feature.

261

262### Local Models

263

264Local models can also be configured via OpenAI-compatible API. Here are two common examples:

265

266#### Ollama

267

268```json

269{

270 "providers": {

271 "ollama": {

272 "name": "Ollama",

273 "base_url": "http://localhost:11434/v1/",

274 "type": "openai",

275 "models": [

276 {

277 "name": "Qwen 3 30B",

278 "id": "qwen3:30b",

279 "context_window": 256000,

280 "default_max_tokens": 20000

281 }

282 ]

283 }

284 }

285}

286```

287

288#### LM Studio

289

290```json

291{

292 "providers": {

293 "lmstudio": {

294 "name": "LM Studio",

295 "base_url": "http://localhost:1234/v1/",

296 "type": "openai",

297 "models": [

298 {

299 "name": "Qwen 3 30B",

300 "id": "qwen/qwen3-30b-a3b-2507",

301 "context_window": 256000,

302 "default_max_tokens": 20000

303 }

304 ]

305 }

306 }

307}

308```

309

310### Custom Providers

311

312Crush supports custom provider configurations for both OpenAI-compatible and

313Anthropic-compatible APIs.

314

315#### OpenAI-Compatible APIs

316

317Here’s an example configuration for Deepseek, which uses an OpenAI-compatible

318API. Don't forget to set `DEEPSEEK_API_KEY` in your environment.

319

320```json

321{

322 "$schema": "https://charm.land/crush.json",

323 "providers": {

324 "deepseek": {

325 "type": "openai",

326 "base_url": "https://api.deepseek.com/v1",

327 "api_key": "$DEEPSEEK_API_KEY",

328 "models": [

329 {

330 "id": "deepseek-chat",

331 "name": "Deepseek V3",

332 "cost_per_1m_in": 0.27,

333 "cost_per_1m_out": 1.1,

334 "cost_per_1m_in_cached": 0.07,

335 "cost_per_1m_out_cached": 1.1,

336 "context_window": 64000,

337 "default_max_tokens": 5000

338 }

339 ]

340 }

341 }

342}

343```

344

345#### Anthropic-Compatible APIs

346

347Custom Anthropic-compatible providers follow this format:

348

349```json

350{

351 "$schema": "https://charm.land/crush.json",

352 "providers": {

353 "custom-anthropic": {

354 "type": "anthropic",

355 "base_url": "https://api.anthropic.com/v1",

356 "api_key": "$ANTHROPIC_API_KEY",

357 "extra_headers": {

358 "anthropic-version": "2023-06-01"

359 },

360 "models": [

361 {

362 "id": "claude-sonnet-4-20250514",

363 "name": "Claude Sonnet 4",

364 "cost_per_1m_in": 3,

365 "cost_per_1m_out": 15,

366 "cost_per_1m_in_cached": 3.75,

367 "cost_per_1m_out_cached": 0.3,

368 "context_window": 200000,

369 "default_max_tokens": 50000,

370 "can_reason": true,

371 "supports_attachments": true

372 }

373 ]

374 }

375 }

376}

377```

378

379### Amazon Bedrock

380

381Crush currently supports running Anthropic models through Bedrock, with caching disabled.

382

383* A Bedrock provider will appear once you have AWS configured, i.e. `aws configure`

384* Crush also expects the `AWS_REGION` or `AWS_DEFAULT_REGION` to be set

385* To use a specific AWS profile set `AWS_PROFILE` in your environment, i.e. `AWS_PROFILE=myprofile crush`

386

387### Vertex AI Platform

388

389Vertex AI will appear in the list of available providers when `VERTEXAI_PROJECT` and `VERTEXAI_LOCATION` are set. You will also need to be authenticated:

390

391```bash

392gcloud auth application-default login

393```

394

395To add specific models to the configuration, configure as such:

396

397```json

398{

399 "$schema": "https://charm.land/crush.json",

400 "providers": {

401 "vertexai": {