Crush crush-config

Use when the user needs help configuring Crush — working with crush.json, setting up providers, configuring LSPs, adding MCP servers, managing skills or permissions, or changing Crush behavior.

install

source · Clone the upstream repo

git clone https://github.com/charmbracelet/crush

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/charmbracelet/crush "$T" && mkdir -p ~/.claude/skills && cp -r "$T/internal/skills/builtin/crush-config" ~/.claude/skills/charmbracelet-crush-crush-config && rm -rf "$T"

manifest: internal/skills/builtin/crush-config/SKILL.md

source content

Crush Configuration

Crush uses JSON configuration files with the following priority (highest to lowest):

```
.crush.json
```
(project-local, hidden)
```
crush.json
```
(project-local)

$XDG_CONFIG_HOME/crush/crush.json

$HOME/.config/crush/crush.json

(global)

Basic Structure

{
  "$schema": "https://charm.land/crush.json",
  "models": {},
  "providers": {},
  "mcp": {},
  "lsp": {},
  "options": {},
  "permissions": {},
  "tools": {}
}

The

$schema

property enables IDE autocomplete but is optional.

Common Tasks

Add a custom provider: add an entry under
```
providers
```
with
```
type
```
,
```
base_url
```
,
```
api_key
```
, and
```
models
```
.
Disable a builtin or local skill: add the skill name to
```
options.disabled_skills
```
.
Add an MCP server: add an entry under
```
mcp
```
with
```
type
```
and either
```
command
```
(stdio) or
```
url
```
(http/sse).

Model Selection

{
  "models": {
    "large": {
      "model": "claude-sonnet-4-20250514",
      "provider": "anthropic",
      "max_tokens": 16384
    },
    "small": {
      "model": "claude-haiku-4-20250514",
      "provider": "anthropic"
    }
  }
}

```
large
```
is the primary coding model;
```
small
```
is for summarization.
Only
```
model
```
and
```
provider
```
are required.

Optional tuning:

reasoning_effort

think

max_tokens

temperature

top_p

top_k

frequency_penalty

presence_penalty

provider_options

Custom Providers

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

```
type
```
(required):
```
openai
```
,
```
openai-compat
```
, or
```
anthropic
```
```
api_key
```
supports
```
$ENV_VAR
```
syntax.

Additional fields:

disable

system_prompt_prefix

extra_headers

extra_body

provider_options

LSP Configuration

{
  "lsp": {
    "go": {
      "command": "gopls",
      "env": { "GOTOOLCHAIN": "go1.24.5" }
    },
    "typescript": {
      "command": "typescript-language-server",
      "args": ["--stdio"]
    }
  }
}

```
command
```
(required),
```
args
```
,
```
env
```
cover most setups.

Additional fields:

disabled

filetypes

root_markers

init_options

options

timeout

MCP Servers

{
  "mcp": {
    "filesystem": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/mcp-server.js"]
    },
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer $GH_PAT"
      }
    }
  }
}

```
type
```
(required):
```
stdio
```
,
```
sse
```
, or
```
http
```
Additional fields:
```
env
```
,
```
disabled
```
,
```
disabled_tools
```
,
```
timeout
```
.

Options

{
  "options": {
    "skills_paths": ["./skills"],
    "disabled_tools": ["bash", "sourcegraph"],
    "disabled_skills": ["crush-config"],
    "tui": {
      "compact_mode": false,
      "diff_mode": "unified",
      "transparent": false
    },
    "auto_lsp": true,
    "debug": false,
    "debug_lsp": false,
    "attribution": {
      "trailer_style": "assisted-by",
      "generated_with": true
    }
  }
}

[!IMPORTANT] The following skill paths are loaded by default and DO NOT NEED to be added to
skills_paths
:
.agents/skills
,
.crush/skills
,
.claude/skills
,
.cursor/skills

Other options:

context_paths

progress

disable_notifications

disable_auto_summarize

disable_metrics

disable_provider_auto_update

disable_default_providers

data_directory

initialize_as

Tool Permissions

{
  "permissions": {
    "allowed_tools": ["view", "ls", "grep", "edit"]
  }
}

Environment Variables

```
CRUSH_GLOBAL_CONFIG
```
- Override global config location
```
CRUSH_GLOBAL_DATA
```
- Override data directory location
```
CRUSH_SKILLS_DIR
```
- Override default skills directory