schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://github.com/charmbracelet/crush/internal/config/config",
  "$ref": "#/$defs/Config",
  "$defs": {
    "Attribution": {
      "properties": {
        "trailer_style": {
          "type": "string",
          "enum": [
            "none",
            "co-authored-by",
            "assisted-by"
          ],
          "description": "Style of attribution trailer to add to commits",
          "default": "assisted-by"
        },
        "co_authored_by": {
          "type": "boolean",
          "description": "Deprecated: use trailer_style instead",
          "deprecated": true
        },
        "generated_with": {
          "type": "boolean",
          "description": "Add Generated with Crush line to commit messages and issues and PRs",
          "default": true
        }
      },
      "additionalProperties": false,
      "type": "object"
    },
    "Completions": {
      "properties": {
        "max_depth": {
          "type": "integer",
          "description": "Maximum depth for the ls tool",
          "default": 0,
          "examples": [
            10
          ]
        },
        "max_items": {
          "type": "integer",
          "description": "Maximum number of items to return for the ls tool",
          "default": 1000,
          "examples": [
            100
          ]
        }
      },
      "additionalProperties": false,
      "type": "object"
    },
    "Config": {
      "properties": {
        "$schema": {
          "type": "string"
        },
        "models": {
          "additionalProperties": {
            "$ref": "#/$defs/SelectedModel"
          },
          "type": "object",
          "description": "Model configurations for different model types"
        },
        "providers": {
          "additionalProperties": {
            "$ref": "#/$defs/ProviderConfig"
          },
          "type": "object",
          "description": "AI provider configurations"
        },
        "mcp": {
          "$ref": "#/$defs/MCPs",
          "description": "Model Context Protocol server configurations"
        },
        "lsp": {
          "$ref": "#/$defs/LSPs",
          "description": "Language Server Protocol configurations"
        },
        "options": {
          "$ref": "#/$defs/Options",
          "description": "General application options"
        },
        "permissions": {
          "$ref": "#/$defs/Permissions",
          "description": "Permission settings for tool usage"
        },
        "tools": {
          "$ref": "#/$defs/Tools",
          "description": "Tool configurations"
        },
        "hooks": {
          "additionalProperties": {
            "items": {
              "$ref": "#/$defs/HookConfig"
            },
            "type": "array"
          },
          "type": "object",
          "description": "User-defined shell commands that fire on hook events (e.g. PreToolUse)"
        }
      },
      "additionalProperties": false,
      "type": "object"
    },
    "HookConfig": {
      "properties": {
        "name": {
          "type": "string",
          "description": "Friendly display name shown in the TUI for this hook"
        },
        "matcher": {
          "type": "string",
          "description": "Regex pattern tested against the tool name. Empty means match all tools."
        },
        "command": {
          "type": "string",
          "description": "Shell command to execute when the hook fires"
        },
        "timeout": {
          "type": "integer",
          "description": "Timeout in seconds for the hook command",
          "default": 30
        }
      },
      "additionalProperties": false,
      "type": "object",
      "required": [
        "command"
      ]
    },
    "LSPConfig": {
      "properties": {
        "disabled": {
          "type": "boolean",
          "description": "Whether this LSP server is disabled",
          "default": false
        },
        "command": {
          "type": "string",
          "description": "Command to execute for the LSP server",
          "examples": [
            "gopls"
          ]
        },
        "args": {
          "items": {
            "type": "string"
          },
          "type": "array",
          "description": "Arguments to pass to the LSP server command"
        },
        "env": {
          "additionalProperties": {
            "type": "string"
          },
          "type": "object",
          "description": "Environment variables to set to the LSP server command"
        },
        "filetypes": {
          "items": {
            "type": "string",
            "examples": [
              "go",
              "mod",
              "rs",
              "c",
              "js",
              "ts"
            ]
          },
          "type": "array",
          "description": "File types this LSP server handles"
        },
        "root_markers": {
          "items": {
            "type": "string",
            "examples": [
              "go.mod",
              "package.json",
              "Cargo.toml"
            ]
          },
          "type": "array",
          "description": "Files or directories that indicate the project root"
        },
        "init_options": {
          "type": "object",
          "description": "Initialization options passed to the LSP server during initialize request"
        },
        "options": {
          "type": "object",
          "description": "LSP server-specific settings passed during initialization"
        },
        "timeout": {
          "type": "integer",
          "description": "Timeout in seconds for LSP server initialization",
          "default": 30,
          "examples": [
            60,
            120
          ]
        }
      },
      "additionalProperties": false,
      "type": "object"
    },
    "LSPs": {
      "additionalProperties": {
        "$ref": "#/$defs/LSPConfig"
      },
      "type": "object"
    },
    "MCPConfig": {
      "properties": {
        "command": {
          "type": "string",
          "description": "Command to execute for stdio MCP servers",
          "examples": [
            "npx"
          ]
        },
        "env": {
          "additionalProperties": {
            "type": "string"
          },
          "type": "object",
          "description": "Environment variables to set for the MCP server"
        },
        "args": {
          "items": {
            "type": "string"
          },
          "type": "array",
          "description": "Arguments to pass to the MCP server command"
        },
        "type": {
          "type": "string",
          "enum": [
            "stdio",
            "sse",
            "http"
          ],
          "description": "Type of MCP connection",
          "default": "stdio"
        },
        "url": {
          "type": "string",
          "format": "uri",
          "description": "URL for HTTP or SSE MCP servers",
          "examples": [
            "http://localhost:3000/mcp"
          ]
        },
        "disabled": {
          "type": "boolean",
          "description": "Whether this MCP server is disabled",
          "default": false
        },
        "disabled_tools": {
          "items": {
            "type": "string",
            "examples": [
              "get-library-doc"
            ]
          },
          "type": "array",
          "description": "List of tools from this MCP server to disable"
        },
        "enabled_tools": {
          "items": {
            "type": "string",
            "examples": [
              "get-library-doc"
            ]
          },
          "type": "array",
          "description": "Allow list of tools from this MCP server"
        },
        "timeout": {
          "type": "integer",
          "description": "Timeout in seconds for MCP server connections",
          "default": 15,
          "examples": [
            30,
            60,
            120
          ]
        },
        "headers": {
          "additionalProperties": {
            "type": "string"
          },
          "type": "object",
          "description": "HTTP headers for HTTP/SSE MCP servers"
        },
        "oauth": {
          "type": "boolean",
          "description": "Enable OAuth 2.1 authorization flow for this MCP server (HTTP transport only)",
          "default": false
        },
        "oauth_client_id": {
          "type": "string",
          "description": "Pre-registered OAuth client ID for servers without dynamic client registration"
        },
        "oauth_client_secret": {
          "type": "string",
          "description": "Pre-registered OAuth client secret paired with oauth_client_id"
        },
        "oauth_callback_port": {
          "type": "integer",
          "description": "Fixed localhost port for the OAuth callback"
        }
      },
      "additionalProperties": false,
      "type": "object",
      "required": [
        "type"
      ]
    },
    "MCPs": {
      "additionalProperties": {
        "$ref": "#/$defs/MCPConfig"
      },
      "type": "object"
    },
    "Model": {
      "properties": {
        "id": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "cost_per_1m_in": {
          "type": "number"
        },
        "cost_per_1m_out": {
          "type": "number"
        },
        "cost_per_1m_in_cached": {
          "type": "number"
        },
        "cost_per_1m_out_cached": {
          "type": "number"
        },
        "context_window": {
          "type": "integer"
        },
        "default_max_tokens": {
          "type": "integer"
        },
        "can_reason": {
          "type": "boolean"
        },
        "reasoning_levels": {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "default_reasoning_effort": {
          "type": "string"
        },
        "supports_attachments": {
          "type": "boolean"
        },
        "options": {
          "$ref": "#/$defs/ModelOptions"
        }
      },
      "additionalProperties": false,
      "type": "object",
      "required": [
        "id",
        "name",
        "cost_per_1m_in",
        "cost_per_1m_out",
        "cost_per_1m_in_cached",
        "cost_per_1m_out_cached",
        "context_window",
        "default_max_tokens",
        "can_reason",
        "supports_attachments"
      ]
    },
    "ModelOptions": {
      "properties": {
        "temperature": {
          "type": "number"
        },
        "top_p": {
          "type": "number"
        },
        "top_k": {
          "type": "integer"
        },
        "frequency_penalty": {
          "type": "number"
        },
        "presence_penalty": {
          "type": "number"
        },
        "provider_options": {
          "type": "object"
        }
      },
      "additionalProperties": false,
      "type": "object"
    },
    "OAuthClient": {
      "properties": {
        "client_id": {
          "type": "string"
        },
        "client_secret": {
          "type": "string"
        },
        "auth_url": {
          "type": "string"
        },
        "token_url": {
          "type": "string"
        },
        "auth_style": {
          "type": "integer"
        }
      },
      "additionalProperties": false,
      "type": "object"
    },
    "Options": {
      "properties": {
        "context_paths": {
          "items": {
            "type": "string",
            "examples": [
              ".cursorrules",
              "CRUSH.md"
            ]
          },
          "type": "array",
          "description": "Paths to files containing context information for the AI"
        },
        "global_context_paths": {
          "items": {
            "type": "string"
          },
          "type": "array",
          "description": "Paths to files containing global context information for the AI",
          "default": [
            "~/.config/crush/CRUSH.md",
            "~/.config/AGENTS.md"
          ]
        },
        "skills_paths": {
          "items": {
            "type": "string",
            "examples": [
              "~/.config/crush/skills",
              "./skills"
            ]
          },
          "type": "array",
          "description": "Paths to directories containing Agent Skills (folders with SKILL.md files)"
        },
        "tui": {
          "$ref": "#/$defs/TUIOptions",
          "description": "Terminal user interface options"
        },
        "debug": {
          "type": "boolean",
          "description": "Enable debug logging",
          "default": false
        },
        "debug_lsp": {
          "type": "boolean",
          "description": "Enable debug logging for LSP servers",
          "default": false
        },
        "disable_auto_summarize": {
          "type": "boolean",
          "description": "Disable automatic conversation summarization",
          "default": false
        },
        "data_directory": {
          "type": "string",
          "description": "Directory for storing application data. Relative paths are resolved against the working directory; absolute paths are used as-is.",
          "default": ".crush",
          "examples": [
            ".crush"
          ]
        },
        "disabled_tools": {
          "items": {
            "type": "string",
            "examples": [
              "bash",
              "sourcegraph"
            ]
          },
          "type": "array",
          "description": "List of built-in tools to disable and hide from the agent"
        },
        "disable_provider_auto_update": {
          "type": "boolean",
          "description": "Disable providers auto-update",
          "default": false
        },
        "disable_default_providers": {
          "type": "boolean",
          "description": "Ignore all default/embedded providers. When enabled, providers must be fully specified in the config file with base_url, models, and api_key - no merging with defaults occurs",
          "default": false
        },
        "attribution": {
          "$ref": "#/$defs/Attribution",
          "description": "Attribution settings for generated content"
        },
        "disable_metrics": {
          "type": "boolean",
          "description": "Disable sending metrics",
          "default": false
        },
        "initialize_as": {
          "type": "string",
          "description": "Name of the context file to create/update during project initialization",
          "default": "AGENTS.md",
          "examples": [
            "AGENTS.md",
            "CRUSH.md",
            "CLAUDE.md",
            "docs/LLMs.md"
          ]
        },
        "auto_lsp": {
          "type": "boolean",
          "description": "Automatically setup LSPs based on root markers",
          "default": true
        },
        "progress": {
          "type": "boolean",
          "description": "Show indeterminate progress updates during long operations",
          "default": true
        },
        "disable_notifications": {
          "type": "boolean",
          "description": "Deprecated: Use notification_style instead. Disable desktop notifications",
          "default": false
        },
        "notification_style": {
          "type": "string",
          "enum": [
            "auto",
            "native",
            "osc",
            "bell",
            "disabled"
          ],
          "description": "Notification style to use. Options: auto (default)",
          "default": "auto"
        },
        "disabled_skills": {
          "items": {
            "type": "string",
            "examples": [
              "crush-config"
            ]
          },
          "type": "array",
          "description": "List of skill names to disable and hide from the agent"
        }
      },
      "additionalProperties": false,
      "type": "object"
    },
    "Permissions": {
      "properties": {
        "allowed_tools": {
          "items": {
            "type": "string",
            "examples": [
              "bash",
              "view"
            ]
          },
          "type": "array",
          "description": "List of tools that don't require permission prompts"
        }
      },
      "additionalProperties": false,
      "type": "object"
    },
    "ProviderConfig": {
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique identifier for the provider",
          "examples": [
            "openai"
          ]
        },
        "name": {
          "type": "string",
          "description": "Human-readable name for the provider",
          "examples": [
            "OpenAI"
          ]
        },
        "base_url": {
          "type": "string",
          "format": "uri",
          "description": "Base URL for the provider's API",
          "examples": [
            "https://api.openai.com/v1"
          ]
        },
        "type": {
          "type": "string",
          "enum": [
            "openai",
            "openai-compat",
            "openrouter",
            "vercel",
            "anthropic",
            "google",
            "azure",
            "bedrock",
            "google-vertex",
            "hyper",
            "litellm",
            "llamacpp",
            "lmstudio",
            "ollama",
            "omlx"
          ],
          "description": "Provider type that determines the API format",
          "default": "openai"
        },
        "api_key": {
          "type": "string",
          "description": "API key for authentication with the provider",
          "examples": [
            "$OPENAI_API_KEY"
          ]
        },
        "oauth": {
          "$ref": "#/$defs/Token",
          "description": "OAuth2 token for authentication with the provider"
        },
        "disable": {
          "type": "boolean",
          "description": "Whether this provider is disabled",
          "default": false
        },
        "system_prompt_prefix": {
          "type": "string",
          "description": "Custom prefix to add to system prompts for this provider"
        },
        "extra_headers": {
          "additionalProperties": {
            "type": "string"
          },
          "type": "object",
          "description": "Additional HTTP headers to send with requests"
        },
        "extra_body": {
          "type": "object",
          "description": "Additional fields to include in request bodies, only works with openai-compatible providers"
        },
        "provider_options": {
          "type": "object",
          "description": "Additional provider-specific options for this provider"
        },
        "flat_rate": {
          "type": "boolean",
          "description": "Flat-rate mode for this provider"
        },
        "discover_models": {
          "type": "boolean",
          "description": "Auto-discover models from /v1/models endpoint. When true with existing models they are merged (yours win)",
          "default": true
        },
        "models": {
          "items": {
            "$ref": "#/$defs/Model"
          },
          "type": "array",
          "description": "List of models available from this provider"
        }
      },
      "additionalProperties": false,
      "type": "object"
    },
    "SelectedModel": {
      "properties": {
        "model": {
          "type": "string",
          "description": "The model ID as used by the provider API",
          "examples": [
            "gpt-4o"
          ]
        },
        "provider": {
          "type": "string",
          "description": "The model provider ID that matches a key in the providers config",
          "examples": [
            "openai"
          ]
        },
        "reasoning_effort": {
          "type": "string",
          "enum": [
            "low",
            "medium",
            "high"
          ],
          "description": "Reasoning effort level for OpenAI models that support it"
        },
        "think": {
          "type": "boolean",
          "description": "Enable thinking mode for Anthropic models that support reasoning"
        },
        "max_tokens": {
          "type": "integer",
          "maximum": 200000,
          "description": "Maximum number of tokens for model responses",
          "examples": [
            4096
          ]
        },
        "temperature": {
          "type": "number",
          "maximum": 1,
          "minimum": 0,
          "description": "Sampling temperature",
          "examples": [
            0.7
          ]
        },
        "top_p": {
          "type": "number",
          "maximum": 1,
          "minimum": 0,
          "description": "Top-p (nucleus) sampling parameter",
          "examples": [
            0.9
          ]
        },
        "top_k": {
          "type": "integer",
          "description": "Top-k sampling parameter"
        },
        "frequency_penalty": {
          "type": "number",
          "description": "Frequency penalty to reduce repetition"
        },
        "presence_penalty": {
          "type": "number",
          "description": "Presence penalty to increase topic diversity"
        },
        "provider_options": {
          "type": "object",
          "description": "Additional provider-specific options for the model"
        }
      },
      "additionalProperties": false,
      "type": "object",
      "required": [
        "model",
        "provider"
      ]
    },
    "TUIOptions": {
      "properties": {
        "compact_mode": {
          "type": "boolean",
          "description": "Enable compact mode for the TUI interface",
          "default": false
        },
        "diff_mode": {
          "type": "string",
          "enum": [
            "unified",
            "split"
          ],
          "description": "Diff mode for the TUI interface"
        },
        "completions": {
          "$ref": "#/$defs/Completions",
          "description": "Completions UI options"
        },
        "transparent": {
          "type": "boolean",
          "description": "Enable transparent background for the TUI interface",
          "default": false
        },
        "scrollbar": {
          "type": "string",
          "enum": [
            "default",
            "always",
            "never"
          ],
          "description": "Chat scrollbar visibility",
          "default": "default"
        }
      },
      "additionalProperties": false,
      "type": "object"
    },
    "Token": {
      "properties": {
        "access_token": {
          "type": "string"
        },
        "refresh_token": {
          "type": "string"
        },
        "expires_in": {
          "type": "integer"
        },
        "expires_at": {
          "type": "integer"
        },
        "client": {
          "$ref": "#/$defs/OAuthClient"
        }
      },
      "additionalProperties": false,
      "type": "object",
      "required": [
        "access_token",
        "expires_in",
        "expires_at"
      ]
    },
    "ToolGlob": {
      "properties": {
        "timeout": {
          "type": "integer",
          "description": "Timeout for the glob tool call"
        }
      },
      "additionalProperties": false,
      "type": "object"
    },
    "ToolGrep": {
      "properties": {
        "timeout": {
          "type": "integer",
          "description": "Timeout for the grep tool call"
        }
      },
      "additionalProperties": false,
      "type": "object"
    },
    "ToolLs": {
      "properties": {
        "max_depth": {
          "type": "integer",
          "description": "Maximum depth for the ls tool",
          "default": 0,
          "examples": [
            10
          ]
        },
        "max_items": {
          "type": "integer",
          "description": "Maximum number of items to return for the ls tool",
          "default": 1000,
          "examples": [
            100
          ]
        }
      },
      "additionalProperties": false,
      "type": "object"
    },
    "Tools": {
      "properties": {
        "ls": {
          "$ref": "#/$defs/ToolLs"
        },
        "grep": {
          "$ref": "#/$defs/ToolGrep"
        },
        "glob": {
          "$ref": "#/$defs/ToolGlob"
        }
      },
      "additionalProperties": false,
      "type": "object"
    }
  }
}