Skip to main content
skill CX Codex

collaborating-with-codex — Claude Code skill: what it does, install

collaborating-with-codex is a Claude Code skill that sends bounded coding tasks to a separate local or SSH-based Codex CLI session. Claude Code retains final edits and verification.

MIT ★ 475 updated 2026-10-13

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add cnfjlhj/ai-collab-playbook --skill collaborating-with-codex -a claude-code
Open on GitHub

What collaborating-with-codex does

The skill calls Codex CLI through scripts/codex_bridge.py. Delegate a prototype, a debugging task, or a code review, then use the returned JSON, which includes a session ID and agent messages. Your Claude Code session keeps control of scope, synthesis, final edits, and verification.

Pass the first response’s SESSION_ID to continue a session. For remote work, SSH must connect without an interactive prompt; the host needs codex and a POSIX-compatible shell. With SSH enabled, --cd and --image refer to paths on the remote host. The default sandbox is read-only, so tasks that need to modify files require a different sandbox setting.

What it helps with

  • delegate a prototype and request a diff
  • send a debugging task to a separate Codex session
  • get a review while retaining control of final edits
  • resume work with a SESSION_ID
  • run Codex against a project over SSH

Example prompts for the agent

  • Review this code and return notes without editing the files.
  • Diagnose the failing test and suggest a patch.
  • Connect to server-alias and inspect the remote project for test failures.

How to install collaborating-with-codex

1Skills CLI (Vercel)

npx skills add cnfjlhj/ai-collab-playbook --skill collaborating-with-codex -a claude-code

2Manually: put the files in place

~/.claude/skills/collaborating-with-codex/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/collaborating-with-codex/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about collaborating-with-codex

How do I install collaborating-with-codex in Claude Code?

Run npx skills add cnfjlhj/ai-collab-playbook --skill collaborating-with-codex -a claude-code. The skill file is at ~/.claude/skills/collaborating-with-codex/SKILL.md.

What does collaborating-with-codex do?

It starts a separate Codex CLI session for prototyping, debugging, or code review. The current Claude Code session remains in charge of the final result.

Can I resume a Codex session over SSH?

Yes. Pass the SESSION_ID and reconnect to the same SSH host. The remote machine needs codex and a POSIX-compatible shell.

Source text

SKILL.md · MIT
---
name: collaborating-with-codex
description: Use when you explicitly want a second local or SSH remote Codex CLI session to prototype, debug, or review code, while your current session remains the primary owner of the final result.
---

## Quick Start

```bash
python scripts/codex_bridge.py --cd "/path/to/project" --PROMPT "Your task"
```

Remote Codex over SSH:

```bash
python scripts/codex_bridge.py --ssh "server-alias" --cd "/remote/project" --PROMPT "Your task"
```

**Output:** JSON with `success`, `SESSION_ID`, `agent_messages`, and optional `error`.

## Collaboration Rules

- Keep the current session responsible for scope, synthesis, final edits, and verification.
- Delegate a bounded task with a concrete output contract such as a diff, diagnosis, or review note.
- Avoid overlapping write scope between sessions unless the second session is review-only.
- Start with read-only access; expand the sandbox only when the delegated task requires it.
- Do not set model or profile overrides unless the user explicitly asked for them.

## Parameters

```
usage: codex_bridge.py [-h] --PROMPT PROMPT --cd CD [--sandbox {read-only,workspace-write,danger-full-access}] [--SESSION_ID SESSION_ID] [--skip-git-repo-check]
                       [--return-all-messages] [--image IMAGE] [--model MODEL] [--yolo] [--profile PROFILE] [--ssh SSH] [--ssh-option SSH_OPTION]
                       [--codex-bin CODEX_BIN]

Codex Bridge

options:
  -h, --help            show this help message and exit
  --PROMPT PROMPT       Instruction for the task to send to codex.
  --cd CD               Set the workspace root for codex before executing the task.
  --sandbox {read-only,workspace-write,danger-full-access}
                        Sandbox policy for model-generated commands. Defaults to `read-only`.
  --SESSION_ID SESSION_ID
                        Resume the specified session of the codex. Defaults to `None`, start a new session.
  --skip-git-repo-check
                        Allow codex running outside a Git repository (useful for one-off directories).
  --return-all-messages
                        Return all messages (e.g. reasoning, tool calls, etc.) from the codex session. Set to `False` by default, only the agent's final reply message is
                        returned.
  --image IMAGE         Attach one or more image files to the initial prompt. Separate multiple paths with commas or repeat the flag.
  --model MODEL         The model to use for the codex session. This parameter is strictly prohibited unless explicitly specified by the user.
  --yolo                Run every command without approvals or sandboxing. Only use when `sandbox` couldn't be applied.
  --profile PROFILE     Configuration profile name to load from `~/.codex/config.toml`. This parameter is strictly prohibited unless explicitly specified by the user.
  --ssh SSH             Run Codex on a remote host via SSH. Value can be an SSH alias or user@host. When set, --cd and --image paths are remote paths.
  --ssh-option SSH_OPTION
                        Extra ssh option, repeatable. Example: --ssh-option=-J --ssh-option=bastion
  --codex-bin CODEX_BIN
                        Codex executable to run locally or on the remote host. Defaults to `codex`. `--remote-codex` is accepted as a backward-compatible alias.
```

## Multi-turn Sessions

**Always capture `SESSION_ID`** from the first response for follow-up:

```bash
# Initial task
python scripts/codex_bridge.py --cd "/project" --PROMPT "Analyze auth in login.py"

# Continue with SESSION_ID
python scripts/codex_bridge.py --cd "/project" --SESSION_ID "uuid-from-response" --PROMPT "Write unit tests for that"
```

Remote sessions use the same `SESSION_ID`, but continue them against the same SSH host:

```bash
python scripts/codex_bridge.py --ssh "server-alias" --cd "/remote/project" --SESSION_ID "uuid-from-response" --PROMPT "Now implement it"
```

## SSH Remote Codex

Use `--ssh` when the repository, runtime, or credentials needed for the task live on a remote server.

Requirements:
- Local machine can run `ssh <host>` non-interactively.
- Remote host has `codex` installed and available in the remote non-interactive shell `PATH`, or pass `--codex-bin "/absolute/path/to/codex"`.
- The remote host should use a POSIX-compatible shell for command quoting.
- `--cd` is a remote absolute path when `--ssh` is set.
- `--image` paths are also remote paths when `--ssh` is set. Upload local images first if Codex on the server needs them.

Examples:

```bash
# Use an SSH config alias
python scripts/codex_bridge.py --ssh "gpu-box" --cd "/srv/app" --PROMPT "Review this service for race conditions"

# Use user@host and a remote codex path
python scripts/codex_bridge.py --ssh "[email protected]" --codex-bin "/home/ubuntu/.local/bin/codex" --cd "/home/ubuntu/app" --PROMPT "Run the failing tests and diagnose"

# Use a jump host
python scripts/codex_bridge.py --ssh "private-box" --ssh-option=-J --ssh-option=bastion --cd "/workspace/repo" --PROMPT "Inspect the deployment scripts"
```

Do not use `--ssh` for local repositories. Do not pass `--model` or `--profile` unless the user explicitly requested them.

## Common Patterns

**Prototyping (read-only, request diffs):**
```bash
python scripts/codex_bridge.py --cd "/project" --PROMPT "Generate unified diff to add logging"
```

**Debug with full trace:**
```bash
python scripts/codex_bridge.py --cd "/project" --PROMPT "Debug this error" --return-all-messages
```

**Remote debug with write access:**
```bash
python scripts/codex_bridge.py --ssh "server-alias" --cd "/remote/project" --sandbox workspace-write --PROMPT "Fix the failing integration test and summarize the patch"
```

© cnfjlhj · MIT · cnfjlhj/ai-collab-playbook

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set18

The whole set →
论文精读 论文精读 is a Claude Code prompt for reading English academic papers paragraph by paragraph, preserving the original text and providing a scholarly Chinese translation and analytical commentary. GP ChatGPT ★ 475repo stars research-lead-sidecar The research-lead-sidecar skill keeps the lead agent on the critical path while bounded side tasks go to subagents. Use it for research-led work where the lead still needs to own the final decisions. CX Codex +1 ★ 475repo stars spec-first-mvp The spec-first-mvp skill stops development before implementation and requires a short spec, a list of throwaway probes, and a go/no-go decision point. CX Codex +1 ★ 475repo stars collaborating-with-gemini collaborating-with-gemini connects Gemini CLI as a second opinion for diff inspection, bug analysis, and prototyping via a Python bridge. CX Codex +1 ★ 475repo stars question-refiner question-refiner transforms a vague research question into a structured deep-research brief. Asks clarifying questions, collects requirements for format, sources and scope, then generates a ready-to-use prompt. CX Codex +1 ★ 475repo stars collaborating-with-claude collaborating-with-claude consults Claude Code CLI as an advisor for diff reviews and tradeoffs while your primary agent builds. CX Codex +1 ★ 475repo stars paper-review-pipeline paper-review-pipeline is a Claude Code skill that reviews near-final ML conference papers section by section, prioritizes issues from P0 to P2, and drafts rebuttal responses. CX Codex +1 ★ 475repo stars paper2html paper2html converts academic papers from arXiv, LaTeX or PDF into self-contained Chinese reading pages with KaTeX math and verified evidence. CX Codex +1 ★ 475repo stars

Project sponsors

Companies that keep this analytics open