Code Rooms
---
name: omx-codex-app-bridge
description: Use when the user wants to integrate oh-my-codex (OMX) with Codex App or plain Codex sessions safely, launch real OMX from the shell, keep OMX state isolated from the current repo by default, choose an explicit OMX work root, and avoid unsupported behavior from pretending OMX runtime workflows are active inside the app.
# OMX Codex App Bridge
Use this skill when the user wants real `oh-my-codex` behavior from a Codex App session without relying on global installation or pretending the App is already inside the OMX runtime.
## Core contract
- Treat `autopilot`, `ralph`, `ultrawork`, `ultraqa`, `team`, `swarm`, and similar OMX runtime keywords as **runtime-only**.
- In Codex App or plain Codex sessions without actual OMX runtime state, do **not** act as if those workflows are active just because the words appeared.
- When the user wants an App-safe equivalent, keep working with native Codex surfaces such as planning, clarification, or native subagents.
- When the user explicitly wants real OMX behavior, launch upstream OMX from the shell with the bundled wrapper.
This matches the upstream OMX guidance: App-safe by default, shell-launched runtime when explicitly requested.
## Safety rules
- Keep all runtime state local to the chosen OMX work root.
- Do not default OMX to the current workspace root.
- Ask where OMX should work before bootstrapping or setup. Prefer a separate sibling or external path outside the current repo.
- Treat use of the current workspace root as `in-place` mode. Only allow it when the user explicitly confirms they want OMX to manage that repo directly.
- Do not install OMX globally with `npm -g`.
- Do not copy or sync `~/.codex/auth.json`, `~/.codex/config.toml`, or any other global Codex files into the project.
- Use work-root-local Codex auth under `./.codex/`.
- Build the upstream OMX checkout with `npm install --ignore-scripts` to avoid upstream `postinstall` surprises.
- Do not default to `--madmax`; dangerous upstream launch modes must be explicit.
- Explain that project-local `CODEX_HOME` isolates auth/config/state, but does not sandbox machine access by itself.
- Explain explicitly that `in-place` mode may create or update `AGENTS.md`, `./.codex/`, `./.omx/`, and `./.omx-codex-app-bridge/` in that repo.
## Paths
The wrapper uses these paths inside the chosen OMX work root:
- `./.codex/` for the Codex home used by OMX
- `./.omx/` for upstream OMX runtime state
- `./.omx-codex-app-bridge/` for the local upstream checkout and bridge logs
- `./AGENTS.md` may be created or refreshed by upstream OMX during `setup --scope project`
## Wrapper script
Do not assume `scripts/omx-bridge.sh` exists inside the user's repository. The wrapper lives inside the installed skill directory.
Resolve it like this:
```bash
BRIDGE_SCRIPT="${CODEX_HOME:-$HOME/.codex}/skills/omx-codex-app-bridge/scripts/omx-bridge.sh"
```
Run the wrapper at:
`$BRIDGE_SCRIPT`
Common commands:
OMX_ROOT="../my-project-omx-workspace"
bash "$BRIDGE_SCRIPT" --project-root "$OMX_ROOT" bootstrap
bash "$BRIDGE_SCRIPT" --project-root "$OMX_ROOT" setup
bash "$BRIDGE_SCRIPT" --project-root "$OMX_ROOT" codex-login-status
bash "$BRIDGE_SCRIPT" --project-root "$OMX_ROOT" codex-login-device
OPENAI_API_KEY=... bash "$BRIDGE_SCRIPT" --project-root "$OMX_ROOT" codex-login-api-key
bash "$BRIDGE_SCRIPT" --project-root "$OMX_ROOT" doctor
bash "$BRIDGE_SCRIPT" --project-root "$OMX_ROOT" launch
bash "$BRIDGE_SCRIPT" --project-root "$OMX_ROOT" launch-dangerous
bash "$BRIDGE_SCRIPT" --project-root "$OMX_ROOT" exec --skip-git-repo-check -C . "Reply with exactly OMX-EXEC-OK"
bash "$BRIDGE_SCRIPT" --project-root "$OMX_ROOT" omx team 3:executor "fix the failing tests"
# Explicit in-place opt-in for the current repo only when intentional
bash "$BRIDGE_SCRIPT" --in-place setup
## Recommended workflow
1. If the user only wants an App-safe equivalent of an OMX concept, stay in the App and explain the runtime boundary briefly.
2. If the user wants actual OMX runtime behavior:
- ask where OMX should work
- recommend a separate work root outside the current repo
- if the user wants the current repo root, warn that OMX may create or update `AGENTS.md`, `./.codex/`, `./.omx/`, and `./.omx-codex-app-bridge/` there
- only use `--in-place` after explicit confirmation
- run `bootstrap`
- run `setup`
- verify local auth with `codex-login-status`
- if needed, run `codex-login-device` or `codex-login-api-key`
- run `doctor`
- then run `launch`, `exec`, `question`, or `omx ...`
3. Only use `launch-dangerous` when the user explicitly wants the upstream dangerous launch path that bypasses Codex approvals and sandboxing.
4. Prefer `exec`, `question`, and `launch` wrappers over manually reconstructing the upstream command line.
## Auth behavior
- `launch`, `exec`, and `question` require work-root-local Codex auth in `./.codex/`.
- If local auth is missing, stop and point the user to:
- `bash "$BRIDGE_SCRIPT" --project-root "$OMX_ROOT" codex-login-device`
- `OPENAI_API_KEY=... bash "$BRIDGE_SCRIPT" --project-root "$OMX_ROOT" codex-login-api-key`
- Do not fall back to global auth implicitly.
- `codex-login-api-key` requires a real OpenAI API key. If the user's main `~/.codex` is authenticated by ChatGPT account session tokens, that does not count as an API key; use `codex-login-device` for the isolated project login instead.
- If the user asks whether this bridge is "safe", be precise: it isolates state and defaults to safer launch args, but it is not a system sandbox.
## Environment overrides
Use only when needed:
- `OMX_PROJECT_ROOT`
- `OMX_ALLOW_IN_PLACE`
- `OMX_SOURCE_DIR`
- `OMX_REPO_URL`
- `OMX_REPO_REF`
- `OMX_ENTRYPOINT`
- `CODEX_BIN`
- `NODE_BIN`
- `NPM_BIN`
- `GIT_BIN`
The wrapper defaults to a tested upstream `oh-my-codex` commit pin. Only override `OMX_REPO_REF` when the user explicitly wants a different upstream revision.
## Example prompts
- `Use $omx-codex-app-bridge to bootstrap oh-my-codex in a separate workspace without touching my global Codex setup.`
- `Use $omx-codex-app-bridge and launch real OMX team mode from this repo.`
- `Use $omx-codex-app-bridge para subir o OMX num workspace separado deste projeto e nao mexer no ~/.codex.`
- `Use $omx-codex-app-bridge para rodar o runtime real do OMX pelo shell, mas manter o App em modo seguro.`
