Omx Setup

OMX Setup

Use this skill when users want to install or refresh oh-my-codex for the current project plus user-level OMX directories.

Command

omx setup [--force] [--merge-agents] [--dry-run] [--verbose] [--scope <user|project>] [--plugin|--legacy|--install-mode <legacy|plugin>]

If you only want lightweight AGENTS.md scaffolding for an existing repo or subtree, use omx agents-init [path] instead of full setup.

Supported setup flags (current implementation):

• --force: overwrite/reinstall managed artifacts where applicable
• --merge-agents: when AGENTS.md already exists, preserve user-authored content and insert/refresh OMX-managed generated sections between explicit <!-- OMX:AGENTS:START --> / <!-- OMX:AGENTS:END --> markers
• --dry-run: print actions without mutating files
• --verbose: print per-file/per-step details
• --scope: choose install scope (user, project)
• --plugin: use Codex plugin delivery for bundled skills while archiving/removing legacy OMX-managed prompts/skills, refreshing setup-owned native agent TOMLs for agent_type routing, and keeping setup-owned runtime hooks
• --legacy: use legacy setup delivery, overriding any persisted plugin install mode
• --install-mode: explicitly choose setup delivery mode (legacy or plugin); canonical form for scripted setup

What this setup actually does

omx setup performs these steps:

1. Resolve setup scope:

• --scope explicit value
• else persisted ./.omx/setup-scope.json (with automatic migration of legacy values)
• if a TTY user has persisted setup preferences, omx setup first summarizes the recorded choices and asks whether to keep, review/change, or reset them
• else interactive prompt on TTY (default user)
• else default user (safe for CI/tests)

2. If scope is user, resolve user skill delivery mode:

• explicit --plugin, --legacy, or --install-mode legacy|plugin, if present
• persisted install mode in ./.omx/setup-scope.json, if present and the TTY review decision is keep
• else discovered installed plugin cache under ${CODEX_HOME:-~/.codex}/plugins/cache/**/.codex-plugin/plugin.json with name: oh-my-codex makes plugin the default
• else interactive prompt on TTY (legacy by default, or plugin when a plugin cache is discovered)
• else default legacy unless a plugin cache is discovered

3. Create directories and persist effective scope/install mode 4. In legacy mode, install prompts/native agents/skills and merge full config.toml. In plugin mode, archive/remove legacy OMX-managed prompts/skills, refresh installable native agent TOMLs for agent_type routing, clean up stale generated non-installable native agents, and keep native Codex hooks installed. 5. Verify Team CLI API interop markers exist in built dist/cli/team.js 6. Generate AGENTS.md defaults only when selected/allowed (or legacy behavior outside plugin mode) 7. Configure notify hook references outside plugin mode and write ./.omx/hud-config.json

Important behavior notes

• omx setup prompts for scope when no scope is provided and stdin/stdout are TTY. If ./.omx/setup-scope.json already exists, setup now summarizes the saved choices first and asks whether to keep them, review/change them, or reset and behave like a fresh setup run.
• Non-interactive setup never blocks for this review prompt: it keeps deterministic CLI/persisted/default behavior for CI and scripted installs.
• In user scope, omx setup also prompts for skill delivery mode when no prior install mode is kept; installed plugin cache discovery makes plugin mode the default prompt/non-interactive choice.
• Local project orchestration file is ./AGENTS.md (project root).
• If AGENTS.md exists and neither --force nor --merge-agents is used, interactive TTY runs ask whether to overwrite. Non-interactive runs preserve the file.
• Use --merge-agents to keep existing project guidance while allowing setup to refresh OMX-managed AGENTS sections and the generated model capability table idempotently.
• Scope targets:
• user: user directories (~/.codex, ~/.codex/skills, ~/.omx/agents)
• project: local directories (./.codex, ./.codex/skills, ./.omx/agents)
• User-scope skill delivery targets:
• legacy: keep installing/updating OMX skills in the resolved user skill root
• plugin: rely on Codex plugin discovery for bundled skills and plugin-scoped lifecycle hooks when Codex reports plugin_hooks; archive/remove legacy OMX-managed prompts/skills, refresh installable setup-owned native agent TOMLs for agent_type routing, and remove only stale generated/non-installable native agents. Setup still enables setup-owned runtime feature flags (plugin_hooks = true and goals = true when supported, or legacy setup-managed hooks/codex_hooks fallback when plugin hooks are not reported).
• Migration hint: in user scope, if historical ~/.agents/skills still exists alongside ${CODEX_HOME:-~/.codex}/skills, current setup prints a cleanup hint. Why the paths differ: ${CODEX_HOME:-~/.codex}/skills/ is the path current Codex CLI natively loads as its skill root; ~/.agents/skills/ was the skill root in an older Codex CLI release before ~/.codex became the standard home directory. OMX writes only to the canonical ${CODEX_HOME:-~/.codex}/skills/ path. When both directories exist simultaneously, Codex discovers skills from both trees and may show duplicate entries in Enable/Disable Skills. Archive or remove ~/.agents/skills/ to resolve this.
• If persisted scope is project, omx launch automatically uses CODEX_HOME=./.codex unless user explicitly overrides CODEX_HOME.
• Plugin mode prompts separately for optional AGENTS.md defaults and optional developer_instructions defaults. If developer_instructions already exists, setup asks before overwriting it; non-interactive runs preserve it.
• With --force or --merge-agents, AGENTS updates may still be skipped if an active OMX session is detected (safety guard).
• Legacy persisted scope values (project-local) are automatically migrated to project with a one-time warning.

Setup-owned configuration surfaces

Use this map when reconciling setup behavior or debugging a confusing install:

If $omx-setup is missing or stale

The source repo ships skills/omx-setup/SKILL.md and the catalog marks it active. If Codex does not show $omx-setup, treat it as an installation/discovery issue rather than a missing source skill:

1. Run omx setup --verbose in the intended scope. 2. Run omx doctor and check the reported setup scope, Codex home, skill root, and hook/config status. 3. If using project scope, confirm ./.codex/skills/omx-setup/SKILL.md exists. 4. If using user scope, confirm ${CODEX_HOME:-~/.codex}/skills/omx-setup/SKILL.md exists in legacy mode, or that the oh-my-codex plugin is installed/discovered in plugin mode. 5. If duplicate/stale skills appear, check for legacy ~/.agents/skills overlap and follow the cleanup hint printed by setup/doctor.

Recommended workflow

1. Run setup:

omx setup --force --verbose

2. Verify installation:

omx doctor

3. Start Codex with OMX in the target project directory.

Expected verification indicators

From omx doctor, expect:

• Prompts installed (scope-dependent: user or project)
• Skills installed (scope-dependent: user or project)
• AGENTS.md found in project root
• .omx/state exists
• CLI-first config present in the scope target config.toml; first-party OMX MCP servers and shared MCP registry sync are omitted by default unless setup was run with --mcp compat

Troubleshooting

• If using local source changes, run build first:

npm run build

• If your global omx points to another install, run local entrypoint:

node bin/omx.js setup --force --verbose
node bin/omx.js doctor

• If AGENTS.md was not overwritten during --force, stop active OMX session and rerun setup.
• If AGENTS.md was not merged during --merge-agents, stop active OMX session and rerun setup.