Crush：极简 AI 编码助手发布

你的全新编程搭档现已登陆你最喜爱的终端。将你的工具、代码和工作流接入你选择的 LLM。

终端里的编程新搭档，无缝接入你的工具、代码与工作流，全面兼容主流 LLM 模型。

多模型：从丰富的 LLM 中进行选择，也可以通过兼容 OpenAI 或 Anthropic 的 API 添加自己的模型

灵活：可在会话过程中切换 LLM，同时保留上下文

基于会话：每个项目可维护多个工作会话和上下文

LSP 增强：Crush 和你一样，使用 LSP 获取额外上下文

可扩展：通过 MCP（http、stdio 和 sse）添加功能

随处可用：为 macOS、Linux、Windows（PowerShell 和 WSL）、Android、FreeBSD、OpenBSD 和 NetBSD 上的所有终端提供一流支持

工业级：基于 Charm 生态系统构建。该生态系统为超过 2.5 万个应用提供支持，涵盖领先的开源项目和业务关键型基础设施

使用包管理器：

# 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

# Winget
winget install charmbracelet.crush

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

你可以通过官方 Charm NUR 中的 nur.repos.charmbracelet.crush 获取 Crush，这是在 Nix 中获得最新版 Crush 的最佳方式。

你也可以通过 NUR，使用 nix-shell 试用 Crush：

# 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'

通过 NUR 使用 NixOS 和 Home Manager 模块

Crush 通过 NUR 提供 NixOS 和 Home Manager 模块。你可以从 NUR 导入这些模块，直接在 flake 中使用。由于它会自动检测当前是 Home Manager 还是 NixOS 上下文，因此两者可以使用完全相同的导入方式 :)

{
  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;
              };
            };
          };
        }
      ];
    };
  };
}

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

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

提供 Debian 和 RPM 格式的软件包

提供适用于 Linux、macOS、Windows、FreeBSD、OpenBSD 和 NetBSD 的二进制文件

或者直接使用 Go 安装：

go install github.com/charmbracelet/crush@latest

在 illumos（OpenIndiana、OmniOS）上，上述命令可以直接使用。只有原生操作系统通知不可用；基于终端的通知（OSC）和终端响铃仍然有效。在 Oracle Solaris 上，请添加 -tags sqlite3_dotlk，让本地数据库使用点文件锁：

go install -tags sqlite3_dotlk github.com/charmbracelet/crush@latest

使用 Crush 可能会提高生产力，而第一次使用该应用时，你也可能发现自己完全沉迷其中。如果症状持续存在，请加入 Slack 或 Discord，让我们其他人也一起沉迷。

最快的入门方式是在模型选择器中选择一个 Hyper 模型。按照相应步骤完成身份验证，之后便可开始使用。

Hyper 是 Charm 推出的 Crush 官方服务提供商。它采用订阅制，提供免费套餐，并针对 Crush 进行了优化。它注重隐私，实行零数据保留（ZDR），并以符合 GDPR 为设计目标。有关 Hyper 的更多信息。

你也可以将 Crush 与 Anthopic、OpenAI、Gemini、OpenRouter 等许多其他服务提供商配合使用。按 ctrl+l 打开模型选择器，选择你想使用的服务提供商，然后粘贴 API 密钥。

此外，你也可以为首选服务提供商设置环境变量：

另请注意，Crush 几乎可以支持任何服务提供商，包括本地模型。更多信息请参阅下文的“自定义服务提供商”。

你希望 Crush 支持某个服务提供商吗？是否有现有模型需要更新？

Crush 的默认模型列表由 Catwalk 管理。Catwalk 是一个由社区支持的开源仓库，其中收录了兼容 Crush 的模型，欢迎参与贡献。

Crush 内置了一个 crush-config 技能，用于配置自身。在许多情况下，你只需让 Crush 自行完成配置即可。

Crush 无需任何配置即可出色运行。不过，如果你确实需要或希望自定义 Crush，可以在项目本地或全局添加配置，优先级如下：

$HOME/.config/crush/crush.json

配置本身以 JSON 对象形式存储：

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

另外，Crush 还会在另一个位置存储应用状态等临时数据：

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

# Windows
%LOCALAPPDATA%\crush\crush.json

你可以通过设置以下内容覆盖用户配置和数据配置的位置：

Crush 可以像你一样使用 LSP 获取额外上下文，为其决策提供依据。可以按如下方式手动添加 LSP：

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

Crush 还通过三种传输类型支持模型上下文协议（MCP）服务器：用于命令行服务器的 stdio、用于 HTTP 端点的 http，以及用于服务器发送事件的 sse。

command、args、env、headers 和 url 均支持 Shell 风格的值展开（$VAR、${VAR:-default}、$(command)、引号和嵌套），因此开箱即用地支持基于文件存储的密钥。你可以使用 "$TOKEN" 或 "$(cat /path/to/secret/token)" 之类的值。展开操作通过 Crush 的嵌入式 Shell 执行，因此相同语法适用于所有受支持的系统，包括 Windows。

默认情况下，未设置的变量会展开为空字符串，这与 bash 的行为一致。对于必需的凭据，请使用 ${VAR:?message}。这样一来，如果变量未设置，加载时就会直接失败并显示 message，而不是悄无声息地解析为空值：

{ "api_key": "${CODEBERG_TOKEN:?set CODEBERG_TOKEN}" }

如果请求头（包括 MCP 请求头和服务提供商的 extra_headers）的值解析为空字符串，该请求头将从传出的请求中移除，而不会以 Header: 的形式发送。这样，当变量未设置时，像 "OpenAI-Organization": "$OPENAI_ORG_ID" 这种由可选环境变量控制的请求头就能保持整洁。

服务提供商的 extra_body 是不会执行展开的 JSON 透传字段；由环境变量驱动的值应放入 extra_headers，或者服务提供商的 api_key / base_url 中，这些字段都会执行展开。

安全提示：crush.json 是受信任代码。其中的任何 $(...) 都会在加载时、UI 出现之前，以你的 Shell 权限执行。不要在尚未审查其 crush.json 的目录中启动 Crush。

{
  "$schema": "https://charm.land/crush.json",
  "mcp": {
    "filesystem": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/mcp-server.js"],
      "timeout": 120,
      "disabled": false,
      "disabled_tools": ["some-tool-name"],
      "env": {
        "NODE_ENV": "production"
      }
    },
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "timeout": 120,
      "disabled": false,
      "disabled_tools": ["create_issue", "create_pull_request"],
      "headers": {
        "Authorization": "Bearer $GH_PAT"
      }
    },
    "streaming-service": {
      "type": "sse",
      "url": "https://example.com/mcp/sse",
      "timeout": 120,
      "disabled": false,
      "headers": {
        "API-Key": "$(echo $API_KEY)"
      }
    }
  }
}

需要 OAuth 的 HTTP 和 SSE MCP 服务器可以使用 Crush 内置的授权码流程，而不必使用静态的 Authorization 请求头。设置 "oauth": true 即可启用：

{
  "mcp": {
    "linear": {
      "type": "http",
      "url": "https://mcp.linear.app/mcp",
      "oauth": true
    }
  }
}

某些服务器（GitHub、Slack）不支持动态客户端注册。对于这类服务器，请在提供方处注册 OAuth 应用，并直接提供凭据。所有值都支持 shell 展开：

{
  "mcp": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "oauth": true,
      "oauth_client_id": "Iv1.abc123def456",
      "oauth_client_secret": "$GITHUB_MCP_SECRET",
      "oauth_callback_port": 40704
    }
  }
}

设置 oauth_client_id 后，Crush 会跳过动态客户端注册，并以指定客户端的身份进行身份验证。如果省略该配置，Crush 会自动尝试动态注册（适用于 Linear、Notion 以及其他支持 RFC 7591 的服务器）。

Crush 已初步支持 hooks。有关详细信息，请参阅 hook 指南。

共享客户端之间的工作区

当 Crush 连接到共享后端运行时（例如，两个 TUI 与同一个 crush serve 通信），客户端会根据解析后的 --cwd 分组到不同工作区。具有相同 --cwd 的两个客户端会加入同一个底层工作区，因此它们会共享会话列表、消息历史记录、权限队列、LSP 和 MCP 状态。

加入过程是隐式的：让第二个客户端指向相同的工作目录，它就会连接到现有工作区。不过，默认情况下，每次新调用仍会在独立的新会话中启动。若要接续另一个客户端已经打开的对话，请使用会话管理器（会话选择器）并选择该会话。会话管理器会为每个会话显示两个状态信号：

IsBusy：当该会话中的 AI 智能体轮次正在执行时，会设置此状态。

AttachedClients：报告当前正在查看该会话的客户端数量。

当 AttachedClients 不为零时（通常还会同时出现 IsBusy），表明该会话正在另一个客户端上“进行中”；加入该会话后，视图会实时同步。

创建工作区的第一个客户端会确定该工作区的进程级标志。具体来说，--yolo 和 --debug 遵循“先到者优先”规则：之后以不同标志值连接到同一 --cwd 的客户端不会更改正在运行的工作区。系统会输出一行 debug 日志来记录这种不一致，而工作区仍会保留创建时使用的标志。

只要至少有一个客户端保持着连接到工作区的 SSE 事件流，工作区就会继续存在。当最后一个事件流断开连接后，工作区将被销毁。在执行 POST /v1/workspaces 后会有一个短暂的宽限期，避免已经创建工作区但尚未打开事件流的客户端在完成连接之前，其工作区就被清理。

Crush 会自动包含两个用于跨项目指令的文件。

~/.config/crush/CRUSH.md：存放可能会让其他智能体式编程工具感到困惑的 Crush 专用规则。如果你只使用 Crush，只需编辑这一个文件。

~/.config/AGENTS.md：存放其他编程工具也可能读取的通用指令。不要在这里提及 Crush 专用的功能或工作流。通常只有在你同时使用多种智能体式编程工具，并希望在它们之间共享指令时，才需要关注此文件。

你可以通过配置中的 global_context_paths 选项自定义这些路径：

{
  "$schema": "https://charm.land/crush.json",
  "options": {
    "global_context_paths": [
      "~/path/to/custom/context/file.md",
      "/full/path/to/folder/of/files/" // recursively load all .md files in folder
    ]
  }
}

默认情况下，Crush 会遵循 .gitignore 文件，但你也可以创建 .crushignore 文件，指定希望 Crush 忽略的其他文件和目录。当你希望某些文件纳入版本控制，却不希望 Crush 在提供上下文时考虑它们，这项功能会很有用。

.crushignore 文件使用与 .gitignore 相同的语法，可以放在项目根目录或子目录中。

默认情况下，Crush 会在运行工具调用前请求你的许可。如果愿意，你也可以允许工具直接执行，不再提示授权。请谨慎使用。

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

你也可以使用 --yolo 标志运行 Crush，从而完全跳过所有权限提示。使用此功能时务必万分谨慎。

禁用内置工具

如果你希望彻底阻止 Crush 使用某些内置工具，可以通过 options.disabled_tools 列表将其禁用。被禁用的工具会对 AI 智能体完全隐藏。

{
  "$schema": "https://charm.land/crush.json",
  "options": {
    "disabled_tools": ["bash", "sourcegraph"]
  }
}

若要禁用 MCP 服务器提供的工具，请参阅 MCP 配置部分。

如果你希望彻底阻止 Crush 使用某些技能，可以通过 options.disabled_skills 列表将其禁用。被禁用的技能会对 AI 智能体隐藏，包括内置技能和从磁盘发现的技能。

{
  "$schema": "https://charm.land/crush.json",
  "options": {
    "disabled_skills": ["crush-config"]
  }
}

Crush 支持 Agent Skills 开放标准，可通过可复用的技能包扩展 AI 智能体的能力。技能是包含 SKILL.md 指令文件的文件夹，Crush 可以发现这些技能，并在需要时激活它们。

我们会在以下全局路径中查找技能：

$XDG_CONFIG_HOME/agents/skills 或 ~/.config/agents/skills/

$XDG_CONFIG_HOME/crush/skills 或 ~/.config/crush/skills/

在 Windows 上，我们还会查找 %LOCALAPPDATA%\agents\skills\ 或 %USERPROFILE%\AppData\Local\agents\skills\，以及 %LOCALAPPDATA%\crush\skills\ 或 %USERPROFILE%\AppData\Local\crush\skills\

%LOCALAPPDATA%\agents\skills\ 或 %USERPROFILE%\AppData\Local\agents\skills\

%LOCALAPPDATA%\crush\skills\ 或 %USERPROFILE%\AppData\Local\crush\skills\

通过 options.skills_paths 配置的其他路径

除此之外，我们还会从项目中的以下相对路径加载技能：

{
  "$schema": "https://charm.land/crush.json",
  "options": {
    "skills_paths": [
      "~/.config/crush/skills", // Windows: "%LOCALAPPDATA%\\crush\\skills",
      "./project-skills",
    ],
  },
}

你可以从 anthropics/skills 获取示例技能并开始使用：

# Unix
mkdir -p ~/.config/crush/skills
cd ~/.config/crush/skills
git clone https://github.com/anthropics/skills.git _temp
mv _temp/skills/* . && rm -rf _temp

# Windows (PowerShell)
mkdir -Force "$env:LOCALAPPDATA\crush\skills"
cd "$env:LOCALAPPDATA\crush\skills"
git clone https://github.com/anthropics/skills.git _temp
mv _temp/skills/* . ; rm -r -force _temp

技能可以配置为能够从命令面板（Ctrl+P）调用的命令。在技能的 YAML frontmatter 中添加 user-invocable: true：

---
name: my-skill
description: A skill that can be invoked as a command.
user-invocable: true
---

可由用户调用的技能会显示在命令面板中，并带有 user: 或 project: 前缀：

全局目录中的技能显示为 user:skill-name

项目目录中的技能显示为 project:skill-name

调用技能后，其指令会被加载到对话上下文中。

若要阻止模型自动触发某项技能，同时仍允许用户调用它，请添加 disable-model-invocation: true：

---
name: my-skill
description: Only invocable by users, not the model.
user-invocable: true
disable-model-invocation: true
---

设置了 disable-model-invocation 的技能不会出现在模型的可用技能列表中，但用户仍可手动调用它们。

桌面通知

当工具调用需要权限，以及 AI 智能体完成其轮次时，Crush 会发送桌面通知。只有在终端窗口未获得焦点，且你的终端支持报告焦点状态时，才会发送这些通知。

{
  "$schema": "https://charm.land/crush.json",
  "options": {
    "disable_notifications": false, // default
  },
}

禁用桌面通知

要禁用桌面通知，在配置中将 disable_notifications 设置为 true。在 macOS 上，由于平台限制，通知目前缺少图标。

项目初始化与上下文文件

初始化项目时，Crush 会分析你的代码库并创建一个上下文文件，以便在未来的会话中更有效地工作。默认情况下，该文件名为 AGENTS.md，但你可以使用 initialize_as 选项自定义名称和位置：

{
  "$schema": "https://charm.land/crush.json",
  "options": {
    "initialize_as": "AGENTS.md"
  }
}

如果你希望使用不同的命名约定或想将文件放在特定目录中（例如 CRUSH.md 或 docs/LLMs.md），这会很有用。Crush 会用项目特定的上下文填充该文件，例如构建命令、代码模式和初始化期间发现的约定。

Git 提交属性配置

默认情况下，Crush 会向其创建的 Git 提交和拉取请求添加属性信息。你可以使用 attribution 选项自定义此行为：

{
  "$schema": "https://charm.land/crush.json",
  "options": {
    "attribution": {
      "trailer_style": "co-authored-by",
      "generated_with": true
    }
  }
}

trailer_style：控制添加到提交消息的属性尾部（默认值：assisted-by）

• assisted-by：添加 Assisted-by: Crush:[ModelID] 如约定中所示
• co-authored-by：添加 Co-Authored-By: Crush <crush@charm.land>
• none：无属性尾部

generated_with：为 true 时（默认值），在提交消息和拉取请求描述中添加 💘 Generated with Crush 一行

自定义提供商配置

Crush 支持 OpenAI 兼容和 Anthropic 兼容 API 的自定义提供商配置。

请注意，我们支持两种 OpenAI "类型"。请确保选择正确的类型以确保最佳体验！

• openai 应在通过 OpenAI 代理或路由请求时使用。
• openai-compat 应在使用具有 OpenAI 兼容 API 的非 OpenAI 提供商时使用。

以下是 Deepseek 的示例配置，它使用 OpenAI 兼容 API。不要忘记在环境中设置 DEEPSEEK_API_KEY。

{
  "$schema": "https://charm.land/crush.json",
  "providers": {
    "deepseek": {
      "type": "openai-compat",
      "base_url": "https://api.deepseek.com/v1",
      "api_key": "$DEEPSEEK_API_KEY",
      "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
        }
      ]
    }
  }
}

自定义 Anthropic 兼容提供商遵循以下格式：

{
  "$schema": "https://charm.land/crush.json",
  "providers": {
    "custom-anthropic": {
      "type": "anthropic",
      "base_url": "https://api.anthropic.com/v1",
      "api_key": "$ANTHROPIC_API_KEY",
      "extra_headers": {
        "anthropic-version": "2023-06-01"
      },
      "models": [
        {
          "id": "claude-sonnet-4-20250514",
          "name": "Claude Sonnet 4",
          "cost_per_1m_in": 3,
          "cost_per_1m_out": 15,
          "cost_per_1m_in_cached": 3.75,
          "cost_per_1m_out_cached": 0.3,
          "context_window": 200000,
          "default_max_tokens": 50000,
          "can_reason": true,
          "supports_attachments": true
        }
      ]
    }
  }
}

AWS Bedrock 支持

Crush 目前支持通过 Bedrock 运行 Anthropic 模型，但禁用了缓存。

配置完 AWS 后（即运行 aws configure），Bedrock 提供商就会出现。

Crush 还希望设置 AWS_REGION 或 AWS_DEFAULT_REGION。

要使用特定的 AWS 配置文件，在环境中设置 AWS_PROFILE，例如 AWS_PROFILE=myprofile crush。

或者，除了 aws configure 外，你也可以直接设置 AWS_BEARER_TOKEN_BEDROCK。

Vertex AI 支持

当设置 VERTEXAI_PROJECT 和 VERTEXAI_LOCATION 时，Vertex AI 会出现在可用提供商列表中。你还需要进行身份验证：

gcloud auth application-default login

要向配置中添加特定模型，按如下方式配置：

{
  "$schema": "https://charm.land/crush.json",
  "providers": {
    "vertexai": {
      "models": [
        {
          "id": "claude-sonnet-4@20250514",
          "name": "VertexAI Sonnet 4",
          "cost_per_1m_in": 3,
          "cost_per_1m_out": 15,
          "cost_per_1m_in_cached": 3.75,
          "cost_per_1m_out_cached": 0.3,
          "context_window": 200000,
          "default_max_tokens": 50000,
          "can_reason": true,
          "supports_attachments": true
        }
      ]
    }
  }
}

本地提供商的自动发现

Crush 可以从本地提供商自动发现模型。添加一个 type 设置为 llamacpp、omlx、lmstudio、litellm 或 ollama 的自定义提供商，并省略 models 列表。Crush 将自动填充模型列表。

{
  "providers": {
    "ollama": {
      "name": "Ollama",
      "base_url": "http://localhost:11434/v1/",
      "type": "ollama"
    }
  }
}

对于 llama.cpp（llama-server），指向服务器的基础 URL：

{
  "providers": {
    "llamacpp": {
      "name": "llama.cpp",
      "base_url": "http://localhost:2222",
      "type": "llamacpp"
    }
  }
}

你仍然可以显式列出模型。用户定义的模型始终优先于发现的模型，你设置的任何字段都不会被自动发现覆盖。如果模型列表为空，自动发现将针对任何 openai-compat 提供商运行，或者如果你传递 "discover_models": true，它将合并找到的模型与你手动配置的模型。

{
  "providers": {
    "ollama": {
      "name": "Ollama",
      "base_url": "http://localhost:11434/v1/",
      "type": "ollama",
      "models": [
        {
          "name": "Qwen 3 30B",
          "id": "qwen3:30b",
          "context_window": 256000,
          "default_max_tokens": 20000
        }
      ],
      "discover_models": true
    }
  }
}

日志

有时你需要查看日志。幸运的是，Crush 会记录各种内容。日志存储在相对于项目的 ./.crush/logs/crush.log 中。

CLI 还包含一些辅助命令，可以更轻松地查看最近的日志：

# 打印最后 1000 行
crush logs

# 打印最后 500 行
crush logs --tail 500

# 实时跟踪日志
crush logs --follow

需要更多日志记录？使用 --debug 标志运行 crush，或在配置中启用它：

{
  "$schema": "https://charm.land/crush.json",
  "options": {
    "debug": true,
    "debug_lsp": true
  }
}

提供商自动更新

默认情况下，Crush 自动检查来自 Catwalk（开源 Crush pro）的最新提供商和模型列表