Oh-my-codex omx-setup

Setup and configure oh-my-codex using current CLI behavior

install

source · Clone the upstream repo

git clone https://github.com/Yeachan-Heo/oh-my-codex

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/Yeachan-Heo/oh-my-codex "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/omx-setup" ~/.claude/skills/yeachan-heo-oh-my-codex-omx-setup && rm -rf "$T"

manifest: skills/omx-setup/SKILL.md

source content

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>]

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
```
--dry-run
```
: print actions without mutating files
```
--verbose
```
: print per-file/per-step details
```
--scope
```
: choose install scope (
```
user
```
,
```
project
```
)

What this setup actually does

omx setup

performs these steps:

Resolve setup scope:
- ```
--scope
```
  explicit value
- else persisted
```
./.omx/setup-scope.json
```
  (with automatic migration of legacy values)
- else interactive prompt on TTY (default
```
user
```
  )
- else default
```
user
```
  (safe for CI/tests)
Create directories and persist effective scope
Install prompts, native agent configs, skills, and merge config.toml (scope determines target directories)
Verify Team CLI API interop markers exist in built
```
dist/cli/team.js
```
Generate project-root
```
./AGENTS.md
```
from
```
templates/AGENTS.md
```
(or skip when existing and no force)
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).
If
```
AGENTS.md
```
exists and
```
--force
```
is not used, interactive TTY runs ask whether to overwrite. Non-interactive runs preserve the file.

Scope targets:

user

: user directories (

~/.codex

~/.codex/skills

~/.omx/agents

)

project

: local directories (

./.codex

./.codex/skills

./.omx/agents

)

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
```
.
With
```
--force
```
, AGENTS overwrite 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.

Recommended workflow

Run setup:

omx setup --force --verbose

Verify installation:

omx doctor

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

OMX MCP servers configured in scope target

config.toml

(

~/.codex/config.toml

./.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.