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] [--dry-run] [--verbose] [--scope <user|project-local|project>]

Supported setup flags (current implementation):

• --force: overwrite/reinstall managed artifacts where applicable
• --dry-run: print actions without mutating files
• --verbose: print per-file/per-step details
• --scope: choose install scope (user, project-local, project)

What this setup actually does

omx setup performs these steps:

1. Resolve setup scope:
   • --scope explicit value
   • else persisted ./.omx/setup-scope.json
   • else interactive prompt on TTY (default user)
   • else default user (safe for CI/tests)
2. Create project OMX directories (./.omx/state, ./.omx/plans, ./.omx/logs) and persist effective scope
3. For user/project-local scope:
   • install prompts
   • remove legacy prompt shims
   • install native agent configs
   • install skills
   • merge OMX config.toml
4. For project scope: skip prompt/skill/config/native-agent installs with console messages
5. Verify required team MCP comm tool exports exist in built dist/mcp/state-server.js
6. Generate project-root ./AGENTS.md from templates/AGENTS.md (or skip when existing and no force)
7. Configure notify hook references and write ./.omx/hud-config.json

Important behavior notes

• omx setup only prompts for scope when no scope is provided/persisted and stdin/stdout are TTY.
• Local project orchestration file is ./AGENTS.md (project root).
• Scope targets:
  • user: user directories (~/.codex, ~/.agents/skills, ~/.omx/agents)
  • project-local: local directories (./.codex, ./.agents/skills, ./.omx/agents)
  • project: project-only OMX setup (./.omx/*, AGENTS.md, HUD)
• If persisted scope is project-local, omx launch automatically uses CODEX_HOME=./.codex unless user explicitly overrides CODEX_HOME.
• With --force, AGENTS overwrite may still be skipped if an active OMX session is detected (safety guard).

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-local)
• Skills installed (scope-dependent: user or project-local)
• AGENTS.md found in project root
• .omx/state exists
• OMX MCP servers configured in scope target config.toml (~/.codex/config.toml or ./.codex/config.toml)

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.