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
}