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.
2026-06-09 10:13:17 +00:00 · 2026-06-04 01:59:48 +02:00
parent ab414934e3
commit 620a061a90
7 changed files with 190 additions and 8 deletions
@@ -78,3 +78,4 @@ integrations/qwen/agents/
 integrations/kimi/*/
 !integrations/openclaw/README.md
 !integrations/kimi/README.md
+integrations/codex/agents/*
@@ -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**:
@@ -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
@@ -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.
@@ -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
+```
@@ -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"
@@ -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
 }