CLI Module Codemap

Responsibility

The src/cli/ directory provides the command-line interface for installing and configuring oh-my-opencode-slim, an OpenCode plugin. It handles:

Installation orchestration: Interactive and non-interactive installation flows
Configuration management: Reading, parsing, and writing OpenCode configuration files
Skill management: Installing recommended skills (via npx) and custom skills (bundled)
Provider configuration: Setting up model mappings for different AI providers (Kimi, OpenAI, Zen)
System integration: Detecting OpenCode installation, validating environment

Design

Architecture Pattern

The CLI module follows a layered architecture with clear separation of concerns:

┌─────────────────────────────────────────┐
│         index.ts (Entry Point)          │
│    - Argument parsing                    │
│    - Command routing                     │
└─────────────────┬───────────────────────┘
                  │
┌─────────────────▼───────────────────────┐
│         install.ts (Orchestrator)       │
│    - Interactive TUI                     │
│    - Installation workflow               │
│    - Step-by-step execution              │
└─────────────────┬───────────────────────┘
                  │
    ┌─────────────┼─────────────┐
    │             │             │
┌───▼────┐  ┌────▼────┐  ┌────▼──────┐
│ config │  │ skills  │  │  system   │
│  -io   │  │         │  │           │
│ paths  │  │custom   │  │           │
│providers│ │         │  │           │
└────────┘  └─────────┘  └────────────┘

Key Abstractions

1. Configuration Abstraction

OpenCodeConfig (types.ts):

interface OpenCodeConfig {
  plugin?: string[];
  provider?: Record<string, unknown>;
  agent?: Record<string, unknown>;
  [key: string];
}

Represents the main OpenCode configuration file (opencode.json/opencode.jsonc).

InstallConfig (types.ts):

interface InstallConfig {
  hasKimi: boolean;
  hasOpenAI: boolean;
  hasOpencodeZen: boolean;
  hasTmux: boolean;
  installSkills: boolean;
  installCustomSkills: boolean;
}

User preferences collected during installation.

2. Skill Abstractions

RecommendedSkill (skills.ts):

interface RecommendedSkill {
  name: string;
  repo: string;
  skillName: string;
  allowedAgents: string[];
  description: string;
  postInstallCommands?: string[];
}

Skills installed via npx skills add from external repositories.

CustomSkill (custom-skills.ts):

interface CustomSkill {
  name: string;
  description: string;
  allowedAgents: string[];
  sourcePath: string;
}

Skills bundled in the repository, copied directly to ~/.config/opencode/skills/.

3. Result Abstraction

ConfigMergeResult (types.ts):

interface ConfigMergeResult {
  success: boolean;
  configPath: string;
  error?: string;
}

Standardized result type for configuration operations.

Design Patterns

Atomic Write Pattern (config-io.ts):
- Write to temporary file (.tmp)
- Rename to target path (atomic operation)
- Backup existing file (.bak) before writes
JSONC Support (config-io.ts):
- Strip comments (single-line // and multi-line /* */)
- Remove trailing commas
- Parse as standard JSON
Provider Priority (providers.ts):
- Kimi > OpenAI > Zen-free (fallback)
- Hybrid mode: Kimi for orchestrator/designer, OpenAI for oracle
Skill Permission Model (skills.ts):
- Orchestrator gets * (all skills)
- Other agents get role-specific skills
- Wildcard support (*, !skill)

Flow

Installation Flow

User runs: bunx oh-my-opencode-slim install
         │
         ▼
┌─────────────────────────────────────────┐
│ index.ts: parseArgs()                   │
│ - Parse CLI arguments                   │
│ - Validate --no-tui mode requirements   │
└─────────────────┬───────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────┐
│ install.ts: install()                   │
│                                         │
│ ┌─────────────────────────────────────┐ │
│ │ Interactive Mode (--tui, default)   │ │
│ │ 1. Check OpenCode installed         │ │
│ │ 2. Ask user questions (TUI)         │ │
│ │    - Kimi access?                   │ │
│ │    - OpenAI access?                 │ │
│ │    - Install recommended skills?    │ │
│ │    - Install custom skills?         │ │
│ └─────────────────────────────────────┘ │
│                                         │
│ ┌─────────────────────────────────────┐ │
│ │ Non-Interactive Mode (--no-tui)     │ │
│ │ - Validate all required flags       │ │
│ │ - Convert args to InstallConfig     │ │
│ └─────────────────────────────────────┘ │
└─────────────────┬───────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────┐
│ install.ts: runInstall()                │
│                                         │
│ Step 1: Check OpenCode installation     │
│   └─> system.ts: isOpenCodeInstalled() │
│                                         │
│ Step 2: Add plugin to config            │
│   └─> config-io.ts:                     │
│      addPluginToOpenCodeConfig()        │
│      - Parse existing config            │
│      - Add 'oh-my-opencode-slim'        │
│      - Remove old versions              │
│      - Atomic write                     │
│                                         │
│ Step 3: Disable default agents          │
│   └─> config-io.ts:                     │
│      disableDefaultAgents()             │
│      - Set agent.explore.disable=true   │
│      - Set agent.general.disable=true   │
│                                         │
│ Step 4: Write lite config               │
│   └─> config-io.ts: writeLiteConfig()   │
│      └─> providers.ts:                  │
│         generateLiteConfig()            │
│         - Determine active preset       │
│         - Build agent configurations    │
│         - Map models to agents          │
│         - Assign skills per agent       │
│         - Add MCPs per agent            │
│                                         │
│ Step 5: Install recommended skills      │
│   └─> skills.ts: installSkill()        │
│      - npx skills add <repo>            │
│      - Run post-install commands        │
│                                         │
│ Step 6: Install custom skills           │
│   └─> custom-skills.ts:                 │
│      installCustomSkill()               │
│      - Copy from src/skills/            │
│      - To ~/.config/opencode/skills/    │
│                                         │
│ Step 7: Print summary & next steps      │
└─────────────────────────────────────────┘

Configuration Detection Flow

detectCurrentConfig() [config-io.ts]
         │
         ▼
┌─────────────────────────────────────────┐
│ Parse opencode.json/jsonc               │
│ - Check for plugin entry                │
│ - Check for kimi provider               │
└─────────────────┬───────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────┐
│ Parse oh-my-opencode-slim.json          │
│ - Extract preset name                   │
│ - Check agent models for OpenAI/Zen     │
│ - Check tmux.enabled flag               │
└─────────────────────────────────────────┘

Model Mapping Flow

generateLiteConfig() [providers.ts]
         │
         ▼
┌─────────────────────────────────────────┐
│ Determine active preset                 │
│ - hasKimi → 'kimi'                      │
│ - hasOpenAI → 'openai'                  │
│ - else → 'zen-free'                     │
└─────────────────┬───────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────┐
│ For each agent (orchestrator, oracle,   │
│ librarian, explorer, designer, fixer):  │
│                                         │
│ 1. Get model from MODEL_MAPPINGS        │
│ 2. Apply hybrid logic (if needed)       │
│ 3. Assign skills:                       │
│    - Orchestrator: '*'                  │
│    - Others: role-specific skills       │
│ 4. Add MCPs from DEFAULT_AGENT_MCPS     │
└─────────────────────────────────────────┘

Integration

External Dependencies

Module	Dependency	Purpose
`system.ts`	`opencode` CLI	Check installation, get version
`skills.ts`	`npx skills`	Install recommended skills
`skills.ts`	`npm`	Install agent-browser globally
`skills.ts`	`agent-browser` CLI	Install browser automation
`system.ts`	`tmux` CLI	Check tmux installation

Internal Dependencies

index.ts
  └─> install.ts
       ├─> config-io.ts
       │    ├─> paths.ts
       │    └─> providers.ts
       ├─> custom-skills.ts
       ├─> skills.ts
       └─> system.ts

config-manager.ts (barrel)
  ├─> config-io.ts
  ├─> paths.ts
  ├─> providers.ts
  └─> system.ts

Configuration Files

File	Location	Purpose
`opencode.json`	`~/.config/opencode/`	Main OpenCode config
`opencode.jsonc`	`~/.config/opencode/`	Main config with comments
`oh-my-opencode-slim.json`	`~/.config/opencode/`	Plugin-specific config

Consumers

End Users: Via bunx oh-my-opencode-slim install
OpenCode: Reads generated configs to load plugin and agents
CI/CD: Via --no-tui flag for automated installations

Data Flow Summary

User Input (CLI args or TUI)
         │
         ▼
InstallConfig (preferences)
         │
         ├─> OpenCodeConfig (main config)
         │    - Plugin registration
         │    - Agent disabling
         │
         └─> LiteConfig (plugin config)
              - Preset selection
              - Model mappings
              - Skill assignments
              - MCP configurations
              - Tmux settings

Key Files Reference

File	Lines	Purpose
`index.ts`	68	CLI entry point, argument parsing
`install.ts`	402	Installation orchestration, TUI
`config-io.ts`	251	Config file I/O, JSONC parsing
`providers.ts`	110	Model mappings, config generation
`skills.ts`	132	Recommended skills management
`custom-skills.ts`	99	Bundled skills management
`paths.ts`	48	Path resolution utilities
`system.ts`	53	System checks (OpenCode, tmux)
`types.ts`	40	TypeScript type definitions
`config-manager.ts`	5	Barrel exports

codemap.md 13 KB Permalink History Raw