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.

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.

#!/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.