omx-setup
[OMX] Setup and configure oh-my-codex using current CLI behavior
- License 许可
- Apache-2.0
- 最近更新
- 2026-10-23
- Stars
- ★ 45
- Forks
- 12
01 前言 Front Matter
- name
- omx-setup
- description
- [OMX] Setup and configure oh-my-codex using current CLI behavior
03 SKILL.md 正文
OMX Setup
Use this task card to install or refresh OMX for the current project and/or user scope. Shared safety, lifecycle, hook, team, autonomy, and cancellation rules live in AGENTS.md. Do not infer new CLI behavior from this card; the implementation is authoritative.
Command and alternatives
omx setup [--force] [--merge-agents|--no-merge-agents|--clear-merge-agents-policy] [--dry-run] [--verbose] [--scope <user|project>] [--plugin|--legacy|--install-mode <legacy|plugin>] [--mcp <none|compat>] [--no-mcp|--with-mcp] [--disable-team|--enable-team|--team-mode <enabled|disabled>]
omx agents-init [path] [--dry-run] [--force] [--verbose]
Use agents-init for lightweight AGENTS.md scaffolding only, not a full install.
Supported setup options:
--force: overwrite/reinstall managed artifacts; transient, not persisted or replayed.--merge-agents,--no-merge-agents,--clear-merge-agents-policy: exact bare selectors (no values/equals). Repeated identical selectors are idempotent; conflicting selectors fail before mutations. Set persists an explicit policy per invoking project root; clear removes it and cannot combine with a set. Merge refreshes managed sections; no-merge only suppresses that branch and is not a preserve mode.--dry-run,--verbose: preview actions or show per-file/per-step detail.--scope user|project: choose user (~/.codex,~/.omx/agents) or project (./.codex,./.omx/agents) targets.--plugin/--legacy: select delivery mode;--install-mode legacy|pluginis the canonical scripted spelling. Conflicting mode flags fail.--mcp none|compat(plus--no-mcp/--with-mcp): omit or enable first-party MCP compatibility and shared registry sync.--disable-team,--enable-team,--team-mode enabled|disabled: select Team skill/context generation; conflicting selectors fail.
Resolve setup
- Scope: explicit flag, valid persisted
./.omx/setup-scope.json, TTY choice (defaultuser), or non-interactiveuser. Legacyproject-localmigrates toproject. - Mode: explicit flag, persisted mode when retained, discovered
${CODEX_HOME:-~/.codex}/plugins/cache/**/.codex-plugin/plugin.jsonwithname: oh-my-codex(plugin default), otherwise legacy. TTY reruns summarize saved choices and offer keep/review/reset; non-interactive runs do not block. - Create required directories and atomically persist preferences only after successful setup.
What setup changes
- Legacy mode installs prompts/native agents/skills and merges full config.toml.
- Plugin mode archives/removes legacy OMX-managed prompts/skills, refreshes installable native agent TOMLs and stale generated non-installable agents, and keeps setup-owned runtime hooks.
- Both modes verify Team CLI interop markers in built
dist/cli/team.js, generate AGENTS defaults only when selected/allowed, and write./.omx/hud-config.json; notification hook references are setup-owned outside plugin skill delivery. AGENTS.mdis./AGENTS.md. Without--forceor--merge-agents, interactive runs ask before overwrite and non-interactive runs preserve it. Active-session safeguards may skip writes. Plugin mode may separately prompt for AGENTS anddeveloper_instructionsdefaults; non-interactive runs preserve existing files.- Plugin mode enables setup-owned runtime flags (
plugin_hooks,goals, or legacyhooks/codex_hooksfallback). Project scope usesCODEX_HOME=./.codexunless explicitly overridden.
Verify
omx setup --dry-run --verbose
omx doctor
Expect doctor evidence for prompts and skills in the selected scope, project-root AGENTS.md, .omx/state, and CLI-first config in the scope target config.toml. First-party MCP and shared registry sync are omitted unless setup used --mcp compat (if supported by the installed CLI).
If using local source, run npm run build before node dist/cli/omx.js setup --force --verbose and node dist/cli/omx.js doctor. A preserved customized AGENTS.md is not a failure. Use --force or --merge-agents only when the requested refresh requires replacing managed content, after inspecting its dry-run and preserving customizations; do not edit lifecycle state manually.
Discovery troubleshooting
If $omx-setup is absent/stale: run omx setup --verbose, then omx doctor; verify ./.codex/skills/omx-setup/SKILL.md for project scope or ${CODEX_HOME:-~/.codex}/skills/omx-setup/SKILL.md for legacy user scope. In plugin mode verify the oh-my-codex plugin is installed/discovered. For duplicates, inspect overlapping skill names across the standard .agents/skills and OMX .codex/skills roots; retain one Codex entry per name and preserve unrelated skills.
Exit contract
Report selected scope/mode, dry-run versus mutation, AGENTS policy, affected roots, and doctor indicators. Stop only after setup completes successfully and verification identifies the expected files/config; on failure preserve the exact command output and rerun the smallest corrective command. Do not claim installation from a dry-run alone.
04 同仓库更多 Skills
worker
[OMX] Team worker protocol (ACK, mailbox, task lifecycle) for tmux-based OMX teams
wiki
[OMX] Persistent markdown project wiki stored under repository omx_wiki with keyword search and lifecycle capture
visual-ralph
[OMX] Implement or restyle frontend UI against a generated image, static reference, or live URL through measured capture-and-compare iteration.
ultraqa
[OMX] Adversarial dynamic e2e QA workflow - generate hostile scenarios, test, verify, fix, report, and clean up
ultragoal
[OMX] Create and execute durable repo-native multi-goal plans over Codex goal mode artifacts.
team
[OMX] N coordinated agents on shared task list using tmux-based orchestration