Crush

About the Project

Crush is an open-source AI coding agent developed by Charm that runs in the terminal. It supports multi-model switching, LSP integration, MCP servers, and agentic coding workflows, with a polished UI and smooth interactions.

• GitHub: https://github.com/charmbracelet/crush

📦 Before You Begin

What you'll need

• Node.js installed
• A working Models Hub address (must end with /v1)
• A working Models Hub API Key (generated in the console)
• The name of the model you want to use (such as claude-sonnet-4-6, gemini-2.5-flash, etc.), which must exactly match the model ID in the Models Hub console

🚀 Step 1: Install Crush

npm install -g @charmland/crush

macOS users can also install via Homebrew:

brew install charmbracelet/tap/crush

Verify the installation:

crush --version

🔧 Step 2: Edit the Configuration File

Configuration file location:

• Linux / macOS: ~/.config/crush/crush.json
• Windows: %USERPROFILE%\.config\crush\crush.json

If the file does not exist, create it yourself. Fill in the following content:

{
  "$schema": "https://charm.land/crush.json",
  "providers": {
    "modelsok": {
      "type": "openai-compat",
      "base_url": "https://modelsok.com/v1",
      "api_key": "$MODELSOK_API_KEY",
      "models": [
        {
          "id": "claude-sonnet-4-6",
          "name": "Claude Sonnet 4.6",
          "context_window": 200000,
          "default_max_tokens": 32768,
          "can_reason": true
        },
        {
          "id": "gemini-2.5-flash",
          "name": "Gemini 2.5 Flash",
          "context_window": 1000000,
          "default_max_tokens": 32768,
          "can_reason": false
        }
      ]
    }
  }
}

Key fields

• type must be openai-compat
• base_url must end with /v1
• api_key references the $MODELSOK_API_KEY variable, avoiding writing the plaintext key into the configuration file
• models[].id must exactly match the Models Hub console

🔑 Step 3: Set the Environment Variable

Linux / macOS

export MODELSOK_API_KEY="ms_live_your_key"

Windows (PowerShell)

$env:MODELSOK_API_KEY="your-modelsok-api-key"

It's recommended to write this into your shell configuration file to make it persistent.

✅ Step 4: Launch and Select a Model

Enter your project directory:

cd /path/to/my-project
crush

Press Ctrl+L (or type /model) to open the model switcher, select the modelsok provider, then choose your target model. Send a test message to verify the response.

❓ FAQ