crush

[!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 is a tool for building software with AI.

Installation

Crush has first class support for macOS, Linux, and Windows.

Nightly builds are available while Crush is in development.

• Packages are available in Debian, RPM, APK, and PKG formats
• Binaries are available for Linux, macOS and Windows

You can also just install it with go:

git clone [email protected]:charmbracelet/crush.git
cd crush
go install

Not a developer? Here’s a quick how-to.

Download the latest [nightly release](https://github.com/charmbracelet/crush/releases) for your system. The [macOS ARM64 one](https://github.com/charmbracelet/crush/releases/download/nightly/crush_0.1.0-nightly_Darwin_arm64.tar.gz) is most likely what you want. Next, open a terminal and run the following commands: ```bash cd ~/Downloads tar -xvzf crush_0.1.0-nightly_Darwin_arm64.tar.gz -C crush sudo mv ./crush/crush /usr/local/bin/crush rm -rf ./crush ``` Then, run Crush by typing `crush`. ---

Nix

Crush provides a Nix flake for easy installation and configuration management.

Installation

Install directly from the flake:

nix profile install github:charmbracelet/crush

Or run without installing:

nix run github:charmbracelet/crush

NixOS Module

Add Crush to your NixOS configuration:

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    crush.url = "github:charmbracelet/crush";
  };

  outputs = { nixpkgs, crush, ... }: {
    nixosConfigurations.your-hostname = nixpkgs.lib.nixosSystem {
      modules = [
        crush.nixosModules.default
        {
          programs.crush = {
            enable = true;
            settings = {
              providers = {
                openai = {
                  name = "OpenAI";
                  provider_type = "openai";
                  api_key = "sk-fake123456789abcdef...";
                };
              };
              lsp = {
                go = { command = "gopls"; };
                nix = { command = "nil"; };
              };
            };
          };
        }
      ];
    };
  };
}

Home Manager Module

Home Manager configuration uses identical settings structure:

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    home-manager.url = "github:nix-community/home-manager";
    crush.url = "github:charmbracelet/crush";
  };

  outputs = { nixpkgs, home-manager, crush, ... }: {
    homeConfigurations.your-username = home-manager.lib.homeManagerConfiguration {
      modules = [
        crush.homeManagerModules.default
        { programs.crush.enable = true; }
      ];
    };
  };
}

Getting Started

The quickest way to get started to grab an API key for your preferred provider such as Anthropic, OpenAI, or Groq, 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
GEMINI_API_KEY	Google Gemini
VERTEXAI_PROJECT	Google Cloud VertexAI (Gemini)
VERTEXAI_LOCATION	Google Cloud VertexAI (Gemini)
GROQ_API_KEY	Groq
AWS_ACCESS_KEY_ID	AWS Bedrock (Claude)
AWS_SECRET_ACCESS_KEY	AWS Bedrock (Claude)
AWS_REGION	AWS Bedrock (Claude)
AZURE_OPENAI_ENDPOINT	Azure OpenAI models
AZURE_OPENAI_API_KEY	Azure OpenAI models (optional when using Entra ID)
AZURE_OPENAI_API_VERSION	Azure OpenAI models

Configuration

For many use cases, Crush can be run with no config. That said, if you do need config, it can be added either local to the project itself, or globally. Configuration has the following priority:

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

LSPs

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

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

MCPs

Crush supports Model Context Protocol (MCP) servers through three transport types: stdio for command-line servers, http for HTTP endpoints, and sse for Server-Sent Events. Environment variable expansion is supported using $(echo $VAR) syntax.

{
  "mcp": {
    "filesystem": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/mcp-server.js"],
      "env": {
        "NODE_ENV": "production"
      }
    },
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "$(echo Bearer $GH_MCP_TOKEN)"
      }
    },
    "streaming-service": {
      "type": "sse",
      "url": "https://example.com/mcp/sse",
      "headers": {
        "API-Key": "$(echo $API_KEY)"
      }
    }
  }
}

Logging

Enable debug logging with the -d flag or in config. View logs with crush logs. Logs are stored in .crush/logs/crush.log.

# Run with debug logging
crush -d

# View last 1000 lines
crush logs

# Follow logs in real-time
crush logs -f

# Show last 500 lines
crush logs -t 500

Add to your crush.json config file:

{
  "options": {
    "debug": true,
    "debug_lsp": true
  }
}

Configurable Default Permissions

Crush includes a permission system to control which tools can be executed without prompting. You can configure allowed tools in your crush.json config file:

{
  "permissions": {
    "allowed_tools": [
      "view",
      "ls",
      "grep",
      "edit:write",
      "mcp_context7_get-library-doc"
    ]
  }
}

The allowed_tools array accepts:

• Tool names (e.g., "view") - allows all actions for that tool
• Tool:action combinations (e.g., "edit:write") - allows only specific actions

You can also skip all permission prompts entirely by running Crush with the --yolo flag.

OpenAI-Compatible APIs

Crush supports all OpenAI-compatible APIs. Here's an example configuration for Deepseek, which uses an OpenAI-compatible API. Don't forget to set DEEPSEEK_API_KEY in your environment.

{
  "providers": {
    "deepseek": {
      "provider_type": "openai",
      "base_url": "https://api.deepseek.com/v1",
      "models": [
        {
          "id": "deepseek-chat",
          "name": "Deepseek V3",
          "cost_per_1m_in": 0.27,
          "cost_per_1m_out": 1.1,
          "cost_per_1m_in_cached": 0.07,
          "cost_per_1m_out_cached": 1.1,
          "context_window": 64000,
          "default_max_tokens": 5000
        }
      ]
    }
  }
}

Whatcha think?

We’d love to hear your thoughts on this project. Feel free to drop us a note!

• Twitter
• The Fediverse
• Discord

License

MIT

---

Part of Charm.

Charm热爱开源 • Charm loves open source