opencode-schema.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "definitions": {
    "agent": {
      "description": "Agent configuration",
      "properties": {
        "color": {
          "description": "Badge color for subagent display (e.g., 'blue', 'orange', 'primary', 'warning')",
          "type": "string"
        },
        "description": {
          "description": "Description of the agent's purpose",
          "type": "string"
        },
        "disabled": {
          "default": false,
          "description": "Whether the agent is disabled and excluded from the registry entirely",
          "type": "boolean"
        },
        "hidden": {
          "default": false,
          "description": "Whether the agent is hidden from TUI agent switching",
          "type": "boolean"
        },
        "maxTokens": {
          "description": "Maximum tokens for the agent",
          "minimum": 1,
          "type": "integer"
        },
        "maxTurns": {
          "description": "Maximum number of tool-use turns per request for this agent. Default is 100.",
          "minimum": 1,
          "type": "integer"
        },
        "mode": {
          "description": "Agent mode: 'agent' for primary agents, 'subagent' for agents invoked by task tool",
          "enum": [
            "agent",
            "subagent"
          ],
          "type": "string"
        },
        "model": {
          "description": "Model ID for the agent",
          "enum": [
            "claude-4.5-opus",
            "claude-4-5-sonnet[1m]",
            "claude-4.6-opus",
            "claude-4.6-sonnet",
            "bedrock.claude-4.5-sonnet",
            "gemini-3.0-flash",
            "gemini-3.0-pro",
            "gpt-5",
            "o3",
            "o4-mini",
            "vertexai.claude-opus-4-5",
            "vertexai.claude-opus-4-6",
            "vertexai.claude-sonnet-4-5-m",
            "vertexai.claude-sonnet-4-6",
            "vertexai.gemini-3.0-flash",
            "vertexai.gemini-3.0-pro"
          ],
          "type": "string"
        },
        "name": {
          "description": "Display name for the agent",
          "type": "string"
        },
        "parallelToolUse": {
          "default": true,
          "description": "Whether to enable parallel tool execution for this agent. When true (default), independent tool calls run concurrently. Set to false to force sequential execution.",
          "type": "boolean"
        },
        "permission": {
          "additionalProperties": {
            "anyOf": [
              {
                "description": "Simple permission action",
                "enum": [
                  "allow",
                  "deny",
                  "ask"
                ],
                "type": "string"
              },
              {
                "additionalProperties": {
                  "enum": [
                    "allow",
                    "deny",
                    "ask"
                  ],
                  "type": "string"
                },
                "description": "Granular permission patterns (glob-pattern keys to action values)",
                "type": "object"
              }
            ]
          },
          "description": "Agent-specific permission overrides. Keys are tool names (e.g., 'bash', 'edit', 'skill'), values are either a simple action string or an object with glob-pattern keys",
          "type": "object"
        },
        "prompt": {
          "description": "Custom system prompt for the agent",
          "type": "string"
        },
        "reasoningEffort": {
          "description": "Reasoning effort for models that support it (OpenAI, Anthropic). 'max' is only available for models with maximum thinking support.",
          "enum": [
            "low",
            "medium",
            "high",
            "max"
          ],
          "type": "string"
        },
        "tools": {
          "additionalProperties": {
            "description": "Whether the tool is enabled for this agent",
            "type": "boolean"
          },
          "description": "Tool enable/disable configuration",
          "type": "object"
        }
      },
      "required": [
        "model"
      ],
      "type": "object"
    }
  },
  "description": "Configuration schema for the OpenCode application",
  "properties": {
    "agents": {
      "additionalProperties": {
        "description": "Agent configuration",
        "properties": {
          "color": {
            "description": "Badge color for subagent display (e.g., 'blue', 'orange', 'primary', 'warning')",
            "type": "string"
          },
          "description": {
            "description": "Description of the agent's purpose",
            "type": "string"
          },
          "disabled": {
            "default": false,
            "description": "Whether the agent is disabled and excluded from the registry entirely",
            "type": "boolean"
          },
          "hidden": {
            "default": false,
            "description": "Whether the agent is hidden from TUI agent switching",
            "type": "boolean"
          },
          "maxTokens": {
            "description": "Maximum tokens for the agent",
            "minimum": 1,
            "type": "integer"
          },
          "maxTurns": {
            "description": "Maximum number of tool-use turns per request for this agent. Default is 100.",
            "minimum": 1,
            "type": "integer"
          },
          "mode": {
            "description": "Agent mode: 'agent' for primary agents, 'subagent' for agents invoked by task tool",
            "enum": [
              "agent",
              "subagent"
            ],
            "type": "string"
          },
          "model": {
            "description": "Model ID for the agent",
            "enum": [
              "claude-4.5-opus",
              "claude-4-5-sonnet[1m]",
              "claude-4.6-opus",
              "claude-4.6-sonnet",
              "bedrock.claude-4.5-sonnet",
              "gemini-3.0-flash",
              "gemini-3.0-pro",
              "gpt-5",
              "o3",
              "o4-mini",
              "vertexai.claude-opus-4-5",
              "vertexai.claude-opus-4-6",
              "vertexai.claude-sonnet-4-5-m",
              "vertexai.claude-sonnet-4-6",
              "vertexai.gemini-3.0-flash",
              "vertexai.gemini-3.0-pro"
            ],
            "type": "string"
          },
          "name": {
            "description": "Display name for the agent",
            "type": "string"
          },
          "parallelToolUse": {
            "default": true,
            "description": "Whether to enable parallel tool execution for this agent. When true (default), independent tool calls run concurrently. Set to false to force sequential execution.",
            "type": "boolean"
          },
          "permission": {
            "additionalProperties": {
              "anyOf": [
                {
                  "description": "Simple permission action",
                  "enum": [
                    "allow",
                    "deny",
                    "ask"
                  ],
                  "type": "string"
                },
                {
                  "additionalProperties": {
                    "enum": [
                      "allow",
                      "deny",
                      "ask"
                    ],
                    "type": "string"
                  },
                  "description": "Granular permission patterns (glob-pattern keys to action values)",
                  "type": "object"
                }
              ]
            },
            "description": "Agent-specific permission overrides. Keys are tool names (e.g., 'bash', 'edit', 'skill'), values are either a simple action string or an object with glob-pattern keys",
            "type": "object"
          },
          "prompt": {
            "description": "Custom system prompt for the agent",
            "type": "string"
          },
          "reasoningEffort": {
            "description": "Reasoning effort for models that support it (OpenAI, Anthropic). 'max' is only available for models with maximum thinking support.",
            "enum": [
              "low",
              "medium",
              "high",
              "max"
            ],
            "type": "string"
          },
          "tools": {
            "additionalProperties": {
              "description": "Whether the tool is enabled for this agent",
              "type": "boolean"
            },
            "description": "Tool enable/disable configuration",
            "type": "object"
          }
        },
        "required": [
          "model"
        ],
        "type": "object"
      },
      "description": "Agent configurations",
      "properties": {
        "coder": {
          "$ref": "#/definitions/agent"
        },
        "descriptor": {
          "$ref": "#/definitions/agent"
        },
        "explorer": {
          "$ref": "#/definitions/agent"
        },
        "hivemind": {
          "$ref": "#/definitions/agent"
        },
        "summarizer": {
          "$ref": "#/definitions/agent"
        },
        "workhorse": {
          "$ref": "#/definitions/agent"
        }
      },
      "type": "object"
    },
    "autoCompact": {
      "default": true,
      "description": "Enable automatic compaction of session history",
      "type": "boolean"
    },
    "contextPaths": {
      "default": [
        ".github/copilot-instructions.md",
        ".cursorrules",
        ".cursor/rules/",
        "CLAUDE.md",
        "CLAUDE.local.md",
        "opencode.md",
        "opencode.local.md",
        "OpenCode.md",
        "OpenCode.local.md",
        "OPENCODE.md",
        "OPENCODE.local.md",
        "AGENTS.md",
        "AGENTS.local.md"
      ],
      "description": "Context paths for the application",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "data": {
      "description": "Storage configuration",
      "properties": {
        "directory": {
          "default": ".opencode",
          "description": "Directory where application data is stored",
          "type": "string"
        }
      },
      "required": [
        "directory"
      ],
      "type": "object"
    },
    "debug": {
      "default": false,
      "description": "Enable debug mode",
      "type": "boolean"
    },
    "debugLSP": {
      "default": false,
      "description": "Enable LSP debug mode",
      "type": "boolean"
    },
    "disableLSPDownload": {
      "default": false,
      "description": "Disable automatic downloading and installation of LSP servers. Can also be set via OPENCODE_DISABLE_LSP_DOWNLOAD environment variable.",
      "type": "boolean"
    },
    "lsp": {
      "additionalProperties": {
        "description": "LSP configuration for a language server",
        "properties": {
          "args": {
            "description": "Command arguments for the LSP server",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "command": {
            "description": "Command to execute for the LSP server",
            "type": "string"
          },
          "disabled": {
            "default": false,
            "description": "Whether the LSP server is disabled",
            "type": "boolean"
          },
          "env": {
            "additionalProperties": {
              "type": "string"
            },
            "description": "Environment variables to set when starting the LSP server",
            "type": "object"
          },
          "extensions": {
            "description": "File extensions this LSP server should handle (e.g., [\".go\", \".mod\"])",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "initialization": {
            "description": "Initialization options sent to the LSP server during the initialize request. Options vary by server.",
            "type": "object"
          }
        },
        "type": "object"
      },
      "description": "Language Server Protocol configurations. Built-in servers are auto-detected; use this to override, disable, or add custom servers.",
      "type": "object"
    },
    "maxTurns": {
      "description": "Global maximum number of agent tool-use turns per request. When set, overrides per-agent maxTurns. Also settable via --max-turns CLI flag.",
      "minimum": 1,
      "type": "integer"
    },
    "mcpServers": {
      "additionalProperties": {
        "description": "MCP server configuration",
        "properties": {
          "args": {
            "description": "Command arguments for the MCP server",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "command": {
            "description": "Command to execute for the MCP server",
            "type": "string"
          },
          "env": {
            "description": "Environment variables for the MCP server",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "headers": {
            "additionalProperties": {
              "type": "string"
            },
            "description": "HTTP headers for SSE type MCP servers",
            "type": "object"
          },
          "type": {
            "default": "stdio",
            "description": "Type of MCP server",
            "enum": [
              "stdio",
              "sse"
            ],
            "type": "string"
          },
          "url": {
            "description": "URL for SSE type MCP servers",
            "type": "string"
          }
        },
        "required": [
          "command"
        ],
        "type": "object"
      },
      "description": "Model Control Protocol server configurations",
      "type": "object"
    },
    "permission": {
      "additionalProperties": {
        "anyOf": [
          {
            "description": "Simple permission action for all uses of this tool",
            "enum": [
              "allow",
              "deny",
              "ask"
            ],
            "type": "string"
          },
          {
            "additionalProperties": {
              "enum": [
                "allow",
                "deny",
                "ask"
              ],
              "type": "string"
            },
            "description": "Granular permission patterns (glob-pattern keys to action values)",
            "type": "object"
          }
        ]
      },
      "description": "Global permission configuration. Keys are tool names (e.g., 'bash', 'edit', 'skill'). Values are either a simple action string or an object with glob-pattern keys.",
      "properties": {
        "skill": {
          "additionalProperties": {
            "description": "Permission action",
            "enum": [
              "allow",
              "deny",
              "ask"
            ],
            "type": "string"
          },
          "description": "Skill permission patterns (supports wildcards like 'internal-*')",
          "type": "object"
        }
      },
      "type": "object"
    },
    "providers": {
      "additionalProperties": {
        "description": "Provider configuration",
        "properties": {
          "apiKey": {
            "description": "API key for the provider",
            "type": "string"
          },
          "baseURL": {
            "description": "Base URL for the provider instead of default one",
            "type": "string"
          },
          "disabled": {
            "default": false,
            "description": "Whether the provider is disabled",
            "type": "boolean"
          },
          "headers": {
            "additionalProperties": {
              "type": "string"
            },
            "description": "Extra headers to attach to request",
            "type": "object"
          },
          "provider": {
            "description": "Provider type",
            "enum": [
              "anthropic",
              "openai",
              "gemini",
              "bedrock",
              "vertexai"
            ],
            "type": "string"
          }
        },
        "type": "object"
      },
      "description": "LLM provider configurations",
      "type": "object"
    },
    "sessionProvider": {
      "description": "Session storage provider configuration",
      "properties": {
        "mysql": {
          "description": "MySQL-specific configuration",
          "properties": {
            "connectionTimeout": {
              "default": 30,
              "description": "Connection timeout in seconds",
              "type": "integer"
            },
            "database": {
              "description": "MySQL database name",
              "type": "string"
            },
            "dsn": {
              "description": "MySQL Data Source Name (DSN) connection string",
              "type": "string"
            },
            "host": {
              "description": "MySQL server host",
              "type": "string"
            },
            "maxConnections": {
              "default": 10,
              "description": "Maximum number of open connections",
              "type": "integer"
            },
            "maxIdleConnections": {
              "default": 5,
              "description": "Maximum number of idle connections",
              "type": "integer"
            },
            "password": {
              "description": "MySQL password",
              "type": "string"
            },
            "port": {
              "default": 3306,
              "description": "MySQL server port",
              "type": "integer"
            },
            "username": {
              "description": "MySQL username",
              "type": "string"
            }
          },
          "type": "object"
        },
        "type": {
          "default": "sqlite",
          "description": "Type of session storage provider",
          "enum": [
            "sqlite",
            "mysql"
          ],
          "type": "string"
        }
      },
      "type": "object"
    },
    "shell": {
      "description": "Shell configuration for the bash tool",
      "properties": {
        "args": {
          "default": [
            "-l"
          ],
          "description": "Arguments to pass to the shell",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "path": {
          "description": "Path to the shell executable",
          "type": "string"
        }
      },
      "type": "object"
    },
    "skills": {
      "description": "Skills configuration",
      "properties": {
        "paths": {
          "description": "Custom paths to search for skills (supports ~ for home directory and relative paths)",
          "items": {
            "type": "string"
          },
          "type": "array"
        }
      },
      "type": "object"
    },
    "tui": {
      "description": "Terminal User Interface configuration",
      "properties": {
        "theme": {
          "default": "opencode",
          "description": "TUI theme name",
          "enum": [
            "opencode",
            "catppuccin",
            "dracula",
            "flexoki",
            "gruvbox",
            "monokai",
            "onedark",
            "tokyonight",
            "tron"
          ],
          "type": "string"
        }
      },
      "type": "object"
    },
    "wd": {
      "description": "Working directory for the application",
      "type": "string"
    },
    "webSearch": {
      "description": "Web search provider configuration",
      "properties": {
        "providers": {
          "additionalProperties": {
            "description": "Search provider configuration",
            "properties": {
              "apiKey": {
                "description": "API key for the provider. Supports 'env:VAR_NAME' syntax. Falls back to LOCAL_ENDPOINT_API_KEY env var.",
                "type": "string"
              },
              "baseUrl": {
                "description": "Full URL to POST search queries to",
                "type": "string"
              },
              "description": {
                "description": "Human-readable description shown to the LLM to help select the right provider",
                "type": "string"
              }
            },
            "required": [
              "baseUrl"
            ],
            "type": "object"
          },
          "description": "Search provider configurations keyed by provider name",
          "type": "object"
        }
      },
      "type": "object"
    }
  },
  "title": "OpenCode Configuration",
  "type": "object"
}