Troubleshooting & Doctor
Relevant source files
The following files were used as context for generating this wiki page:
The Troubleshooting & Doctor system is a diagnostic suite designed to ensure the health and operational readiness of the Oh-My-OpenCode environment. It centralizes 14 distinct health checks ranging from installation integrity and configuration validity to authentication status and tool connectivity. The system provides developers with actionable feedback to resolve environmental blockers before starting an orchestration session.
This module is primarily accessed via the bunx oh-my-opencode doctor command, which utilizes a Terminal User Interface (TUI) powered by @clack/prompts to deliver formatted diagnostic reports. Sources: src/cli/AGENTS.md:5-10, src/cli/AGENTS.md:25-35
Diagnostic Architecture
The Doctor system is organized into a modular hierarchy where an orchestration runner executes a collection of standardized check definitions. Each check is an independent unit that returns a CheckResult containing the status and a descriptive message.
System Flow
The diagnostic flow moves from the CLI entry point through the runner, which iterates over a registry of check definitions.
The system leverages symbols to indicate status: ✓ (pass), ✗ (fail), ⚠ (warn), and ℹ (info). Sources: src/cli/AGENTS.md:65-72
Core Diagnostic Categories
The diagnostic suite is divided into several logical categories that cover the entire lifecycle of the plugin.
| Category | Description | Specific Checks |
|---|---|---|
| Installation | Verifies core platform integrity. | OpenCode version, plugin version. |
| Configuration | Validates settings and schema. | JSONC validity, Zod schema validation, Model resolution. |
| Authentication | Ensures API keys are active. | Anthropic, OpenAI, and Google provider status. |
| Dependencies | Checks for external binary tools. | AST-Grep, Comment Checker, GitHub CLI. |
| Tools | Validates integration endpoints. | LSP connectivity, MCP validation. |
Sources: src/cli/AGENTS.md:40-52
Authentication Diagnostics
The system validates API connectivity for different LLM providers. These checks ensure that the orchestrator can communicate with the configured models.
- Anthropic/OpenAI/Google: Verifies the presence and validity of API keys required by agents like Sisyphus or Prometheus.
Sources: src/cli/doctor/checks/auth.ts (referenced file), src/cli/AGENTS.md:46
Dependency Verification
The plugin relies on several external binaries to perform code analysis and version control tasks.
- AST-Grep: Required for structural code searches and pattern-based refactoring.
- GitHub CLI (gh): Required for PR management, issue viewing, and remote repository cloning used by the Librarian agent.
- Comment Checker: Used for project-level code quality enforcement.
Sources: src/cli/doctor/checks/dependencies.ts (referenced file), src/cli/AGENTS.md:49, src/cli/AGENTS.md:104
Agent-Level Troubleshooting
Beyond the CLI Doctor, individual agents include internal failure recovery protocols and self-correction logic.
Failure Recovery Protocol
If implementation or verification steps fail during an autonomous session, primary agents follow a strict "Shotgun Debugging" prevention loop.
Verification Requirements
For a task to be marked "Completed" and pass the internal troubleshooting gate, it must satisfy three pillars of evidence:
- LSP Diagnostics: Must return zero new errors on changed files.
- Build Integrity: The build command must exit with code 0.
- Test Results: All related tests must pass.
Sources: src/agents/hephaestus.ts:280-290, src/agents/hephaestus.ts:70-80
Implementation Guidelines for Diagnostics
When extending the troubleshooting suite, developers must adhere to the factory pattern used for check definitions.
Adding a New Check
- Location: Create the check file in
src/cli/doctor/checks/. - Factory: Export a
getXXXCheckDefinition()function. - Registration: Add the factory to
getAllCheckDefinitions()in the main registry.
Sources: src/cli/AGENTS.md:55-60
Anti-Patterns in Diagnostics
- Silent Failures: Checks should never throw exceptions; they should return a
failstatus with a descriptive message. - Blocking non-TTY: Always verify
process.stdout.isTTYbefore rendering interactive elements. - Manual Parsing: Use
parseJsonc()from shared utilities instead ofJSON.parseto support comments in configuration files.
Sources: src/cli/AGENTS.md:75-82
Summary
The Troubleshooting & Doctor system provides a robust safety net for the Oh-My-OpenCode plugin. By combining pre-flight CLI diagnostics with agent-level autonomous recovery loops, it ensures that technical debt and environmental issues are surfaced early and handled systematically. This dual-layered approach maintains high reliability in complex multi-agent orchestration tasks. Sources: src/cli/AGENTS.md:1-15, src/agents/hephaestus.ts:60-70