fix: refresh codex config and docs

.codex/AGENTS.md

@@ -39,6 +39,20 @@ Available skills:
 
 Configure in `~/.codex/config.toml` under `[mcp_servers]`. See `.codex/config.toml` for reference configuration with GitHub, Context7, Memory, and Sequential Thinking servers.
 
+## Multi-Agent Support
+
+Codex now supports multi-agent workflows behind the experimental `features.multi_agent` flag.
+
+- Enable it in `.codex/config.toml` with `[features] multi_agent = true`
+- Define project-local roles under `[agents.<name>]`
+- Point each role at a TOML layer under `.codex/agents/`
+- Use `/agent` inside Codex CLI to inspect and steer child agents
+
+Sample role configs in this repo:
+- `.codex/agents/explorer.toml` — read-only evidence gathering
+- `.codex/agents/reviewer.toml` — correctness/security review
+- `.codex/agents/docs-researcher.toml` — API and release-note verification
+
 ## Key Differences from Claude Code
 
 | Feature | Claude Code | Codex CLI |
@@ -47,7 +61,7 @@ Configure in `~/.codex/config.toml` under `[mcp_servers]`. See `.codex/config.to
 | Context file | CLAUDE.md + AGENTS.md | AGENTS.md only |
 | Skills | Skills loaded via plugin | `.agents/skills/` directory |
 | Commands | `/slash` commands | Instruction-based |
-| Agents | Subagent Task tool | Single agent model |
+| Agents | Subagent Task tool | Multi-agent via `/agent` and `[agents.<name>]` roles |
 | Security | Hook-based enforcement | Instruction + sandbox |
 | MCP | Full support | Command-based only |
 

.codex/agents/docs-researcher.toml

@@ -0,0 +1,9 @@
+model = "gpt-5.4"
+model_reasoning_effort = "medium"
+sandbox_mode = "read-only"
+
+developer_instructions = """
+Verify APIs, framework behavior, and release-note claims against primary documentation before changes land.
+Cite the exact docs or file paths that support each claim.
+Do not invent undocumented behavior.
+"""

.codex/agents/explorer.toml

@@ -0,0 +1,9 @@
+model = "o4-mini"
+model_reasoning_effort = "medium"
+sandbox_mode = "read-only"
+
+developer_instructions = """
+Stay in exploration mode.
+Trace the real execution path, cite files and symbols, and avoid proposing fixes unless the parent agent asks for them.
+Prefer targeted search and file reads over broad scans.
+"""

.codex/agents/reviewer.toml

@@ -0,0 +1,9 @@
+model = "gpt-5.4"
+model_reasoning_effort = "high"
+sandbox_mode = "read-only"
+
+developer_instructions = """
+Review like an owner.
+Prioritize correctness, security, behavioral regressions, and missing tests.
+Lead with concrete findings and avoid style-only feedback unless it hides a real bug.
+"""

.codex/config.toml

@@ -1,42 +1,37 @@
-# Everything Claude Code (ECC) — Codex CLI Reference Configuration
+#:schema https://developers.openai.com/codex/config-schema.json
+
+# Everything Claude Code (ECC) — Codex Reference Configuration
 #
-# Copy this file to ~/.codex/config.toml to apply globally.
+# Copy this file to ~/.codex/config.toml for global defaults, or keep it in
-# Or keep it in your project root for project-level config.
+# the project root as .codex/config.toml for project-local settings.
 #
-# Docs: https://github.com/openai/codex
+# Official docs:
+# - https://developers.openai.com/codex/config-reference
+# - https://developers.openai.com/codex/multi-agent
 
 # Model selection
 model = "o4-mini"
 model_provider = "openai"
 
-# Permissions
+# Top-level runtime settings (current Codex schema)
-[permissions]
-# "untrusted" = no writes, "on-request" = ask per action, "never" = full auto
 approval_policy = "on-request"
-# "off", "workspace-read", "workspace-write", "danger-full-access"
 sandbox_mode = "workspace-write"
+web_search = "live"
 
-# Notifications (macOS)
+# External notifications receive a JSON payload on stdin.
-[notify]
+notify = [
-command = "terminal-notifier -title 'Codex ECC' -message 'Task completed!' -sound default"
+  "terminal-notifier",
-on_complete = true
+  "-title", "Codex ECC",
+  "-message", "Task completed!",
+  "-sound", "default",
+]
 
-# History - persistent instructions applied to every session
+# Prefer AGENTS.md and project-local .codex/AGENTS.md for instructions.
-[history]
+# model_instructions_file replaces built-in instructions instead of AGENTS.md,
-# These are prepended to every conversation
+# so leave it unset unless you intentionally want a single override file.
-persistent_instructions = """
+# model_instructions_file = "/absolute/path/to/instructions.md"
-Follow ECC principles:
-1. Test-Driven Development (TDD) - write tests first, 80%+ coverage required
-2. Immutability - always create new objects, never mutate
-3. Security-First - validate all inputs, no hardcoded secrets
-4. Conventional commits: feat|fix|refactor|docs|test|chore|perf|ci: description
-5. File organization: many small files (200-400 lines, 800 max)
-6. Error handling: handle at every level, never swallow errors
-7. Input validation: schema-based validation at system boundaries
-"""
 
-# MCP Servers
+# MCP servers
-# Codex supports command-based MCP servers
 [mcp_servers.github]
 command = "npx"
 args = ["-y", "@modelcontextprotocol/server-github"]
@@ -62,19 +57,41 @@ args = ["-y", "@modelcontextprotocol/server-sequential-thinking"]
 # command = "npx"
 # args = ["-y", "firecrawl-mcp"]
 #
-# [mcp_servers.railway]
+# [mcp_servers.cloudflare]
 # command = "npx"
-# args = ["-y", "@anthropic/railway-mcp"]
+# args = ["-y", "@cloudflare/mcp-server-cloudflare"]
 
-# Features
 [features]
-web_search_request = true
+# Codex multi-agent support is experimental as of March 2026.
+multi_agent = true
 
-# Profiles — switch with CODEX_PROFILE=<name>
+# Profiles — switch with `codex -p <name>`
 [profiles.strict]
 approval_policy = "on-request"
-sandbox_mode = "workspace-read"
+sandbox_mode = "read-only"
+web_search = "cached"
 
 [profiles.yolo]
 approval_policy = "never"
 sandbox_mode = "workspace-write"
+web_search = "live"
+
+# Optional project-local multi-agent roles.
+# Keep these commented in global config, because config_file paths are resolved
+# relative to the config.toml file and must exist at load time.
+#
+# [agents]
+# max_threads = 6
+# max_depth = 1
+#
+# [agents.explorer]
+# description = "Read-only codebase explorer for gathering evidence before changes are proposed."
+# config_file = "agents/explorer.toml"
+#
+# [agents.reviewer]
+# description = "PR reviewer focused on correctness, security, and missing tests."
+# config_file = "agents/reviewer.toml"
+#
+# [agents.docs_researcher]
+# description = "Documentation specialist that verifies APIs, framework behavior, and release notes."
+# config_file = "agents/docs-researcher.toml"

README.md

@@ -893,27 +893,29 @@ ECC provides **first-class Codex support** for both the macOS app and CLI, with
 ### Quick Start (Codex App + CLI)
 
 ```bash
-# Copy the reference config to your home directory
+# Run Codex CLI in the repo — AGENTS.md and .codex/ are auto-detected
-cp .codex/config.toml ~/.codex/config.toml
-
-# Run Codex CLI in the repo — AGENTS.md is auto-detected
 codex
+
+# Optional: copy the global-safe defaults to your home directory
+cp .codex/config.toml ~/.codex/config.toml
 ```
 
 Codex macOS app:
 - Open this repository as your workspace.
 - The root `AGENTS.md` is auto-detected.
-- Optional: copy `.codex/config.toml` to `~/.codex/config.toml` for CLI/app behavior consistency.
+- `.codex/config.toml` and `.codex/agents/*.toml` work best when kept project-local.
+- Optional: copy `.codex/config.toml` to `~/.codex/config.toml` for global defaults; keep the multi-agent role files project-local unless you also copy `.codex/agents/`.
 
 ### What's Included
 
 | Component | Count | Details |
 |-----------|-------|---------|
-| Config | 1 | `.codex/config.toml` — model, permissions, MCP servers, persistent instructions |
+| Config | 1 | `.codex/config.toml` — top-level approvals/sandbox/web_search, MCP servers, notifications, profiles |
 | AGENTS.md | 2 | Root (universal) + `.codex/AGENTS.md` (Codex-specific supplement) |
 | Skills | 16 | `.agents/skills/` — SKILL.md + agents/openai.yaml per skill |
 | MCP Servers | 4 | GitHub, Context7, Memory, Sequential Thinking (command-based) |
 | Profiles | 2 | `strict` (read-only sandbox) and `yolo` (full auto-approve) |
+| Agent Roles | 3 | `.codex/agents/` — explorer, reviewer, docs-researcher |
 
 ### Skills
 
@@ -940,7 +942,24 @@ Skills at `.agents/skills/` are auto-loaded by Codex:
 
 ### Key Limitation
 
-Codex does **not yet provide Claude-style hook execution parity**. ECC enforcement there is instruction-based via `AGENTS.md` and `persistent_instructions`, plus sandbox permissions.
+Codex does **not yet provide Claude-style hook execution parity**. ECC enforcement there is instruction-based via `AGENTS.md`, optional `model_instructions_file` overrides, and sandbox/approval settings.
+
+### Multi-Agent Support
+
+Current Codex builds support experimental multi-agent workflows.
+
+- Enable `features.multi_agent = true` in `.codex/config.toml`
+- Define roles under `[agents.<name>]`
+- Point each role at a file under `.codex/agents/`
+- Use `/agent` in the CLI to inspect or steer child agents
+
+ECC ships three sample role configs:
+
+| Role | Purpose |
+|------|---------|
+| `explorer` | Read-only codebase evidence gathering before edits |
+| `reviewer` | Correctness, security, and missing-test review |
+| `docs_researcher` | Documentation and API verification before release/docs changes |
 
 ---
 
@@ -1090,7 +1109,7 @@ ECC is the **first plugin to maximize every major AI coding tool**. Here's how e
 - **AGENTS.md** at root is the universal cross-tool file (read by all 4 tools)
 - **DRY adapter pattern** lets Cursor reuse Claude Code's hook scripts without duplication
 - **Skills format** (SKILL.md with YAML frontmatter) works across Claude Code, Codex, and OpenCode
-- Codex's lack of hooks is compensated by `persistent_instructions` and sandbox permissions
+- Codex's lack of hooks is compensated by `AGENTS.md`, optional `model_instructions_file` overrides, and sandbox permissions
 
 ---