A complete AI agency at your fingertips - From frontend wizards to Reddit community ninjas, from whimsy injectors to reality checkers. Each agent is a specialized expert with personality, processes, and proven deliverables.
Shell
feat: add Codex agent conversion and install support (#362)
Yunus Kılıç620a061a90d1
diff --git a/.gitignore b/.gitignoreindex 00428b40..a17eb273 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.mdindex 33e05e00..e12e10fc 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.mdindex 2dfcf361..5d1d913c 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.</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 matchingdiff --git a/integrations/README.md b/integrations/README.mdindex 60237524..5b132d24 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.mdnew file mode 100644index 00000000..8b44d468--- /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/<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+```diff --git a/scripts/convert.sh b/scripts/convert.shindex 323937de..fa6f231c 100755--- a/scripts/convert.sh+++ b/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" inantigravity) 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() {esacdone- 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=falsefor t in "${valid_tools[@]}"; do [[ "$t" == "$tool" ]] && valid=true && break; doneif ! $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")elsetools_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_dirparallel_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"donerm -rf "$parallel_out_dir"- local idx=7+ local idx=8for t in aider windsurf; doprogress_bar "$idx" "$n_tools"printf "\n"diff --git a/scripts/install.sh b/scripts/install.shindex bb293223..76cc4552 100755--- a/scripts/install.sh+++ b/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}/.odetect_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" inclaude-code) install_claude_code ;;@@ -531,6 +549,7 @@ install_tool() {windsurf) install_windsurf ;;qwen) install_qwen ;;kimi) install_kimi ;;+ codex) install_codex ;;esac}