[FEATURE]: add opencode doctor diagnostic command #21269

Feature hasn't been suggested before.

• I have verified this feature I'm about to request hasn't been suggested before.

Describe the enhancement you want to request

OpenCode supports tons of providers, models, agents, MCP servers, LSP servers, formatters, and plugins -- all of which can be misconfigured in subtle ways. Right now there's no single command to check if everything is working. You end up running debug config, debug lsp, manually checking env vars, etc. and piecing together what's broken.

I'd like to add an opencode doctor command that runs a full diagnostic of your setup and gives you a clear, color-coded report of what's working and what isn't.

Here's what it would check:

Environment - OpenCode version and install method, Bun version, Git version, database connectivity

Updates - Whether auto-update is enabled, if there's a newer version available

Configuration - Try loading and validating the config. Catch JSON parse errors, schema issues, config directory typos. Show which config directories are being read from.

Providers & Models - This is the big one for OpenCode since it's provider-agnostic. For each provider: credential status (stored key, env var, OAuth, or nothing). Check if the default model can be resolved. Check if we can fetch from the model database (models.dev).

Agents - List all agents (native + custom), check if their configured models can be resolved, warn about unusually large descriptions eating into context.

Tools & Permissions - How many tools are available, which ones are disabled by permission rules, basic detection of shadowed/conflicting rules.

LSP Servers - Status of each language server (connected or error).

MCP Servers - Status of each MCP server (connected, disabled, failed, needs auth). Tool count for connected servers. Error messages for failed ones.

Formatters - Which formatters are enabled and what file extensions they cover. OpenCode has 20+ built-in formatters (prettier, gofmt, ruff, biome, etc.) and users often don't know which are active.

Plugins - How many loaded, any errors during loading.

Context Analysis - Warn about large agent descriptions, high MCP tool counts, or oversized configs that put pressure on the context window.

Environment Variables - Show active OPENCODE_* flags, flag invalid values (e.g. non-numeric for numeric flags), highlight experimental flags that are turned on.

Paths - Show global directories (data, config, cache, state) and verify they exist and are writable.

Each section is independently wrapped in error handling so one failure doesn't block the rest.

Flags:

• --json for machine-readable output (useful for CI, bug reports)
• --verbose for full details (all env vars, all tools, all paths)

Example output:

$ opencode doctor

Environment
  ✓ OpenCode v1.3.2 (latest channel)
  ✓ Installed via bun
  ✓ Bun v1.3.14
  ✓ Git v2.43.0
  ✓ Database: OK

Configuration
  ✓ Config loaded from ~/.config/opencode, ./.opencode
  ✓ Schema valid

Providers & Models
  ✓ anthropic - API key (env: ANTHROPIC_API_KEY)
  ✓ openai - API key (stored)
  ✗ google - no credentials
  ✓ Default model: anthropic/claude-sonnet-4-20250514
  ✓ Model database: 156 models from 18 providers

Agents
  ✓ 4 agents (3 native, 1 custom)
  ✓ All agent models resolvable

Tools & Permissions
  ✓ 27 tools available
  ⚠ 2 tools disabled by permission rules: edit, write

LSP Servers
  ✓ typescript - connected
  ✗ pyright - error

MCP Servers
  ✓ filesystem - connected (12 tools)
  ⚠ slack - needs authentication

Formatters
  ✓ 4 formatters active: prettier (js/ts/css), gofmt (go), ruff (py), biome (json)

Plugins
  ✓ 2 plugins loaded, no errors

Paths
  ✓ data    ~/.local/share/opencode
  ✓ config  ~/.config/opencode
  ✓ cache   ~/.cache/opencode
  ✓ state   ~/.local/state/opencode

All the APIs already exist: Config.get(), Auth.all(), Provider.defaultModel(), ModelsDev.get(), Agent.list(), ToolRegistry.tools(), Permission.disabled(), LSP.status(), MCP.status(), Format.status(), Plugin.list(), Global.Path, etc. This is about wiring them into a clean user-facing report.

Implementation would be 2 files: one new doctor.ts command and a registration line in index.ts.

Happy to work on a PR for this.