oh-my-opencode/src/cli/AGENTS.md

CLI KNOWLEDGE BASE

OVERVIEW

CLI for oh-my-opencode: interactive installer, health diagnostics (doctor), runtime launcher. Entry: bunx oh-my-opencode.

STRUCTURE

cli/
├── index.ts              # Commander.js entry, subcommand routing
├── install.ts            # Interactive TUI installer (436 lines)
├── config-manager.ts     # JSONC parsing, env detection (725 lines)
├── types.ts              # CLI-specific types
├── commands/             # CLI subcommands
├── doctor/               # Health check system
│   ├── index.ts          # Doctor command entry
│   ├── runner.ts         # Health check orchestration
│   ├── constants.ts      # Check categories
│   ├── types.ts          # Check result interfaces
│   └── checks/           # 17+ individual checks (auth, config, dependencies, gh, lsp, mcp, opencode, plugin, version)
├── get-local-version/    # Version detection
└── run/                  # OpenCode session launcher
    ├── completion.ts     # Completion logic
    └── events.ts         # Event handling

CLI COMMANDS

Command	Purpose
install	Interactive setup wizard
doctor	Environment health checks
run	Launch OpenCode session

DOCTOR CHECKS

17+ checks in doctor/checks/:

• version.ts (OpenCode >= 1.0.150)
• config.ts (plugin registered)
• bun.ts, node.ts, git.ts
• anthropic-auth.ts, openai-auth.ts, google-auth.ts
• lsp-.ts, mcp-.ts

CONFIG-MANAGER (669 lines)

• JSONC support (comments, trailing commas)
• Multi-source: User (~/.config/opencode/) + Project (.opencode/)
• Zod validation
• Legacy format migration
• Error aggregation for doctor

HOW TO ADD CHECK

1. Create src/cli/doctor/checks/my-check.ts:

   export const myCheck: DoctorCheck = {
     name: "my-check",
     category: "environment",
     check: async () => {
       return { status: "pass" | "warn" | "fail", message: "..." }
     }
   }
   

2. Add to src/cli/doctor/checks/index.ts

ANTI-PATTERNS

• Blocking prompts in non-TTY (check process.stdout.isTTY)
• Hardcoded paths (use shared utilities)
• JSON.parse for user files (use parseJsonc)
• Silent failures in doctor checks