Skip to main content
The Codex converter creates prompts and skills from Claude Code plugins, with TOML configuration for MCP servers.

​
Installation

bunx @every-env/compound-plugin install compound-engineering --to codex

​
Output Structure

Writes to ~/.codex/: 
~/.codex/
├── prompts/
│   └── *.md              # Command prompts
├── skills/
│   ├── agent-name/
│   │   └── SKILL.md      # Agent converted to skill
│   ├── command-name/
│   │   └── SKILL.md      # Command converted to skill
│   └── existing-skill/   # Pass-through skills
└── config.toml           # MCP server config
Each command becomes both a prompt (in prompts/) and a skill (in skills/). The prompt delegates to the skill.

​
Conversion Details

​
Commands → Prompts + Skills

Every command generates two files: Prompt (~/.codex/prompts/command-name.md): 
---
description: Turn feature ideas into detailed plans
argument-hint: <feature description>
---

Use the $command-name skill for this command and follow its instructions.

Original command body here...
Skill (~/.codex/skills/command-name/SKILL.md): 
---
name: command-name
description: Turn feature ideas into detailed plans
---

## Arguments
<feature description>

## Allowed tools
- Read
- Write
- Bash

Original command body here...

​
Agents → Skills

Agents are converted to skills: 
---
name: plan-specialist
description: Planning agent for complex features
---

## Capabilities
- Break down complex features
- Identify dependencies
- Create detailed plans

You are a planning specialist...

​
Content Transformation

The converter rewrites Claude-specific syntax: Task agent calls: 
- Task repo-research-analyst(feature_description)
+ Use the $repo-research-analyst skill to: feature_description
Slash commands: 
- Run /workflows:plan to create a plan
+ Run /prompts:workflows-plan to create a plan
Agent references: 
- Consult @code-review-agent for feedback
+ Consult $code-review-agent skill for feedback
Path rewriting: 
- ~/.claude/skills/
+ ~/.codex/skills/

​
Description Truncation

Codex has a 1024 character limit for descriptions: 
// Long descriptions are truncated with ellipsis
const description = "This is a very long description...".slice(0, 1021) + "..."
If a description exceeds 1024 characters, it will be truncated with ... appended.

​
MCP Servers

MCP servers are written to ~/.codex/config.toml: 
# Generated by compound-plugin

[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem"]

[mcp_servers.filesystem.env]
ALLOWED_PATHS = "/Users/you/projects"

[mcp_servers.remote-api]
url = "https://api.example.com/mcp"
http_headers = { Authorization = "Bearer ${TOKEN}" }
Supports both stdio (command-based) and remote (HTTP/SSE) servers.
Existing config.toml content is preserved. The converter only adds/updates MCP server blocks.

​
Name Normalization

Command and skill names are normalized:
InputOutput
workflows:planworkflows-plan
Plan Reviewplan-review
my/commandmy-command
UPPERCASEuppercase
Rules:
  • Lowercase only
  • Colons, slashes, spaces → hyphens
  • Special characters removed
  • Multiple hyphens collapsed

​
Deduplication

If a name collision occurs, a suffix is added: 
plan
plan-2
plan-3

​
Tool Name Mapping

Claude tool names are mapped to Codex equivalents:
ClaudeCodex
Bashbash
Readread
Writewrite
Editedit
Grepgrep
Globglob
WebFetchwebfetch
Tasktask

​
Example Output

Input (Claude command): 
{
  "name": "workflows:plan",
  "description": "Create implementation plan",
  "argumentHint": "<feature description>",
  "allowedTools": ["Read", "Write"],
  "body": "You are a planning agent. Task repo-research-analyst(research the feature)."
}
Output (~/.codex/prompts/workflows-plan.md): 
---
description: Create implementation plan
argument-hint: <feature description>
---

Use the $workflows-plan skill for this command and follow its instructions.

You are a planning agent. Use the $repo-research-analyst skill to: research the feature.
Output (~/.codex/skills/workflows-plan/SKILL.md): 
---
name: workflows-plan
description: Create implementation plan
---

## Arguments
<feature description>

## Allowed tools
- Read
- Write

You are a planning agent. Use the $repo-research-analyst skill to: research the feature.

​
Limitations

  • Descriptions are truncated at 1024 characters
  • No hooks support (Codex doesn’t have a hooks equivalent)
  • Commands with disableModelInvocation: true are skipped
  • Model field is not included (Codex uses global model config)

​
Sync Support

Use the sync command to sync personal Claude config: 
bunx @every-env/compound-plugin sync --target codex
This syncs:
  • Personal skills from ~/.claude/skills/ (as symlinks)
  • Personal commands from ~/.claude/commands/ (as prompts)
  • MCP servers from ~/.claude/settings.json (merged into config.toml)

​
See Also

Codex Documentation

Official Codex documentation

Sync Command

Sync personal Claude config to Codex