crush-code-agent-ide/README.md

⌬ Crush

⚠️ 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.

A powerful terminal-based AI assistant for developers, providing intelligent coding assistance directly in your terminal.

Overview

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

For a quick video overview, check out Crush + Gemini 2.5 Pro: BYE Claude Code! I'm SWITCHING To the FASTEST AI Coder!

Features

• Interactive TUI: Built with Bubble Tea for a smooth terminal experience
• Multiple AI Providers: Support for OpenAI, Anthropic Claude, Google Gemini, AWS Bedrock, Groq, Azure OpenAI, and OpenRouter
• Session Management: Save and manage multiple conversation sessions
• Tool Integration: AI can execute commands, search files, and modify code
• Vim-like Editor: Integrated editor with text input capabilities
• Persistent Storage: SQLite database for storing conversations and sessions
• LSP Integration: Language Server Protocol support for code intelligence
• File Change Tracking: Track and visualize file changes during sessions
• External Editor Support: Open your preferred editor for composing messages
• Named Arguments for Custom Commands: Create powerful custom commands with multiple named placeholders

Installation

Using the Install Script

# Install the latest version
curl -fsSL https://raw.githubusercontent.com/charmbracelet/crush/refs/heads/main/install | bash

# Install a specific version
curl -fsSL https://raw.githubusercontent.com/charmbracelet/crush/refs/heads/main/install | VERSION=0.1.0 bash

Using Homebrew (macOS and Linux)

brew install crush-ai/tap/crush

Using AUR (Arch Linux)

# Using yay
yay -S crush-ai-bin

# Using paru
paru -S crush-ai-bin

Using Go

go install github.com/charmbracelet/crush@latest

Configuration

Crush looks for configuration in the following locations:

• $HOME/.crush.json
• $XDG_CONFIG_HOME/crush/.crush.json
• ./.crush.json (local directory)

Auto Compact Feature

Crush 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:

• Monitors token usage during your conversation
• Automatically triggers summarization when usage reaches 95% of the model's context window
• Creates a new session with the summary, allowing you to continue your work without losing context
• Helps prevent "out of context" errors that can occur with long conversations

You can enable or disable this feature in your configuration file:

{
  "autoCompact": true // default is true
}

Environment Variables

You can configure Crush using environment variables:

Environment Variable	Purpose
ANTHROPIC_API_KEY	For Claude models
OPENAI_API_KEY	For OpenAI models
GEMINI_API_KEY	For Google Gemini models
VERTEXAI_PROJECT	For Google Cloud VertexAI (Gemini)
VERTEXAI_LOCATION	For Google Cloud VertexAI (Gemini)
GROQ_API_KEY	For Groq models
AWS_ACCESS_KEY_ID	For AWS Bedrock (Claude)
AWS_SECRET_ACCESS_KEY	For AWS Bedrock (Claude)
AWS_REGION	For AWS Bedrock (Claude)
AZURE_OPENAI_ENDPOINT	For Azure OpenAI models
AZURE_OPENAI_API_KEY	For Azure OpenAI models (optional when using Entra ID)
AZURE_OPENAI_API_VERSION	For Azure OpenAI models
LOCAL_ENDPOINT	For self-hosted models
SHELL	Default shell to use (if not specified in config)

Shell Configuration

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

You can override this in your configuration file:

{
  "shell": {
    "path": "/bin/zsh",
    "args": ["-l"]
  }
}

This 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.

Configuration File Structure

{
  "data": {
    "directory": ".crush"
  },
  "providers": {
    "openai": {
      "apiKey": "your-api-key",
      "disabled": false
    },
    "anthropic": {
      "apiKey": "your-api-key",
      "disabled": false
    },
    "groq": {
      "apiKey": "your-api-key",
      "disabled": false
    },
    "openrouter": {
      "apiKey": "your-api-key",
      "disabled": false
    }
  },
  "agents": {
    "coder": {
      "model": "claude-3.7-sonnet",
      "maxTokens": 5000
    },
    "task": {
      "model": "claude-3.7-sonnet",
      "maxTokens": 5000
    },
    "title": {
      "model": "claude-3.7-sonnet",
      "maxTokens": 80
    }
  },
  "shell": {
    "path": "/bin/bash",
    "args": ["-l"]
  },
  "mcpServers": {
    "example": {
      "type": "stdio",
      "command": "path/to/mcp-server",
      "env": [],
      "args": []
    }
  },
  "lsp": {
    "go": {
      "disabled": false,
      "command": "gopls"
    }
  },
  "debug": false,
  "debugLSP": false,
  "autoCompact": true
}

Supported AI Models

Crush supports a variety of AI models from different providers:

OpenAI

• GPT-4.1 family (gpt-4.1, gpt-4.1-mini, gpt-4.1-nano)
• GPT-4.5 Preview
• GPT-4o family (gpt-4o, gpt-4o-mini)
• O1 family (o1, o1-pro, o1-mini)
• O3 family (o3, o3-mini)
• O4 Mini

Anthropic

• Claude 4 Sonnet
• Claude 4 Opus
• Claude 3.5 Sonnet
• Claude 3.5 Haiku
• Claude 3.7 Sonnet
• Claude 3 Haiku
• Claude 3 Opus

Google

• Gemini 2.5
• Gemini 2.5 Flash
• Gemini 2.0 Flash
• Gemini 2.0 Flash Lite

AWS Bedrock

• Claude 3.7 Sonnet

Groq

• Llama 4 Maverick (17b-128e-instruct)
• Llama 4 Scout (17b-16e-instruct)
• QWEN QWQ-32b
• Deepseek R1 distill Llama 70b
• Llama 3.3 70b Versatile

Azure OpenAI

• GPT-4.1 family (gpt-4.1, gpt-4.1-mini, gpt-4.1-nano)
• GPT-4.5 Preview
• GPT-4o family (gpt-4o, gpt-4o-mini)
• O1 family (o1, o1-mini)
• O3 family (o3, o3-mini)
• O4 Mini

Google Cloud VertexAI

• Gemini 2.5
• Gemini 2.5 Flash

Usage

# Start Crush
crush

# Start with debug logging
crush -d

# Start with a specific working directory
crush -c /path/to/project

Non-interactive Prompt Mode

You 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.

# Run a single prompt and print the AI's response to the terminal
crush -p "Explain the use of context in Go"

# Get response in JSON format
crush -p "Explain the use of context in Go" -f json

# Run without showing the spinner (useful for scripts)
crush -p "Explain the use of context in Go" -q

In this mode, Crush will process your prompt, print the result to standard output, and then exit. All permissions are auto-approved for the session.

By 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.

Output Formats

Crush supports the following output formats in non-interactive mode:

Format	Description
text	Plain text output (default)
json	Output wrapped in a JSON object

The output format is implemented as a strongly-typed OutputFormat in the codebase, ensuring type safety and validation when processing outputs.

Command-line Flags

Flag	Short	Description
--help	-h	Display help information
--debug	-d	Enable debug mode
--cwd	-c	Set current working directory
--prompt	-p	Run a single prompt in non-interactive mode
--output-format	-f	Output format for non-interactive mode (text, json)
--quiet	-q	Hide spinner in non-interactive mode

Keyboard Shortcuts

Global Shortcuts

Shortcut	Action
Ctrl+C	Quit application
Ctrl+?	Toggle help dialog
?	Toggle help dialog (when not in editing mode)
Ctrl+L	View logs
Ctrl+A	Switch session
Ctrl+K	Command dialog
Ctrl+O	Toggle model selection dialog
Esc	Close current overlay/dialog or return to previous mode

Chat Page Shortcuts

Shortcut	Action
Ctrl+N	Create new session
Ctrl+X	Cancel current operation/generation
i	Focus editor (when not in writing mode)
Esc	Exit writing mode and focus messages

Editor Shortcuts

Shortcut	Action
Ctrl+S	Send message (when editor is focused)
Enter or Ctrl+S	Send message (when editor is not focused)
Ctrl+E	Open external editor
Esc	Blur editor and focus messages

Session Dialog Shortcuts

Shortcut	Action
↑ or k	Previous session
↓ or j	Next session
Enter	Select session
Esc	Close dialog

Model Dialog Shortcuts

Shortcut	Action
↑ or k	Move up
↓ or j	Move down
← or h	Previous provider
→ or l	Next provider
Esc	Close dialog

Permission Dialog Shortcuts

Shortcut	Action
← or left	Switch options left
→ or right or tab	Switch options right
Enter or space	Confirm selection
a	Allow permission
A	Allow permission for session
d	Deny permission

Logs Page Shortcuts

Shortcut	Action
Backspace or q	Return to chat page

AI Assistant Tools

Crush's AI assistant has access to various tools to help with coding tasks:

File and Code Tools

Tool	Description	Parameters
glob	Find files by pattern	pattern (required), path (optional)
grep	Search file contents	pattern (required), path (optional), include (optional), literal_text (optional)
ls	List directory contents	path (optional), ignore (optional array of patterns)
view	View file contents	file_path (required), offset (optional), limit (optional)
write	Write to files	file_path (required), content (required)
edit	Edit files	Various parameters for file editing
patch	Apply patches to files	file_path (required), diff (required)
diagnostics	Get diagnostics information	file_path (optional)

Other Tools

Tool	Description	Parameters
bash	Execute shell commands	command (required), timeout (optional)
fetch	Fetch data from URLs	url (required), format (required), timeout (optional)
sourcegraph	Search code across public repositories	query (required), count (optional), context_window (optional), timeout (optional)
agent	Run sub-tasks with the AI agent	prompt (required)

Architecture

Crush is built with a modular architecture:

• cmd: Command-line interface using Cobra
• internal/app: Core application services
• internal/config: Configuration management
• internal/db: Database operations and migrations
• internal/llm: LLM providers and tools integration
• internal/tui: Terminal UI components and layouts
• internal/logging: Logging infrastructure
• internal/message: Message handling
• internal/session: Session management
• internal/lsp: Language Server Protocol integration

Custom Commands

Crush supports custom commands that can be created by users to quickly send predefined prompts to the AI assistant.

Creating Custom Commands

Custom commands are predefined prompts stored as Markdown files in one of three locations:

1. User Commands (prefixed with user:):

   $XDG_CONFIG_HOME/crush/commands/
   

   (typically ~/.config/crush/commands/ on Linux/macOS)

   or

   $HOME/.crush/commands/
   

2. Project Commands (prefixed with project:):

   <PROJECT DIR>/.crush/commands/
   

Each .md file in these directories becomes a custom command. The file name (without extension) becomes the command ID.

For example, creating a file at ~/.config/crush/commands/prime-context.md with content:

RUN git ls-files
READ README.md

This creates a command called user:prime-context.

Command Arguments

Crush 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).

For example:

# Fetch Context for Issue $ISSUE_NUMBER

RUN gh issue view $ISSUE_NUMBER --json title,body,comments
RUN git grep --author="$AUTHOR_NAME" -n .
RUN grep -R "$SEARCH_PATTERN" $DIRECTORY

When you run a command with arguments, Crush will prompt you to enter values for each unique placeholder. Named arguments provide several benefits:

• Clear identification of what each argument represents
• Ability to use the same argument multiple times
• Better organization for commands with multiple inputs

Organizing Commands

You can organize commands in subdirectories:

~/.config/crush/commands/git/commit.md

This creates a command with ID user:git:commit.

Using Custom Commands

1. Press Ctrl+K to open the command dialog
2. Select your custom command (prefixed with either user: or project:)
3. Press Enter to execute the command

The content of the command file will be sent as a message to the AI assistant.

Built-in Commands

Crush includes several built-in commands:

Command	Description
Initialize Project	Creates or updates the CRUSH.md memory file with project-specific information
Compact Session	Manually triggers the summarization of the current session, creating a new session with the summary

MCP (Model Context Protocol)

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

MCP Features

• External Tool Integration: Connect to external tools and services via a standardized protocol
• Tool Discovery: Automatically discover available tools from MCP servers
• Multiple Connection Types:
  • Stdio: Communicate with tools via standard input/output
  • SSE: Communicate with tools via Server-Sent Events
• Security: Permission system for controlling access to MCP tools

Configuring MCP Servers

MCP servers are defined in the configuration file under the mcpServers section:

{
  "mcpServers": {
    "example": {
      "type": "stdio",
      "command": "path/to/mcp-server",
      "env": [],
      "args": []
    },
    "web-example": {
      "type": "sse",
      "url": "https://example.com/mcp",
      "headers": {
        "Authorization": "Bearer token"
      }
    }
  }
}

MCP Tool Usage

Once 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.

LSP (Language Server Protocol)

Crush integrates with Language Server Protocol to provide code intelligence features across multiple programming languages.

LSP Features

• Multi-language Support: Connect to language servers for different programming languages
• Diagnostics: Receive error checking and linting information
• File Watching: Automatically notify language servers of file changes

Configuring LSP

Language servers are configured in the configuration file under the lsp section:

{
  "lsp": {
    "go": {
      "disabled": false,
      "command": "gopls"
    },
    "typescript": {
      "disabled": false,
      "command": "typescript-language-server",
      "args": ["--stdio"]
    }
  }
}

LSP Integration with AI

The AI assistant can access LSP features through the diagnostics tool, allowing it to:

• Check for errors in your code
• Suggest fixes based on diagnostics

While the LSP client implementation supports the full LSP protocol (including completions, hover, definition, etc.), currently only diagnostics are exposed to the AI assistant.

Using a self-hosted model provider

Crush can also load and use models from a self-hosted (OpenAI-like) provider. This is useful for developers who want to experiment with custom models.

Configuring a self-hosted provider

You can use a self-hosted model by setting the LOCAL_ENDPOINT environment variable. This will cause Crush to load and use the models from the specified endpoint.

LOCAL_ENDPOINT=http://localhost:1235/v1

Configuring a self-hosted model

You can also configure a self-hosted model in the configuration file under the agents section:

{
  "agents": {
    "coder": {
      "model": "local.granite-3.3-2b-instruct@q8_0",
      "reasoningEffort": "high"
    }
  }
}

Development

Prerequisites

• Go 1.24.0 or higher

Building from Source

# Clone the repository
git clone https://github.com/charmbracelet/crush.git
cd crush

# Build
go build -o crush

# Run
./crush

Acknowledgments

Crush gratefully acknowledges the contributions and support from these key individuals:

• @isaacphi - For the mcp-language-server project which provided the foundation for our LSP client implementation
• @adamdottv - For the design direction and UI/UX architecture

Special thanks to the broader open source community whose tools and libraries have made this project possible.

License

Crush is licensed under the MIT License. See the LICENSE file for details.

Contributing

Contributions are welcome! Here's how you can contribute:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Please make sure to update tests as appropriate and follow the existing code style.