README.md · crush · git.iko.soy

git.iko.soy/crush

crush/README.md

235 lines 6.8 kB history raw

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.

4# Crush

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>

11Crush is a tool for building software with AI.

13## Installation

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

17Nightly builds are available while Crush is in development.

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

22You can also just install it with go:

24```

25git clone git@github.com:charmbracelet/crush.git

26cd crush

27go install

28```

30<details>

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

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.

35Next, open a terminal and run the following commands:

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

44Then, run Crush by typing `crush`.

46---

48</details>

50## Getting Started

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.

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

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 |

73## Configuration

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:

771. `.crush.json`

782. `crush.json`

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

81### LSPs

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

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

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,