Enabling Codex Support for Claude Code Agents

Hello, this is Fukatsu from Scalar. In this post, I will share how I enabled "Nexus Architect"—the architecture design agent I built for Claude Code and introduced in my previous article—to also work with OpenAI Codex.

I will explain the process of making the skills, rules, and hooks originally exclusive to Claude Code work with Codex, covering how I utilized the two tools, what differed, and what remained the same.

---

What is Nexus Architect?

Nexus Architect is an agent system that automates the design, analysis, code generation, and review of microservice systems using ScalarDB. As detailed in my previous article (Coding Agent for ScalarDB), the key points are as follows:

• Two plugins: architect (architecture design, migration, review) and scalardb (app development, code review)
• 51 skills: Covering investigation, analysis, evaluation, design, implementation, review, and reporting
• 7-phase pipeline: Automated execution controlled by a dependency graph via skill-dependencies.yaml
• Designed for Claude Code: .claude-plugin/ plugin definition, CLAUDE.md, and PostToolUse hooks

nexus-architect/
├── CLAUDE.md                # Guide for Claude Code
├── AGENTS.md                # Codex compatibility layer (added this time)
├── .claude-plugin/
│   └── plugin.json          # Plugin definition (architect + scalardb)
├── skills/                  # SKILL.md for 51 skills
├── rules/                   # 12 domain rules
├── hooks/
│   ├── validate-frontmatter.sh
│   └── validate-mermaid.sh
└── workflow/                # Pipeline specification

When the implementation for Claude Code was mostly complete, the idea of making it callable from Codex arose. However, Claude Code and Codex have different design philosophies. I decided to start by investigating both sides to identify what is the same and what is different.

---

Investigation Process: Looking through both tools simultaneously

Step 1: Asking Codex to "Identify the differences"

First, I launched Codex, had it read the repository, and instructed it as follows:

This folder contains agents, skills, and rules for Claude Code. Please investigate this folder and identify the parts where operation differs for Codex.

From Codex's perspective, the identified differences were as follows:

Different tool names

SKILL.md files frequently reference Claude Code-specific tool names such as Read, Write, Edit, Bash, Task, Glob, and Grep. Codex does not have these tools and instead uses apply_patch or shell commands for equivalent operations.

Different skill invocation methods

In Claude Code, skills can be invoked via slash commands like /architect:start. Codex lacks this command system, requiring direct reading and execution of the skill files located at skills/start/SKILL.md.

Hooks do not run automatically

validate-frontmatter.sh and validate-mermaid.sh are executed automatically after Write/Edit operations as PostToolUse hooks in Claude Code. Since Codex lacks this mechanism, manual execution is required.

model: frontmatter is ignored

Each SKILL.md frontmatter includes specifications like model: opus or model: sonnet. While Claude Code reads this to switch models, Codex does not interpret frontmatter and will continue to use one model for the entire session.

@rules/ references are not resolved

CLAUDE.md references documents using the @ prefix, such as @rules/output-conventions.md. Since Codex is unfamiliar with this syntax, conversion to repository-relative paths is necessary.

Paths under .claude/ are invisible

Some skills reference Claude Code installation paths like .claude/docs/api-reference.md or .claude/rules/. These paths do not exist for Codex.

Step 2: Asking Claude Code to "Identify the differences with Codex"

Next, I conducted an investigation from the Claude Code side.

I am modifying the agent, skills, and rules stored in this folder for Claude Code so that they can be used from Codex. Please identify the parts where the operation differs in order to make it usable in both Claude Code and Codex.

Claude Code pointed out the following additional points:

Handling of the AskUserQuestion tool

Skills like start/SKILL.md and pipeline/SKILL.md make heavy use of AskUserQuestion due to their interactive workflows. While Codex has a chat-based interface, it lacks this specific tool, so an alternative pattern is needed to present choices as a numbered list and wait for a reply.

Differences in Task / Subagent execution models

In Claude Code, you can launch sub-agents in parallel using the Task tool. The review-* skills use this to achieve 5-perspective parallel reviews. Since Codex lacks explicit sub-agent branching, a fallback is required to execute them sequentially in the main thread.

disable-model-invocation: true frontmatter

pipeline/SKILL.md has this flag; Claude Code treats the skill as an orchestrator without passing it to the model. Because Codex does not interpret this flag, when it reads the file, an explanation is needed that "you should manually execute each phase according to the dependency graph."

CLAUDE_PLUGIN_ROOT variable

When referencing sub-agent templates (skills/common/subagents/), the skill files use the path ${CLAUDE_PLUGIN_ROOT}/skills/common/subagents/. Since Codex lacks a plugin mechanism, a declaration is required to treat the repository root as CLAUDE_PLUGIN_ROOT.

Organizing the differences: What is different and what is not?

By cross-referencing the two investigations, the differences could be organized into the following six categories:

Category	Claude Code	Codex	Strategy
Tool Name	Read, Write, Edit, Bash	cat/sed, apply_patch, shell	Document mapping in AGENTS.md
Skill Invocation	/architect:start	Read skills/start/SKILL.md directly	Document mapping rules in AGENTS.md
Hooks	Automated via PostToolUse	Manual execution of hooks/*.sh	Document manual steps in AGENTS.md
Model Switching	Automatic via model: frontmatter	Use session model	Add model recommendation table in AGENTS.md
.claude/ Path	References installed paths	References alternative paths in repo	Add fallback paths in AGENTS.md
Sub-agents	Parallel launch via Task tool	Sequential execution in main thread	Describe execution policy in AGENTS.md

Conversely, the items that did not require any changes are as follows:

• SKILL.md core logic: The steps themselves within the skills require no changes.
• rules/ documents: Domain rules can be shared by both.
• skill-dependencies.yaml: The dependency graph structure is valid in both environments.
• hooks/ shell scripts: The scripts themselves continue to work (only the method of invocation changes).
• Output directory structure: reports/, generated/, and work/ can be shared as-is.

I settled on the strategy of creating a thin compatibility layer that absorbs the differences in invocation methods and environment without changing the content of the skills themselves.

Modifying for Codex: Creating AGENTS.md

Once the differences were clarified, I requested Codex to perform the modifications.

The main task was to create a new AGENTS.md. Just as Claude Code reads CLAUDE.md, Codex reads AGENTS.md as instructions for the agent.

# AGENTS.md

## Codex Command Mapping

When the user invokes a Claude-style command in Codex, map it to the matching local skill:

- `/architect:<name>` -> read and follow `skills/<name>/SKILL.md`
- `/scalardb:<name>` -> read and follow `skills/<name>/SKILL.md`
- `@rules/...`, `@templates/...`, `@skills/...` -> resolve as repository-relative paths

## Claude Tool Mapping

- `Read`          -> use `sed`, `cat`, or `rg` to read files
- `Write`         -> create files with `apply_patch`
- `Edit`          -> use `apply_patch`
- `Bash`          -> use shell commands
- `Task`/`Subagent` -> run in main Codex thread unless user asks for sub-agents
- `AskUserQuestion` -> present numbered choices in chat and wait for reply
- `Skill`         -> open the referenced `SKILL.md` and follow it

Furthermore, I defined fallback paths for .claude/docs/ references.

## Runtime Paths (Fallbacks for Codex)

- `.claude/docs/api-reference.md`           -> `skills/common/references/api-reference.md`
- `.claude/docs/exception-hierarchy.md`     -> `skills/common/references/exception-hierarchy.md`
- `.claude/docs/configuration-reference.md` -> `skills/common/references/configuration-reference.md`
- `.claude/docs/code-patterns/*`            -> `skills/common/references/code-patterns/*`
- `.claude/rules/*`                         -> `rules/*`

I also added a model recommendation table. In Claude Code, the model: opus specification is applied automatically, but in Codex, humans need to select the appropriate model.

## Model Recommendations

| Opus equivalent      | Sonnet equivalent           | Haiku equivalent sufficient |
|---|---|---|
| analyze, design-api, | evaluate-ddd, evaluate-mmi, | init-output, render-mermaid |
| design-microservices,| investigate, review-*, ...  |                             |
| map-domains, ...     |                             |                             |

I also explicitly stated the manual execution of hooks.

## Validation

After editing any report Markdown file or Mermaid diagram, run validation manually:

```bash
hooks/validate-frontmatter.sh reports/before/example/technology-stack.md
hooks/validate-mermaid.sh reports/before/example/codebase-structure.md

Both hooks accept Claude Code hook JSON on stdin, so Claude Code compatibility is preserved.

Finally, I wrote the instructions for **addressing `disable-model-invocation` in `pipeline/SKILL.md`**.

```markdown
## Pipeline Skill

`skills/pipeline/SKILL.md` is an orchestrator. The `disable-model-invocation: true`
frontmatter is a Claude Code plugin hint; Codex does not interpret it. Treat the file
as the orchestration specification and follow the dependency graph manually.

---

Reviewing and Modifying with Claude Code

After Codex generated the first draft of AGENTS.md, I reviewed it using Claude Code. Since Claude Code is deeply familiar with CLAUDE.md and the suite of skills, it is well-suited for verifying whether the content written from the perspective of Codex inadvertently breaks Claude Code compatibility.

Claude Code identified three points for revision:

1. Retain references to .claude-plugin/

The initial draft of AGENTS.md omitted mentions of CLAUDE.md and .claude-plugin/. To maintain Claude Code compatibility, I explicitly added instructions stating that these should not be altered.

## Interaction Rules

- Preserve Claude Code compatibility. Do not remove `.claude-plugin/`,
  `CLAUDE.md`, or Claude-specific frontmatter unless explicitly asked.

2. Handling of .claude/configuration/databases.env

DB migration-related skills reference .claude/configuration/databases.env. The Codex draft attempted to rewrite this path to a repository-internal path, but since the file is shared with Claude Code, the correct approach was to leave this path as is.

For migration skills that mention `.claude/configuration/databases.env` or `.claude/output/`,
keep those paths unless the user asks to migrate the runtime state.
They are compatibility paths and can be used by both Claude Code and Codex.

3. Explicitly ignoring ExitPlanMode

Some skills call ExitPlanMode at the end of the planning phase. Since Codex does not have this tool, I added ExitPlanMode -> ignore to AGENTS.md.

---

How to Use After the Update

By adding AGENTS.md, I can now invoke the same skills from Codex.

Claude Code (No changes)

claude plugin marketplace add wfukatsu/nexus-architect
claude plugin install architect@nexus-architect --scope user
claude plugin install scalardb@nexus-architect --scope user

# Invoking skills
/architect:start ./target-project
/scalardb:model

Codex (Newly supported)

# Use the same commands in chat (forwarded to skill files via AGENTS.md)
/architect:start ./target-project

# Or specify the skill file directly
Use skills/design-microservices/SKILL.md to design the target architecture for ./target-app.

Executing hooks requires manual intervention.

# After editing a report
hooks/validate-frontmatter.sh reports/before/example/technology-stack.md
hooks/validate-mermaid.sh reports/before/example/codebase-structure.md

---

Lessons Learned

SKILL.md required no changes

I initially expected to rewrite several skill files, but in reality, the core of SKILL.md remained largely unchanged. The essence of a skill is not how a tool is invoked, but the logic of what to investigate, what to output, and what to pass to the next phase. This remains constant across both tools.

Differences were absorbed by a "translation table for bridging environments"

Differences in tool names and automated hook execution were ultimately absorbed by a single translation sheet: AGENTS.md. Because the skills were written as "self-contained specifications," I felt the differences in execution engines could be handled externally.

Roles of the two tools became clear

Codex was excellent at calmly pointing out "what is different when viewed from the outside." Claude Code was excellent at "reviewing with an understanding of the internal design intent." This process unintentionally evolved into a natural division of labor: Implementing with Codex -> Reviewing with Claude Code.

The design of the model: frontmatter will pay off in the future

While currently ignored by Codex, information regarding "which model is appropriate for which skill" is recorded in SKILL.md. If Codex eventually interprets frontmatter, it will benefit from this immediately. For now, the recommendation table in AGENTS.md serves as a substitute.

---

Conclusion

Looking back at the Codex support implementation for Nexus Architect:

1. Investigated with Codex: Identified differences in tool names, skill invocation, and issues regarding hooks, models, and paths.
2. Investigated with Claude Code: Identified alternatives for AskUserQuestion, sub-agent execution models, and handling of disable-model-invocation.
3. Organized differences: Categorized into 6 groups, separating what needed changing from what did not.
4. Created AGENTS.md with Codex: Documented the translation table, command mapping, model recommendations, fallback paths, and validation procedures.
5. Reviewed & refined with Claude Code: Corrected statements that might break compatibility and confirmed the accurate representation of intent.

There were zero changes to the SKILL.md files themselves; only one file (AGENTS.md) was added. The system is now in a state where the same set of skills can be used in both Claude Code and Codex environments.

The repository is here: nexus-architect

For detailed command references and Codex setup instructions, please see docs/codex-usage.md.