oh-my-opencode-slim/codemap.md

Repository Atlas: oh-my-opencode-slim

Project Responsibility

oh-my-opencode-slim is an OpenCode plugin that adds a specialist-agent operating model on top of the host runtime. Its core job is to:

• define orchestrator and specialist agents,
• load layered plugin configuration and per-agent permissions,
• expose additional tools and MCP integrations,
• manage delegated session orchestration and terminal multiplexer visualization,
• inject workflow-enforcement hooks,
• ship install-time skills and a bootstrap CLI.

This codemap intentionally covers the plugin repository itself and excludes the nested opencode/ upstream checkout.

System Entry Points

Path	Role
package.json	Package manifest, dependency graph, release scripts, published file list.
src/index.ts	Main plugin bootstrap: wires agents, tools, MCPs, hooks, council/session managers, multiplexer session mirroring, interview manager, and config merge behavior.
src/cli/index.ts	CLI entrypoint for installation/bootstrap workflows.
src/config/schema.ts	Source-of-truth runtime config schema used by validation and schema generation.
scripts/generate-schema.ts	Generates oh-my-opencode-slim.schema.json from the Zod config schema.

Repository Directory Map

Directory	Responsibility Summary	Detailed Map
src/	Main application surface that composes plugin bootstrap, runtime modules, and installer-facing code.	View Map
src/agents/	Agent factory layer for orchestrator and specialists, including MCP assignment and permission shaping.	View Map
src/cli/	Installer, config editing, provider preset generation, and built-in skill installation.	View Map
src/config/	Configuration schema, loaders, constant tables, and agent/MCP policy helpers.	View Map
src/council/	Multi-model council orchestration and synthesis fallback flow.	View Map
src/hooks/	Aggregated runtime hook surface for prompt transforms, recovery logic, nudges, and lifecycle policies.	View Map
src/hooks/apply-patch/	Structured apply_patch parsing, matching, recovery, and rewrite pipeline.	View Map
src/hooks/auto-update-checker/	Startup update detection, cache handling, and optional install prompt flow.	View Map
src/hooks/delegate-task-retry/	Post-tool retry guidance for failed delegation attempts.	View Map
src/hooks/filter-available-skills/	Skill-visibility filtering based on agent permission policy.	View Map
src/hooks/foreground-fallback/	Interactive-session fallback control path for rate-limit or degraded foreground execution.	View Map
src/hooks/json-error-recovery/	JSON/tool-output recovery helpers for malformed model responses.	View Map
src/hooks/phase-reminder/	Message-transform reminder enforcing orchestrator workflow phases.	View Map
src/hooks/post-file-tool-nudge/	Post-read/write reminder path that nudges delegation-aware next steps.	View Map
src/hooks/todo-continuation/	Auto-continue behavior for outstanding todo execution.	View Map
src/interview/	/interview feature: prompt/state orchestration, persistence, local UI, and dashboard mode.	View Map
src/mcp/	Built-in MCP registry and per-provider MCP definitions.	View Map
src/multiplexer/	Terminal multiplexer abstraction layer with backend selection, session mirroring, and shutdown lifecycle orchestration.	View Map
src/multiplexer/tmux/	tmux backend implementation for pane lifecycle and layout management.	View Map
src/multiplexer/zellij/	zellij backend implementation for tab/pane lifecycle.	View Map
src/skills/	Bundled install-time OpenCode skills shipped as static payloads.	View Map
src/skills/codemap/	Repository-mapping skill package and codemap state-management script.	View Map
src/skills/simplify/	Behavior-preserving simplification skill package.	View Map
src/tools/	Tool export surface for AST-grep, smartfetch, and council orchestration with strict schema-based execution paths.	View Map
src/tools/ast-grep/	AST-grep binary management and AST-aware search/replace tool flow.	View Map
src/tools/smartfetch/	Fetch/extract/cache pipeline for web content and secondary-model summarization.	View Map
src/utils/	Cross-cutting helpers for logging, session metadata, subagent depth tracking, environment, and runtime operations.	View Map
scripts/	Build/release validation and generated-artifact maintenance scripts.	View Map

Runtime Control Flow

1. Plugin startup

   • OpenCode loads src/index.ts.
   • Config is loaded and normalized through src/config/.
   • Agent definitions are produced by src/agents/.
   • Tool factories from src/tools/ and MCP definitions from src/mcp/ are registered.
   • Hooks from src/hooks/ are attached.
   • Delegation/council orchestration, multiplexer session mirroring, and interview support are initialized.

2. Interactive request handling

   • The orchestrator prompt drives routing decisions.
   • Tool calls resolve through src/tools/ or built-in OpenCode tools.
   • Hooks can transform prompts/messages or repair tool failures before/after execution.

3. Delegated execution

   • OpenCode child sessions are created by delegation/council flows and tracked by plugin utilities.
   • src/multiplexer/ optionally mirrors those sessions into tmux/zellij panes.
   • Results flow back into the parent session through notifications/output polling.

4. Install/release path

   • src/cli/ configures host OpenCode instances.
   • src/skills/ is copied into the user skill directory.
   • scripts/ validates generated schema, package completeness, and host-load behavior.

Key Cross-Module Integration Points

• src/index.ts is the central composition root for nearly every runtime subsystem.
• src/config/ feeds src/agents/, session/delegation utilities, and MCP registration.
• src/cli/skills.ts and src/cli/custom-skills.ts bridge install-time skill packaging with runtime permission policy.
• Session/delegation utilities depend on src/multiplexer/ and cooperate with helpers in src/utils/.
• src/tools/council.ts delegates into src/council/.
• src/hooks/filter-available-skills/ and agent permission logic rely on shared skill names from the CLI/config layer.
• src/interview/ hooks into plugin command/event surfaces exposed by src/index.ts.

Root Assets

• README.md: user-facing product overview, install docs, and agent descriptions.
• AGENTS.md: agent operating conventions for this repository.
• biome.json: formatting/lint policy.
• tsconfig.json: TypeScript compiler settings.
• .slim/codemap.json: codemap change-detection state for this repository.

Recommended Reading Order

1. codemap.md
2. src/codemap.md
3. One of:
   • src/agents/codemap.md
   • src/multiplexer/codemap.md
   • src/tools/codemap.md
   • src/hooks/codemap.md
4. Relevant subsystem sub-map for the task at hand