codex-cli-bridge

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Codex CLI Bridge Skill

Codex CLI桥接Skill

Purpose

用途

This skill creates a comprehensive bridge between Claude Code and OpenAI's Codex CLI, enabling seamless interoperability through:

Documentation Translation: Converts CLAUDE.md → AGENTS.md (reference-based, no file duplication)
Execution Helpers: Python wrappers for Codex CLI commands (always uses
```
codex exec
```
)
Skill Documentation: Makes Claude Skills accessible to Codex CLI users

本Skill在Claude Code与OpenAI Codex CLI之间搭建了全面的桥接，通过以下方式实现无缝互操作：

文档转换：将CLAUDE.md转换为AGENTS.md（基于引用，无文件重复）
执行助手：Codex CLI命令的Python包装器（始终使用
```
codex exec
```
）
Skill文档化：让Codex CLI用户也能使用Claude Skills

Key Capabilities

核心功能

1. CLAUDE.md → AGENTS.md Generation

1. CLAUDE.md → AGENTS.md生成

Parses CLAUDE.md and project structure

Scans

.claude/skills/

.claude/agents/

documentation/

folders

Generates comprehensive AGENTS.md with file path references
Reference-based: No file duplication, only links to existing files
Documents Skills with most relevant usage method (bash scripts vs prompt references)

解析CLAUDE.md和项目结构

扫描

.claude/skills/

、

.claude/agents/

、

documentation/

文件夹

生成包含文件路径引用的完整AGENTS.md
基于引用：无文件重复，仅链接至现有文件
为Skills记录最相关的使用方式（bash脚本 vs 提示词引用）

2. Safety Mechanism

2. 安全机制

Auto-checks Codex CLI installation (
```
codex --version
```
)
Auto-runs
/init
if CLAUDE.md missing (with user notification)
Validates authentication and environment
User-friendly error messages

自动检查Codex CLI安装（
```
codex --version
```
）
若CLAUDE.md缺失则自动运行
/init
（并通知用户）
验证身份认证和环境配置
友好的错误提示信息

3. Codex CLI Execution Helpers

3. Codex CLI执行助手

```
exec_analysis()
```
- Read-only analysis tasks (gpt-5, read-only sandbox)
```
exec_edit()
```
- Code editing tasks (gpt-5-codex, workspace-write)
```
exec_with_search()
```
- Web search-enabled tasks
```
resume_session()
```
- Continue last Codex session
Always uses
codex exec
(never plain
```
codex
```
- critical for Claude Code)

```
exec_analysis()
```
- 只读分析任务（gpt-5，只读沙箱）
```
exec_edit()
```
- 代码编辑任务（gpt-5-codex，可写入工作区）
```
exec_with_search()
```
- 支持网页搜索的任务
```
resume_session()
```
- 继续上一个Codex会话
始终使用
codex exec
（绝不使用纯
```
codex
```
——这对Claude Code至关重要）

4. Skill Documentation for Codex CLI

4. 面向Codex CLI用户的Skill文档

Prompt-only skills: Show how to reference in Codex prompts
Functional skills: Show how to execute Python scripts directly
Complex skills: Show both methods
Includes proper
```
codex exec
```
command syntax
Model selection guidance (gpt-5 vs gpt-5-codex)

仅提示词类Skills：展示如何在Codex提示词中引用
功能类Skills：展示如何直接执行Python脚本
复杂Skills：同时展示两种方式
包含正确的
```
codex exec
```
命令语法
模型选择指导（gpt-5 vs gpt-5-codex）

Input Requirements

输入要求

For AGENTS.md Generation

生成AGENTS.md时

json

{
  "action": "generate-agents-md",
  "project_root": "/path/to/project",
  "options": {
    "validate_codex": true,
    "auto_init": true,
    "include_mcp": true,
    "skill_detail_level": "relevant"
  }
}

json

{
  "action": "generate-agents-md",
  "project_root": "/path/to/project",
  "options": {
    "validate_codex": true,
    "auto_init": true,
    "include_mcp": true,
    "skill_detail_level": "relevant"
  }
}

For Codex Execution

执行Codex任务时

json

{
  "action": "codex-exec",
  "task_type": "analysis|edit|search",
  "prompt": "Your task description",
  "model": "gpt-5|gpt-5-codex",
  "sandbox": "read-only|workspace-write|danger-full-access"
}

json

{
  "action": "codex-exec",
  "task_type": "analysis|edit|search",
  "prompt": "Your task description",
  "model": "gpt-5|gpt-5-codex",
  "sandbox": "read-only|workspace-write|danger-full-access"
}

Output Formats

输出格式

AGENTS.md Structure

AGENTS.md结构

markdown

undefined

markdown

undefined

AGENTS.md

Project Overview

项目概述

[From CLAUDE.md]

[来自CLAUDE.md]

Available Skills

可用Skills

Skill Name

Skill名称

Location:

path/to/skill/

Using from Codex CLI: [Most relevant method]

位置：

path/to/skill/

在Codex CLI中使用：[最相关的方法]

Workflow Patterns

工作流模式

[Slash commands → Codex equivalents]

[斜杠命令 → Codex等效命令]

MCP Integration

MCP集成

[MCP server references]

[MCP服务器引用]

Command Reference

命令对照表

Claude Code	Codex CLI
[Mappings]

undefined

Claude Code	Codex CLI
[映射关系]

undefined

Execution Helper Output

执行助手输出

python

{
  "status": "success|error",
  "output": "Command output",
  "session_id": "uuid",
  "model_used": "gpt-5|gpt-5-codex",
  "command": "codex exec ..."
}

python

{
  "status": "success|error",
  "output": "Command output",
  "session_id": "uuid",
  "model_used": "gpt-5|gpt-5-codex",
  "command": "codex exec ..."
}

Python Scripts

Python脚本

safety_mechanism.py

Check Codex CLI installation
Validate CLAUDE.md exists (auto-run /init if missing)
Environment validation
User notifications

检查Codex CLI安装情况
验证CLAUDE.md是否存在（若缺失则自动运行/init）
环境配置验证
用户通知

claude_parser.py

Parse CLAUDE.md sections
Scan skills, agents, commands
Extract quality gates and MCP configuration
Return file paths only (no content duplication)

解析CLAUDE.md的各个章节
扫描Skills、Agents、命令
提取质量门限和MCP配置
仅返回文件路径（无内容重复）

project_analyzer.py

Auto-detect project structure
Discover all Claude Code assets
Generate project metadata
Build reference map

自动检测项目结构
发现所有Claude Code资产
生成项目元数据
构建引用映射

agents_md_generator.py

Template-based AGENTS.md generation
File path references (no duplication)
Skill documentation (most relevant method)
Workflow translation (Claude → Codex)

基于模板生成AGENTS.md
文件路径引用（无重复）
Skill文档（最相关的使用方法）
工作流转换（Claude → Codex）

skill_documenter.py

Document skills for Codex CLI users
Determine most relevant usage method per skill type
Generate bash examples for Python scripts
Create Codex prompt templates

为Codex CLI用户编写Skill文档
为每种Skill类型确定最相关的使用方法
为Python脚本生成bash示例
创建Codex提示词模板

codex_executor.py

Python wrappers for Codex CLI commands
Intelligent model selection (gpt-5 vs gpt-5-codex)
Sandbox mode helpers
Session management
Always uses
codex exec

Codex CLI命令的Python包装器
智能模型选择（gpt-5 vs gpt-5-codex）
沙箱模式助手
会话管理
始终使用
codex exec

Usage Examples

使用示例

Example 1: Generate AGENTS.md

示例1：生成AGENTS.md

User prompt:

Generate AGENTS.md for this project

What happens:

Safety mechanism checks Codex CLI installed
Checks CLAUDE.md exists (auto-runs /init if missing)
Parses CLAUDE.md and project structure
Generates AGENTS.md with file references
Documents all skills with most relevant usage method

Output: Complete AGENTS.md file in project root

用户提示词：

Generate AGENTS.md for this project

执行流程：

安全机制检查Codex CLI是否已安装
检查CLAUDE.md是否存在（若缺失则自动运行/init）
解析CLAUDE.md和项目结构
生成包含文件引用的AGENTS.md
为所有Skills记录最相关的使用方法

输出：项目根目录下的完整AGENTS.md文件

Example 2: Execute Codex Analysis Task

示例2：执行Codex分析任务

User prompt:

Use Codex to analyze this codebase for security vulnerabilities

What happens:

python

from codex_executor import CodexExecutor

executor = CodexExecutor()
result = executor.exec_analysis(
    "Analyze this codebase for security vulnerabilities",
    model="gpt-5"
)

Executes:

bash

codex exec -m gpt-5 -s read-only \
  -c model_reasoning_effort=high \
  "Analyze this codebase for security vulnerabilities"

用户提示词：

Use Codex to analyze this codebase for security vulnerabilities

执行过程：

python

from codex_executor import CodexExecutor

executor = CodexExecutor()
result = executor.exec_analysis(
    "Analyze this codebase for security vulnerabilities",
    model="gpt-5"
)

实际执行命令：

bash

codex exec -m gpt-5 -s read-only \
  -c model_reasoning_effort=high \
  "Analyze this codebase for security vulnerabilities"

Example 3: Execute Codex Code Editing

示例3：执行Codex代码编辑

User prompt:

Use Codex to refactor main.py for better async patterns

What happens:

python

executor = CodexExecutor()
result = executor.exec_edit(
    "Refactor main.py for better async patterns",
    model="gpt-5-codex"
)

Executes:

bash

codex exec -m gpt-5-codex -s workspace-write \
  -c model_reasoning_effort=high \
  "Refactor main.py for better async patterns"

用户提示词：

Use Codex to refactor main.py for better async patterns

执行过程：

python

executor = CodexExecutor()
result = executor.exec_edit(
    "Refactor main.py for better async patterns",
    model="gpt-5-codex"
)

实际执行命令：

bash

codex exec -m gpt-5-codex -s workspace-write \
  -c model_reasoning_effort=high \
  "Refactor main.py for better async patterns"

Example 4: Resume Codex Session

示例4：恢复Codex会话

User prompt:

Continue the previous Codex session

What happens:

python

executor = CodexExecutor()
result = executor.resume_session()

Executes:

bash

codex exec resume --last

用户提示词：

Continue the previous Codex session

执行过程：

python

executor = CodexExecutor()
result = executor.resume_session()

实际执行命令：

bash

codex exec resume --last

Best Practices

最佳实践

For AGENTS.md Generation

AGENTS.md生成

Always run on projects with CLAUDE.md (or let auto-init create it)
Validate Codex CLI installed first
Keep skills documented with most relevant method (bash vs prompt)
Use reference-based approach (no file duplication)

仅在包含CLAUDE.md的项目上运行（或让自动初始化功能创建它）
先验证Codex CLI已安装
为Skills记录最相关的使用方法（bash vs 提示词）
使用基于引用的方式（无文件重复）

For Codex Execution

Codex任务执行

Use
codex exec
always (never plain
```
codex
```
in Claude Code)
Choose correct model:
- ```
gpt-5
```
  : General reasoning, architecture, analysis
- ```
gpt-5-codex
```
  : Code editing, specialized coding tasks
Choose correct sandbox:
- ```
read-only
```
  : Safe analysis (default)
- ```
workspace-write
```
  : File modifications
- ```
danger-full-access
```
  : Network access (rarely needed)
Enable search when needed (
```
--search
```
flag)

始终使用
codex exec
（在Claude Code中绝不使用纯
```
codex
```
）
选择正确的模型：
- ```
gpt-5
```
  ：通用推理、架构设计、分析任务
- ```
gpt-5-codex
```
  ：代码编辑、专业编码任务
选择正确的沙箱模式：
- ```
read-only
```
  ：安全分析（默认）
- ```
workspace-write
```
  ：文件修改
- ```
danger-full-access
```
  ：网络访问（极少需要）
必要时启用搜索（
```
--search
```
参数）

For Skill Documentation

Skill文档编写

Prompt-only skills: Reference in Codex prompts
Functional skills: Execute Python scripts directly
Complex skills: Show both methods
Always provide working examples

仅提示词类Skills：在Codex提示词中引用
功能类Skills：直接执行Python脚本
复杂Skills：同时展示两种方法
始终提供可运行的示例

Command Integration

命令集成

This skill integrates with existing Claude Code commands:

/init
: Auto-generates AGENTS.md after CLAUDE.md creation
/update-claude
: Regenerates AGENTS.md when CLAUDE.md changes
/check-docs
: Validates AGENTS.md exists and is in sync
/sync-agents-md
: Manual AGENTS.md regeneration
/codex-exec <task>
: Wrapper using codex_executor.py

本Skill与现有Claude Code命令集成：

/init
：创建CLAUDE.md后自动生成AGENTS.md
/update-claude
：当CLAUDE.md更新时重新生成AGENTS.md
/check-docs
：验证AGENTS.md是否存在且内容同步
/sync-agents-md
：手动重新生成AGENTS.md
/codex-exec <task>
：使用codex_executor.py的包装器

Installation

安装

Prerequisites

前置条件

Codex CLI installed:

bash

codex --version  # Should show v0.48.0 or higher

Codex authenticated:
bash
```
codex login
```
Claude Code v1.0+

已安装Codex CLI：

bash

codex --version  # 应显示v0.48.0或更高版本

已完成Codex身份认证：
bash
```
codex login
```
Claude Code v1.0+

Install Skill

安装Skill

Option 1: Copy to project

bash

cp -r generated-skills/codex-cli-bridge ~/.claude/skills/

Option 2: Use from this repository

bash

undefined

选项1：复制到项目中

bash

cp -r generated-skills/codex-cli-bridge ~/.claude/skills/

选项2：直接使用本仓库

bash

undefined

Skill auto-discovered when Claude Code loads this project

当Claude Code加载本项目时会自动发现该Skill

undefined

undefined

Troubleshooting

故障排除

Error: "Codex CLI not found"

错误："Codex CLI not found"

Solution: Install Codex CLI and ensure it's in PATH

bash

which codex  # Should return path
codex --version  # Should work

解决方案：安装Codex CLI并确保其在PATH中

bash

which codex  # 应返回路径
codex --version  # 应能正常运行

Error: "CLAUDE.md not found"

错误："CLAUDE.md not found"

Solution: Skill auto-runs

/init

with notification. If it fails:

bash

undefined

解决方案：Skill会自动运行

/init

并通知用户。若失败则手动执行：

bash

undefined

Manually run /init

手动运行/init

/init

undefined

/init

undefined

Error: "stdout is not a terminal"

错误："stdout is not a terminal"

Solution: Always use

codex exec

, never plain

codex

bash

❌ codex -m gpt-5 "task"
✅ codex exec -m gpt-5 "task"

解决方案：始终使用

codex exec

，绝不使用纯

codex

bash

❌ codex -m gpt-5 "task"
✅ codex exec -m gpt-5 "task"

AGENTS.md Out of Sync

AGENTS.md内容不同步

Solution: Regenerate manually

bash

/sync-agents-md

解决方案：手动重新生成

bash

/sync-agents-md

References

参考资料

Codex CLI Docs:
```
openai-codex-cli-instructions.md
```
Claude Skills Docs:
```
claude-skills-instructions.md
```

Example Skills:

claude-skills-examples/codex-cli-skill.md

AGENTS.md Spec: https://agents.md/

Codex CLI文档：
```
openai-codex-cli-instructions.md
```
Claude Skills文档：
```
claude-skills-instructions.md
```

示例Skills：

claude-skills-examples/codex-cli-skill.md

AGENTS.md规范：https://agents.md/

Version

版本

v1.0.0 - Initial release (2025-10-30)

v1.0.0 - 初始版本（2025-10-30）

License

许可证

Apache 2.0

Created by: Claude Code Skills Factory Maintained for: Cross-tool team collaboration (Claude Code ↔ Codex CLI) Sync Status: Reference-based bridge (one-way sync: CLAUDE.md → AGENTS.md)

Apache 2.0

创建者：Claude Code Skills Factory 维护目标：跨工具团队协作（Claude Code ↔ Codex CLI） 同步状态：基于引用的桥接（单向同步：CLAUDE.md → AGENTS.md）