Configuration

TIP

Crush ships with a builtin crush-config skill for configuring itself. In many cases you can simply ask Crush to configure itself.

Crush runs great with no configuration. That said, if you do need or want to customize Crush, configuration can be added either local to the project itself, or globally, with the following priority:

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

Configuration itself is stored as a JSON object:

{
  "$schema": "https://charm.land/crush.json",
  "this-setting": { "this": "that" },
  "that-setting": ["ceci", "cela"]
}

As an additional note, Crush also stores ephemeral data, such as application state, in one additional location:

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

# Windows
%LOCALAPPDATA%\crush\crush.json

TIP

You can override the user and data config locations by setting:

• CRUSH_GLOBAL_CONFIG
• CRUSH_GLOBAL_DATA

Configuration Sections

Section	Description
providers	LLM providers and models
lsp	Language Server Protocol configurations
mcp	Model Context Protocol servers
hooks	User-defined shell hooks
permissions	Tool permission overrides
options	General settings (skills, tools, UI, etc.) — run crush schema

JSON Schema

Crush validates your configuration against a JSON schema. Reference the schema in your config for IDE autocompletion and validation:

{
  "$schema": "https://charm.land/crush.json"
}

Ignoring Files

Crush respects .gitignore files by default, but you can also create a .crushignore file to specify additional files and directories that Crush should ignore. This is useful for excluding files that you want in version control but don't want Crush to consider when providing context.

The .crushignore file uses the same syntax as .gitignore and can be placed in the root of your project or in subdirectories.