From 77f38955b3bf01cdab61ee2a6347fd4b976b8f48 Mon Sep 17 00:00:00 2001 From: Affaan Mustafa Date: Tue, 10 Mar 2026 19:22:37 -0700 Subject: [PATCH] fix: refresh codex config and docs --- .codex/AGENTS.md | 16 +++++- .codex/agents/docs-researcher.toml | 9 ++++ .codex/agents/explorer.toml | 9 ++++ .codex/agents/reviewer.toml | 9 ++++ .codex/config.toml | 83 ++++++++++++++++++------------ README.md | 35 ++++++++++--- 6 files changed, 119 insertions(+), 42 deletions(-) create mode 100644 .codex/agents/docs-researcher.toml create mode 100644 .codex/agents/explorer.toml create mode 100644 .codex/agents/reviewer.toml diff --git a/.codex/AGENTS.md b/.codex/AGENTS.md index 03730594..6de01b1e 100644 --- a/.codex/AGENTS.md +++ b/.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.]` +- 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.]` roles | | Security | Hook-based enforcement | Instruction + sandbox | | MCP | Full support | Command-based only | diff --git a/.codex/agents/docs-researcher.toml b/.codex/agents/docs-researcher.toml new file mode 100644 index 00000000..f8bd48dd --- /dev/null +++ b/.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. +""" diff --git a/.codex/agents/explorer.toml b/.codex/agents/explorer.toml new file mode 100644 index 00000000..af7c1965 --- /dev/null +++ b/.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. +""" diff --git a/.codex/agents/reviewer.toml b/.codex/agents/reviewer.toml new file mode 100644 index 00000000..269c5e49 --- /dev/null +++ b/.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. +""" diff --git a/.codex/config.toml b/.codex/config.toml index 87d9747a..c60224ac 100644 --- a/.codex/config.toml +++ b/.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. -# Or keep it in your project root for project-level config. +# Copy this file to ~/.codex/config.toml for global defaults, or keep it in +# 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 -[permissions] -# "untrusted" = no writes, "on-request" = ask per action, "never" = full auto +# Top-level runtime settings (current Codex schema) approval_policy = "on-request" -# "off", "workspace-read", "workspace-write", "danger-full-access" sandbox_mode = "workspace-write" +web_search = "live" -# Notifications (macOS) -[notify] -command = "terminal-notifier -title 'Codex ECC' -message 'Task completed!' -sound default" -on_complete = true +# External notifications receive a JSON payload on stdin. +notify = [ + "terminal-notifier", + "-title", "Codex ECC", + "-message", "Task completed!", + "-sound", "default", +] -# History - persistent instructions applied to every session -[history] -# These are prepended to every conversation -persistent_instructions = """ -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 -""" +# Prefer AGENTS.md and project-local .codex/AGENTS.md for instructions. +# model_instructions_file replaces built-in instructions instead of AGENTS.md, +# so leave it unset unless you intentionally want a single override file. +# model_instructions_file = "/absolute/path/to/instructions.md" -# MCP Servers -# Codex supports command-based MCP servers +# 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= +# Profiles — switch with `codex -p ` [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" diff --git a/README.md b/README.md index 09267ca5..25d6c091 100644 --- a/README.md +++ b/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 -cp .codex/config.toml ~/.codex/config.toml - -# Run Codex CLI in the repo — AGENTS.md is auto-detected +# Run Codex CLI in the repo — AGENTS.md and .codex/ are 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.]` +- 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 ---