Imported from srod/oh-my-opencode-config (AGENTS.md). Install upstream with npx skills add srod/oh-my-opencode-config. Copyright stays with the author.

oh-my-opencode-config

Interactive CLI for managing model assignments in oh-my-opencode.json.

Runtime: Bun only. No npm/yarn/pnpm.

bun install        # deps
bun run build      # tsc → dist/
bun run dev        # hot reload (--conditions=source)
bun run test       # bun:test (--conditions=source)
bun run check      # biome lint+format
bun run typecheck  # tsc --noEmit

Task Completion Requirements

• Both bun run check:fix and bun run typecheck must pass before considering tasks completed.
• Use bun run test for task completion rather than invoking bun test directly.

Structure

src/
├── cli/
│   ├── index.ts       # Commander setup, all command registration
│   ├── types.ts       # BaseCommandOptions (imported by ALL commands)
│   └── commands/      # Command implementations [see: cli/commands/AGENTS.md]
├── config/            # Config handling [see: config/AGENTS.md]
├── types/             # Zod schemas (Config, Model, Requirements, Colors)
├── models/            # Models cache parser + opencode.json custom model loader
├── validation/        # Model capability validation (type guards, not assertions)
├── prompts/           # @clack/prompts TUI (agents, models, variants, provider, searchable select)
├── profile/           # Named config profiles via symlinks (save/load/switch/delete/rename)
├── diff/              # Config diff generation + chalk formatting
├── backup/            # Backup rotation (keep 10) + restore
├── errors/            # Error classes (7) + centralized handler
├── update/            # CLI update notifier (npm registry check, 24h cache)
├── utils/             # Shared utilities (fs, output, npm, merge, execa, bun-file)
├── scripts/           # sync-agent-defaults (fetch upstream model-requirements.ts)
├── test-utils/        # Shared test helpers (asMock, clack mocks)
└── index.ts           # Entry (#!/usr/bin/env bun)

Where to Look

Key Files

• Models cache: ~/.cache/opencode/models.json (read-only, from opencode models)
• Available models cache: ~/.cache/oh-my-opencode-config/available-models.json (1h TTL)
• User config: ~/.config/opencode/oh-my-opencode.json
• Project config: .opencode/oh-my-opencode.json (precedence)
• OpenCode config: ~/.config/opencode/opencode.json (custom models from plugins)
• Profiles: sibling to config (e.g. oh-my-opencode-{name}.json, symlinked)
• Profile template: oh-my-opencode.template.json (merged into profiles on save)

Most-Imported Modules (Centrality)

Conventions

Type Safety (STRICT)

• No any — enforced by biome + tsconfig
• No ! (non-null assertion) — enforced
• No as Type — use type guards (isAgentName, isCapability, hasProperty, isErrnoException)
• Zod schemas for all external data (never raw JSON.parse)
• noUncheckedIndexedAccess: true
• as const satisfies for readonly constant records

Shared Utilities (USE THESE, don't inline)

File Operations

• Atomic writes: temp file + fs.rename [see: config/writer.ts, utils/fs.ts]
• Symlink resolution in atomicWrite (up to 40 levels, loop detection)
• Use Bun.file() / Bun.write() over node:fs

Error Handling

• Custom errors in src/errors/types.ts (7 classes: CacheMissing, CacheCorrupted, PermissionDenied, ConcurrentModification, InvalidConfig, GracefulExit, CacheExpired)
• Profile errors in src/profile/manager.ts (6 classes: ProfileName, ProfileActive, ProfileNotFound, ProfileExists, DanglingSymlink + base ProfileError)
• Centralized handling via handleError(error, verbose)
• User cancellation → GracefulExitError → exit 0
• No stack traces to users (only with --verbose)

Profile Architecture

• Profiles stored as oh-my-opencode-{name}.json files
• Active profile = symlink from oh-my-opencode.json → profile file
• Atomic symlink swap via temp symlink + rename
• Template merge on save (oh-my-opencode.template.json + deepMerge)
• Auto-creates "default" profile on first save

Testing

• Co-located: *.test.ts next to source
• bun:test framework
• Mock with mock.module(), spy with spyOn
• File tests: fs.mkdtemp + os.tmpdir() for isolation
• Shared mock setup: src/cli/commands/test-mocks.ts (central mock registry, 178 lines)
• Clack mocks: src/test-utils/clack-mocks.ts (pre-built prompt mocks)
• Mock helper: src/test-utils/mocks.ts (asMock() for type-safe mock casting)
• Baseline: 273 pass, 0 fail across 23 files

Anti-Patterns

Known Deviations

• Uses execa instead of Bun.$ for shell (except models/parser.ts which uses Bun.$)
• .js extensions in imports (NodeNext)
• tsc build instead of bun build
• Path aliases: #backup/*, #cli/*, #config/*, #diff/*, #errors/*, #models/*, #profile/*, #prompts/*, #types/*, #update/*, #utils/*, #validation/*

Commands

Global flags: --json --config <path> --opencode-config <path> --refresh --verbose --dry-run --template <path> --no-update-notifier