1---
2name: crush-config
3description: 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.
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