Crush

<p align="center"> <a href="https://stuff.charm.sh/crush/charm-crush.png"><img width="450" alt="Charm Crush Logo" src="https://github.com/user-attachments/assets/cf8ca3ce-8b02-43f0-9d0f-5a331488da4b" /></a><br /> <a href="https://github.com/charmbracelet/crush/releases"><img src="https://img.shields.io/github/release/charmbracelet/crush" alt="Latest Release"></a> <a href="https://github.com/charmbracelet/crush/actions"><img src="https://github.com/charmbracelet/crush/actions/workflows/build.yml/badge.svg" alt="Build Status"></a> </p> <p align="center">Your new coding bestie, now available in your favourite terminal.<br />Your tools, your code, and your workflows, wired into your LLM of choice.</p> <p align="center">终端里的编程新搭档，<br />无缝接入你的工具、代码与工作流，全面兼容主流 LLM 模型。</p> <p align="center"><img width="800" alt="Crush Demo" src="https://github.com/user-attachments/assets/58280caf-851b-470a-b6f7-d5c4ea8a1968" /></p>

Features

• Multi-Model: choose from a wide range of LLMs or add your own via OpenAI- or Anthropic-compatible APIs
• Flexible: switch LLMs mid-session while preserving context
• Session-Based: maintain multiple work sessions and contexts per project
• LSP-Enhanced: Crush uses LSPs for additional context, just like you do
• Extensible: add capabilities via MCPs (http, stdio, and sse)
• Works Everywhere: first-class support in every terminal on macOS, Linux, Windows (PowerShell and WSL), Android, FreeBSD, OpenBSD, and NetBSD
• Industrial Grade: built on the Charm ecosystem, powering 25k+ applications, from leading open source projects to business-critical infrastructure

Installation

Use a package manager:

# Homebrew
brew install charmbracelet/tap/crush

# NPM
npm install -g @charmland/crush

# Arch Linux (btw)
yay -S crush-bin

# Nix
nix run github:numtide/nix-ai-tools#crush

# FreeBSD
pkg install crush

Windows users:

# Winget
winget install charmbracelet.crush

# Scoop
scoop bucket add charm https://github.com/charmbracelet/scoop-bucket.git
scoop install crush

<details> <summary><strong>Nix (NUR)</strong></summary>

Crush is available via the official Charm NUR in nur.repos.charmbracelet.crush, which is the most up-to-date way to get Crush in Nix.

You can also try out Crush via the NUR with nix-shell:

# Add the NUR channel.
nix-channel --add https://github.com/nix-community/NUR/archive/main.tar.gz nur
nix-channel --update

# Get Crush in a Nix shell.
nix-shell -p '(import <nur> { pkgs = import <nixpkgs> {}; }).repos.charmbracelet.crush'

NixOS & Home Manager Module Usage via NUR

Crush provides NixOS and Home Manager modules via NUR. You can use these modules directly in your flake by importing them from NUR. Since it auto detects whether its a home manager or nixos context you can use the import the exact same way :)

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    nur.url = "github:nix-community/NUR";
  };

  outputs = { self, nixpkgs, nur, ... }: {
    nixosConfigurations.your-hostname = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        nur.modules.nixos.default
        nur.repos.charmbracelet.modules.crush
        {
          programs.crush = {
            enable = true;
            settings = {
              providers = {
                openai = {
                  id = "openai";
                  name = "OpenAI";
                  base_url = "https://api.openai.com/v1";
                  type = "openai";
                  api_key = "sk-fake123456789abcdef...";
                  models = [
                    {
                      id = "gpt-4";
                      name = "GPT-4";
                    }
                  ];
                };
              };
              lsp = {
                go = { command = "gopls"; enabled = true; };
                nix = { command = "nil"; enabled = true; };
              };
              options = {
                context_paths = [ "/etc/nixos/configuration.nix" ];
                tui = { compact_mode = true; };
                debug = false;
              };
            };
          };
        }
      ];
    };
  };
}

</details> <details> <summary><strong>Debian/Ubuntu</strong></summary>

sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://repo.charm.sh/apt/gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/charm.gpg
echo "deb [signed-by=/etc/apt/keyrings/charm.gpg] https://repo.charm.sh/apt/ * *" | sudo tee /etc/apt/sources.list.d/charm.list
sudo apt update && sudo apt install crush

</details> <details> <summary><strong>Fedora/RHEL</strong></summary>

echo '[charm]
name=Charm
baseurl=https://repo.charm.sh/yum/
enabled=1
gpgcheck=1
gpgkey=https://repo.charm.sh/yum/gpg.key' | sudo tee /etc/yum.repos.d/charm.repo
sudo yum install crush

</details>

Or, download it:

• Packages are available in Debian and RPM formats
• Binaries are available for Linux, macOS, Windows, FreeBSD, OpenBSD, and NetBSD

Or just install it with Go:

go install github.com/charmbracelet/crush@latest

[!WARNING] Productivity may increase when using Crush and you may find yourself nerd sniped when first using the application. If the symptoms persist, join the [Discord][discord] and nerd snipe the rest of us.

Getting Started

The quickest way to get started is to grab an API key for your preferred provider such as Anthropic, OpenAI, Groq, OpenRouter, or Vercel AI Gateway and just start Crush. You'll be prompted to enter your API key.

That said, you can also set environment variables for preferred providers.

| Environment Variable | Provider | | --------------------------- | -------------------------------------------------- | | ANTHROPIC_API_KEY | Anthropic | | OPENAI_API_KEY | OpenAI | | VERCEL_API_KEY | Vercel AI Gateway | | GEMINI_API_KEY | Google Gemini | | SYNTHETIC_API_KEY | Synthetic | | ZAI_API_KEY | Z.ai | | MINIMAX_API_KEY | MiniMax | | HF_TOKEN | Hugging Face Inference | | CEREBRAS_API_KEY | Cerebras | | OPENROUTER_API_KEY | OpenRouter | | IONET_API_KEY | io.net | | GROQ_API_KEY | Groq | | VERTEXAI_PROJECT | Google Cloud VertexAI (Gemini) | | VERTEXAI_LOCATION | Google Cloud VertexAI (Gemini) | | AWS_ACCESS_KEY_ID | Amazon Bedrock (Claude) | | AWS_SECRET_ACCESS_KEY | Amazon Bedrock (Claude) | | AWS_REGION | Amazon Bedrock (Claude) | | AWS_PROFILE | Amazon Bedrock (Custom Profile) | | AWS_BEARER_TOKEN_BEDROCK | Amazon Bedrock | | AZURE_OPENAI_API_ENDPOINT | Azure OpenAI models | | AZURE_OPENAI_API_KEY | Azure OpenAI models (optional when using Entra ID) | | AZURE_OPENAI_API_VERSION | Azure OpenAI models |

Subscriptions

If you prefer subscription-based usage, here are some plans that work well in Crush:

• Synthetic
• GLM Coding Plan
• Kimi Code
• MiniMax Coding Plan

By the Way

Is there a provider you’d like to see in Crush? Is there an existing model that needs an update?

Crush’s default model listing is managed in Catwalk, a community-supported, open source repository of Crush-compatible models, and you’re welcome to contribute.

<a href="https://github.com/charmbracelet/catwalk"><img width="174" height="174" alt="Catwalk Badge" src="https://github.com/user-attachments/assets/95b49515-fe82-4409-b10d-5beb0873787d" /></a>

Configuration

[!TIP] Crush ships with a builtin crush-config skill for configuring itself. In many cases you can simply ask Crush to configure itself.

Crush runs great with no configuration. That said, if you do need or want to customize Crush, configuration can be added either local to the project itself, or globally, with the following priority:

1. .crush.json
2. crush.json
3. $HOME/.config/crush/crush.json

Configuration itself is stored as a JSON object:

{
  "this-setting": { "this": "that" },
  "that-setting": ["ceci", "cela"]
}

As an additional note, Crush also stores ephemeral data, such as application state, in one additional location:

# Unix
$HOME/.local/share/crush/crush.json

# Windows
%LOCALAPPDATA%\crush\crush.json

[!TIP] You can override the user and data config locations by setting:

• CRUSH_GLOBAL_CONFIG
• CRUSH_GLOBAL_DATA

LSPs

Crush can use LSPs for additional context to help inform its decisions, just like you would. LSPs can be added manually like so:

{
  "$schema": "https://charm.land/crush.json",
  "lsp": {
    "go": {
      "command": "gopls",
      "env": {
        "GOTOOLCHAIN": "go1.24.5"
      }
    },
    "typescript": {
      "command": "typescript-language-server",
      "args": ["--stdio"]
    },