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
15Nightly builds are available while Crush is in development.
16
17- [Packages](https://github.com/charmbracelet/crush/releases/tag/nightly) are available in Debian and RPM formats
18- [Binaries](https://github.com/charmbracelet/crush/releases/tag/nightly) are available for Linux and macOS
19
20You can also just install it with go:
21
22```
23git clone git@github.com:charmbracelet/crush.git
24cd crush
25go install
26```
27
28Note that Crush doesn't support Windows yet, however Windows support is planned and in progress.
29
30## Getting Started
31
32For now, the quickest way to get started is to set an environment variable for
33your preferred provider. Note that you can switch between providers mid-
34sessions, so you're welcome to set environment variables for multiple
35providers.
36
37| Environment Variable | Provider |
38| -------------------------- | -------------------------------------------------- |
39| `ANTHROPIC_API_KEY` | Anthropic |
40| `OPENAI_API_KEY` | OpenAI |
41| `GEMINI_API_KEY` | Google Gemini |
42| `VERTEXAI_PROJECT` | Google Cloud VertexAI (Gemini) |
43| `VERTEXAI_LOCATION` | Google Cloud VertexAI (Gemini) |
44| `GROQ_API_KEY` | Groq |
45| `AWS_ACCESS_KEY_ID` | AWS Bedrock (Claude) |
46| `AWS_SECRET_ACCESS_KEY` | AWS Bedrock (Claude) |
47| `AWS_REGION` | AWS Bedrock (Claude) |
48| `AZURE_OPENAI_ENDPOINT` | Azure OpenAI models |
49| `AZURE_OPENAI_API_KEY` | Azure OpenAI models (optional when using Entra ID) |
50| `AZURE_OPENAI_API_VERSION` | Azure OpenAI models |
51
52## Configuration
53
54For 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:
55
561. `.crush.json`
572. `crush.json`
583. `$HOME/.config/crush/crush.json`
59
60### LSPs
61
62Crush can use LSPs for additional context to help inform its decisions, just like you would. LSPs can be added manually like so:
63
64```json
65{
66 "lsp": {
67 "go": {
68 "command": "gopls"
69 },
70 "typescript": {
71 "command": "typescript-language-server",
72 "args": ["--stdio"]
73 },
74 "nix": {
75 "command": "alejandra"
76 }
77 }
78}
79```
80
81### OpenAI-Compatible APIs
82
83Crush 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.
84
85```json
86{
87 "providers": {
88 "deepseek": {
89 "provider_type": "openai",
90 "base_url": "https://api.deepseek.com/v1",
91 "models": [
92 {
93 "id": "deepseek-chat",
94 "model": "Deepseek V3",
95 "cost_per_1m_in": 0.27,
96 "cost_per_1m_out": 1.1,
97 "cost_per_1m_in_cached": 0.07,
98 "cost_per_1m_out_cached": 1.1,
99 "context_window": 64000,
100 "default_max_tokens": 5000
101 }
102 ]
103 }
104 }
105}
106```
107
108### Local AI Model Providers
109
110Crush is compatible with local AI model applications that implement OpenAI's API standard. This includes popular tools like Ollama, LM Studio, LocalAI, Jan.ai, and many others. Running models locally gives you complete privacy and control over your AI infrastructure.
111
112#### Ollama
113
114[Ollama](https://ollama.com) is a popular tool for running AI models locally. It packages models with all dependencies, making deployment simple and reliable.
115
116**Installation:**
117```bash
118# Install Ollama
119curl -fsSL https://ollama.com/install.sh | sh
120
121# Download and run a model
122ollama run llama3.2:3b
123```
124
125**Auto-Discovery:**
126Crush automatically detects Ollama installations and discovers available models without any configuration needed. Simply install Ollama and pull models - they'll appear in the model switcher automatically.
127
128**Manual Configuration (Optional):**
129For advanced use cases or custom configurations, you can manually define Ollama providers:
130
131```json
132{
133 "providers": {
134 "ollama": {
135 "type": "openai",
136 "base_url": "http://localhost:11434/v1",
137 "api_key": "ollama",
138 "models": [
139 {
140 "id": "llama3.2:3b",
141 "model": "Llama 3.2 3B",
142 "context_window": 131072,
143 "default_max_tokens": 4096,
144 "cost_per_1m_in": 0,
145 "cost_per_1m_out": 0
146 }
147 ]
148 }
149 }
150}
151```
152
153#### Other Local AI Tools
154
155For other local AI applications (LM Studio, LocalAI, Jan.ai, etc.), you can configure them manually using the OpenAI-compatible API format shown above.
156
157## Whatcha think?
158
159We’d love to hear your thoughts on this project. Feel free to drop us a note!
160
161- [Twitter](https://twitter.com/charmcli)
162- [The Fediverse](https://mastodon.social/@charmcli)
163- [Discord](https://charm.sh/chat)
164
165## License
166
167[MIT](https://github.com/charmbracelet/crush/raw/main/LICENSE)
168
169---
170
171Part of [Charm](https://charm.land).
172
173<a href="https://charm.sh/"><img alt="The Charm logo" width="400" src="https://stuff.charm.sh/charm-banner-next.jpg" /></a>
174
175<!--prettier-ignore-->
176Charm热爱开源 • Charm loves open source