oh-my-opencode Admin & Architecture Guide

This guide is for administrators, platform engineers, and developers who need to deploy, configure, secure, extend, or understand the internals of oh-my-opencode (package oh-my-opencode, also oh-my-openagent, invoked as omo). It is the deep companion to the User Guide — every configuration option, the system architecture, the security model, operational procedures, and a developer-level map of the codebase.

oh-my-opencode is a Bun/TypeScript monorepo (v4.7.5) authored by YeonGyu-Kim. It ships two harness adapters from one engine: an OpenCode plugin (plugin id oh-my-openagent) and a Codex plugin (omo-codex, branded LazyCodex).

1. Executive Summary

Operational reality: because oh-my-opencode runs in-process on each user's machine, the administrator's job is (1) establishing a known-good configuration, (2) controlling which features/models are enabled, (3) managing model access and fallback, and (4) supporting users via omo doctor. There is no central database, message broker, or backend to run.

2. Architecture

2.1 High-level

 Developer machine
 ┌──────────────────────────────────────────────────────────────┐
 │  OpenCode (host)                                               │
 │   └── oh-my-opencode plugin  (id: "oh-my-openagent")          │
 │        server() bootstrap                                      │
 │          ├── loadPluginConfig()      ← oh-my-opencode.jsonc    │
 │          ├── createManagers()                                  │
 │          │     ├── BackgroundManager   (parallel sub-agents)   │
 │          │     ├── TmuxSessionManager  (panes for team/bg)     │
 │          │     ├── SkillMcpManager     (skill-backed MCP)      │
 │          │     └── ConfigHandler       (agents/models/tools)   │
 │          ├── createTools()    → tool registry (filtered)       │
 │          ├── createHooks()    → core + continuation + skill    │
 │          └── createPluginInterface()                           │
 │                                                                │
 │   Bundled MCP servers (spawned as needed):                     │
 │     ast-grep (omo-ast-grep) · git-bash (omo-git-bash) · lsp    │
 │     context7 · grep_app · websearch (exa/tavily)               │
 └──────────────────────────────────────────────────────────────┘
        │ models (HTTP)                         │ optional
        ▼                                       ▼
  Providers: Anthropic / OpenAI / Gemini   OpenClaw gateway
  Copilot / MiniMax / Kimi / Z.ai / …      (Discord · Telegram)

The plugin's server() function (in src/index.ts → src/testing/create-plugin-module.ts) is the single entry point OpenCode calls at startup. It:

1. Initializes config context and migrates any legacy workspace/config files.
2. Loads and validates oh-my-opencode config.
3. Creates the long-lived managers (background, tmux, skill-MCP, config handler).
4. Builds the tool registry (honoring disabled_tools, max_tools, etc.).
5. Wires the hook set (core, continuation, and skill hooks).
6. Optionally starts OpenClaw and a tmux availability check.
7. Returns the plugin interface (hooks + tools) to OpenCode.

2.2 Monorepo layout

The repository is a Bun workspace. Top-level areas:

2.3 The two harness adapters

oh-my-opencode is engineered so the same capabilities work across two different host agents:

• OpenCode plugin — the primary target. Loaded in-process via the @opencode-ai/plugin API. Full feature set.
• omo-codex / LazyCodex — a Codex plugin built from packages/omo-codex. It ships as discrete Codex components (comment-checker, git-bash, lsp, rules, telemetry, start-work-continuation, ultrawork, ulw-loop), each a small Codex plugin wired through Codex's SessionStart/UserPromptSubmit/PostToolUse/Stop/PostCompact hooks. Installed via lazycodex-ai install into ~/.codex/plugins/cache/sisyphuslabs/omo/<version> under the sisyphuslabs marketplace.

Shared logic lives in packages/*-core so both adapters stay behavior-equivalent (cross-package equivalence is enforced by tests, e.g. telemetry constants).

2.4 Parallelism model

Heavy lifting is parallelized through the BackgroundManager (src/features/background-agent/):

• Spawns child sessions for delegated/background tasks with concurrency control (ConcurrencyManager), per-provider/per-model concurrency caps, and a parent-wake notifier that resumes the parent when children complete.
• Enforces a circuit breaker (max tool calls per sub-agent) and multiple staleness/TTL timeouts to reclaim stuck or crashed tasks.
• Detects and prevents session parent cycles and runaway subagent spawning.

When tmux is enabled, the TmuxSessionManager mirrors each child/team session into a pane for visualization and reaps zombie panes.

3. Requirements

4. Configuration Mastery

4.1 Config file location and precedence

oh-my-opencode reads oh-my-opencode.jsonc (preferred) or oh-my-opencode.json from:

• The global OpenCode config directory (e.g. ~/.config/opencode/oh-my-opencode.jsonc), and
• Per-project locations under the project's .opencode/ directory.

Project config is merged over global config. A legacy oh-my-openagent.jsonc/.json file is automatically migrated to the oh-my-opencode name (a .bak is left behind). The config directory is resolved by src/shared/opencode-config-dir.ts, honoring OPENCODE_CONFIG_DIR / XDG_CONFIG_HOME and OpenCode-vs-desktop build differences.

Important

The config is validated strictly by OhMyOpenCodeConfigSchema (zod). Unknown-shaped values and out-of-range numbers are rejected, and omo doctor surfaces the exact field. Add "$schema" pointing at the published schema (oh-my-opencode.schema.json, exported by the package as ./schema.json) for editor autocompletion.

{
  "$schema": "./node_modules/oh-my-opencode/dist/oh-my-opencode.schema.json",
  "default_run_agent": "sisyphus",
  "hashline_edit": true,
  "model_fallback": true
}

4.2 Top-level configuration reference

Every top-level key of OhMyOpenCodeConfigSchema:

4.3 Agent overrides (agents)

agents maps an agent name (built-in or custom) to an override object. Built-in overridable names include sisyphus, sisyphus-junior, hephaestus, prometheus, atlas, metis, momus, oracle, librarian, explore, multimodal-looker, plus OpenCode's build/plan and OpenCode-Builder. Custom keys (e.g. "technical-writer") are also accepted.

Override fields (AgentOverrideConfigSchema):

{
  "agents": {
    "sisyphus":     { "category": "ultrabrain", "temperature": 0.1 },
    "momus":        { "category": "quick" },
    "technical-writer": {
      "model": "anthropic/claude-sonnet-4-6",
      "temperature": 0.3,
      "prompt_append": "file://./prompts/tech-writer.md"
    }
  }
}

4.4 Categories (categories)

Categories decouple "what kind of work" from "which model". Built-in category names: visual-engineering, ultrabrain, deep, artistry, quick, unspecified-low, unspecified-high, writing. Each maps to a CategoryConfig:

{
  "categories": {
    "ultrabrain": { "model": "anthropic/claude-opus-4-6", "reasoningEffort": "high" },
    "quick":      { "model": "openai/gpt-5.4", "reasoningEffort": "low" },
    "writing":    { "model": "anthropic/claude-sonnet-4-6", "temperature": 0.4 }
  }
}

4.5 Fallback models

fallback_models (on agents and categories) accepts a string, a string array, or an array of objects. Object form:

{ "model": "openai/gpt-5.4", "variant": "high", "reasoningEffort": "high", "temperature": 0.3 }

disabled_providers removes whole provider prefixes from every chain at load time; if a primary model points at a disabled provider, it is replaced by the first allowed entry in the same chain.

4.6 Claude Code interop (claude_code)

oh-my-opencode can import assets from a local Claude Code setup:

Relevant env toggles: OPENCODE_DISABLE_CLAUDE_CODE, OPENCODE_DISABLE_CLAUDE_CODE_PLUGINS, CLAUDE_CONFIG_DIR, CLAUDE_PLUGINS_HOME.

4.7 Experimental flags (experimental)

4.8 Skills (skills)

Either a list of skill names, or an object with sources, enable, disable, plus per-skill definition entries:

{
  "skills": {
    "sources": [{ "path": "skill/", "recursive": true, "glob": "**/SKILL.md" }],
    "enable": ["frontend-ui-ux"],
    "disable": ["remove-ai-slops"]
  }
}

A skill definition may set description, template, from, model, agent, subtask, argument-hint, allowed-tools, metadata, and disable.

4.9 Ralph Loop (ralph_loop)

4.10 Runtime fallback (runtime_fallback)

Boolean true, or an object:

{ "runtime_fallback": { "enabled": true, "timeout_seconds": 30, "max_fallback_attempts": 3 } }

4.11 Background tasks (background_task)

4.12 Model capabilities (model_capabilities)

Refresh manually with omo refresh-model-capabilities. Related env: ANTHROPIC_1M_CONTEXT, VERTEX_ANTHROPIC_1M_CONTEXT.

4.13 Team mode (team_mode)

Team-mode tool access is gated by the team-tool-gating hook: lead-only actions are rejected for members, and a session can't join two teams.

4.14 Git master (git_master)

Caution

git_env_prefix is validated against a strict pattern to prevent shell injection. A value like A=1; rm -rf / is rejected. Set it to "" to disable.

4.15 tmux (tmux)

isolation controls where agent panes appear: in your current window (inline), a separate window (window), or a fully detached session (session).

4.16 Other blocks

• keyword_detector — { enabled_expansions?, disabled_keywords? } over ultrawork, search, analyze, team, hyperplan, hyperplan-ultrawork.
• browser_automation_engine — provider: playwright (default, via @playwright/mcp), agent-browser (Vercel CLI), dev-browser (persistent state), or playwright-cli (token-efficient).
• websearch — provider: exa (default, no key) or tavily (requires TAVILY_API_KEY).
• sisyphus_agent — { disabled, default_builder_enabled, planner_enabled, replace_plan, tdd (default true) }.
• sisyphus — { tasks: { storage_path?, task_list_id?, claude_code_compat } }.
• default_mode — { ultrawork:false, ralph_loop:false } to auto-activate per session.
• comment_checker — { custom_prompt } (use {{comments}} placeholder).
• notification — { force_enable }.
• babysitting — { timeout_ms: 120000 }.

5. Hooks Reference

Hooks are the mechanism by which oh-my-opencode modifies host behavior at lifecycle points. The full set (HookNameSchema) — disable any via disabled_hooks:

todo-continuation-enforcer, session-recovery, session-notification, comment-checker, tool-output-truncator, question-label-truncator, directory-agents-injector, directory-readme-injector, empty-task-response-detector, think-mode, model-fallback, anthropic-context-window-limit-recovery, preemptive-compaction, rules-injector, background-notification, auto-update-checker, startup-toast, keyword-detector, agent-usage-reminder, non-interactive-env, interactive-bash-session, thinking-block-validator, tool-pair-validator, ralph-loop, category-skill-reminder, compaction-context-injector, compaction-todo-preserver, claude-code-hooks, auto-slash-command, edit-error-recovery, json-error-recovery, delegate-task-retry, prometheus-md-only, sisyphus-junior-notepad, team-tool-gating, no-sisyphus-gpt, no-hephaestus-non-gpt, start-work, atlas, unstable-agent-babysitter, task-resume-info, stop-continuation-guard, tasks-todowrite-disabler, runtime-fallback, write-existing-file-guard, notepad-write-guard, bash-file-read-guard, anthropic-effort, hashline-read-enhancer, read-image-resizer, todo-description-override, webfetch-redirect-guard, fsync-skip-warning, plan-format-validator, legacy-plugin-toast.

Representative groupings:

6. Security

6.1 Trust model

oh-my-opencode runs in-process with the host agent on a developer machine and has the same filesystem/network reach as that agent. It is not a network service and exposes no inbound ports of its own (the optional OpenClaw reply listener and any MCP servers are the exceptions — see below). Treat the configuration file as security-relevant: it determines which models, tools, and remote integrations are active.

6.2 Built-in safety mechanisms

6.3 Telemetry and privacy

• A single anonymous daily-active event is sent to PostHog per machine per UTC day (OpenCode side and, separately, Codex side). It includes platform/OS/CPU/locale metadata and a SHA-256-hashed install id — never prompts, file contents, API keys, or raw hostnames. Person profiles are disabled.
• Opt out with any of: OMO_DISABLE_POSTHOG=1, OMO_SEND_ANONYMOUS_TELEMETRY=0 (and Codex-specific OMO_CODEX_DISABLE_POSTHOG=1, OMO_CODEX_SEND_ANONYMOUS_TELEMETRY=0). Test runs set OMO_DISABLE_POSTHOG.
• Dedup state lives at $XDG_DATA_HOME/omo-codex/posthog-activity.json (or ~/.local/share/...), written atomically.
• Endpoint overrides: POSTHOG_HOST (default https://us.i.posthog.com), POSTHOG_API_KEY.
• The bundled LSP, rules, and comment-checker components run entirely locally and make no network calls.

Important

For locked-down/offline fleets, set OMO_DISABLE_POSTHOG=1 and auto_update: false (and consider disabled_mcps for context7/websearch, which reach the network). The webfetch-redirect-guard hook also constrains outbound web fetches.

6.4 Provider credentials

Model and integration credentials are supplied as environment variables and never stored by oh-my-opencode beyond what OpenCode/Codex manage. Recognized provider/integration env vars include ANTHROPIC_API_KEY, OPENAI_API_KEY, GITHUB_TOKEN, CONTEXT7_API_KEY, EXA_API_KEY, TAVILY_API_KEY, and the OAuth flows handled by omo login/logout/status. The MCP env-cleaner prevents these from leaking into unrelated MCP subprocesses unless explicitly allowlisted via mcp_env_allowlist.

7. Operations

7.1 Install, validate, repair

npx oh-my-opencode install                 # interactive
npx oh-my-opencode install --no-tui \
    --claude max20 --openai yes             # scripted
omo doctor                                  # full health check
omo doctor --status                         # compact dashboard
omo doctor --json                           # machine-readable
omo doctor --verbose                        # detailed diagnostics
omo cleanup [--project <path>] [--json]     # remove Codex/omx artifacts

omo doctor checks (via src/cli/doctor/checks/) host detection, config validity, model resolution, MCP reachability, and agent registration. It is the first tool to reach for in any incident.

7.2 Updates

If auto_update is enabled, the auto-update-checker hook notifies users when a newer version is available. For controlled fleets, disable it (auto_update: false) and roll updates through your package manager. Verify a published release is not a stale binary (a real past incident, community issue #4635) with omo version / omo get-local-version after upgrading.

7.3 OpenClaw remote control (optional)

openclaw enables outbound notifications and an inbound reply listener over Discord/Telegram. Outbound uses gateways (HTTP or command) and hooks; inbound uses replyListener:

{
  "openclaw": {
    "enabled": true,
    "gateways": { "notify": { "type": "http", "url": "https://...", "method": "POST" } },
    "hooks": { "onIdle": { "gateway": "notify", "instruction": "Ask the user what to do next" } },
    "replyListener": {
      "telegramBotToken": "...", "telegramChatId": "...",
      "authorizedDiscordUserIds": ["123..."],
      "pollIntervalMs": 3000, "rateLimitPerMinute": 10, "maxMessageLength": 500
    }
  }
}

The reply listener is rate-limited (rateLimitPerMinute, default 10) and message-size-capped. Restrict who can drive the agent with authorizedDiscordUserIds. Relevant env: OPENCLAW_REPLY_CHANNEL, OPENCLAW_REPLY_TARGET, OPENCLAW_REPLY_THREAD, OMO_OPENCLAW_DEBUG, OMO_OPENCLAW_COMMAND_TIMEOUT_MS.

Warning

OpenClaw's reply listener accepts inbound messages that steer an autonomous coding agent. Treat its credentials and the authorized-user list as production secrets, and prefer it only on machines you control.

7.4 Logs and debugging

7.5 Disabling features safely

To reduce surface area or work around a bad interaction, disable narrowly rather than uninstalling:

{
  "disabled_hooks":   ["auto-update-checker", "startup-toast"],
  "disabled_mcps":    ["context7", "websearch"],
  "disabled_agents":  ["multimodal-looker"],
  "disabled_skills":  ["remove-ai-slops"],
  "disabled_commands":["ralph-loop"],
  "disabled_tools":   ["todowrite", "todoread"]
}

8. Code Quality & Conventions

• Language/runtime: TypeScript built and bundled with Bun; tsgo (TypeScript native preview) for type-checking; zod v4 for all runtime validation.
• Tests: Extensive bun test suites colocated with source (the repo is heavily test-covered — most extracted "error messages" are in fact test assertions). Codex components use vitest/node --test. CI runs across Ubuntu, macOS, and Windows.
• Style: Strict TS (exactOptionalPropertyTypes, noUncheckedIndexedAccess, verbatimModuleSyntax, etc.); Biome for lint/format on the web and Codex components.
• BDD naming: Tests follow #given / #when / #then conventions.
• Workspace cores: Logic shared across harnesses lives in pure-TS packages/*-core libraries with no host dependency, keeping the OpenCode and Codex adapters equivalent.
• Bundling shims: src/shared/bun-*-shim.ts provide Node fallbacks for Bun-only APIs so bundled output runs under plain Node (e.g. OpenCode Desktop).

8.1 Build, type-check, publish

bun run build                 # bundle src/index.ts + cli + schema (Bun target)
bun run typecheck             # tsgo across root + packages
bun test                      # full test suite
bun run build:binaries        # per-platform binaries (script/build-binaries.ts)
bun run build:schema          # regenerate oh-my-opencode.schema.json
bun run build:model-capabilities  # refresh bundled model capability table

Publishing is driven by script/publish.ts (env: BUMP, VERSION, REPUBLISH, SKIP_PLATFORM_PACKAGES) and marketplace sync by script/sync-lazycodex-marketplace.ts.

9. Internals: Subsystem Deep-Dive

9.1 Known issues & community-reported behavior

From the issue tracker (useful when supporting users):

• Model routing can be dropped on restart, falling back to defaults (#3570).
• Certain MiniMax variants stop mid-plan; mitigated by unstable-agent babysitting (#3198).
• run --json may exit before a background parent-wake completes (#4721).
• Stale model capabilities require refresh-model-capabilities for newly-released models (#4692, #3535, #3649).
• Builtin shared-skills may not appear as slash commands on some OpenCode Desktop builds (#4714).
• A published platform binary once shipped a stale version — verify after upgrade (#4635).

9.2 Suggested improvements

• Centralize hardcoded model references into configurable constants (open community proposal #839) — would simplify fleet-wide model policy.
• Free/alternative paths for MCP features where some currently assume paid services (#642).
• Provider-prefix robustness for newer providers (e.g. minimax-cn) so capability detection and routing don't lag model launches (#3535, #4707).
• Harden restart-time config reload so model routing can't silently revert to defaults (#3570).

10. Quick Reference

CLI

omo install [--no-tui] [--claude no|yes|max20] [--openai ...] [--gemini ...]
            [--copilot ...] [--opencode-zen ...] [--zai-coding-plan ...]
            [--kimi-for-coding ...] [--opencode-go ...] [--vercel-ai-gateway ...]
            [--codex-autonomous] [--skip-auth]
omo run <message> [-a agent] [-m provider/model] [-d dir] [-p port]
            [--attach url] [--session-id id] [--on-complete cmd]
            [--json] [--verbose] [--no-timestamp]
omo doctor [--status] [--verbose] [--json]
omo cleanup [--codex-home path] [--project path] [--json]
omo get-local-version [-d dir] [--json]
omo refresh-model-capabilities [-d dir] [--source-url url] [--json]
omo boulder [-d dir] [-w work-id] [--json]
omo ulw-loop [args...]
omo version
omo login|logout|status <server-name> [--server-url url] [--client-id id] [--scopes ...]
npx lazycodex-ai install [--codex-autonomous]

Built-in agents

sisyphus, sisyphus-junior, hephaestus, prometheus, atlas, oracle, librarian, explore, multimodal-looker, metis, momus (plus OpenCode build/plan).

Categories

ultrabrain, deep, visual-engineering, artistry, writing, quick, unspecified-low, unspecified-high.

Keywords

ultrawork/ulw, search, analyze, team, hyperplan, hyperplan-ultrawork.

Commands

/ralph-loop, /ulw-loop, /cancel-ralph, /refactor, /start-work, /stop-continuation, /remove-ai-slops, /hyperplan.

Bundled MCP servers

ast-grep (omo-ast-grep), git-bash (omo-git-bash), lsp (lsp-tools-mcp), context7, grep_app, websearch (exa/tavily).

Key environment variables

Config file

oh-my-opencode.jsonc / oh-my-opencode.json — OpenCode config dir (global) and project .opencode/. Validated by OhMyOpenCodeConfigSchema. Schema published as oh-my-opencode.schema.json (package export ./schema.json).