crabcode.schema.json

{
  "$defs": {
    "ImageOpenCommandConfigFile": {
      "additionalProperties": false,
      "properties": {
        "args": {
          "default": [
            "{path}"
          ],
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "command": {
          "type": "string"
        }
      },
      "required": [
        "command"
      ],
      "type": "object"
    },
    "CompactionConfigFile": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "additionalProperties": false,
          "properties": {
            "auto": {
              "default": true,
              "description": "Automatically compact when estimated context reaches the usable window.",
              "type": "boolean"
            },
            "prune": {
              "default": false,
              "description": "Remove stale tool outputs from provider requests while preserving durable history.",
              "type": "boolean"
            },
            "reserved": {
              "description": "Token buffer reserved before the context limit for compaction and model output.",
              "minimum": 0,
              "type": "integer"
            }
          },
          "type": "object"
        }
      ]
    },
    "ImageOpenWith": {
      "anyOf": [
        {
          "enum": [
            "auto",
            "system",
            "editor"
          ],
          "type": "string"
        },
        {
          "$ref": "#/$defs/ImageOpenCommandConfigFile"
        }
      ]
    },
    "ImagesConfigFile": {
      "additionalProperties": false,
      "properties": {
        "openWith": {
          "$ref": "#/$defs/ImageOpenWith",
          "default": "auto"
        },
        "open_with": {
          "$ref": "#/$defs/ImageOpenWith",
          "default": "auto"
        }
      },
      "type": "object"
    },
    "EditorConfigFile": {
      "anyOf": [
        {
          "type": "string",
          "description": "Shell template for the Open action on a file path. Placeholders: {pathname}, {path}, {filename}, {pathname_raw}, {line}, {column}, {col}, {location}."
        },
        {
          "additionalProperties": false,
          "properties": {
            "open": {
              "type": "string",
              "description": "Shell template for the Open action on a file path. Placeholders: {pathname}, {path}, {filename}, {pathname_raw}, {line}, {column}, {col}, {location}."
            },
            "suspend": {
              "type": "boolean",
              "default": false,
              "description": "Leave the TUI, run `open` in the terminal, then restore crabcode. Use this for Helix and Neovim without a multiplexer."
            },
            "text": {
              "anyOf": [
                {
                  "$ref": "#/$defs/EditorOpenerConfigFile"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Optional UTF-8 plain-text opener. Used after ordered filename overrides, before open or automatic detection. String shorthand defaults suspend to false; object suspend does not inherit editor.suspend. Bounded content heuristic excludes known binary/container signatures; unreadable and non-regular files fall back."
            },
            "overrides": {
              "type": "object",
              "description": "Case-insensitive basename globs in document order; the first match wins, before text and open. Each entry has its own suspend (default false).",
              "additionalProperties": {
                "$ref": "#/$defs/EditorOpenerConfigFile"
              }
            }
          },
          "type": "object"
        }
      ],
      "description": "Deprecated legacy editor configuration. Prefer fileActions.open. Legacy filename overrides always run before editor.text."
    },
    "ReasoningEffort": {
      "enum": [
        "none",
        "off",
        "minimal",
        "low",
        "medium",
        "high",
        "xhigh",
        "extra-high",
        "max"
      ],
      "type": "string"
    },
    "AgentConfigFile": {
      "additionalProperties": true,
      "properties": {
        "reasoningEffort": {
          "description": "Subagent reasoning effort override. Use null/false/none/off or omit to send no reasoning_effort parameter; use an effort string to send that explicit value.",
          "anyOf": [
            {
              "$ref": "#/$defs/ReasoningEffort"
            },
            {
              "const": false
            },
            {
              "type": "null"
            }
          ]
        },
        "reasoning_effort": {
          "description": "Alias for reasoningEffort.",
          "anyOf": [
            {
              "$ref": "#/$defs/ReasoningEffort"
            },
            {
              "const": false
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "type": "object"
    },
    "AgentConfigMap": {
      "additionalProperties": {
        "$ref": "#/$defs/AgentConfigFile"
      },
      "type": "object"
    },
    "TerminalNotificationMode": {
      "anyOf": [
        {
          "enum": [
            "auto",
            "enabled",
            "disabled",
            "on",
            "off",
            "true",
            "false"
          ],
          "type": "string"
        },
        {
          "type": "boolean"
        }
      ]
    },
    "TerminalNotificationCondition": {
      "enum": [
        "unfocused",
        "always"
      ],
      "type": "string"
    },
    "MacosNotificationBackend": {
      "enum": [
        "crabcode",
        "osascript"
      ],
      "type": "string"
    },
    "NotificationEventConfigFile": {
      "additionalProperties": false,
      "properties": {
        "terminal": {
          "$ref": "#/$defs/TerminalNotificationMode"
        },
        "soundEnabled": {
          "type": [
            "boolean",
            "null"
          ]
        },
        "sound_enabled": {
          "type": [
            "boolean",
            "null"
          ]
        },
        "soundFile": {
          "type": [
            "string",
            "null"
          ]
        },
        "sound_file": {
          "type": [
            "string",
            "null"
          ]
        },
        "desktop": {
          "default": false,
          "type": [
            "boolean",
            "null"
          ]
        }
      },
      "type": "object"
    },
    "NotificationsConfigFile": {
      "additionalProperties": false,
      "properties": {
        "complete": {
          "anyOf": [
            {
              "$ref": "#/$defs/NotificationEventConfigFile"
            },
            {
              "type": "null"
            }
          ]
        },
        "subagentComplete": {
          "anyOf": [
            {
              "$ref": "#/$defs/NotificationEventConfigFile"
            },
            {
              "type": "null"
            }
          ]
        },
        "subagent_complete": {
          "anyOf": [
            {
              "$ref": "#/$defs/NotificationEventConfigFile"
            },
            {
              "type": "null"
            }
          ]
        },
        "error": {
          "anyOf": [
            {
              "$ref": "#/$defs/NotificationEventConfigFile"
            },
            {
              "type": "null"
            }
          ]
        },
        "permission": {
          "anyOf": [
            {
              "$ref": "#/$defs/NotificationEventConfigFile"
            },
            {
              "type": "null"
            }
          ]
        },
        "question": {
          "anyOf": [
            {
              "$ref": "#/$defs/NotificationEventConfigFile"
            },
            {
              "type": "null"
            }
          ]
        },
        "terminalCondition": {
          "$ref": "#/$defs/TerminalNotificationCondition",
          "default": "unfocused"
        },
        "terminal_condition": {
          "$ref": "#/$defs/TerminalNotificationCondition",
          "default": "unfocused"
        },
        "macosBackend": {
          "$ref": "#/$defs/MacosNotificationBackend",
          "default": "crabcode"
        },
        "macos_backend": {
          "$ref": "#/$defs/MacosNotificationBackend",
          "default": "crabcode"
        }
      },
      "type": "object"
    },
    "WebsearchProvider": {
      "enum": [
        "exa-hosted-mcp",
        "firecrawl-hosted-mcp",
        "exa",
        "tavily",
        "perplexity",
        "brave",
        "ollama-cloud",
        "serpapi",
        "keiro"
      ],
      "type": "string"
    },
    "WebsearchConfigFile": {
      "additionalProperties": false,
      "properties": {
        "enabled": {
          "type": "boolean"
        },
        "provider": {
          "$ref": "#/$defs/WebsearchProvider",
          "default": "exa-hosted-mcp"
        },
        "endpoint": {
          "type": [
            "string",
            "null"
          ]
        },
        "apiKey": {
          "description": "Optional API key value. Use placeholders like {env:EXA_API_KEY} or {file:~/.keys/exa}. Required for keyed providers; optional for exa-hosted-mcp and firecrawl-hosted-mcp.",
          "anyOf": [
            {
              "type": "string"
            },
            {
              "const": false
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "type": "object"
    },
    "EditorOpenerConfigFile": {
      "anyOf": [
        {
          "type": "string",
          "minLength": 1
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "open"
          ],
          "properties": {
            "open": {
              "type": "string",
              "minLength": 1
            },
            "suspend": {
              "type": "boolean",
              "default": false
            }
          }
        }
      ]
    },
    "FileActionOpenerConfigFile": {
      "anyOf": [
        {
          "type": "string",
          "minLength": 1
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": ["open"],
          "properties": {
            "open": {
              "type": ["string", "null"],
              "minLength": 1
            },
            "suspend": {
              "type": ["boolean", "null"],
              "default": false
            }
          }
        },
        {
          "type": "null"
        }
      ],
      "description": "File action opener. Null values delete inherited keys during source-layer merging."
    },
    "FileActionsConfigFile": {
      "type": [
        "object",
        "null"
      ],
      "additionalProperties": false,
      "properties": {
        "open": {
          "$ref": "#/$defs/FileActionOpenConfigFile"
        }
      },
      "description": "Configure file actions. Without open, legacy editor remains active. Invalid fileActions/open/default/overrides structure warns and preserves legacy editor; invalid individual overrides warn and are skipped."
    },
    "FileActionOpenConfigFile": {
      "type": [
        "object",
        "null"
      ],
      "additionalProperties": false,
      "properties": {
        "default": {
          "anyOf": [
            {
              "$ref": "#/$defs/FileActionOpenerConfigFile"
            },
            {
              "type": "null"
            }
          ],
          "description": "Default opener: command or {open, suspend}. Omitted/null selects the detected integrated editor or system application. system explicitly selects the OS default application."
        },
        "overrides": {
          "type": [
            "object",
            "null"
          ],
          "propertyNames": {
            "anyOf": [
              {
                "const": "type:text"
              },
              {
                "type": "string",
                "minLength": 1,
                "pattern": "^(?!type:).+"
              }
            ]
          },
          "additionalProperties": {
            "$ref": "#/$defs/FileActionOpenerConfigFile"
          },
          "description": "Ordered case-insensitive basename globs or exact type:text content predicate (bounded UTF-8 plain-text heuristic). First match wins in written order, including type:text. Only type:text is supported; other type: keys warn and are skipped. Each opener suspend defaults independently to false."
        }
      },
      "description": "Replaces legacy editor entirely when valid. Default is used only if no override matches; no fallback field. Layered objects merge deeply: existing rule positions stay fixed, new rules append, and null removes inherited keys."
    }
  },
  "$id": "https://raw.githubusercontent.com/blankeos/crabcode/main/crabcode.schema.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "properties": {
    "$schema": {
      "type": [
        "string",
        "null"
      ]
    },
    "agent": {
      "anyOf": [
        {
          "$ref": "#/$defs/AgentConfigMap"
        },
        {
          "type": "null"
        }
      ]
    },
    "command": true,
    "compaction": {
      "$ref": "#/$defs/CompactionConfigFile"
    },
    "default_agent": true,
    "disabled_providers": true,
    "enabled_providers": true,
    "formatter": true,
    "instructions": true,
    "images": {
      "anyOf": [
        {
          "$ref": "#/$defs/ImagesConfigFile"
        },
        {
          "type": "null"
        }
      ]
    },
    "editor": {
      "anyOf": [
        {
          "$ref": "#/$defs/EditorConfigFile"
        },
        {
          "type": "null"
        }
      ],
      "deprecated": true,
      "description": "Deprecated: use fileActions.open. Retained for compatibility; a valid fileActions.open replaces this entire configuration."
    },
    "mcp": true,
    "model": {
      "type": [
        "string",
        "null"
      ]
    },
    "small_model": {
      "description": "Optional lightweight model used for background tasks like session title generation. Title generation is disabled unless this is configured.",
      "type": [
        "string",
        "null"
      ]
    },
    "smallModel": {
      "description": "Alias for small_model.",
      "type": [
        "string",
        "null"
      ]
    },
    "notifications": {
      "anyOf": [
        {
          "$ref": "#/$defs/NotificationsConfigFile"
        },
        {
          "type": "null"
        }
      ]
    },
    "permission": true,
    "provider": true,
    "theme": {
      "type": [
        "string",
        "null"
      ]
    },
    "tui": {
      "description": "Crabcode terminal UI settings. compactMode takes precedence over the saved /compact-mode preference.",
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "compactMode": {
          "description": "Enable sticky headers for compact mode. Alias: compact_mode.",
          "type": "boolean"
        },
        "compact_mode": {
          "description": "Alias for compactMode.",
          "type": "boolean"
        }
      }
    },
    "tools": true,
    "websearch": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "$ref": "#/$defs/WebsearchConfigFile"
        },
        {
          "type": "null"
        }
      ]
    },
    "watcher": true,
    "fileActions": {
      "$ref": "#/$defs/FileActionsConfigFile"
    }
  },
  "title": "CrabcodeConfigFile",
  "type": "object"
}