The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
fix: refresh codex config and docs
Affaan Mustafa77f38955b3bf
diff --git a/.codex/AGENTS.md b/.codex/AGENTS.mdindex 03730594b..6de01b1e6 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.<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 |diff --git a/.codex/agents/docs-researcher.toml b/.codex/agents/docs-researcher.tomlnew file mode 100644index 000000000..f8bd48ddb--- /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.tomlnew file mode 100644index 000000000..af7c19659--- /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.tomlnew file mode 100644index 000000000..269c5e498--- /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.tomlindex 87d9747aa..c60224aca 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 selectionmodel = "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=<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"diff --git a/README.md b/README.mdindex 09267ca5f..25d6c091a 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-detectedcodex++# 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---