omx-setup

name	omx-setup
description	Setup and configure oh-my-codex using current CLI behavior

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: is the path current Codex CLI natively loads as its skill root; was the skill root in an older Codex CLI release before became the standard home directory. OMX writes only to the canonical path. When both directories exist simultaneously, Codex discovers skills from both trees and may show duplicate entries in Enable/Disable Skills. Archive or remove to resolve this.

Setup-owned configuration surfaces

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

Surface	Owner	Notes
./.omx/setup-scope.json	omx setup	Persists setup scope and user-scope skill delivery mode. TTY reruns summarize it and offer keep/review/reset.
~/.codex/config.toml / ./.codex/config.toml	omx setup generated blocks + user edits	Setup refreshes OMX-managed blocks while preserving supported manual content; setup-owned runtime feature flags include multi_agent, child_agents_md, the Codex hook feature flag (hooks or legacy codex_hooks), and goals.
~/.codex/hooks.json / ./.codex/hooks.json	omx setup shared ownership	Setup owns OMX native hook wrappers and preserves user-owned hooks.
prompts, skills, native agents	omx setup or Codex plugin delivery	Legacy mode installs local files; plugin mode relies on plugin discovery for bundled skills, archives/removes legacy OMX-managed prompt/skill copies, and refreshes setup-owned native agent TOMLs for agent_type routing while cleaning up stale generated/non-installable native agents.
AGENTS.md	omx setup with overwrite safety	Generated defaults or managed refreshes are guarded by force/session checks.
./.omx/hud-config.json	omx setup / $hud	Setup creates the focused default; $hud can adjust it later.
notification hooks	omx setup / $configure-notifications	Setup wires defaults outside plugin skill delivery; notification skill owns deeper provider configuration.

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.