subcodex

zippoxer's avatarfrom zippoxer

Collaborate with Codex (GPT-5.2) via named sessions. Trigger: user asks to work with Codex, use Codex, ask Codex, involve Codex, etc.CRITICAL: Use subcodex CLI via Bash, NOT the Task subagent tool.

⭐3stars🔀0forks📁View on GitHub🕐Updated Jan 9, 2026
[Developer Tools]

When & Why to Use This Skill

Subcodex is an advanced agentic skill that enables seamless collaboration between Claude and Codex (GPT-5.2) through persistent, named sessions. It is specifically designed to handle long-running, complex programming tasks by offloading execution to a background process, allowing Claude to manage high-level strategy while Codex handles direct file system modifications, code generation, and deep architectural reviews.

Use Cases

  • Executing complex, time-intensive coding tasks (up to 30+ minutes) in the background without interrupting the user's workflow.
  • Conducting high-reasoning code reviews on uncommitted changes or specific git branches to identify security vulnerabilities and over-engineering.
  • Maintaining persistent development context across multiple conversation sessions using named sessions (e.g., 'feature-migration-x7k2').
  • Implementing large-scale refactoring or new feature sets where Claude acts as the lead architect and Codex serves as the primary execution engine.
  • Automating system-level changes and script executions within a controlled, named sandbox environment.
namesubcodex
description|
Collaborate with Codex (GPT-5.2) via named sessions. Triggeruser asks to work with Codex, use Codex, ask Codex, involve Codex, etc.
CRITICALUse subcodex CLI via Bash, NOT the Task subagent tool.

subcodex

Named Codex sessions that persist across conversation compacts.

Quick Reference

# New session
./skills/subcodex/subcodex new <name> "prompt"

# Resume session
./skills/subcodex/subcodex resume <session-name> "prompt"

# List sessions (shows last 25, use --all for all)
./skills/subcodex/subcodex list

# Code review
./skills/subcodex/subcodex review --uncommitted <name>
./skills/subcodex/subcodex review --base main <name> "focus on security..."

Critical: Background Execution

ALWAYS use run_in_background: true — Codex takes 1-30+ minutes.

After starting a background command:

  1. Tell the user you're waiting for Codex
  2. Stop immediately — don't poll or check
  3. You'll be notified via <task-notification> when Codex is done

Codex Capabilities

Codex can read, write, and execute — just like you. Tell it to make changes directly, not to provide diffs or suggestions.

Options:

  • --reasoning low|medium|high|xhigh (default: high)
  • --read-only — read-only sandbox
  • --dangerous — full system access

Sessions

Session names get a random suffix: my-task becomes my-task-x7k2.

Use the full name (with suffix) when resuming:

./skills/subcodex/subcodex resume my-task-x7k2 "continue with..."

subcodex list shows: status (running/stopped), tool_calls, cwd, duration.

Code Reviews

# Review uncommitted changes
./skills/subcodex/subcodex review --uncommitted my-review

# Review against branch
./skills/subcodex/subcodex review --base main my-review

# Review specific commit
./skills/subcodex/subcodex review --commit HEAD my-review

# Add instructions
./skills/subcodex/subcodex review --uncommitted my-review "read these relevant docs first, focus on security, suggest simplifications, .."

Reviews use --reasoning xhigh and read-only mode by default.

Collaboration

Claude leads, Codex executes. Use Codex to review designs and implement complex tasks. Push back on over-engineering.

Typical flow:

  1. Claude proposes approach
  2. Codex reviews/critiques
  3. Claude decides
  4. Codex implements
  5. Claude reviews result

Push for simple code: less abstraction, fail-fast, no "just in case" code.