1---
2name: crush-config
3description: Configure Crush settings including providers, LSPs, MCPs, skills, permissions, and behavior options. Use when the user needs help with crush.json configuration, setting up providers, configuring LSPs, adding MCP servers, or changing Crush behavior.
4---
5
6# Crush Configuration
7
8Crush uses JSON configuration files with the following priority (highest to lowest):
9
101. `.crush.json` (project-local, hidden)
112. `crush.json` (project-local)
123. `$XDG_CONFIG_HOME/crush/crush.json` or `$HOME/.config/crush/crush.json` (global)
13
14## Basic Structure
15
16```json
17{
18 "$schema": "https://charm.land/crush.json",
19 "models": {},
20 "providers": {},
21 "mcp": {},
22 "lsp": {},
23 "options": {},
24 "permissions": {},
25 "tools": {}
26}
27```
28
29The `$schema` property enables IDE autocomplete but is optional.
30
31## Common Tasks
32
33- Add a custom provider: add an entry under `providers` with `type`, `base_url`, `api_key`, and `models`.
34- Disable a builtin or local skill: add the skill name to `options.disabled_skills`.
35- Add an MCP server: add an entry under `mcp` with `type` and either `command` (stdio) or `url` (http/sse).
36
37## Model Selection
38
39```json
40{
41 "models": {
42 "large": {
43 "model": "claude-sonnet-4-20250514",
44 "provider": "anthropic",
45 "max_tokens": 16384
46 },
47 "small": {
48 "model": "claude-haiku-4-20250514",
49 "provider": "anthropic"
50 }
51 }
52}
53```
54
55- `large` is the primary coding model; `small` is for summarization.
56- Only `model` and `provider` are required.
57- Optional tuning: `reasoning_effort`, `think`, `max_tokens`, `temperature`, `top_p`, `top_k`, `frequency_penalty`, `presence_penalty`, `provider_options`.
58
59## Custom Providers
60
61```json
62{
63 "providers": {
64 "deepseek": {
65 "type": "openai-compat",
66 "base_url": "https://api.deepseek.com/v1",
67 "api_key": "$DEEPSEEK_API_KEY",
68 "models": [
69 {
70 "id": "deepseek-chat",
71 "name": "Deepseek V3",
72 "context_window": 64000
73 }
74 ]
75 }
76 }
77}
78```
79
80- `type` (required): `openai`, `openai-compat`, or `anthropic`
81- `api_key` supports `$ENV_VAR` syntax.
82- Additional fields: `disable`, `system_prompt_prefix`, `extra_headers`, `extra_body`, `provider_options`.
83
84## LSP Configuration
85
86```json
87{
88 "lsp": {
89 "go": {
90 "command": "gopls",
91 "env": { "GOTOOLCHAIN": "go1.24.5" }
92 },
93 "typescript": {
94 "command": "typescript-language-server",
95 "args": ["--stdio"]
96 }
97 }
98}
99```
100
101- `command` (required), `args`, `env` cover most setups.
102- Additional fields: `disabled`, `filetypes`, `root_markers`, `init_options`, `options`, `timeout`.
103
104## MCP Servers
105
106```json
107{
108 "mcp": {
109 "filesystem": {
110 "type": "stdio",
111 "command": "node",
112 "args": ["/path/to/mcp-server.js"]
113 },
114 "github": {
115 "type": "http",
116 "url": "https://api.githubcopilot.com/mcp/",
117 "headers": {
118 "Authorization": "Bearer $GH_PAT"
119 }
120 }
121 }
122}
123```
124
125- `type` (required): `stdio`, `sse`, or `http`
126- Additional fields: `env`, `disabled`, `disabled_tools`, `timeout`.
127
128## Options
129
130```json
131{
132 "options": {
133 "skills_paths": ["./skills"],
134 "disabled_tools": ["bash", "sourcegraph"],
135 "disabled_skills": ["crush-config"],
136 "tui": {
137 "compact_mode": false,
138 "diff_mode": "unified",
139 "transparent": false
140 },
141 "auto_lsp": true,
142 "debug": false,
143 "debug_lsp": false,
144 "attribution": {
145 "trailer_style": "assisted-by",
146 "generated_with": true
147 }
148 }
149}
150```
151
152> [!IMPORTANT]
153> The following skill paths are loaded by default and DO NOT NEED to be added to `skills_paths`:
154> `.agents/skills`, `.crush/skills`, `.claude/skills`, `.cursor/skills`
155
156Other options: `context_paths`, `progress`, `disable_notifications`, `disable_auto_summarize`, `disable_metrics`, `disable_provider_auto_update`, `disable_default_providers`, `data_directory`, `initialize_as`.
157
158## Tool Permissions
159
160```json
161{
162 "permissions": {
163 "allowed_tools": ["view", "ls", "grep", "edit"]
164 }
165}
166```
167
168## Environment Variables
169
170- `CRUSH_GLOBAL_CONFIG` - Override global config location
171- `CRUSH_GLOBAL_DATA` - Override data directory location
172- `CRUSH_SKILLS_DIR` - Override default skills directory