05e1927 · crush · git.iko.soy

git.iko.soy/crush

on main help sign in

docs(readme): general update

05e1927Christian Rocha1 year ago

README.md+148−84

compare with main

unifiedsplit

@@ -1,60 +1,101 @@

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

1# Crush

6

3

7− <img width="450" alt="Charm Crush Art" src="https://github.com/user-attachments/assets/9ab4c30c-9327-46b6-a722-3ad0e20f6976" />

4+ <img width="450" alt="Charm Crush Art" src="https://github.com/user-attachments/assets/4cd517be-476b-4a78-971c-810a0b1af3f6" />

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

5 <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>

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

10

7

12−Crush is a tool for building software with AI.

9+Your new coding bestie, available in your favourite terminal. Your tools, your

10+code, and your workflows, wired into your LLM of choice.

11+

12+<img width="800" alt="Crush Demo" src="https://github.com/user-attachments/assets/a67e22a5-167f-4aa0-bcbf-4248740b6fd4" />

13+

14+## Features

15+

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

17+- **Flexible:** switch LLMs mid-session while preserving context

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

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

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

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

14## Installation

23## Installation

16−Crush has first class support for macOS, Linux, and Windows.

25+Use a package manager:

18−Nightly builds are available while Crush is in development.

27+```bash

28+# macOS or Linux

29+brew install charmbracelet/tap/crush

20−- [Packages](https://github.com/charmbracelet/crush/releases/tag/nightly) are available in Debian, RPM, APK, and PKG formats

31+# NPM

21−- [Binaries](https://github.com/charmbracelet/crush/releases/tag/nightly) are available for Linux, macOS and Windows

32+npm install -g @charmland/crush

23−You can also just install it with go:

34+# Arch Linux (btw)

35+yay -S crush-bin

25−```

37+# Windows (with Winget)

26−git clone git@github.com:charmbracelet/crush.git

38+winget install charmbracelet.crush

27−cd crush

39+

28−go install

40+# Nix

41+nix-shell -p nur.repos.charmbracelet.crush

29```

42```

31<details>

44<details>

32−<summary>Not a developer? Here’s a quick how-to.</summary>

45+<summary>Debian/Ubuntu</summary>

34−Download 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.

47+```bash

48+sudo mkdir -p /etc/apt/keyrings

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

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

51+sudo apt update && sudo apt install crush

52+```

36−Next, open a terminal and run the following commands:

54+</details>

55+

56+<details>

57+<summary>Fedora/RHEL</summary>

38```bash

59```bash

39−cd ~/Downloads

60+echo '[charm]

40−tar -xvzf crush_0.1.0-nightly_Darwin_arm64.tar.gz -C crush

61+name=Charm

41−sudo mv ./crush/crush /usr/local/bin/crush

62+baseurl=https://repo.charm.sh/yum/

42−rm -rf ./crush

63+enabled=1

64+gpgcheck=1

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

66+sudo yum install crush

43```

67```

45−Then, run Crush by typing `crush`.

69+</details>

47−---

71+Or, download it:

49−</details>

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

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

75+

76+[releases]: https://github.com/charmbracelet/crush/releases

77+

78+Or just install it with go:

79+

80+```

81+go install github.com/charmbracelet/crush@latest

82+```

83+

84+> [!WARNING]

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

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

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

51## Getting Started

89## Getting Started

53−The quickest way to get started to grab an API key for your preferred

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

54−provider such as Anthropic, OpenAI, or Groq, and just start Crush. You'll be

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

55−prompted to enter your API key.

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

57−That said, you can also set environment variables for preferred providers:

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

96+

97+<details>

98+<summary>Supported Environment Variables</summary>

59| Environment Variable | Provider |

100| Environment Variable | Provider |

60| -------------------------- | -------------------------------------------------- |

101| -------------------------- | -------------------------------------------------- |

@@ -71,17 +112,31 @@ That said, you can also set environment variables for preferred providers:

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

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

72| `AZURE_OPENAI_API_VERSION` | Azure OpenAI models |

113| `AZURE_OPENAI_API_VERSION` | Azure OpenAI models |

114

115+</details>

116+

74## Configuration

117## Configuration

118

76−For 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:

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

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

121+or globally, with the following priority:

122

78−1. `.crush.json`

123+1. `./.crush.json`

79−2. `crush.json`

124+2. `./crush.json`

803. `$HOME/.config/crush/crush.json`

1253. `$HOME/.config/crush/crush.json`

126

127+Configuration itself is stored as a JSON object:

128+

129+```json

130+{

131+ "this-setting": { }

132+ "that-setting": { }

133+}

134+```

135+

82### LSPs

136### LSPs

137

84−Crush can use LSPs for additional context to help inform its decisions, just like you would. LSPs can be added manually like so:

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

139+like you would. LSPs can be added manually like so:

140

86```json

141```json

87{

142{

@@ -94,7 +149,7 @@ Crush can use LSPs for additional context to help inform its decisions, just lik

94 "args": ["--stdio"]

149 "args": ["--stdio"]

95 },

150 },

96 "nix": {

151 "nix": {

97− "command": "alejandra"

152+ "command": "nil"

98 }

153 }

99 }

154 }

100}

155}

@@ -102,7 +157,10 @@ Crush can use LSPs for additional context to help inform its decisions, just lik

102

157

103### MCPs

158### MCPs

104

159

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

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

105−Crush 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.

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

163+using `$(echo $VAR)` syntax.

106

164

107```json

165```json

108{

166{

@@ -133,37 +191,11 @@ Crush supports Model Context Protocol (MCP) servers through three transport type

133}

191}

134```

192```

135

193

136−### Logging

194+### Whitelisting Tools

137−

138−Enable debug logging with the `-d` flag or in config. View logs with `crush logs`. Logs are stored in `.crush/logs/crush.log`.

139−```bash

140−# Run with debug logging

141−crush -d

142−

143−# View last 1000 lines

144−crush logs

145

195

146−# Follow logs in real-time

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

147−crush logs -f

197+you'd like, you can whitelist tools to be executed without prompting you for

148−

198+permissions. Use this with care.

149−# Show last 500 lines

150−crush logs -t 500

151−```

152−

153−Add 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−

166−Crush 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

199

168```json

200```json

169{

201{

@@ -172,27 +204,25 @@ Crush includes a permission system to control which tools can be executed withou

172 "view",

204 "view",

173 "ls",

205 "ls",

174 "grep",

206 "grep",

175− "edit:write",

207+ "edit",

176 "mcp_context7_get-library-doc"

208 "mcp_context7_get-library-doc"

177 ]

209 ]

178 }

210 }

179}

211}

180```

212```

181

213

182−The `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−

187−You can also skip all permission prompts entirely by running Crush with the `--yolo` flag.

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

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

188

216

189### Custom Providers

217### Custom Providers

190

218

191−Crush supports custom provider configurations for both OpenAI-compatible and Anthropic-compatible APIs.

219+Crush supports custom provider configurations for both OpenAI-compatible and

220+Anthropic-compatible APIs.

192

221

193#### OpenAI-Compatible APIs

222#### OpenAI-Compatible APIs

194

223

195−Here's an example configuration for Deepseek, which uses an OpenAI-compatible API. Don't forget to set `DEEPSEEK_API_KEY` in your environment.

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

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

196

226

197```json

227```json

198{

228{

@@ -220,7 +250,7 @@ Here's an example configuration for Deepseek, which uses an OpenAI-compatible AP

220

250

221#### Anthropic-Compatible APIs

251#### Anthropic-Compatible APIs

222

252

223−You can also configure custom Anthropic-compatible providers:

253+Custom Anthropic-compatible providers follow this format:

224

254

225```json

255```json

226{

256{

@@ -234,14 +264,15 @@ You can also configure custom Anthropic-compatible providers:

234 },

264 },

235 "models": [

265 "models": [

236 {

266 {

237− "id": "claude-3-sonnet",

267+ "id": "claude-sonnet-4-20250514",

238− "model": "Claude 3 Sonnet",

268+ "name": "Claude Sonnet 4",

239− "cost_per_1m_in": 3000,

269+ "cost_per_1m_in": 3,

240− "cost_per_1m_out": 15000,

270+ "cost_per_1m_out": 15,

241− "cost_per_1m_in_cached": 300,

271+ "cost_per_1m_in_cached": 3.75,

242− "cost_per_1m_out_cached": 15000,

272+ "cost_per_1m_out_cached": 0.3,

243 "context_window": 200000,

273 "context_window": 200000,

244− "default_max_tokens": 4096,

274+ "default_max_tokens": 50000,

275+ "can_reason": true,

245 "supports_attachments": true

276 "supports_attachments": true

246 }

277 }

247 ]

278 ]

@@ -250,23 +281,56 @@ You can also configure custom Anthropic-compatible providers:

250}

281}

251```

282```

252

283

284+## Logging

285+

286+Sometimes you need to look at logs. Luckily, Crush logs all sorts of

287+stuff. Logs are stored in `./.crush/logs/crush.log` relative to the project.

288+

289+The CLI also contains some helper commands to make perusing recent logs easier:

290+

291+```bash

292+# Print the last 1000 lines

293+crush logs

294+

295+# Print the last 500 lines

296+crush logs --tail 500

297+

298+# Follow logs in real time

299+crush logs --follow

300+```

301+

302+Want more logging? Run `crush` with the `--debug` flag, or enable it in the

303+config:

304+

305+```json

306+{

307+ "options": {

308+ "debug": true,

309+ "debug_lsp": true

310+ }

311+}

312+```

313+

253## Whatcha think?

314## Whatcha think?

254

315

255We’d love to hear your thoughts on this project. Feel free to drop us a note!

316We’d love to hear your thoughts on this project. Feel free to drop us a note!

256

317

257- [Twitter](https://twitter.com/charmcli)

318- [Twitter](https://twitter.com/charmcli)

319+- [Discord][discord]

320+- [Slack](https://charm.land/slack)

258- [The Fediverse](https://mastodon.social/@charmcli)

321- [The Fediverse](https://mastodon.social/@charmcli)

259−- [Discord](https://charm.sh/chat)

322+

323+[discord]: https://charm.land/discord

260

324

261## License

325## License

262

326

263−[MIT](https://github.com/charmbracelet/crush/raw/main/LICENSE)

327+[FSL-1.1-MIT](https://github.com/charmbracelet/crush/raw/main/LICENSE)

264

328

265---

329---

266

330

267Part of [Charm](https://charm.land).

331Part of [Charm](https://charm.land).

268

332

269−<a href="https://charm.sh/"><img alt="The Charm logo" width="400" src="https://stuff.charm.sh/charm-banner-next.jpg" /></a>

333+<a href="https://charm.land/"><img alt="The Charm logo" width="400" src="https://stuff.charm.sh/charm-banner-next.jpg" /></a>

270

334

271

335

272Charm热爱开源 • Charm loves open source

336Charm热爱开源 • Charm loves open source