diff --git a/README.md b/README.md index c13138e197a3bdae140fb8a0fcf402fe78757faf..18767a8fc74fc1583caebb1e66d9c2e9a1feb77f 100644 --- a/README.md +++ b/README.md @@ -1,654 +1,25 @@ -> [!NOTE] -> This is the original OpenCode repository, now continuing at [Charm](https://github.com/charmbracelet) with its original creator, [Kujtim Hoxha](https://github.com/kujtimiihoxha). -> Development is continuing under a new name as we prepare for a public relaunch. -> Follow [@charmcli](https://x.com/charmcli) or join our [Discord](https://charm.sh/chat) for updates. +> [!WARNING] +> 🚧 This is a pre-release under heavy, active development. Things are still in flux but we’re excited to share early progress. -# ⌬ Crush +# Crush -

+

+ Latest Release + Build Status +

-> **⚠️ 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. +Crush is a tool for building software with AI. -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](https://github.com/charmbracelet/bubbletea) 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 - -```bash -# 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) - -```bash -brew install crush-ai/tap/crush -``` - -### Using AUR (Arch Linux) - -```bash -# Using yay -yay -S crush-ai-bin - -# Using paru -paru -S crush-ai-bin -``` - -### Using Go - -```bash -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: - -```json -{ - "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: - -```json -{ - "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 - -```json -{ - "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 - -```bash -# 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. - -```bash -# 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:`): - - ``` - /.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: - -```markdown -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: - -```markdown -# 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: - -```json -{ - "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: - -```json -{ - "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. - -```bash -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: - -```json -{ - "agents": { - "coder": { - "model": "local.granite-3.3-2b-instruct@q8_0", - "reasoningEffort": "high" - } - } -} -``` - -## Development - -### Prerequisites - -- Go 1.24.0 or higher - -### Building from Source - -```bash -# 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](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 -- [@adamdottv](https://github.com/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](LICENSE) file for details. +[MIT](https://github.com/charmbracelet/crush/raw/main/LICENSE) -## Contributing +--- -Contributions are welcome! Here's how you can contribute: +Part of [Charm](https://charm.sh). -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 +The Charm logo -Please make sure to update tests as appropriate and follow the existing code style. + +Charm热爱开源 • Charm loves open source