1> [!NOTE]
2> This is the original OpenCode repository, now continuing at [Charm](https://github.com/charmbracelet) with its original creator, [Kujtim Hoxha](https://github.com/kujtimiihoxha).
3> Development is continuing under a new name as we prepare for a public relaunch.
4> Follow [@charmcli](https://x.com/charmcli) or join our [Discord](https://charm.sh/chat) for updates.
5
6# ⌬ Crush
7
8<p align="center"><img src="https://github.com/user-attachments/assets/9ae61ef6-70e5-4876-bc45-5bcb4e52c714" width="800"></p>
9
10> **⚠️ Early Development Notice:** This project is in early development and is not yet ready for production use. Features may change, break, or be incomplete. Use at your own risk.
11
12A powerful terminal-based AI assistant for developers, providing intelligent coding assistance directly in your terminal.
13
14## Overview
15
16Crush is a Go-based CLI application that brings AI assistance to your terminal. It provides a TUI (Terminal User Interface) for interacting with various AI models to help with coding tasks, debugging, and more.
17
18<p>For a quick video overview, check out
19<a href="https://www.youtube.com/watch?v=P8luPmEa1QI"><img width="25" src="https://upload.wikimedia.org/wikipedia/commons/0/09/YouTube_full-color_icon_%282017%29.svg"> Crush + Gemini 2.5 Pro: BYE Claude Code! I'm SWITCHING To the FASTEST AI Coder!</a></p>
20
21<a href="https://www.youtube.com/watch?v=P8luPmEa1QI"><img width="550" src="https://i3.ytimg.com/vi/P8luPmEa1QI/maxresdefault.jpg"></a><p>
22
23## Features
24
25- **Interactive TUI**: Built with [Bubble Tea](https://github.com/charmbracelet/bubbletea) for a smooth terminal experience
26- **Multiple AI Providers**: Support for OpenAI, Anthropic Claude, Google Gemini, AWS Bedrock, Groq, Azure OpenAI, and OpenRouter
27- **Session Management**: Save and manage multiple conversation sessions
28- **Tool Integration**: AI can execute commands, search files, and modify code
29- **Vim-like Editor**: Integrated editor with text input capabilities
30- **Persistent Storage**: SQLite database for storing conversations and sessions
31- **LSP Integration**: Language Server Protocol support for code intelligence
32- **File Change Tracking**: Track and visualize file changes during sessions
33- **External Editor Support**: Open your preferred editor for composing messages
34- **Named Arguments for Custom Commands**: Create powerful custom commands with multiple named placeholders
35
36## Installation
37
38### Using the Install Script
39
40```bash
41# Install the latest version
42curl -fsSL https://raw.githubusercontent.com/charmbracelet/crush/refs/heads/main/install | bash
43
44# Install a specific version
45curl -fsSL https://raw.githubusercontent.com/charmbracelet/crush/refs/heads/main/install | VERSION=0.1.0 bash
46```
47
48### Using Homebrew (macOS and Linux)
49
50```bash
51brew install crush-ai/tap/crush
52```
53
54### Using AUR (Arch Linux)
55
56```bash
57# Using yay
58yay -S crush-ai-bin
59
60# Using paru
61paru -S crush-ai-bin
62```
63
64### Using Go
65
66```bash
67go install github.com/charmbracelet/crush@latest
68```
69
70## Configuration
71
72Crush looks for configuration in the following locations:
73
74- `$HOME/.crush.json`
75- `$XDG_CONFIG_HOME/crush/.crush.json`
76- `./.crush.json` (local directory)
77
78### Auto Compact Feature
79
80Crush includes an auto compact feature that automatically summarizes your conversation when it approaches the model's context window limit. When enabled (default setting), this feature:
81
82- Monitors token usage during your conversation
83- Automatically triggers summarization when usage reaches 95% of the model's context window
84- Creates a new session with the summary, allowing you to continue your work without losing context
85- Helps prevent "out of context" errors that can occur with long conversations
86
87You can enable or disable this feature in your configuration file:
88
89```json
90{
91 "autoCompact": true // default is true
92}
93```
94
95### Environment Variables
96
97You can configure Crush using environment variables:
98
99| Environment Variable | Purpose |
100| -------------------------- | ------------------------------------------------------ |
101| `ANTHROPIC_API_KEY` | For Claude models |
102| `OPENAI_API_KEY` | For OpenAI models |
103| `GEMINI_API_KEY` | For Google Gemini models |
104| `VERTEXAI_PROJECT` | For Google Cloud VertexAI (Gemini) |
105| `VERTEXAI_LOCATION` | For Google Cloud VertexAI (Gemini) |
106| `GROQ_API_KEY` | For Groq models |
107| `AWS_ACCESS_KEY_ID` | For AWS Bedrock (Claude) |
108| `AWS_SECRET_ACCESS_KEY` | For AWS Bedrock (Claude) |
109| `AWS_REGION` | For AWS Bedrock (Claude) |
110| `AZURE_OPENAI_ENDPOINT` | For Azure OpenAI models |
111| `AZURE_OPENAI_API_KEY` | For Azure OpenAI models (optional when using Entra ID) |
112| `AZURE_OPENAI_API_VERSION` | For Azure OpenAI models |
113| `LOCAL_ENDPOINT` | For self-hosted models |
114| `SHELL` | Default shell to use (if not specified in config) |
115
116### Shell Configuration
117
118Crush allows you to configure the shell used by the bash tool. By default, it uses the shell specified in the `SHELL` environment variable, or falls back to `/bin/bash` if not set.
119
120You can override this in your configuration file:
121
122```json
123{
124 "shell": {
125 "path": "/bin/zsh",
126 "args": ["-l"]
127 }
128}
129```
130
131This is useful if you want to use a different shell than your default system shell, or if you need to pass specific arguments to the shell.
132
133### Configuration File Structure
134
135```json
136{
137 "data": {
138 "directory": ".crush"
139 },
140 "providers": {
141 "openai": {
142 "apiKey": "your-api-key",
143 "disabled": false
144 },
145 "anthropic": {
146 "apiKey": "your-api-key",
147 "disabled": false
148 },
149 "groq": {
150 "apiKey": "your-api-key",
151 "disabled": false
152 },
153 "openrouter": {
154 "apiKey": "your-api-key",
155 "disabled": false
156 }
157 },
158 "agents": {
159 "coder": {
160 "model": "claude-3.7-sonnet",
161 "maxTokens": 5000
162 },
163 "task": {
164 "model": "claude-3.7-sonnet",
165 "maxTokens": 5000
166 },
167 "title": {
168 "model": "claude-3.7-sonnet",
169 "maxTokens": 80
170 }
171 },
172 "shell": {
173 "path": "/bin/bash",
174 "args": ["-l"]
175 },
176 "mcpServers": {
177 "example": {
178 "type": "stdio",
179 "command": "path/to/mcp-server",
180 "env": [],
181 "args": []
182 }
183 },
184 "lsp": {
185 "go": {
186 "disabled": false,
187 "command": "gopls"
188 }
189 },
190 "debug": false,
191 "debugLSP": false,
192 "autoCompact": true
193}
194```
195
196## Supported AI Models
197
198Crush supports a variety of AI models from different providers:
199
200### OpenAI
201
202- GPT-4.1 family (gpt-4.1, gpt-4.1-mini, gpt-4.1-nano)
203- GPT-4.5 Preview
204- GPT-4o family (gpt-4o, gpt-4o-mini)
205- O1 family (o1, o1-pro, o1-mini)
206- O3 family (o3, o3-mini)
207- O4 Mini
208
209### Anthropic
210
211- Claude 4 Sonnet
212- Claude 4 Opus
213- Claude 3.5 Sonnet
214- Claude 3.5 Haiku
215- Claude 3.7 Sonnet
216- Claude 3 Haiku
217- Claude 3 Opus
218
219### Google
220
221- Gemini 2.5
222- Gemini 2.5 Flash
223- Gemini 2.0 Flash
224- Gemini 2.0 Flash Lite
225
226### AWS Bedrock
227
228- Claude 3.7 Sonnet
229
230### Groq
231
232- Llama 4 Maverick (17b-128e-instruct)
233- Llama 4 Scout (17b-16e-instruct)
234- QWEN QWQ-32b
235- Deepseek R1 distill Llama 70b
236- Llama 3.3 70b Versatile
237
238### Azure OpenAI
239
240- GPT-4.1 family (gpt-4.1, gpt-4.1-mini, gpt-4.1-nano)
241- GPT-4.5 Preview
242- GPT-4o family (gpt-4o, gpt-4o-mini)
243- O1 family (o1, o1-mini)
244- O3 family (o3, o3-mini)
245- O4 Mini
246
247### Google Cloud VertexAI
248
249- Gemini 2.5
250- Gemini 2.5 Flash
251
252## Usage
253
254```bash
255# Start Crush
256crush
257
258# Start with debug logging
259crush -d
260
261# Start with a specific working directory
262crush -c /path/to/project
263```
264
265## Non-interactive Prompt Mode
266
267You can run Crush in non-interactive mode by passing a prompt directly as a command-line argument. This is useful for scripting, automation, or when you want a quick answer without launching the full TUI.
268
269```bash
270# Run a single prompt and print the AI's response to the terminal
271crush -p "Explain the use of context in Go"
272
273# Get response in JSON format
274crush -p "Explain the use of context in Go" -f json
275
276# Run without showing the spinner (useful for scripts)
277crush -p "Explain the use of context in Go" -q
278```
279
280In this mode, Crush will process your prompt, print the result to standard output, and then exit. All permissions are auto-approved for the session.
281
282By default, a spinner animation is displayed while the model is processing your query. You can disable this spinner with the `-q` or `--quiet` flag, which is particularly useful when running Crush from scripts or automated workflows.
283
284### Output Formats
285
286Crush supports the following output formats in non-interactive mode:
287
288| Format | Description |
289| ------ | ------------------------------- |
290| `text` | Plain text output (default) |
291| `json` | Output wrapped in a JSON object |
292
293The output format is implemented as a strongly-typed `OutputFormat` in the codebase, ensuring type safety and validation when processing outputs.
294
295## Command-line Flags
296
297| Flag | Short | Description |
298| ----------------- | ----- | --------------------------------------------------- |
299| `--help` | `-h` | Display help information |
300| `--debug` | `-d` | Enable debug mode |
301| `--cwd` | `-c` | Set current working directory |
302| `--prompt` | `-p` | Run a single prompt in non-interactive mode |
303| `--output-format` | `-f` | Output format for non-interactive mode (text, json) |
304| `--quiet` | `-q` | Hide spinner in non-interactive mode |
305
306## Keyboard Shortcuts
307
308### Global Shortcuts
309
310| Shortcut | Action |
311| -------- | ------------------------------------------------------- |
312| `Ctrl+C` | Quit application |
313| `Ctrl+?` | Toggle help dialog |
314| `?` | Toggle help dialog (when not in editing mode) |
315| `Ctrl+L` | View logs |
316| `Ctrl+A` | Switch session |
317| `Ctrl+K` | Command dialog |
318| `Ctrl+O` | Toggle model selection dialog |
319| `Esc` | Close current overlay/dialog or return to previous mode |
320
321### Chat Page Shortcuts
322
323| Shortcut | Action |
324| -------- | --------------------------------------- |
325| `Ctrl+N` | Create new session |
326| `Ctrl+X` | Cancel current operation/generation |
327| `i` | Focus editor (when not in writing mode) |
328| `Esc` | Exit writing mode and focus messages |
329
330### Editor Shortcuts
331
332| Shortcut | Action |
333| ------------------- | ----------------------------------------- |
334| `Ctrl+S` | Send message (when editor is focused) |
335| `Enter` or `Ctrl+S` | Send message (when editor is not focused) |
336| `Ctrl+E` | Open external editor |
337| `Esc` | Blur editor and focus messages |
338
339### Session Dialog Shortcuts
340
341| Shortcut | Action |
342| ---------- | ---------------- |
343| `↑` or `k` | Previous session |
344| `↓` or `j` | Next session |
345| `Enter` | Select session |
346| `Esc` | Close dialog |
347
348### Model Dialog Shortcuts
349
350| Shortcut | Action |
351| ---------- | ----------------- |
352| `↑` or `k` | Move up |
353| `↓` or `j` | Move down |
354| `←` or `h` | Previous provider |
355| `→` or `l` | Next provider |
356| `Esc` | Close dialog |
357
358### Permission Dialog Shortcuts
359
360| Shortcut | Action |
361| ----------------------- | ---------------------------- |
362| `←` or `left` | Switch options left |
363| `→` or `right` or `tab` | Switch options right |
364| `Enter` or `space` | Confirm selection |
365| `a` | Allow permission |
366| `A` | Allow permission for session |
367| `d` | Deny permission |
368
369### Logs Page Shortcuts
370
371| Shortcut | Action |
372| ------------------ | ------------------- |
373| `Backspace` or `q` | Return to chat page |
374
375## AI Assistant Tools
376
377Crush's AI assistant has access to various tools to help with coding tasks:
378
379### File and Code Tools
380
381| Tool | Description | Parameters |
382| ------------- | --------------------------- | ---------------------------------------------------------------------------------------- |
383| `glob` | Find files by pattern | `pattern` (required), `path` (optional) |
384| `grep` | Search file contents | `pattern` (required), `path` (optional), `include` (optional), `literal_text` (optional) |
385| `ls` | List directory contents | `path` (optional), `ignore` (optional array of patterns) |
386| `view` | View file contents | `file_path` (required), `offset` (optional), `limit` (optional) |
387| `write` | Write to files | `file_path` (required), `content` (required) |
388| `edit` | Edit files | Various parameters for file editing |
389| `patch` | Apply patches to files | `file_path` (required), `diff` (required) |
390| `diagnostics` | Get diagnostics information | `file_path` (optional) |
391
392### Other Tools
393
394| Tool | Description | Parameters |
395| ------------- | -------------------------------------- | ----------------------------------------------------------------------------------------- |
396| `bash` | Execute shell commands | `command` (required), `timeout` (optional) |
397| `fetch` | Fetch data from URLs | `url` (required), `format` (required), `timeout` (optional) |
398| `sourcegraph` | Search code across public repositories | `query` (required), `count` (optional), `context_window` (optional), `timeout` (optional) |
399| `agent` | Run sub-tasks with the AI agent | `prompt` (required) |
400
401## Architecture
402
403Crush is built with a modular architecture:
404
405- **cmd**: Command-line interface using Cobra
406- **internal/app**: Core application services
407- **internal/config**: Configuration management
408- **internal/db**: Database operations and migrations
409- **internal/llm**: LLM providers and tools integration
410- **internal/tui**: Terminal UI components and layouts
411- **internal/logging**: Logging infrastructure
412- **internal/message**: Message handling
413- **internal/session**: Session management
414- **internal/lsp**: Language Server Protocol integration
415
416## Custom Commands
417
418Crush supports custom commands that can be created by users to quickly send predefined prompts to the AI assistant.
419
420### Creating Custom Commands
421
422Custom commands are predefined prompts stored as Markdown files in one of three locations:
423
4241. **User Commands** (prefixed with `user:`):
425
426 ```
427 $XDG_CONFIG_HOME/crush/commands/
428 ```
429
430 (typically `~/.config/crush/commands/` on Linux/macOS)
431
432 or
433
434 ```
435 $HOME/.crush/commands/
436 ```
437
4382. **Project Commands** (prefixed with `project:`):
439
440 ```
441 <PROJECT DIR>/.crush/commands/
442 ```
443
444Each `.md` file in these directories becomes a custom command. The file name (without extension) becomes the command ID.
445
446For example, creating a file at `~/.config/crush/commands/prime-context.md` with content:
447
448```markdown
449RUN git ls-files
450READ README.md
451```
452
453This creates a command called `user:prime-context`.
454
455### Command Arguments
456
457Crush supports named arguments in custom commands using placeholders in the format `$NAME` (where NAME consists of uppercase letters, numbers, and underscores, and must start with a letter).
458
459For example:
460
461```markdown
462# Fetch Context for Issue $ISSUE_NUMBER
463
464RUN gh issue view $ISSUE_NUMBER --json title,body,comments
465RUN git grep --author="$AUTHOR_NAME" -n .
466RUN grep -R "$SEARCH_PATTERN" $DIRECTORY
467```
468
469When you run a command with arguments, Crush will prompt you to enter values for each unique placeholder. Named arguments provide several benefits:
470
471- Clear identification of what each argument represents
472- Ability to use the same argument multiple times
473- Better organization for commands with multiple inputs
474
475### Organizing Commands
476
477You can organize commands in subdirectories:
478
479```
480~/.config/crush/commands/git/commit.md
481```
482
483This creates a command with ID `user:git:commit`.
484
485### Using Custom Commands
486
4871. Press `Ctrl+K` to open the command dialog
4882. Select your custom command (prefixed with either `user:` or `project:`)
4893. Press Enter to execute the command
490
491The content of the command file will be sent as a message to the AI assistant.
492
493### Built-in Commands
494
495Crush includes several built-in commands:
496
497| Command | Description |
498| ------------------ | --------------------------------------------------------------------------------------------------- |
499| Initialize Project | Creates or updates the CRUSH.md memory file with project-specific information |
500| Compact Session | Manually triggers the summarization of the current session, creating a new session with the summary |
501
502## MCP (Model Context Protocol)
503
504Crush implements the Model Context Protocol (MCP) to extend its capabilities through external tools. MCP provides a standardized way for the AI assistant to interact with external services and tools.
505
506### MCP Features
507
508- **External Tool Integration**: Connect to external tools and services via a standardized protocol
509- **Tool Discovery**: Automatically discover available tools from MCP servers
510- **Multiple Connection Types**:
511 - **Stdio**: Communicate with tools via standard input/output
512 - **SSE**: Communicate with tools via Server-Sent Events
513- **Security**: Permission system for controlling access to MCP tools
514
515### Configuring MCP Servers
516
517MCP servers are defined in the configuration file under the `mcpServers` section:
518
519```json
520{
521 "mcpServers": {
522 "example": {
523 "type": "stdio",
524 "command": "path/to/mcp-server",
525 "env": [],
526 "args": []
527 },
528 "web-example": {
529 "type": "sse",
530 "url": "https://example.com/mcp",
531 "headers": {
532 "Authorization": "Bearer token"
533 }
534 }
535 }
536}
537```
538
539### MCP Tool Usage
540
541Once configured, MCP tools are automatically available to the AI assistant alongside built-in tools. They follow the same permission model as other tools, requiring user approval before execution.
542
543## LSP (Language Server Protocol)
544
545Crush integrates with Language Server Protocol to provide code intelligence features across multiple programming languages.
546
547### LSP Features
548
549- **Multi-language Support**: Connect to language servers for different programming languages
550- **Diagnostics**: Receive error checking and linting information
551- **File Watching**: Automatically notify language servers of file changes
552
553### Configuring LSP
554
555Language servers are configured in the configuration file under the `lsp` section:
556
557```json
558{
559 "lsp": {
560 "go": {
561 "disabled": false,
562 "command": "gopls"
563 },
564 "typescript": {
565 "disabled": false,
566 "command": "typescript-language-server",
567 "args": ["--stdio"]
568 }
569 }
570}
571```
572
573### LSP Integration with AI
574
575The AI assistant can access LSP features through the `diagnostics` tool, allowing it to:
576
577- Check for errors in your code
578- Suggest fixes based on diagnostics
579
580While the LSP client implementation supports the full LSP protocol (including completions, hover, definition, etc.), currently only diagnostics are exposed to the AI assistant.
581
582## Using a self-hosted model provider
583
584Crush can also load and use models from a self-hosted (OpenAI-like) provider.
585This is useful for developers who want to experiment with custom models.
586
587### Configuring a self-hosted provider
588
589You can use a self-hosted model by setting the `LOCAL_ENDPOINT` environment variable.
590This will cause Crush to load and use the models from the specified endpoint.
591
592```bash
593LOCAL_ENDPOINT=http://localhost:1235/v1
594```
595
596### Configuring a self-hosted model
597
598You can also configure a self-hosted model in the configuration file under the `agents` section:
599
600```json
601{
602 "agents": {
603 "coder": {
604 "model": "local.granite-3.3-2b-instruct@q8_0",
605 "reasoningEffort": "high"
606 }
607 }
608}
609```
610
611## Development
612
613### Prerequisites
614
615- Go 1.24.0 or higher
616
617### Building from Source
618
619```bash
620# Clone the repository
621git clone https://github.com/charmbracelet/crush.git
622cd crush
623
624# Build
625go build -o crush
626
627# Run
628./crush
629```
630
631## Acknowledgments
632
633Crush gratefully acknowledges the contributions and support from these key individuals:
634
635- [@isaacphi](https://github.com/isaacphi) - For the [mcp-language-server](https://github.com/isaacphi/mcp-language-server) project which provided the foundation for our LSP client implementation
636- [@adamdottv](https://github.com/adamdottv) - For the design direction and UI/UX architecture
637
638Special thanks to the broader open source community whose tools and libraries have made this project possible.
639
640## License
641
642Crush is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
643
644## Contributing
645
646Contributions are welcome! Here's how you can contribute:
647
6481. Fork the repository
6492. Create a feature branch (`git checkout -b feature/amazing-feature`)
6503. Commit your changes (`git commit -m 'Add some amazing feature'`)
6514. Push to the branch (`git push origin feature/amazing-feature`)
6525. Open a Pull Request
653
654Please make sure to update tests as appropriate and follow the existing code style.