# Crush Configuration

Configures Crush providers, models, MCP servers, hooks and permissions.

- Repository: https://github.com/charmbracelet/crush (28908 stars)
- Category: Engineering
- License: see repository
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add charmbracelet/crush --skill crush-config -g -a claude-code -y`
Codex: `npx skills add charmbracelet/crush --skill crush-config -g -a codex -y`
Cursor: `npx skills add charmbracelet/crush --skill crush-config -g -a cursor -y`
Gemini CLI: `npx skills add charmbracelet/crush --skill crush-config -g -a gemini-cli -y`

## Description

Use when the user needs help configuring Crush, writing crushrc (the Bash config format) or crush.json, setting up providers, models, LSPs, MCP servers, hooks, skills, permissions, or changing Crush behavior.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Crush Configuration

Crush supports two config formats:

- **`crushrc`**, a Bash script that builds config by calling Crush builtins.
  **Preferred.** Because it is real Bash you get includes, secrets,
  conditionals, and variables for free.
- **`crush.json`**, static JSON. Fully supported; see
  [Legacy JSON format](#legacy-json-format).

Both are discovered together and deep-merged. Priority (highest to lowest):

1. `.crushrc` / `crushrc` / `.crush.json` / `crush.json` (project-local,
   closer-to-cwd wins; Windows uses `.\.crushrc` / `.\crushrc`)
2. `$XDG_CONFIG_HOME/crush/crushrc` or `~/.config/crush/crushrc`
   (`%XDG_CONFIG_HOME%\crush\crushrc` or
   `%USERPROFILE%\.config\crush\crushrc` on Windows)

Data directories (`~/.local/share/crush` and `%LOCALAPPDATA%\crush`) contain
machine-owned JSON state only; Crush does not discover or execute a `crushrc`
from those locations.

If a directory has both `crushrc` and `crush.json`, they merge (`crushrc` wins
on conflicts) and Crush logs a warning.

## crushrc at a glance

A `crushrc` is a plain Bash script executed at load time with the same embedded
shell the `bash` tool uses. It builds config by calling builtins (`provider`,
`model`, `mcp`, `lsp`, `hook`, `permissions`, `option`). Statements run top to
bottom; later statements win, and `remove`/`reset` operate on anything defined
earlier or pulled in via `source`.

```bash
#!/usr/bin/env bash
# Includes and secrets are just Bash.
source ~/.config/crush/shared.sh

provider add anthropic --api-key "$ANTHROPIC_API_KEY"

model large anthropic/claude-sonnet-4-20250514 --max-tokens 16384
model small anthropic/claude-haiku-4-20250514

option skill-path ./skills
permissions allow view ls grep edit
```

Values are ordinary Bash, quote and expand normally (`"$VAR"`, `$(cmd)`,
`${VAR:?required}`). A failing `$(command)` aborts the load.

The rest: https://github.com/charmbracelet/crush/blob/HEAD/internal/skills/builtin/crush-config/SKILL.md