From 620a061a90d100b57f958980e7bc37d533cd798b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yunus=20K=C4=B1l=C4=B1=C3=A7?= Date: Thu, 4 Jun 2026 01:59:48 +0200 Subject: [PATCH] feat: add Codex agent conversion and install support (#362) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds Codex as a conversion/install target: each agent → `~/.codex/agents/.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 | 1 + CONTRIBUTING.md | 2 + README.md | 29 +++++++++++-- integrations/README.md | 19 +++++++++ integrations/codex/README.md | 79 ++++++++++++++++++++++++++++++++++++ scripts/convert.sh | 47 +++++++++++++++++++-- scripts/install.sh | 21 +++++++++- 7 files changed, 190 insertions(+), 8 deletions(-) create mode 100644 integrations/codex/README.md diff --git a/.gitignore b/.gitignore index 00428b4..a17eb27 100644 --- a/.gitignore +++ b/.gitignore @@ -78,3 +78,4 @@ integrations/qwen/agents/ integrations/kimi/*/ !integrations/openclaw/README.md !integrations/kimi/README.md +integrations/codex/agents/* diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 33e05e0..e12e10f 100644 --- a/CONTRIBUTING.md +++ b/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**: diff --git a/README.md b/README.md index 2dfcf36..5d1d913 100644 --- a/README.md +++ b/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. +
+Codex + +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. +
+ --- ### 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 diff --git a/integrations/README.md b/integrations/README.md index 6023752..5b132d2 100644 --- a/integrations/README.md +++ b/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. diff --git a/integrations/codex/README.md b/integrations/codex/README.md new file mode 100644 index 0000000..8b44d46 --- /dev/null +++ b/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/.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 +``` diff --git a/scripts/convert.sh b/scripts/convert.sh index 323937d..fa6f231 100755 --- a/scripts/convert.sh +++ b/scripts/convert.sh @@ -19,6 +19,7 @@ # openclaw — OpenClaw workspaces (integrations/openclaw//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// 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" </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.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 }