[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-3616":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":18,"stars30d":19,"stars90d":16,"forks30d":16,"starsTrendScore":20,"compositeScore":21,"rankGlobal":10,"rankLanguage":10,"license":10,"archived":22,"fork":22,"defaultBranch":23,"hasWiki":22,"hasPages":22,"topics":24,"createdAt":10,"pushedAt":10,"updatedAt":25,"readmeContent":26,"aiSummary":27,"trendingCount":16,"starSnapshotCount":16,"syncStatus":28,"lastSyncTime":29,"discoverSource":30},3616,"oh-my-codex","Yeachan-Heo\u002Foh-my-codex","Yeachan-Heo","OmX - Oh My codeX: Your codex is not alone. Add hooks, agent teams, HUDs, and so much more.","https:\u002F\u002Foh-my-codex.dev",null,"TypeScript",30760,2423,73,15,0,44,393,2462,259,117,false,"main",[],"2026-06-12 04:00:18","# oh-my-codex (OMX)\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"https:\u002F\u002Fyeachan-heo.github.io\u002Foh-my-codex-website\u002Fomx-character-nobg.png\" alt=\"oh-my-codex character\" width=\"280\">\n  \u003Cbr>\n  \u003Cem>Start Codex stronger, then let OMX add better prompts, workflows, and runtime help when the work grows.\u003C\u002Fem>\n\u003C\u002Fp>\n\n[![npm version](https:\u002F\u002Fimg.shields.io\u002Fnpm\u002Fv\u002Foh-my-codex)](https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002Foh-my-codex)\n[![License: MIT](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-MIT-yellow.svg)](https:\u002F\u002Fopensource.org\u002Flicenses\u002FMIT)\n[![Node.js](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fnode-%3E%3D20-brightgreen)](https:\u002F\u002Fnodejs.org)\n[![Discord](https:\u002F\u002Fimg.shields.io\u002Fdiscord\u002F1452487457085063218?color=5865F2&logo=discord&logoColor=white&label=Discord)](https:\u002F\u002Fdiscord.gg\u002FPUwSMR9XNk)\n\n**Website:** https:\u002F\u002Fyeachan-heo.github.io\u002Foh-my-codex-website\u002F\n\n**Docs:** [Getting Started](.\u002Fdocs\u002Fgetting-started.html) · [Agents](.\u002Fdocs\u002Fagents.html) · [Skills](.\u002Fdocs\u002Fskills.html) · [Integrations](.\u002Fdocs\u002Fintegrations.html) · [Demo](.\u002FDEMO.md) · [OpenClaw guide](.\u002Fdocs\u002Fopenclaw-integration.md)\n\n**Community:** [Discord](https:\u002F\u002Fdiscord.gg\u002FPUwSMR9XNk) — shared OMX\u002Fcommunity server for oh-my-codex and related tooling.\n\nOMX is a workflow layer for [OpenAI Codex CLI](https:\u002F\u002Fgithub.com\u002Fopenai\u002Fcodex).\n\n\u003Ctable>\n\u003Ctr>\n\u003Ctd>\u003Cstrong>🚨 CAUTION — RECOMMENDED DEFAULT ONLY: macOS or Linux with Codex CLI.\u003C\u002Fstrong>\u003Cbr>\u003Cbr>\u003Cstrong>OMX is primarily designed and actively tuned for that path.\u003C\u002Fstrong>\u003Cbr>\u003Cstrong>Native Windows and Codex App are not the default experience, may break or behave inconsistently, and currently receive less support.\u003C\u002Fstrong>\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftable>\n\nIt keeps Codex as the execution engine and makes it easier to:\n- start a stronger Codex session by default\n- run one consistent workflow from clarification to completion\n- invoke the canonical skills with `$deep-interview`, `$ralplan`, `$team`, and `$ralph`\n- keep project guidance, plans, logs, and state in `.omx\u002F`\n\n## Core Maintainers\n\n| Role | Name | GitHub |\n| --- | --- | --- |\n| Creator & Lead | Yeachan Heo | [@Yeachan-Heo](https:\u002F\u002Fgithub.com\u002FYeachan-Heo) |\n| Maintainer | HaD0Yun | [@HaD0Yun](https:\u002F\u002Fgithub.com\u002FHaD0Yun) |\n\n## Ambassadors\n\n| Name | GitHub |\n| --- | --- |\n| Sigrid Jin | [@sigridjineth](https:\u002F\u002Fgithub.com\u002Fsigridjineth) |\n\n## Top Collaborators\n\n| Name | GitHub |\n| --- | --- |\n| HaD0Yun | [@HaD0Yun](https:\u002F\u002Fgithub.com\u002FHaD0Yun) |\n| Junho Yeo | [@junhoyeo](https:\u002F\u002Fgithub.com\u002Fjunhoyeo) |\n| JiHongKim98 | [@JiHongKim98](https:\u002F\u002Fgithub.com\u002FJiHongKim98) |\n| Lor | [@gobylor](https:\u002F\u002Fgithub.com\u002Fgobylor) |\n| HyunjunJeon | [@HyunjunJeon](https:\u002F\u002Fgithub.com\u002FHyunjunJeon) |\n\n## Recommended default flow\n\nIf you want the default OMX experience, start here:\n\n```bash\nnpm install -g @openai\u002Fcodex oh-my-codex\nomx --madmax --high\n```\n\nOn a real `oh-my-codex` version bump, the global npm install now prints an explicit reminder instead of launching `omx setup` automatically. When you're ready, run `omx setup` manually or use `omx update` to check npm and then run the same setup refresh path.\n\n**Codex plugin install note:** this repo also ships an official Codex plugin layout at `plugins\u002Foh-my-codex` with marketplace metadata in `.agents\u002Fplugins\u002Fmarketplace.json`. That plugin bundles the mirrored skill surface plus plugin-scoped companion metadata for MCP servers and apps. Native\u002Fruntime hooks still stay on the setup\u002Fruntime side rather than the installable plugin manifest. It is still **not** a replacement for `npm install -g oh-my-codex` plus `omx setup`: legacy setup mode installs native agents and prompts, while plugin setup mode relies on plugin discovery for bundled skills and archives\u002Fremoves legacy OMX-managed prompts\u002Fnative-agent TOMLs so stale role files cannot shadow plugin behavior.\n\nThen work normally inside Codex:\n\n```text\n$deep-interview \"clarify the authentication change\"\n$ralplan \"approve the auth plan and review tradeoffs\"\n$ralph \"carry the approved plan to completion\"\n$team 3:executor \"execute the approved plan in parallel\"\n$ultragoal \"turn this launch into durable Codex goals\"\n```\n\nThat is the main path.\nBefore you treat the runtime as ready, run the quick-start smoke test below: `omx doctor` verifies the install shape, while `omx exec` proves the active Codex runtime can actually authenticate and complete a model call from the current environment.\nStart OMX strongly, clarify first when needed, approve the plan, then choose `$team` for coordinated parallel execution or `$ralph` for the persistent completion loop.\n\n## What OMX is for\n\nUse OMX if you already like Codex and want a better day-to-day runtime around it:\n- a standard workflow built around `$deep-interview`, `$ralplan`, `$team`, and `$ralph`\n- durable multi-goal handoffs with `$ultragoal` and `.omx\u002Fultragoal` artifacts when a launch needs sequential Codex goals\n- specialist roles and supporting skills when the task needs them\n- project guidance through scoped `AGENTS.md`\n- durable state under `.omx\u002F` for plans, logs, memory, and mode tracking\n\nIf you want plain Codex with no extra workflow layer, you probably do not need OMX.\n\n## Quick start\n\n### Requirements\n\n- Node.js 20+\n- Codex CLI installed: `npm install -g @openai\u002Fcodex`\n- Codex auth configured and visible in the same shell\u002Fprofile that will run OMX\n- `tmux` on macOS\u002FLinux if you want the recommended durable team runtime\n- `psmux` on native Windows only if you intentionally want the less-supported Windows team path\n\n### A good first session\n\nAfter install, check both boundaries:\n\n```bash\nomx doctor\ncodex login status\nomx exec --skip-git-repo-check -C . \"Reply with exactly OMX-EXEC-OK\"\n```\n\n`omx doctor` catches missing OMX files, hooks, and runtime prerequisites. The real smoke test catches auth, profile, and provider\u002Fbase-URL problems that only appear when Codex performs an actual request.\n\nLaunch OMX the recommended way:\n\n```bash\nomx --madmax --high\n```\n\nOn macOS\u002FLinux interactive terminals with `tmux` available, this starts the\nleader in OMX-managed detached tmux by default so the HUD\u002Fruntime panes can be\ncreated and recovered.\n\nIf you want a one-off launch with no OMX tmux\u002FHUD management, use `--direct`:\n\n```bash\nomx --direct --yolo\n```\n\nFor a persistent shell\u002Fprofile preference, set an environment policy:\n\n```bash\nOMX_LAUNCH_POLICY=direct omx --yolo\n```\n\nReturn to the auto\u002Fdefault behavior with:\n\n```bash\nunset OMX_LAUNCH_POLICY\n```\n\nCLI policy flags win over the environment, and the last CLI policy flag before\n`--` wins:\n\n```bash\nOMX_LAUNCH_POLICY=direct omx --tmux --yolo\n```\n\nUse `OMX_LAUNCH_POLICY=direct|tmux|detached-tmux|auto`. This iteration only\nadds CLI and environment controls; it intentionally does not add a config-file\nsetting. If you run `--direct` from inside an existing tmux pane, OMX will not\ncreate HUD splits, enable mouse mode, or wrap extended-key handling, but the\nprocess still runs inside that already-open terminal pane.\n\nThen try the canonical workflow:\n\n```text\n$deep-interview \"clarify the authentication change\"\n$ralplan \"approve the safest implementation path\"\n$ralph \"carry the approved plan to completion\"\n$team 3:executor \"execute the approved plan in parallel\"\n```\n\nUse `$team` when the approved plan needs coordinated parallel work, or `$ralph` when one persistent owner should keep pushing to completion.\n\n## A simple mental model\n\nOMX does **not** replace Codex.\n\nIt adds a better working layer around it:\n- **Codex** does the actual agent work\n- **OMX role keywords** make useful roles reusable\n- **OMX skills** make common workflows reusable\n- **`.omx\u002F`** stores plans, logs, memory, and runtime state\n\nMost users should think of OMX as **better task routing + better workflow + better runtime**, not as a command surface to operate manually all day.\n\n## Start here if you are new\n\n1. Install or update OMX with `npm install -g @openai\u002Fcodex oh-my-codex`\n2. After install or real OMX version bumps, run `omx setup` yourself when you're ready, or use `omx update` when you also want npm to check for and install the latest build before refreshing setup\n3. Run `omx doctor`\n4. Run a real execution smoke test: `codex login status` and `omx exec --skip-git-repo-check -C . \"Reply with exactly OMX-EXEC-OK\"`\n5. Launch with `omx --madmax --high`\n6. Use `$deep-interview \"...\"` when the request or boundaries are still unclear\n7. Use `$ralplan \"...\"` to approve the plan and review tradeoffs\n8. Choose `$team` for coordinated parallel execution or `$ralph` for persistent completion loops\n\n## Recommended workflow\n\n1. `$deep-interview` — clarify scope when the request or boundaries are still vague.\n2. `$ralplan` — turn that clarified scope into an approved architecture and implementation plan.\n3. `$team` or `$ralph` — use `$team` for coordinated parallel execution, or `$ralph` when you want a persistent completion loop with one owner.\n\n## Common in-session surfaces\n\n| Surface | Use it for |\n| --- | --- |\n| `$deep-interview \"...\"` | clarifying intent, boundaries, and non-goals |\n| `$ralplan \"...\"` | approving the implementation plan and tradeoffs |\n| `$ralph \"...\"` | persistent completion and verification loops |\n| `$team \"...\"` | coordinated parallel execution when the work is big enough |\n| `\u002Fskills` | browsing installed skills and supporting helpers |\n\n## Advanced \u002F operator surfaces\n\nThese are useful, but they are not the main onboarding path.\n\n### Team runtime\n\nUse the team runtime when you specifically need durable tmux\u002Fworktree coordination, not as the default way to begin using OMX. In Codex App or plain outside-tmux sessions, treat `omx team` as a tmux-runtime shell surface rather than a directly available in-app workflow; launch OMX CLI from shell first if you actually want team execution.\n\n```bash\nomx team 3:executor \"fix the failing tests with verification\"\nomx team status \u003Cteam-name>\nomx team resume \u003Cteam-name>\nomx team shutdown \u003Cteam-name>\n```\n\n### Setup, doctor, and HUD\n\nThese are operator\u002Fsupport surfaces:\n- Codex plugin marketplace install\u002Fdiscovery can cache the plugin under `${CODEX_HOME:-~\u002F.codex}\u002Fplugins\u002Fcache\u002F$MARKETPLACE_NAME\u002Foh-my-codex\u002F$VERSION\u002F` (local installs may use `local` as the version identifier); that packaged plugin now includes plugin-scoped companion metadata for MCP servers and apps, while native\u002Fruntime hooks remain setup-owned, so it is still not the full OMX runtime setup\n- `omx setup` installs prompts, skills, AGENTS scaffolding, `.codex\u002Fconfig.toml`, and OMX-managed native Codex hooks in `.codex\u002Fhooks.json`\n  - setup refresh preserves non-OMX hook entries in `.codex\u002Fhooks.json` and only rewrites OMX-managed wrappers\n  - `omx setup --merge-agents` preserves existing `AGENTS.md` guidance while inserting or refreshing generated OMX sections between `\u003C!-- OMX:AGENTS:START -->` \u002F `\u003C!-- OMX:AGENTS:END -->`; without `--merge-agents` or `--force`, non-interactive setup keeps skipping existing `AGENTS.md` files\n  - `omx uninstall` removes OMX-managed wrappers from `.codex\u002Fhooks.json` but keeps the file when user hooks remain\n- `omx update` checks npm immediately, installs the newest global OMX build, then reruns the same interactive setup refresh path\n- fresh OMX-managed `gpt-5.5` config seeding now recommends `model_context_window = 250000` and `model_auto_compact_token_limit = 200000`, but only when those keys are missing\n- `.omx-config.json` model\u002Fenv routing is documented in [the model\u002Fenv routing reference](.\u002Fdocs\u002Freference\u002Fomx-config-schema-routing.md); only edit keys supported by your installed OMX version\n- `omx doctor` verifies the install when something seems wrong; it does not prove that the active Codex profile can make an authenticated model call\n- `omx hud --watch` is a monitoring\u002Fstatus surface, not the primary user workflow\n\nFor non-team sessions, native Codex hooks are now the canonical lifecycle surface:\n- `.codex\u002Fhooks.json` = native Codex hook registrations\n- `.omx\u002Fhooks\u002F*.mjs` = OMX plugin hooks\n- `omx tmux-hook` \u002F notify-hook \u002F derived watcher = tmux + runtime fallback paths\n\nSee [Codex native hook mapping](.\u002Fdocs\u002Fcodex-native-hooks.md) for the current native \u002F fallback matrix.\n\n\n### Troubleshooting false-green readiness\n\nA green `omx doctor` means the install and local runtime wiring look sane. If real execution still fails, check the environment Codex actually uses:\n\n- Run `codex login status` and `omx exec --skip-git-repo-check -C . \"Reply with exactly OMX-EXEC-OK\"` from the same shell\u002Fprofile that will launch OMX.\n- In custom HOME, profile, container, or service shells, confirm the active `~\u002F.codex` (or `CODEX_HOME`) is the one with the expected auth and config. Do not assume your normal user `~\u002F.codex` is visible there.\n- If you depend on a local OpenAI-compatible proxy, confirm the active `~\u002F.codex\u002Fconfig.toml` includes the expected `openai_base_url`; otherwise a proxy-issued key can be sent to the default endpoint and fail with `401 Unauthorized`, `Missing bearer or basic authentication in header`, or `Incorrect API key provided`.\n- If `omx doctor --team` or resume reports a stale team such as `resume_blocker` or a missing tmux session, clean the dead runtime state before retrying:\n\n```bash\nomx team shutdown \u003Cteam-name> --force --confirm-issues\nomx cancel\nomx doctor --team\n```\n\nOnly use the forced team shutdown for a team you have confirmed is dead or intentionally abandoned.\n\nIf `Shift+Enter` still submits instead of inserting a newline inside an OMX-managed tmux session, see [Troubleshooting execution readiness](.\u002Fdocs\u002Ftroubleshooting.md#shiftenter-submits-instead-of-inserting-a-newline-in-tmux-backed-omx-sessions). Current OMX already enables tmux extended-key forwarding around its own Codex launch paths, so a persistent failure is usually a tmux terminal-capability\u002Fdiscoverability problem rather than a net-new OMX feature gap.\n\n### Explore and sparkshell\n\n- `omx explore --prompt \"...\"` is for read-only repository lookup\n- `omx sparkshell \u003Ccommand>` is for shell-native inspection and bounded verification\n- when `.omx\u002Fwiki\u002F` exists, `omx explore` can inject wiki-first context before falling back to broader repository search\n- fallback boundaries are explicit: sparkshell-backend fallback is reported on stderr, and spark-model fallback emits stderr metadata plus an `## OMX Explore fallback` notice in stdout so users can see when cost\u002Fbehavior may differ from the low-cost path\n\nExamples:\n\n```bash\nomx explore --prompt \"find where team state is written\"\nomx sparkshell git status\nomx sparkshell --tmux-pane %12 --tail-lines 400\n```\n\n### Wiki\n\n- `omx wiki` is the CLI parity surface for the OMX wiki MCP server\n- wiki data lives locally under `.omx\u002Fwiki\u002F`\n- the wiki is markdown-first and search-first, not vector-first\n\nExamples:\n\n```bash\nomx wiki list --json\nomx wiki query --input '{\"query\":\"session-start lifecycle\"}' --json\nomx wiki lint --json\nomx wiki refresh --json\n```\n\n### Platform notes for team mode\n\n`omx team` works best on macOS\u002FLinux with `tmux`.\nNative Windows remains a secondary path, and WSL2 is generally the better choice if you want a Windows-hosted setup.\nOn native Windows, OMX accepts `psmux` as the tmux-compatible binary for the existing tmux-backed paths it already uses.\n\n| Platform | Install |\n| --- | --- |\n| macOS | `brew install tmux` |\n| Ubuntu\u002FDebian | `sudo apt install tmux` |\n| Fedora | `sudo dnf install tmux` |\n| Arch | `sudo pacman -S tmux` |\n| Windows | `winget install psmux` |\n| Windows (WSL2) | `sudo apt install tmux` |\n\n## Known issues\n\n### Intel Mac: high `syspolicyd` \u002F `trustd` CPU during startup\n\nOn some Intel Macs, OMX startup — especially with `--madmax --high` — can spike `syspolicyd` \u002F `trustd` CPU usage while macOS Gatekeeper validates many concurrent process launches.\n\nIf this happens, try:\n- `xattr -dr com.apple.quarantine $(which omx)`\n- adding your terminal app to the Developer Tools allowlist in macOS Security settings\n- using lower concurrency (for example, avoid `--madmax --high`)\n\n## Documentation\n\n- [Getting Started](.\u002Fdocs\u002Fgetting-started.html)\n- [Demo guide](.\u002FDEMO.md)\n- [Wiki feature](.\u002Fdocs\u002Fwiki-feature.md)\n- [Agent catalog](.\u002Fdocs\u002Fagents.html)\n- [Skills reference](.\u002Fdocs\u002Fskills.html)\n- [Codex native hook mapping](.\u002Fdocs\u002Fcodex-native-hooks.md)\n- [GitHub \u002F PR \u002F package identity pipeline](.\u002Fdocs\u002Fpipeline\u002Fgithub-pr-package-identity.md)\n- [Integrations](.\u002Fdocs\u002Fintegrations.html)\n- [Troubleshooting execution readiness](.\u002Fdocs\u002Ftroubleshooting.md)\n- [OpenClaw \u002F notification gateway guide](.\u002Fdocs\u002Fopenclaw-integration.md)\n- [Contributing](.\u002FCONTRIBUTING.md)\n- [Changelog](.\u002FCHANGELOG.md)\n\n## Languages\n\n- [English](.\u002FREADME.md)\n- [한국어](.\u002Fdocs\u002Freadme\u002FREADME.ko.md)\n- [日本語](.\u002Fdocs\u002Freadme\u002FREADME.ja.md)\n- [简体中文](.\u002Fdocs\u002Freadme\u002FREADME.zh.md)\n- [繁體中文](.\u002Fdocs\u002Freadme\u002FREADME.zh-TW.md)\n- [Tiếng Việt](.\u002Fdocs\u002Freadme\u002FREADME.vi.md)\n- [Español](.\u002Fdocs\u002Freadme\u002FREADME.es.md)\n- [Português](.\u002Fdocs\u002Freadme\u002FREADME.pt.md)\n- [Русский](.\u002Fdocs\u002Freadme\u002FREADME.ru.md)\n- [Türkçe](.\u002Fdocs\u002Freadme\u002FREADME.tr.md)\n- [Deutsch](.\u002Fdocs\u002Freadme\u002FREADME.de.md)\n- [Français](.\u002Fdocs\u002Freadme\u002FREADME.fr.md)\n- [Italiano](.\u002Fdocs\u002Freadme\u002FREADME.it.md)\n- [Ελληνικά](.\u002Fdocs\u002Freadme\u002FREADME.el.md)\n- [Polski](.\u002Fdocs\u002Freadme\u002FREADME.pl.md)\n- [Українська](.\u002Fdocs\u002Freadme\u002FREADME.uk.md)\n\n## Contributors\n\n| Role | Name | GitHub |\n| --- | --- | --- |\n| Creator & Lead | Yeachan Heo | [@Yeachan-Heo](https:\u002F\u002Fgithub.com\u002FYeachan-Heo) |\n| Maintainer | HaD0Yun | [@HaD0Yun](https:\u002F\u002Fgithub.com\u002FHaD0Yun) |\n\n## Star History\n\n[![Star History Chart](https:\u002F\u002Fapi.star-history.com\u002Fsvg?repos=Yeachan-Heo\u002Foh-my-codex&type=date&legend=top-left)](https:\u002F\u002Fwww.star-history.com\u002F#Yeachan-Heo\u002Foh-my-codex&type=date&legend=top-left)\n\n## License\n\nMIT\n","oh-my-codex (OMX) 是一个为 OpenAI Codex CLI 设计的工作流层，旨在增强代码生成和开发体验。它通过提供更强大的会话启动、一致的工作流程管理以及一系列预定义的技能命令（如 `$deep-interview` 和 `$ralplan`），帮助开发者从项目澄清到完成都能保持高效。此外，OMX 还支持将项目指导、计划、日志等信息保存在 `.omx\u002F` 目录下，便于管理和追踪。该项目主要采用 TypeScript 编写，并推荐在 macOS 或 Linux 系统上使用 Codex CLI 以获得最佳体验。对于需要提高编码效率或希望利用 AI 辅助编程的开发者来说，oh-my-codex 是一个非常实用的工具。",2,"2026-06-11 02:55:02","top_language"]