feat: add Codex agent conversion and install support (#362)

Adds Codex as a conversion/install target: each agent → `~/.codex/agents/<slug>.toml` with the three required Codex fields (name, description, developer_instructions).

Validated: all 184 agents generate valid, parseable TOML (incl. 21k-char agents with embedded code blocks) via the PR's TOML basic-string escaper. Matches OpenAI's documented custom-agent schema.

Thanks @yunuskilicdev.

.gitignore

@@ -78,3 +78,4 @@ integrations/qwen/agents/
 integrations/kimi/*/
 !integrations/openclaw/README.md
 !integrations/kimi/README.md
+integrations/codex/agents/*

CONTRIBUTING.md

@@ -221,6 +221,8 @@ quickstart guide wearing an agent costume does not.
 
 **Qwen Code Compatibility**: Agent bodies support `${variable}` templating for dynamic context (e.g., `${project_name}`, `${task_description}`). Qwen SubAgents use minimal frontmatter: only `name` and `description` are required; `color`, `emoji`, and `version` fields are omitted as Qwen doesn't use them.
 
+**Codex Compatibility**: Codex custom agents are generated as standalone TOML files. The Codex integration keeps a minimal 1:1 mapping: `name` and `description` are copied from frontmatter, and the Markdown body becomes `developer_instructions`. Source-only metadata such as `color`, `emoji`, `vibe`, and other unsupported frontmatter fields are omitted.
+
 ### What Makes a Great Agent?
 
 **Great agents have**:

README.md

@@ -47,7 +47,7 @@ Each agent file contains:
 
 Browse the agents below and copy/adapt the ones you need!
 
-### Option 3: Use with Other Tools (GitHub Copilot, Antigravity, Gemini CLI, OpenCode, OpenClaw, Cursor, Aider, Windsurf, Kimi Code)
+### Option 3: Use with Other Tools (GitHub Copilot, Antigravity, Gemini CLI, OpenCode, OpenClaw, Cursor, Aider, Windsurf, Kimi Code, Codex)
 
 ```bash
 # Step 1 -- generate integration files for all supported tools
@@ -66,6 +66,7 @@ Browse the agents below and copy/adapt the ones you need!
 ./scripts/install.sh --tool aider
 ./scripts/install.sh --tool windsurf
 ./scripts/install.sh --tool kimi
+./scripts/install.sh --tool codex
 ```
 
 See the [Multi-Tool Integrations](#-multi-tool-integrations) section below for full details.
@@ -555,6 +556,7 @@ The Agency works natively with Claude Code, and ships conversion + install scrip
 - **[OpenClaw](https://github.com/openclaw/openclaw)** — `SOUL.md` + `AGENTS.md` + `IDENTITY.md` per agent
 - **[Qwen Code](https://github.com/QwenLM/qwen-code)** — `.md` SubAgent files → `~/.qwen/agents/`
 - **[Kimi Code](https://github.com/MoonshotAI/kimi-cli)** — YAML agent specs → `~/.config/kimi/agents/`
+- **[Codex](https://developers.openai.com/codex/overview)** — TOML custom agents → `~/.codex/agents/`
 
 ---
 
@@ -592,8 +594,9 @@ The installer scans your system for installed tools, shows a checkbox UI, and le
   [ ]  9)  [ ]  Windsurf        (.windsurfrules)
   [ ] 10)  [ ]  Qwen Code       (~/.qwen/agents)
   [ ] 11)  [ ]  Kimi Code       (~/.config/kimi/agents)
+  [ ] 12)  [ ]  Codex           (~/.codex/agents)
 
-  [1-11] toggle   [a] all   [n] none   [d] detected
+  [1-12] toggle   [a] all   [n] none   [d] detected
   [Enter] install   [q] quit
 ```
 
@@ -603,6 +606,7 @@ The installer scans your system for installed tools, shows a checkbox UI, and le
 ./scripts/install.sh --tool opencode
 ./scripts/install.sh --tool openclaw
 ./scripts/install.sh --tool antigravity
+./scripts/install.sh --tool codex
 ```
 
 **Non-interactive (CI/scripts):**
@@ -831,6 +835,24 @@ See [integrations/kimi/README.md](integrations/kimi/README.md) for details.
 
 </details>
 
+<details>
+<summary><strong>Codex</strong></summary>
+
+Each agent is converted into a Codex custom agent TOML file and installed to `~/.codex/agents/`.
+
+```bash
+./scripts/convert.sh --tool codex
+./scripts/install.sh --tool codex
+```
+
+Then reference the custom agent by name in Codex:
+```
+Use the Frontend Developer agent to review this component.
+```
+
+See [integrations/codex/README.md](integrations/codex/README.md) for details.
+</details>
+
 ---
 
 ### Regenerating After Changes
@@ -840,6 +862,7 @@ When you add new agents or edit existing ones, regenerate all integration files:
 ```bash
 ./scripts/convert.sh                    # regenerate all (serial)
 ./scripts/convert.sh --parallel         # regenerate all in parallel (faster)
+./scripts/convert.sh --tool codex       # regenerate just one tool
 ./scripts/convert.sh --tool cursor      # regenerate just one tool
 ```
 
@@ -849,7 +872,7 @@ When you add new agents or edit existing ones, regenerate all integration files:
 
 - [ ] Interactive agent selector web tool
 - [x] Multi-agent workflow examples -- see [examples/](examples/)
-- [x] Multi-tool integration scripts (Claude Code, GitHub Copilot, Antigravity, Gemini CLI, OpenCode, OpenClaw, Cursor, Aider, Windsurf, Qwen Code, Kimi Code)
+- [x] Multi-tool integration scripts (Claude Code, GitHub Copilot, Antigravity, Gemini CLI, OpenCode, OpenClaw, Cursor, Aider, Windsurf, Qwen Code, Kimi Code, Codex)
 - [ ] Video tutorials on agent design
 - [ ] Community agent marketplace
 - [ ] Agent "personality quiz" for project matching

integrations/README.md

@@ -16,6 +16,7 @@ supported agentic coding tools.
 - **[Windsurf](#windsurf)** — `.windsurfrules` in `windsurf/`
 - **[Kimi Code](#kimi-code)** — YAML agent specs in `kimi/`
 - **[Qwen Code](#qwen-code)** — project-scoped `.md` SubAgents in `.qwen/agents/`
+- **[Codex](#codex)** — `.toml` custom agents in `codex/`
 
 ## Quick Install
 
@@ -28,6 +29,7 @@ supported agentic coding tools.
 ./scripts/install.sh --tool copilot
 ./scripts/install.sh --tool openclaw
 ./scripts/install.sh --tool claude-code
+./scripts/install.sh --tool codex
 
 # Gemini CLI needs generated integration files on a fresh clone
 ./scripts/convert.sh --tool gemini-cli
@@ -238,3 +240,20 @@ cd /your/project && /path/to/agency-agents/scripts/install.sh --tool qwen
 ```
 
 See [qwen/README.md](qwen/README.md) for details.
+
+---
+
+## Codex
+
+Each agent is converted into a standalone Codex custom agent TOML file and
+installed to `~/.codex/agents/`.
+
+Because Codex uses generated TOML files rather than the source Markdown
+directly, run the converter before installing from a fresh clone:
+
+```bash
+./scripts/convert.sh --tool codex
+./scripts/install.sh --tool codex
+```
+
+See [codex/README.md](codex/README.md) for details.

integrations/codex/README.md

@@ -0,0 +1,79 @@
+# Codex Integration
+
+Converts all Agency agents into Codex custom agent TOML files. Each source
+agent becomes one standalone `.toml` file containing the minimal Codex-required
+fields: `name`, `description`, and `developer_instructions`.
+
+## Installation
+
+### Prerequisites
+
+- [Codex](https://developers.openai.com/codex/overview) installed
+
+### Convert And Install
+
+```bash
+# Generate integration files (required on fresh clone)
+./scripts/convert.sh --tool codex
+
+# Install agents
+./scripts/install.sh --tool codex
+```
+
+This copies generated agent files to `~/.codex/agents/`.
+
+## Generated Format
+
+Each generated file lives in:
+
+```text
+integrations/codex/agents/<slug>.toml
+```
+
+The mapping is intentionally minimal:
+
+- `name` is copied from the source frontmatter unchanged
+- `description` is copied from the source frontmatter unchanged
+- `developer_instructions` contains the full Markdown body unchanged
+
+Source-only metadata such as `color`, `emoji`, `vibe`, and other unsupported
+frontmatter fields are omitted.
+
+## Usage
+
+After installation, reference the custom agent by name in Codex:
+
+```text
+Use the Frontend Developer agent to review this component.
+```
+
+Codex uses the `name` field inside the TOML file as the source of truth, so the
+generated filename slug is only for filesystem safety.
+
+## Regenerate
+
+After modifying source agents:
+
+```bash
+./scripts/convert.sh --tool codex
+./scripts/install.sh --tool codex
+```
+
+## Troubleshooting
+
+### Codex integration not found
+
+Generate the Codex artifacts before installing:
+
+```bash
+./scripts/convert.sh --tool codex
+```
+
+### Codex not detected
+
+Make sure `codex` is in your PATH, or that `~/.codex/` already exists:
+
+```bash
+which codex
+codex --help
+```

scripts/convert.sh

@@ -19,6 +19,7 @@
 #   openclaw     — OpenClaw workspaces (integrations/openclaw/<agent>/SOUL.md)
 #   qwen         — Qwen Code SubAgent files (~/.qwen/agents/*.md)
 #   kimi         — Kimi Code CLI agent files (~/.config/kimi/agents/)
+#   codex        — Codex custom agent TOML files (~/.codex/agents/*.toml)
 #   all          — All tools (default)
 #
 # Output is written to integrations/<tool>/ relative to the repo root.
@@ -104,6 +105,21 @@ slugify() {
   echo "$1" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//'
 }
 
+# Escape a value for a TOML basic string, including control characters that
+# cannot appear raw in TOML source.
+toml_escape_string() {
+  printf '%s' "$1" | perl -0pe '
+    s/\\/\\\\/g;
+    s/"/\\"/g;
+    s/\n/\\n/g;
+    s/\r/\\r/g;
+    s/\t/\\t/g;
+    s/\f/\\f/g;
+    s/\x08/\\b/g;
+    s/([\x00-\x07\x0B\x0E-\x1F\x7F])/sprintf("\\u%04X", ord($1))/ge;
+  '
+}
+
 # --- Per-tool converters ---
 
 convert_antigravity() {
@@ -132,6 +148,28 @@ ${body}
 HEREDOC
 }
 
+convert_codex() {
+  local file="$1"
+  local name description slug outfile body
+
+  name="$(get_field "name" "$file")"
+  description="$(get_field "description" "$file")"
+  slug="$(slugify "$name")"
+  body="$(get_body "$file")"
+
+  outfile="$OUT_DIR/codex/agents/${slug}.toml"
+  mkdir -p "$(dirname "$outfile")"
+
+  # Codex custom agent format: one TOML file per agent with minimal required
+  # fields only. Use a TOML basic string so control characters in the source
+  # body are encoded safely instead of producing invalid TOML.
+  cat > "$outfile" <<HEREDOC
+name = "$(toml_escape_string "$name")"
+description = "$(toml_escape_string "$description")"
+developer_instructions = "$(toml_escape_string "$body")"
+HEREDOC
+}
+
 convert_gemini_cli() {
   local file="$1"
   local name description slug outdir outfile body
@@ -500,6 +538,7 @@ run_conversions() {
 
       case "$tool" in
         antigravity) convert_antigravity "$file" ;;
+        codex)       convert_codex       "$file" ;;
         gemini-cli)  convert_gemini_cli  "$file" ;;
         opencode)    convert_opencode    "$file" ;;
         cursor)      convert_cursor      "$file" ;;
@@ -536,7 +575,7 @@ main() {
     esac
   done
 
-  local valid_tools=("antigravity" "gemini-cli" "opencode" "cursor" "aider" "windsurf" "openclaw" "qwen" "kimi" "all")
+  local valid_tools=("antigravity" "gemini-cli" "opencode" "cursor" "aider" "windsurf" "openclaw" "qwen" "kimi" "codex" "all")
   local valid=false
   for t in "${valid_tools[@]}"; do [[ "$t" == "$tool" ]] && valid=true && break; done
   if ! $valid; then
@@ -555,7 +594,7 @@ main() {
 
   local tools_to_run=()
   if [[ "$tool" == "all" ]]; then
-    tools_to_run=("antigravity" "gemini-cli" "opencode" "cursor" "aider" "windsurf" "openclaw" "qwen" "kimi")
+    tools_to_run=("antigravity" "gemini-cli" "opencode" "cursor" "aider" "windsurf" "openclaw" "qwen" "kimi" "codex")
   else
     tools_to_run=("$tool")
   fi
@@ -566,7 +605,7 @@ main() {
 
   if $use_parallel && [[ "$tool" == "all" ]]; then
     # Tools that write to separate dirs can run in parallel; buffer output so each tool's output stays together
-    local parallel_tools=(antigravity gemini-cli opencode cursor openclaw qwen)
+    local parallel_tools=(antigravity gemini-cli opencode cursor openclaw qwen codex)
     local parallel_out_dir
     parallel_out_dir="$(mktemp -d)"
     info "Converting: ${#parallel_tools[@]}/${n_tools} tools in parallel (output buffered per tool)..."
@@ -578,7 +617,7 @@ main() {
       [[ -f "$parallel_out_dir/$t" ]] && cat "$parallel_out_dir/$t"
     done
     rm -rf "$parallel_out_dir"
-    local idx=7
+    local idx=8
     for t in aider windsurf; do
       progress_bar "$idx" "$n_tools"
       printf "\n"

scripts/install.sh

@@ -20,6 +20,7 @@
 #   windsurf     -- Copy .windsurfrules to current directory
 #   openclaw     -- Copy workspaces to ~/.openclaw/agency-agents/
 #   qwen         -- Copy SubAgents to ~/.qwen/agents/ (user-wide) or .qwen/agents/ (project)
+#   codex        -- Copy custom agent TOML files to ~/.codex/agents/
 #   all          -- Install for all detected tools (default)
 #
 # Flags:
@@ -101,7 +102,7 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
 INTEGRATIONS="$REPO_ROOT/integrations"
 
-ALL_TOOLS=(claude-code copilot antigravity gemini-cli opencode openclaw cursor aider windsurf qwen kimi)
+ALL_TOOLS=(claude-code copilot antigravity gemini-cli opencode openclaw cursor aider windsurf qwen kimi codex)
 
 # Standard agent category directories (keep sorted, sync with convert.sh / lint-agents.sh)
 AGENT_DIRS=(
@@ -149,6 +150,7 @@ detect_openclaw()     { command -v openclaw >/dev/null 2>&1 || [[ -d "${HOME}/.o
 detect_windsurf()     { command -v windsurf >/dev/null 2>&1 || [[ -d "${HOME}/.codeium" ]]; }
 detect_qwen()         { command -v qwen >/dev/null 2>&1 || [[ -d "${HOME}/.qwen" ]]; }
 detect_kimi()         { command -v kimi >/dev/null 2>&1; }
+detect_codex()        { command -v codex >/dev/null 2>&1 || [[ -d "${HOME}/.codex" ]]; }
 
 is_detected() {
   case "$1" in
@@ -163,6 +165,7 @@ is_detected() {
     windsurf)    detect_windsurf    ;;
     qwen)        detect_qwen        ;;
     kimi)        detect_kimi        ;;
+    codex)       detect_codex       ;;
     *)           return 1 ;;
   esac
 }
@@ -181,6 +184,7 @@ tool_label() {
     windsurf)    printf "%-14s  %s" "Windsurf"     "(.windsurfrules)"        ;;
     qwen)        printf "%-14s  %s" "Qwen Code"    "(~/.qwen/agents)"        ;;
     kimi)        printf "%-14s  %s" "Kimi Code"    "(~/.config/kimi/agents)" ;;
+    codex)       printf "%-14s  %s" "Codex"        "(~/.codex/agents)"       ;;
   esac
 }
 
@@ -518,6 +522,20 @@ install_kimi() {
   ok "Usage: kimi --agent-file ~/.config/kimi/agents/<agent-name>/agent.yaml"
 }
 
+install_codex() {
+  local src="$INTEGRATIONS/codex/agents"
+  local dest="${HOME}/.codex/agents"
+  local count=0
+  [[ -d "$src" ]] || { err "integrations/codex missing. Run convert.sh first."; return 1; }
+  mkdir -p "$dest"
+  local f
+  while IFS= read -r -d '' f; do
+    cp "$f" "$dest/"
+    (( count++ )) || true
+  done < <(find "$src" -maxdepth 1 -name "*.toml" -print0)
+  ok "Codex: $count agents -> $dest"
+}
+
 install_tool() {
   case "$1" in
     claude-code) install_claude_code ;;
@@ -531,6 +549,7 @@ install_tool() {
     windsurf)    install_windsurf    ;;
     qwen)        install_qwen        ;;
     kimi)        install_kimi        ;;
+    codex)       install_codex       ;;
   esac
 }