Technical Briefing: oh-my-codex

The Problem

OMX addresses the limitation of Codex CLI operating as a single-session agent by providing a orchestration layer for multi-agent team execution, persistent state management, and workflow skills. The repository contains 410 files with 270 internal modules and 411 import edges, indicating a complex codebase where changes to core modules ripple widely through the system.

What This Does

OMX adds structure for larger work decomposition and staged execution. The codebase is organized around three primary projects: src (253 files, TypeScript-heavy), scripts (23 files for automation), and bin (1 CLI entry point). Key architectural elements include:

  • Team orchestration via src/team/ - state management (src/team/state.ts with 100 functions, called from 14 files), runtime control (src/team/runtime.ts with 34 functions), and tmux session handling (src/team/tmux-session.ts with 98 functions)
  • Notification system via src/notifications/ - config (src/notifications/config.ts with 29 functions), reply listening (src/notifications/reply-listener.ts with 29 functions), and type definitions
  • CLI entry point at src/cli/index.ts - reaching 404 function(s), defining setup flow, HUD launch, and lifecycle hooks
  • Utility paths via src/utils/paths.ts - 12 functions defining directory resolution, called from 16 other files

The import graph reveals 6 modules in circular dependencies, with src/team/state (Ca 23, Ce 10, instability 0.3) and src/cli/index (Ca 2, Ce 25, instability 0.93) being the most connected and unstable. The call graph shows parse called from 88 places, teamDir from 22, and runTmux from 20, indicating these are high-traffic control flow points.

How It Is Wired

Execution begins at src/cli/index.ts:374 (main entry point), which reaches 404 function(s) and is itself called from 1 place. The control flow proceeds through several entry points:

  • setup (src/cli/setup.ts:196) reaches 54 function(s), called from 3 place(s)
  • launchWithHud (src/cli/index.ts:535) reaches 268 function(s), called from 2 place(s)
  • notifyLifecycle (src/notifications/index.ts:191) reaches 87 function(s), called from 2 place(s)
  • preLaunch (src/cli/index.ts:979) reaches 155 function(s), called from 1 place(s)
  • postLaunch (src/cli/index.ts:1294) reaches 126 function(s), called from 1 place(s)

The single outbound network call originates from the system, not within repository code. State persistence operates via MCP servers with .omx/state/ directory management. The tmux hook mechanism at src/cli/tmux-hook.ts (17 functions) integrates with terminal sessions for interactive mode.

Circular dependency risks exist in src/team/state.ts, src/team/orchestrator.ts, and src/cli/index.ts - changing any of these requires careful ripple analysis due to the 23-module dependant on state and 2 modules importing from cli/index.

How To Use It

Setup (from package.json, npm package manager):

npm install -g oh-my-codex
omx setup
omx doctor

Configuration requires environment variables as documented in README:

  • OMX_TEAM_WORKER_CLI - specifies the Codex CLI executable
  • OMX_TEAM_WORKER_LAUNCH_ARGS - model and reasoning configuration (e.g., --model gpt-5.3-codex-spark -c model_reasoning_effort="low")

Running it: The primary entry is omx team for durable multi-worker execution or $team for skill-based workflows. Example from README:

omx team 2:explore "short scoped analysis task"

The --spark flag enables gpt-5.3-codex-spark routing for team workers without forcing the leader model. Scope-aware setup supports omx setup --scope user|project.

Real-World Use

A development team needing to coordinate multiple Codex workers on a feature implementation can use OMX to decompose work into staged phases: team-plan → team-prd → team-exec → team-verify → team-fix. Persistent state in .omx/state/ allows resumption after interruptions. Notifications via Telegram/Discord keep stakeholders informed of progress. The tmux interactive mode provides inspectable, resumable worker sessions, while non-tmux prompt mode offers a lightweight alternative for headless environments.

Code Health & Issues

The static analysis (measuring 56 findings: 15 high, 41 medium, 0 low across 6 kinds) identifies several production-ready concerns:

  • [HIGH] Add a LICENSE - root directory has no license file, making redistribution rights unclear. Default is all rights reserved.
  • [HIGH/cognitive_load] Oversized files - src/team/state.ts (1485 lines), src/team/tmux-session.ts, src/notifications/config.ts hard to hold in one head; changes ripple widely
  • [HIGH/soundness] Import cycle member - src/team/state.ts, src/team/orchestrator.ts, src/cli/index.ts participate in circular imports
  • [MEDIUM] High branching density - scripts/tmux-hook-engine.js (76 branch points over 157 lines), scripts/notify-hook/state-io.js, src/notifications/config.ts
  • [MEDIUM] Duplicated code blocks - 487 repeated 6-line blocks across 79 files, including scripts/demo-claude-workers.sh, scripts/demo-team-e2e.sh
  • [MEDIUM/clarity] Hub module - src/team/state.ts depended on by 23 modules; src/utils/paths.ts by 19; src/notifications/types.ts by 14
  • [HIGH/cognitive_load] Deep nesting - src/mcp/state-server.ts max indentation depth 9

SDLC observations from repository hygiene:

  • No LICENSE file at root
  • CI: GitHub Actions present, 2 workflows declare no job timeout
  • Dockerfile: absent
  • lockfile: present (package-lock.json)
  • Committed secrets: none found
  • 131 test files present

The Bottom Line

OMX provides a capable orchestration layer for transforming Codex CLI from a single-agent tool into a coordinated multi-worker system. The codebase is substantial (410 files, 270 modules) with measurable technical debt in circular dependencies, oversized files, and duplicated logic. Teams needing durable, inspectable multi-worker execution with persistent state will find value here, particularly those already invested in the Codex ecosystem. The absence of a license file and the circular import structure in core modules are the most significant risks for adoption in client engagements.