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

src/

Responsibility

Core plugin implementation for oh-my-opencode-slim, providing:

• Main plugin initialization and OpenCode integration (index.ts)
• Terminal User Interface (TUI) sidebar plugin for agent status display (tui.ts)
• TUI state persistence and synchronization across sessions (tui-state.ts)

This directory serves as the primary entry point for the plugin's runtime behavior, configuration system, and user-facing UI components.

Design

Architectural Patterns

• Plugin Pattern: The plugin follows OpenCode's plugin architecture with a single exported plugin function that returns agent, tool, and MCP registrations
• Facade Pattern: index.ts acts as a facade that composes multiple subsystems (agents, tools, MCPs, hooks, multiplexer)
• Observer Pattern: Event-driven architecture using OpenCode's event system for session lifecycle, message updates, and tool execution
• Strategy Pattern: Runtime model selection and fallback via ForegroundFallbackManager
• Singleton Pattern: MultiplexerSessionManager maintains single instance for task session management

Data Flow

OpenCode Core → Plugin Initialization (index.ts)
  → Agent Registration (createAgents/getAgentConfigs)
  → Tool Registration (createCouncilTool, createCancelTaskTool, etc.)
  → MCP Registration (createBuiltinMcps)
  → Hook Registration (auto-update, phase reminders, etc.)
  → Event Subscription (session lifecycle, message updates, tool execution)
  → Runtime State Tracking (tui-state.ts)
  → TUI Rendering (tui.ts → sidebar_content slot)

Key Components

File	Role	Dependencies
index.ts	Main plugin entry, orchestrates all subsystems	Config system, agent factories, tool creators, multiplexer
tui.ts	TUI sidebar plugin for agent model display	tui-state.ts, config constants
tui-state.ts	Persistent state management for TUI	Node.js fs/promises, os module

Flow

Plugin Initialization Flow (index.ts)

1. Config Loading: loadPluginConfig() reads and validates plugin configuration
2. Agent Creation: createAgents() instantiates agent definitions with prompts and permissions
3. Agent Configuration: getAgentConfigs() merges defaults with user overrides and runtime presets
4. Tool Registration: Tools are created conditionally based on config (council, cancel_task, webfetch, AST-grep)
5. MCP Registration: Built-in MCPs are created (filesystem, resource, tools, etc.)
6. Multiplexer Setup: Multiplexer session manager initialized for task tool sessions
7. Hook Initialization: Auto-update checker, phase reminders, skill filters, etc.
8. Runtime Model Resolution: Resolves model arrays to single models for startup
9. TUI State Sync: recordTuiAgentModels() captures resolved models/variants for TUI display
10. Health Check: Validates minimum agent/tool/MCP registrations
11. Companion Management: Ensures companion version compatibility

TUI Rendering Flow (tui.ts)

1. Plugin Registration: TUI plugin registered with OpenCode's TUI system via tui export
2. Version Detection: Reads plugin version from package.json or uses 'dev'
3. Config Validation: Checks if current directory has valid plugin config
4. Snapshot Loading: Reads agent models/variants from tui-state.ts
5. Live Updates: Sets up interval to refresh snapshot every 1000ms
6. Sidebar Rendering: Renders sidebar with:
   • Plugin header (OMO-Slim + version)
   • Config status warning (if invalid)
   • Agent list with model/variant details
7. Lifecycle Management: Cleans up interval on dispose

State Persistence Flow (tui-state.ts)

1. State Path Resolution: Determines XDG-compliant state directory (~/.local/share/opencode/storage/oh-my-opencode-slim/tui-state.json)
2. Snapshot Operations:
   • readTuiSnapshot(): Reads and parses state file (returns empty snapshot on error)
   • readTuiSnapshotAsync(): Async variant for TUI rendering
   • recordTuiAgentModels(): Updates both agent models and variants atomically
   • recordTuiAgentModel(): Updates single agent's model/variant
3. Atomic Writes: State updates are atomic (read → mutate → write with timestamp)
4. Error Handling: All operations are best-effort; failures don't crash plugin

Event Handling Flow (index.ts)

Key event flows:

1. Session Lifecycle:

   • session.created → register child session in SubagentDepthTracker
   • session.status → multiplexer session management and companion updates
   • session.deleted → cleanup depth tracker, session agent map, and companion state

2. Message Updates:

   • message.updated → record agent/model usage in TUI state

3. Tool Execution:

   • tool.execute.before → apply patch and task session hooks
   • tool.execute.after → post-tool hooks (retry guidance, JSON error recovery, file-tool nudges)

4. Chat Integration:

   • chat.message → track session → agent mapping
   • experimental.chat.system.transform → inject orchestrator prompt for serve mode
   • experimental.chat.messages.transform → phase reminders, skill filtering, image attachment processing

5. Command Execution:

   • command.execute.before → interview, preset, deepwork, and reflect command hooks

Integration

Consumers

• OpenCode Core: Main plugin entry point consumed by OpenCode's plugin system
• TUI System: tui.ts slot registration consumed by OpenCode's TUI renderer
• Agents: Agent configurations consumed by OpenCode's agent registry
• Tools: Tool definitions consumed by OpenCode's tool system
• MCPs: MCP definitions consumed by OpenCode's MCP registry

Dependencies

• Config System (src/config/): Configuration loading, validation, and runtime presets
• Agents (src/agents/): Agent personalities and permission sets
• Tools (src/tools/): Tool implementations (council, webfetch, AST operations)
• Hooks (src/hooks/): Lifecycle hooks for auto-update, phase reminders, etc.
• Multiplexer (src/multiplexer/): Tmux/Zellij session management for child sessions
• Council (src/council/): Multi-LLM council orchestration
• Companion (src/companion/): Companion version management
• Utils (src/utils/): Logger, environment checks, subagent depth tracking

Cross-Directory Flow

1. Plugin Initialization: src/index.ts imports and composes all subsystems
2. State Synchronization: TUI state in src/tui-state.ts is updated during plugin init and message events
3. UI Integration: TUI plugin in src/tui.ts reads state and renders sidebar
4. Event Propagation: Events flow from OpenCode → plugin handlers → subsystems → state updates

Configuration Integration

• Plugin config loaded via loadPluginConfig() with support for:
  • User overrides from ~/.config/opencode/oh-my-opencode-slim.json
  • Runtime presets via /preset command
  • Environment-based disablement via OH_MY_OPENCODE_SLIM_DISABLE
• Agent configurations merged with user settings from OpenCode config
• Model resolution supports both string models and array-based fallback chains

Error Handling & Resilience

• Config Errors: Non-fatal; plugin continues with defaults and logs warnings
• State Errors: Non-fatal; TUI falls back to empty state
• Event Errors: Wrapped in try/catch; plugin continues operation
• Dependency Failures: Health checks detect missing dependencies (e.g., jsdom for webfetch)

Testing & Validation

• Type Safety: TypeScript strict mode ensures type correctness
• Health Checks: Validates minimum agent/tool/MCP registrations on init
• Config Validation: Schema-based validation via Zod in config system
• TUI State: Best-effort persistence; failures don't affect core functionality

Performance Considerations

• Live Updates: TUI refreshes every 1000ms (configurable via interval)
• Atomic State: State writes are atomic to prevent corruption
• Lazy Initialization: Some subsystems (e.g., webfetch probe) run async without blocking init
• Event-Driven: Minimal polling; relies on OpenCode's event system

Future Extensions

• Dynamic Agent Registration: Support runtime agent addition/removal
• State Migration: Versioned state format for breaking changes
• TUI Customization: Allow user-defined sidebar layouts
• Performance Metrics: Track and display plugin performance in TUI