Imagine having a coding assistant that understands your project, offers helpful suggestions, and fits right into your workflow—all without leaving your terminal. That’s what Crush brings to the table. This clever tool links your code and development setup with powerful language models, making coding faster and easier. Whether you’re new to programming or have years of experience, Crush is built to boost your productivity on systems like macOS, Linux, Windows (PowerShell and WSL), FreeBSD, OpenBSD, and NetBSD.

In this guide, we’ll walk you through everything you need to know about Crush: what it is, its standout features, how to install and set it up, and even how to contribute if you’re interested. All the details come straight from Crush’s technical documentation, so you can trust that it’s accurate and reliable. By the end, you’ll see how Crush can become a key part of your coding routine.

What is Crush?

Crush is a tool you use in your terminal—a command-line program—that connects your coding environment with large language models (LLMs). These models are like smart assistants that help you write code, fix problems, and improve your work, all from the terminal you already use. Crush takes your projects and tools and makes them smarter by tapping into the power of these language models.

It’s perfect for anyone working on code, whether it’s a quick script or a big project. Crush supports many programming languages and setups, acting like a trusty partner that’s always ready to lend a hand.

Key Features of Crush

Crush is packed with useful features that make coding smoother and more enjoyable. Here’s what it offers:

  • Multi-Model Support: You can pick from different language models, like those from OpenAI, Anthropic, or Groq, and even add your own if they work with the right APIs.
  • Flexible Switching: Change between models while you’re working without losing track of what you’re doing—great for testing which one works best.
  • Session Management: Keep multiple tasks going at once, each with its own details, so you can switch between projects easily.
  • LSP Enhancement: Crush uses something called Language Server Protocol (LSP) to get a better sense of your project, giving you spot-on suggestions.
  • Extensibility: Add new features using Model Context Protocol (MCP) servers, which work with http, stdio, or sse connections.
  • Cross-Platform Compatibility: Runs smoothly on macOS, Linux, Windows (PowerShell and WSL), FreeBSD, OpenBSD, and NetBSD.

These features make Crush a flexible tool that fits into all kinds of coding situations, helping you get more done no matter where you work.

How to Install Crush

Getting Crush set up is simple, and there are a few ways to do it depending on what you prefer. You can use a package manager, download ready-made files, or build it yourself with Go. Here’s how:

1. Install via Package Managers

If you like using package managers—tools that handle software installation for you—Crush works with several popular ones:

  • Homebrew (for macOS):

    brew install charmbracelet/tap/crush

    This is a quick way for macOS users to get Crush installed.

  • NPM (for Node.js users):

    npm install -g @charmland/crush

    If you work with JavaScript, this uses the Node.js package manager.

  • Arch Linux (using yay):

    yay -S crush-bin

    A handy option for Arch Linux users.

  • Nix (works on many systems):

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

    This is a flexible choice for various platforms.

Extra Options for Specific Systems

  • Debian or Ubuntu:

    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

    This sets up a repository and installs Crush on Debian-based systems.

  • Fedora or RHEL:

    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

    This works for Fedora or Red Hat-based systems.

2. Download Pre-Compiled Binaries

Don’t want to use a package manager? You can grab ready-to-use files from Crush’s GitHub releases page. Options include:

  • Packages: Files like .deb for Debian or .rpm for Fedora.
  • Binaries: Files for Linux, macOS, Windows, FreeBSD, OpenBSD, and NetBSD.

Just download the one that matches your system, and you’re set.

3. Install with Go

If you use the Go programming language, you can install Crush with this command:

go install github.com/charmbracelet/crush@latest

After installing, type crush in your terminal to check if it’s working. If it runs, you’re ready to go!

Quick Note: Crush can be a game-changer for your workflow. If you run into trouble or have questions, hop over to the Discord community to chat with others or get help.

Getting Started with Crush

Once Crush is installed, it’s time to set it up and start using it. The first thing you’ll need is an API key to connect it to a language model.

Step 1: Get an API Key

Crush needs an API key from a provider like Anthropic, OpenAI, Groq, or OpenRouter. Think of this key as a password that lets Crush talk to these smart models. After you get your key, you can either type it in when Crush asks or set it up ahead of time using an environment variable.

Here are some common environment variables for popular providers:

Variable Name Provider
ANTHROPIC_API_KEY Anthropic
OPENAI_API_KEY OpenAI
GEMINI_API_KEY Google Gemini
GROQ_API_KEY Groq
AWS_ACCESS_KEY_ID AWS Bedrock (Claude)
AWS_SECRET_ACCESS_KEY AWS Bedrock (Claude)
AZURE_OPENAI_API_KEY Azure OpenAI

To set an environment variable, use these commands:

  • Linux or macOS:

    export OPENAI_API_KEY="your_api_key_here"

  • Windows (PowerShell):

    $env:OPENAI_API_KEY = "your_api_key_here"

Step 2: Start Crush

Open your terminal, type crush, and hit Enter. If you’ve set the environment variable, Crush will use it automatically. If not, it’ll ask you to enter your API key. Once it’s connected, you can start using Crush to help with coding tasks like writing snippets or fixing bugs.

Extra Tip: Adding New Models

Crush comes with several built-in models, but you can expand it by contributing to Catwalk, a community project with more Crush-compatible models. It’s a great way to customize your setup!

Configuring Crush for Your Needs

Crush works fine as is, but you can tweak it to match your workflow. You do this by editing JSON files—simple text files with settings—either for a specific project or for all your work.

Crush checks these locations for configuration files, in this order:

  1. ./.crush.json (in your project folder)
  2. ./crush.json (in your project folder)
  3. $HOME/.config/crush/crush.json (a global file in your home directory)

The file uses a basic JSON format like this:

{
   "setting1": { },
   "setting2": { }
}

Let’s look at some ways to customize Crush.

Setting Up LSPs for Better Suggestions

Crush can use Language Server Protocol (LSP) to understand your project better, giving you more accurate tips. To turn this on for certain languages, add this to your configuration file:

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

You’ll need the right language servers installed (like gopls for Go). This makes Crush smarter about your code.

Adding Features with MCPs

Model Context Protocol (MCP) lets Crush connect to outside services for extra power. It works with stdio, http, or sse connections. Here’s an example:

{
  "$schema": "https://charm.land/crush.json",
  "mcp": {
    "filesystem": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/mcp-server.js"]
    },
    "github": {
      "type": "http",
      "url": "https://example.com/mcp/"
    }
  }
}

This lets Crush pull in details from your files or GitHub, making it even more helpful.

Whitelisting Tools for Ease

Crush normally asks permission before running certain tools. To skip that, you can list trusted tools in the configuration:

{
  "$schema": "https://charm.land/crush.json",
  "permissions": {
    "allowed_tools": [
      "view",
      "ls",
      "grep"
    ]
  }
}

Or, use the --yolo flag to skip all permission checks—but be careful, as it lets tools run without asking.

Using Custom Providers

Want to use your own language models? Crush supports custom setups that work with OpenAI or Anthropic APIs. Here’s how to add Deepseek:

{
  "$schema": "https://charm.land/crush.json",
  "providers": {
    "deepseek": {
      "type": "openai",
      "base_url": "https://api.deepseek.com/v1",
      "api_key": "$DEEPSEEK_API_KEY",
      "models": [
        {
          "id": "deepseek-chat",
          "name": "Deepseek V3",
          "context_window": 64000
        }
      ]
    }
  }
}

Set the DEEPSEEK_API_KEY environment variable, and you’re good to go.

Checking Crush Logs for Troubleshooting

If something’s not working right, you can look at Crush’s logs. They’re saved in ./.crush/logs/crush.log in your project folder. Here’s how to view them:

  • See the last 1000 lines:

    crush logs

  • See the last 500 lines:

    crush logs --tail 500

  • Watch logs live:

    crush logs --follow

For more details, run Crush with the --debug flag or add this to your configuration:

{
  "options": {
    "debug": true
  }
}

Development Guidelines for Contributors

Interested in helping improve Crush? Here’s what you need to know to contribute.

Commands for Building and Testing

  • Build: go build . or go run .
  • Test: task test or go test ./...
  • Lint: task lint-fix
  • Format: task fmt (uses gofumpt -w .)

Coding Style Rules

When writing code for Crush, follow these:

  • Naming: Use PascalCase for public items and camelCase for private ones.
  • Errors: Always return errors clearly, using fmt.Errorf to add details.
  • Formatting: Use gofumpt for cleaner code than gofmt.
  • Comments: End comments with periods unless they’re at the end of a line.

Testing with Mock Providers

To test without real API calls, use mock providers like this:

func TestYourFunction(t *testing.T) {
    originalUseMock := config.UseMockProviders
    config.UseMockProviders = true
    defer func() {
        config.UseMockProviders = originalUseMock
        config.ResetProviders()
    }()

    // Your test code here
}

These rules keep Crush’s code consistent and high-quality.

Join the Community and Share Feedback

The Crush team loves hearing from users. You can reach out through:

Crush is licensed under FSL-1.1-MIT and is part of the Charm project.

Wrapping Up

Crush isn’t just a tool—it’s a partner that adjusts to your needs, speeds up your work, and makes coding more fun. With its strong features, easy customization, and support for many systems, it’s ready to be a key part of your coding setup.

Whether you want to simplify your tasks, try new language models, or help build an open-source project, Crush has something for you. Give it a shot and see how it changes the way you code.

Common Questions About Crush

What is Crush?

Crush is a terminal tool that links your coding setup with language models to make programming easier.

Which systems does Crush work on?

It runs on macOS, Linux, Windows (PowerShell and WSL), FreeBSD, OpenBSD, and NetBSD.

How do I install Crush?

Use package managers like Homebrew or NPM, download ready-made files, or build it with Go.

What language models can I use with Crush?

It supports models from Anthropic, OpenAI, Grok, Google Gemini, and more, plus custom options.

How do I check Crush’s logs?

Run crush logs or look at ./.crush/logs/crush.log in your project folder.

Why Choose Crush?

Crush stands out because it’s built to fit into your existing tools and habits. It doesn’t force you to change how you work—instead, it enhances what you already do. For junior college graduates or anyone new to coding, Crush offers a straightforward way to get help without needing to master complicated setups.

The ability to switch models on the fly is a big plus. If one model isn’t giving you the answers you need, you can try another without starting over. And with session management, you can keep your work organized, even if you’re jumping between different projects.

For those who like to dig deeper, the configuration options let you tailor Crush exactly how you want it. Whether it’s connecting to language servers for better suggestions or adding custom models, you’re in control.

Installation Tips and Tricks

If you’re new to terminal commands, don’t worry—installing Crush is easier than it might look. Package managers like Homebrew or NPM do most of the work for you. Just copy and paste the commands into your terminal, and you’ll be up and running in minutes.

Downloading binaries is another simple option. Head to the GitHub releases page, find the file for your system (like .deb for Ubuntu or a binary for Windows), and follow the instructions there. It’s a one-time download, and you’re done.

For Go users, the go install command is quick and keeps Crush up to date with the latest version. If you’re not sure which method to pick, start with a package manager—it’s the most beginner-friendly.

Making the Most of Configuration

Customizing Crush might sound technical, but it’s really about telling the tool what you need. The JSON files are like a set of instructions you can edit with any text editor. If you’re working on a Go project, adding the LSP setup means Crush will understand your code better and offer more useful advice.

The MCP feature is great if you want Crush to pull in extra info, like details from your files or GitHub. It’s a bit more advanced, but the examples in the configuration section make it manageable.

Whitelisting tools is a time-saver if you trust certain commands. And if you’re adventurous, adding a custom provider like Deepseek lets you experiment with different models—perfect for finding what works best for you.

Troubleshooting Made Simple

Logs are your friend when something goes wrong. The crush logs command is an easy way to see what’s happening behind the scenes. If you’re stuck, turning on debug mode with --debug gives you even more info to figure things out.

The Discord community is another resource. It’s a friendly place to ask questions or share what you’ve learned. You don’t have to troubleshoot alone—others are there to help.

Contributing to Crush

If you’re interested in coding beyond just using tools, contributing to Crush is a great way to get involved. The guidelines are clear: build and test your changes, follow the style rules, and use mock providers to keep things safe. It’s a chance to improve a tool you use while learning more about programming.

Final Thoughts

Crush is designed to make coding less of a chore and more of a breeze. It’s flexible enough for different skill levels and powerful enough to handle real work. For junior college grads, it’s an accessible entry into smarter coding tools—no steep learning curve required.

Take some time to install it, play around with the settings, and see how it fits into your projects. You might be surprised at how much easier your work gets with Crush by your side.