Crush Configuration

Crush uses JSON configuration files with the following priority (highest to lowest):

1. .crush.json (project-local, hidden)
2. crush.json (project-local)
3. $XDG_CONFIG_HOME/crush/crush.json or $HOME/.config/crush/crush.json (global)

Basic Structure

{
  "$schema": "https://charm.land/crush.json",
  "models": {},
  "providers": {},
  "mcp": {},
  "lsp": {},
  "options": {},
  "permissions": {},
  "tools": {}
}

The $schema property enables IDE autocomplete but is optional.

Common Tasks

• Add a custom provider: add an entry under providers with type, base_url, api_key, and models.
• Disable a builtin or local skill: add the skill name to options.disabled_skills.
• Add an MCP server: add an entry under mcp with type and either command (stdio) or url (http/sse).

Model Selection

{
  "models": {
    "large": {
      "model": "claude-sonnet-4-20250514",
      "provider": "anthropic",
      "max_tokens": 16384
    },
    "small": {
      "model": "claude-haiku-4-20250514",
      "provider": "anthropic"
    }
  }
}

• large is the primary coding model; small is for summarization.
• Only model and provider are required.
• Optional tuning: reasoning_effort, think, max_tokens, temperature, top_p, top_k, frequency_penalty, presence_penalty, provider_options.

Custom Providers

{
  "providers": {
    "deepseek": {
      "type": "openai-compat",
      "base_url": "https://api.deepseek.com/v1",
      "api_key": "$DEEPSEEK_API_KEY",
      "models": [
        {
          "id": "deepseek-chat",
          "name": "Deepseek V3",
          "context_window": 64000
        }
      ]
    }
  }
}

• type (required): openai, openai-compat, or anthropic
• api_key supports $ENV_VAR syntax.
• Additional fields: disable, system_prompt_prefix, extra_headers, extra_body, provider_options.

LSP Configuration

{
  "lsp": {
    "go": {
      "command": "gopls",
      "env": { "GOTOOLCHAIN": "go1.24.5" }
    },
    "typescript": {
      "command": "typescript-language-server",
      "args": ["--stdio"]
    }
  }
}

• command (required), args, env cover most setups.
• Additional fields: disabled, filetypes, root_markers, init_options, options, timeout.

MCP Servers

{
  "mcp": {
    "filesystem": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/mcp-server.js"]
    },
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer $GH_PAT"
      }
    }
  }
}

• type (required): stdio, sse, or http
• Additional fields: env, disabled, disabled_tools, timeout.

Options

{
  "options": {
    "skills_paths": ["./skills"],
    "disabled_tools": ["bash", "sourcegraph"],
    "disabled_skills": ["crush-config"],
    "tui": {
      "compact_mode": false,
      "diff_mode": "unified",
      "transparent": false
    },
    "auto_lsp": true,
    "debug": false,
    "debug_lsp": false,
    "attribution": {
      "trailer_style": "assisted-by",
      "generated_with": true
    }
  }
}

[!IMPORTANT] The following skill paths are loaded by default and DO NOT NEED to be added to skills_paths: .agents/skills, .crush/skills, .claude/skills, .cursor/skills

Other options: context_paths, progress, disable_notifications, disable_auto_summarize, disable_metrics, disable_provider_auto_update, disable_default_providers, data_directory, initialize_as.

Tool Permissions

{
  "permissions": {
    "allowed_tools": ["view", "ls", "grep", "edit"]
  }
}

Environment Variables

• CRUSH_GLOBAL_CONFIG - Override global config location
• CRUSH_GLOBAL_DATA - Override data directory location
• CRUSH_SKILLS_DIR - Override default skills directory