oh-my-opencode-slim/src/config/codemap.md

Config Module Codemap

Responsibility

src/config/ owns plugin configuration schema, load/merge pipeline, prompt resolution, and helper APIs used by agents, council, and runtime subsystems.

Architecture

Core entry points

• loadPluginConfig(directory) is the top-level loader used by src/index.ts.
• PluginConfigSchema validates and normalizes raw config, including:
  • legacy council field deprecation capture
  • strict guard that prompt / orchestratorPrompt are only for custom agents.
• getAgentPrompt/loadAgentPrompt and related helpers are consumed by agent registry.

Merge and load pipeline

loadPluginConfig(directory):

1. Locate user config (prefer .jsonc, then .json) from:
   • OPENCODE_CONFIG_DIR
   • XDG_CONFIG_HOME/opencode
   • ~/.config/opencode
2. Locate project config at <directory>/.opencode/oh-my-opencode-slim.(jsonc|json).
3. Validate with schema. Invalid/malformed files are warned and ignored by returning null for that file.
4. Merge user+project configs where project takes precedence: nested merges for agents, tmux, multiplexer, interview, backgroundJobs, fallback, council. top-level arrays/values are overridden.
5. If tmux is enabled and no explicit multiplexer is configured, migrate to multiplexer (tmux compatibility path).
6. Apply env override OH_MY_OPENCODE_SLIM_PRESET over config file preset.
7. If preset exists, merge preset agents into agents so explicit root agents still win (deepMerge(preset, config.agents)).
8. Return merged config object.

Prompt discovery

loadAgentPrompt(agentName, preset?):

• Searches config directories for oh-my-opencode-slim/ prompt roots.
• Supports optional preset subdirectory lookup when preset is alphanumeric/ hyphen/underscore-safe.
• For each agent:
  • <agent>.md replacement prompt
  • <agent>_append.md appended prompt
• Read errors are warned and do not fail config load.

Schema surface and compatibility

• Agent override schema supports:
  • model string or ordered fallback array (string or {id, variant})
  • temperature, variant, options, skills, mcps, displayName
  • custom agent prompts (prompt, orchestratorPrompt) only.
• Multiplexer:
  • new unified multiplexer schema (auto|tmux|zellij|none)
  • legacy tmux schema retained and migrated at load time.
• Council:
  • CouncilConfigSchema now normalizes deprecated master* fields into _legacyMasterModel metadata for compatibility
  • supports presets + timeout/retry/execution mode.
• Fallback config supports per-agent chain arrays and retry/backoff values.

Control flow and dependencies

src/index.ts
  └─> loadPluginConfig(directory)
      ├─> Agent override application in src/agents/index.ts
      ├─> MCP defaults/filters in src/config/agent-mcps.ts
      ├─> Council session behavior in src/council/*
      ├─> Fallback/session behavior in runtime hooks
      └─> Multiplexer behavior in src/multiplexer/*

Key collaborators

• constants.ts
  • names/aliases, orchestratable lists, default models/timeouts/modes.
• agent-mcps.ts
  • getAgentMcpList, parseList, getAvailableMcpNames.
• utils.ts
  • alias resolution and custom-agent key discovery.
• loader.ts
  • config IO, deep merge, preset composition, env override, prompt loading.
• schema.ts, council-schema.ts
  • type/shape validation + transformation.

File structure

• index.ts — exported config surface
• loader.ts — load, merge, prompt resolution, tmux migration
• schema.ts — plugin config + agent override schemas
• council-schema.ts — council-specific and legacy compatibility schema
• constants.ts — defaults, names, delegation rules, timeouts
• agent-mcps.ts — MCP defaults and allow-list parsing
• utils.ts — config helper methods