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