Codex Update

Last updated: April 15, 2026

Purpose

This section tracks the work required to bring the WDG AI Development Environment's Claude-heavy workflow support to first-class Codex support.

The goal is not to replace Claude-specific tooling. The goal is to make Codex a peer client with:

• the same project-scoped onboarding
• the same MCP connectivity
• comparable reusable skills
• comparable reusable subagents
• accurate docs and test coverage

What We Are Solving

Today the platform already has:

• AGENTS.md guidance that Codex can read directly
• a root .codex/config.toml
• one example project-local Codex agent

But the automated project setup and sync flows still target Claude-first paths and formats:

• .claude/settings.json
• .claude/skills/
• .claude/agents/

Codex uses different discovery paths and agent formats:

• .codex/config.toml
• .agents/skills/
• .codex/agents/*.toml

That means Codex works in this repo today only through partial manual setup, not through the same supported platform workflow that Claude projects get.

Recommended Direction

The migration plan in this folder assumes these decisions:

1. AGENTS.md remains the shared instruction backbone across assistants.
2. Codex support is added to the existing generic project setup and sync commands rather than introduced as a separate parallel workflow.
3. Skills remain authored as SKILL.md directories, but repository deployment for Codex moves to .agents/skills/.
4. Codex subagents are treated as a separate output format and stored in .codex/agents/*.toml.
5. MCP parity is explicit and tested. Codex should receive the same required WDG MCP servers that other supported assistants receive, unless a server is intentionally excluded.

Documents In This Section

• Current State Audit
• Migration Plan
• Dual-Assistant Maintenance Model
• AI Feature Checklist

Definition Of Success

Codex support is considered complete when all of the following are true:

• wdg create ... generates Codex-ready project files without manual steps.
• wdg <project> ai-config sync refreshes Codex files as well as the existing assistant files.
• wdg <project> skills sync deploys Codex-discoverable skills.
• project repositories can ship Codex subagents in a supported format.
• platform docs describe Codex accurately instead of mentioning it only as a placeholder.
• CLI tests cover the new Codex paths and sync behavior.

External References

• AGENTS.md: https://developers.openai.com/codex/guides/agents-md
• Config basics: https://developers.openai.com/codex/config-basic
• MCP: https://developers.openai.com/codex/mcp
• Skills: https://developers.openai.com/codex/skills
• Subagents: https://developers.openai.com/codex/subagents
• Rules: https://developers.openai.com/codex/rules