codex-collab

Codex Collaboration Skill

Core Philosophy

In any coding process, always consider whether the current task can leverage codex to obtain a more comprehensive and more objective analysis. Claude is responsible for architecture design and overall control, while Codex is responsible for code generation details and an independent review perspective—two independent reasoning paths cross-validate each other, exposing the blind spots of a single perspective.

Prerequisites

• Python 3.12+
• Codex CLI Installed and codex command available (version >= v0.61.0)

Invoke Codex

Execute the built-in script via Bash scripts/codex_exec.py, the script path is relative to the directory where this SKILL.md is located.

python <skill-dir>/scripts/codex_exec.py \
  --prompt "你的指令" \
  --cd /path/to/repo \
  [--sandbox read-only] \
  [--session-id <uuid>] \
  [--all-messages]

Parameter

Parameter	Required	Default Value	Description
--prompt	Yes	-	The task instruction sent to codex
--cd	Yes	-	Root path of the working directory (must exist, otherwise it fails silently)
--sandbox	No	read-only	read-only / workspace-write / danger-full-access
--session-id	No	Empty (new session)	Pass in the session_id returned last time to continue the conversation
--all-messages	No	false	Include the complete reasoning process (used to trace codex's reasoning and tool calls)
--model	No	Empty	Use only when explicitly specified by the user
--profile	No	Empty	Use only when explicitly specified by the user
--yolo	No	false	Skip the sandbox, use with caution
--image	No	Empty	Comma-separated image paths

Security Constraints

Use by default and recommended --sandbox read-only. Codex is strictly forbidden from making actual modifications to the code—when code is needed, only have it provide a unified diff patch. This is the safety cornerstone of the entire collaboration mode: codex provides ideas, and you execute them.

Return Value

The script outputs JSON to stdout:

{"success": true, "session_id": "uuid-string", "agent_messages": "codex 的回复"}

{"success": false, "error": "错误描述"}

After each call, check the success field for error handling.

Session Management

Each successful call returns session_id. Maintain a variable in the conversation CODEX_SESSION_ID：

• First call: do not pass --session-id, extract and remember from the return value session_id
• Subsequent calls: pass in --session-id <CODEX_SESSION_ID> to continue the context
• When switching to an unrelated new task: discard the old session_id and start a new session

Always track CODEX_SESSION_ID, to avoid session confusion.

Collaboration Workflow

1. Requirements Analysis — Let codex fill in your blind spots

After forming a preliminary analysis of the user's requirements, inform codex of the requirements and initial ideas, and ask it to refine the requirements analysis and implementation plan.

Example prompt:

用户需求：{需求描述}

我的初步分析：{你的分析}

请从以下角度补充：
1. 我的分析是否有遗漏的边界情况？
2. 实施计划是否合理？有什么更优方案？
3. 有哪些潜在风险？

2. Plan Review — Let codex review the implementation plan

After generating a plan in plan mode, you can have codex review it from an independent perspective. Codex runs in an independent process and cannot access your conversation context, so the prompt sent to codex must embed the complete plan content, you cannot just say "please review the current plan.".

Steps to build the prompt:

1. Extract the complete plan text from the current conversation context
2. Embed the plan text into the prompt and send it together with the project background
3. Explicitly request from which angles codex should review

Example prompt:

请审查以下实施计划，给出你的评估和改进建议。

## 项目背景
{项目简要描述和当前需求}

## 实施计划
{完整的 plan 内容，逐条列出}

## 审查要点
1. 步骤顺序是否合理？是否有依赖关系被忽略？
2. 是否有遗漏的关键步骤？
3. 各步骤的技术方案是否恰当？有无更优选择？
4. 是否存在潜在的风险或副作用？
5. 预估的改动范围是否准确？

After codex responds, critically evaluate its feedback; update reasonable suggestions into the plan, and ignore unreasonable ones with stated reasons.

3. Code prototype — use codex's implementation as a reference (optional)

Before coding, ask codex for a code implementation prototype. This is not "letting codex write code and then using it directly"; rather, it is obtaining an independent implementation approach, and then rewriting it yourself as production-grade code.

• Require codex to provide only a unified diff patch, and strictly forbid any actual modification to the code
• Use --sandbox read-only to ensure safety
• After obtaining the prototype, use it as a logical reference and rewrite it into production code with high readability and maintainability

Example prompt:

请为以下需求给出代码实现原型，仅输出 unified diff patch，不要做任何真实修改：

{需求描述}

涉及文件：{文件列表}

4. Code review — execute immediately after coding is complete

After completing coding each time, immediately have codex review the changes. An independent AI review perspective can catch issues you might not easily find yourself.

Execute the built-in wrapper script via Bash scripts/codex_review.py to call codex review. The script automatically filters out the 2000+ lines of tool logs and intermediate reasoning in codex output, returning only the review summary and the "Full review comments" block. Review standards refer to references/review_guidelines.md。

codex review usually takes 2-5 minutes. When calling it, be sure to set the Bash timeout to 300000 (5 minutes) to avoid it being automatically converted into a background task.

Common commands:

# 审查未提交改动（staged + unstaged + untracked）
python <skill-dir>/scripts/codex_review.py --uncommitted

# 审查未提交改动，附加自定义审查要求
python <skill-dir>/scripts/codex_review.py --uncommitted "只关注安全性和并发问题"

# 审查相对于某分支的改动
python <skill-dir>/scripts/codex_review.py --base main

# 审查某次提交
python <skill-dir>/scripts/codex_review.py --commit <sha>

All parameters are passed through directly to codex review, and custom review requirements can be passed in via the prompt parameter.

codex review vs codex exec and

• codex review(called via scripts/codex_review.py ) is a dedicated review command, automatically obtains the diff content, and its output is already filtered
• codex review does not return session_id, and does not support multi-turn conversations
• When multi-turn discussion of review feedback is needed, still use codex exec(via codex_exec.py script) to continue the conversation

Continue the review discussion:

After obtaining the review results, if you need to ask follow-up questions about details, use codex_exec.py to start a new session and embed the review conclusions into the prompt:

以下是 codex review 对本次改动的审查意见：

{粘贴 review 输出}

我想针对以下问题深入讨论：
{具体问题}

5. Independent thinking — believing everything in books is worse than having no books at all

codex can only provide references; you must have your own judgment, and even need to question codex's answers. Your ultimate mission with codex is to reach comprehensive and precise opinions, so you must keep arguing to approach a better solution:

• Critically evaluate every suggestion — it may have missed context, or it may be overly cautious
• If you disagree, explain why, and send your rebuttal back to codex to continue the discussion (use session_id to maintain context)
• The final decision-making power is yours

When to proactively suggest using Codex

You do not need to wait for the user to speak. In the following scenarios you should proactively propose it:

• Complex architecture decisions: changes involving multiple modules, API design, data model changes
• Plan review: after completing a plan in plan mode, suggest having codex review the completeness of the steps and the technical approach
• Review after coding is complete: any code change exceeding 50 lines is worth having codex take a look
• Data-intensive scripts: files containing large amounts of hardcoded data, statistics, or test fixtures—humans easily become desensitized to numbers, but AI does not
• Tricky bugs: when troubleshooting alone yields no results, have codex analyze from different angles
• Precisely pinpoint the problem: when you need to quickly narrow down the troubleshooting scope
• Quickly obtain code prototypes: when you need to choose among multiple implementation options

When proactively suggesting, briefly explain the reason, for example: "This change involves coordination across 3 modules; I suggest having codex review it from another angle. Want to give it a try?"

Error handling

• If the script returns success: false, check the error field and inform the user
• Common issues: codex CLI not installed, API key not configured, network timeout
• When encountering session_id failure to obtain, do not retry the same session; directly start a new session