oh-my-customcodex

Your AI Agent Stack. Compiled, Not Configured.

한국어 문서 (Korean)

50 agents. 122 skills. 23 rules. One command.

npm install -g oh-my-customcodex && cd your-project && omcustomcodex init

Philosophy

oh-my-customcodex is built on two ideas:

1. Agent systems are compiled, not configured.

| Compile Concept | oh-my-customcodex | |----------------|-----------------| | Source repository authoring | .codex/skills/ — skill definitions maintained by this package itself | | Installed runtime skills | .agents/skills/ — reusable knowledge and workflows deployed into managed projects | | Build artifacts | .codex/agents/ — executable specialists assembled from skills | | Compiler | mgr-sauron (R017) — structural verification and integrity | | Harness policy | .codex/rules/*.md — behavioral constraints explicitly referenced by AGENTS.md | | Linker | Routing skills — connect agents to tasks | | Standard library | guides/ — shared reference documentation |

Skills are source. Agents are compiled output. Sauron verifies the build. This separation means skills evolve independently of agents, and agents can be recompiled from updated skills at any time.

2. If it can't be done, make it work.

When no specialist exists for a task, oh-my-customcodex does not fail. It creates one.

User: "Review this Terraform module"
  → Routing: no terraform expert found
  → mgr-creator discovers: infra-aws-expert skills + docker-best-practices guide
  → Creates: infra-terraform-expert.md
  → Executes the review immediately
  → Agent persists for future use

This is not a fallback. It is the design. The system treats missing expertise as a build problem — find the right skills, compile a new agent, execute.

How It Works

Orchestration

The main conversation acts as a singleton orchestrator (R010). It never writes files directly. Every action is delegated through routing skills to specialized agents.

User (natural language)
  → Routing skill (intent detection, confidence scoring)
    → Specialized agent (isolated execution)
      → Result returned to orchestrator
        → Response to user

Four routing skills cover the full domain:

| Routing Skill | Routes To | |--------------|-----------| | secretary-routing | Manager agents (mgr-), system agents (sys-) | | dev-lead-routing | Language, backend, frontend, tooling, DB, infra, arch agents | | de-lead-routing | Data engineering agents (de-*) | | qa-lead-routing | QA team (qa-planner, qa-writer, qa-engineer) |

Model and Reasoning Selection

Agents select a Codex/OMX capability lane plus model_reasoning_effort, not a provider-specific model alias. Concrete model IDs are resolved at runtime from OMX_DEFAULT_FRONTIER_MODEL, OMX_DEFAULT_SPARK_MODEL, or the active Codex/OMX configuration. When a lane is not configured, generated TOML omits model and inherits the current Codex model instead of pinning a stale ID.

| Lane | Runtime source | Typical work | |------|----------------|--------------| | frontier | OMX_DEFAULT_FRONTIER_MODEL or active Codex model | Architecture, implementation, verification | | spark | OMX_DEFAULT_SPARK_MODEL (legacy OMX_SPARK_MODEL) | Search, triage, lightweight validation | | inherit | Current Codex session | Roles that should follow the caller |

Use model_reasoning_effort (none, minimal, low, medium, high, xhigh, ultra, or max, subject to model support) independently of the lane. The reasoning-sandwich pattern increases effort for analysis and verification while keeping mechanical implementation at the lowest sufficient effort.

Parallel Execution

Independent tasks run in parallel (R009). The repository harness soft/default dispatch size is 4 with a hard cap of 5; Codex/OMX native capacity is runtime-defined and may provide fewer available slots:

Agent(lang-golang-expert):frontier/high  ┐
Agent(lang-python-expert):frontier/high  ├─ All spawned in one message
Agent(qa-engineer):frontier/medium       │
Agent(arch-documenter):spark/low         ┘

Agents (50)

| Category | Count | Agents | |----------|-------|--------| | Languages | 6 | lang-golang, lang-python, lang-rust, lang-kotlin, lang-typescript, lang-java21 | | Backend | 6 | be-fastapi, be-springboot, be-go-backend, be-express, be-nestjs, be-django | | Frontend | 5 | fe-vercel, fe-vuejs, fe-svelte, fe-flutter, fe-design | | Data Engineering | 6 | de-airflow, de-dbt, de-spark, de-kafka, de-snowflake, de-pipeline | | Database | 4 | db-supabase, db-postgres, db-redis, db-alembic | | Tooling | 3 | tool-npm, tool-optimizer, tool-bun | | Architecture | 2 | arch-documenter, arch-speckit | | Infrastructure | 2 | infra-docker, infra-aws | | QA | 3 | qa-planner, qa-writer, qa-engineer | | Security | 1 | sec-codeql | | Managers | 6 | mgr-creator, mgr-updater, mgr-supplier, mgr-gitnerd, mgr-sauron, mgr-claude-code-bible | | System | 3 | sys-memory-keeper, sys-naggy, tracker-checkpoint | | Auxiliary | 2 | slack-cli, wiki-curator | | Review/Reasoning | 1 | scholastic |

Each agent declares its tools, model, memory scope, and limitations in YAML frontmatter. Tool budgets are enforced per agent type for accuracy.

Skills (122)

| Category | Count | Includes | |----------|-------|----------| | Best Practices | 24 | Go, Python, TypeScript, Kotlin, Rust, React, FastAPI, Spring Boot, Django, Flutter, Docker, AWS, Postgres, Redis, Kafka, dbt, Spark, Snowflake, Airflow, pipeline-architecture-patterns, alembic, and more | | Routing | 4 | secretary, dev-lead, de-lead, qa-lead | | Workflow | 14 | structured-dev-cycle, deep-plan, research, evaluator-optimizer, dag-orchestration, worker-reviewer-pipeline, reasoning-sandwich, pipeline, fsd, and more | | Development | 10 | dev-review, dev-refactor, analysis, create-agent, intent-detection, web-design-guidelines, omcodex:takeover, skill-extractor, pre-generation-arch-check, idea | | Operations | 10 | update-docs, audit-agents, sauron-watch, monitoring-setup, token-efficiency-audit, fix-refs, release-notes, and more | | Memory | 3 | memory-save, memory-recall, memory-management | | Package | 3 | npm-publish, npm-version, npm-audit | | Optimization | 3 | optimize-analyze, optimize-bundle, optimize-report | | Security | 3 | adversarial-review, cve-triage, jinja2-prompts | | Other | 10 | claude-native, gitlab, visual-ralph, visual-verdict, vercel-deploy, skills-sh-search, result-aggregation, writing-clearly-and-concisely, and more |

Skills use a 3-tier scope system: core (universal), harness (agent/skill maintenance), package (project-specific).

Skill Invocations

Use $skill-name to invoke an installed skill explicitly. Use the native /skills command to browse skills available to the current Codex session. The entries below are skill invocations, not custom slash commands.

Development

| Command | What it does | |---------|-------------| | $dev-review | Code review against best practices | | $dev-refactor | Refactor for structure and patterns | | $structured-dev-cycle | 6-stage development: plan → verify → implement → verify → compound → done | | $deep-plan | Research-validated planning | | $research | 10-team parallel analysis with cross-verification | | $sdd-dev | Spec-Driven Development workflow | | $ambiguity-gate | Pre-routing ambiguity analysis | | $pre-generation-arch-check | Check architecture risks before implementation | | $adversarial-review | Attacker-mindset security code review | | $omcustomcodex:goal | Keep a concrete objective in view through planning, execution, and verification | | $omcustomcodex:fsd | Full Self Driving release loop: repeat $pipeline auto-dev + $homework until eligible issues are exhausted | | $pipeline | Execute YAML-defined pipelines | | $pipeline resume | Resume a halted pipeline from last failure point |

Agent Management

| Command | What it does | |---------|-------------| | $omcustomcodex:analysis | Analyze project, auto-configure agents and skills | | $omcustomcodex:create-agent | Create a new agent | | $omcustomcodex:takeover | Extract canonical spec from existing agent or skill | | $idea | Turn a natural-language idea into structured issue specs | | $omcustomcodex:audit-agents | Audit agent dependencies | | $omcustomcodex:update-docs | Sync project structure and documentation | | $omcustomcodex:sauron-watch | Full structural verification (5+3 rounds) | | $omcustomcodex:feedback | Submit feedback as GitHub issue |

Web UI

| Command | What it does | |---------|-------------| | $omcustomcodex:web | Control built-in Web UI (start, stop, status, open) |

Package & Release

| Command | What it does | |---------|-------------| | $omcustomcodex:npm-publish | Publish to npm | | $omcustomcodex:npm-version | Semantic versioning | | $omcustomcodex:npm-audit | Dependency security audit | | $omcustomcodex-release-notes | Generate release notes from git history |

Memory & System

| Command | What it does | |---------|-------------| | $memory-save | Save session context | | $memory-recall | Search and recall memories | | $omcustomcodex:monitoring-setup | OTel monitoring toggle | | $token-efficiency-audit | Audit and tune token-efficiency settings | | $omcustomcodex:loop | Auto-continue background agent workflows (3-continue safety limit) | | $omcustomcodex:lists | Show all commands | | $omcustomcodex:status | System health check |

Harness Behavioral Policies (23)

These Markdown policies are loaded through the AGENTS.md instruction hierarchy; they are not Codex-native Starlark command rules.

| Priority | Count | Purpose | |----------|-------|---------| | MUST | 14 | Safety, permissions, agent design, identification, orchestration, verification, completion, enforcement | | SHOULD | 8 | Interaction, error handling, memory, HUD, ecomode, ontology routing, verification ladder, wiki sync | | MAY | 1 | Optimization |

Key rules: R010 (orchestrator never writes files), R009 (parallel execution mandatory), R017 (sauron verification before push), R020 (completion verification before declaring done), R021 (advisory-first enforcement model), R023 (verification ladder).

Guides (52)

Reference documentation covering best practices, architecture decisions, release compatibility, and integration patterns. Located in guides/ at project root, covering topics from agent design to CI/CD to observability.

Safety

During omcustomcodex init, the validated advisory subset is compiled into the native project registry at .codex/hooks.json:

| Hook | Trigger | Action | |------|---------|--------| | secret-filter | PostToolUse on Bash | Detects AWS keys, API tokens, private keys, bearer tokens | | schema-validator | PreToolUse on Bash, apply_patch | Validates tool inputs and flags dangerous patterns | | destructive-git-guard | PreToolUse on Bash | Warns before commands that can discard Git state | | file-change-validator | PostToolUse on apply_patch | Calls out configuration and lockfile changes |

Security hooks are advisory (exit 0). They warn but never block. Existing custom and OMX handlers are preserved in place when managed handlers are merged. First trust the project's .codex/ configuration layer, then open /hooks after init or update to review and approve the exact command-hook definitions. Codex skips untrusted project hooks, and omcustomcodex never auto-approves hook hashes. The --dangerously-bypass-hook-trust Codex flag is for isolated, pre-vetted automation only, not normal onboarding.

CLI

omcustomcodex init                  # Interactive setup wizard (language, framework, team mode)
omcustomcodex init --lang ko        # Initialize with Korean
omcustomcodex init --from-snapshot  # Install from pre-configured team snapshot
omcustomcodex sync                  # Detect drift between .codex/ state and lockfile
omcustomcodex sync --check          # Check for drift without applying changes
omcustomcodex sync --export         # Export current state as team snapshot
omcustomcodex update                # Update to latest
omcustomcodex list                  # List components
omcustomcodex doctor                # Verify installation
omcustomcodex doctor --fix          # Auto-fix issues
omcustomcodex security              # Scan for security issues
omcustomcodex projects              # List managed projects with version status
omcustomcodex update --all          # Batch update all outdated projects
omcustomcodex serve                 # Start built-in Web UI
omcustomcodex serve-stop            # Stop Web UI

Project Structure

Managed project runtime

your-project/
├── AGENTS.md                   # Entry point
├── .codex/
│   ├── agents/                 # 50 agent definitions
│   ├── rules/                  # Harness Markdown policies; optional native *.rules exec policy
│   ├── hooks/                  # 15 lifecycle hook scripts
│   ├── schemas/                # Tool input validation schemas
│   ├── specs/                  # Extracted canonical specs
│   ├── contexts/               # 4 shared context files
│   └── ontology/               # Knowledge graph for RAG
├── .agents/
│   └── skills/                 # 122 installed skill modules
└── guides/                     # 52 reference documents

Source Repository And Compatibility Surfaces

• This repository keeps package-authoring skills in .codex/skills/; that is a source-repo surface, not the installed project skill path.
• Installed projects use .agents/skills/ for managed skills and .codex/agents/*.toml for managed Codex agents.
• Installed .codex/rules/*.md files are harness behavioral policies. They apply because AGENTS.md explicitly loads or references them; Codex does not treat Markdown in this directory as native command policy.
• Native Codex command execution policy uses Starlark files at .codex/rules/*.rules. These files govern whether shell commands are allowed, prompted, or forbidden and are separate from the harness Markdown policies.
• Repository definitions in .codex/agents/*.md and packaged templates/.claude/agents/*.md are distinct upstream-compatible source inputs: the former uses native model_lane plus model_reasoning_effort, while the latter remains the explicit Claude-compatible schema. omcustomcodex compiles both to the same managed TOML runtime contract; neither Markdown form is an active installed role.
• Other templates/.claude/ and templates/CLAUDE.md* files remain upstream-compatible template inputs; they are not the active Codex runtime surface after install.
• .codex/hooks/ contains managed scripts and explicit Claude-compatibility records; omcustomcodex compiles the validated native subset into the discoverable project registry at .codex/hooks.json.
• Custom and OMX native roles may coexist in .codex/agents/*.toml; omcustomcodex preserves them while synchronizing its generated managed TOML roles.
• Project-scoped MCP configuration lives in .codex/config.toml, and the managed project registry lives in ~/.oh-my-customcodex/projects.json.

External Tool Integrations

RTK is automatically installed during omcustomcodex init for 60-90% token savings. Other tools are optional:

| Tool | Purpose | Install | Status | |------|---------|---------|--------| | RTK | 60-90% token savings on CLI output | Auto-installed via omcustomcodex init | Recommended | | Codex CLI | OpenAI Codex hybrid workflows | npm i -g @openai/codex | Optional | | Gemini CLI | Google Gemini hybrid workflows | npm i -g @google/gemini-cli | Optional |

When installed, each tool is auto-detected at session start and its features become available. When not installed, commands fall back to the built-in GPT Codex + OMX baseline or the next supported integration path.

Development

bun install          # Install dependencies
bun run dev          # Development mode
bun test             # Run tests
bun run build        # Production build

Requirements: Node.js 20.17+/22.13+/23.5+, Bun, Codex CLI. GitHub CLI (gh) and jq are recommended for release automation and local hook validation.

License

This project is licensed under the PolyForm Noncommercial License 1.0.0.

You are free to use, modify, and distribute oh-my-customcodex for any noncommercial purpose — personal projects, research, education, and nonprofit/government use. Commercial use is not permitted under this license.

Need a commercial license? Open an issue or reach out to the author.