codex

Codex Companion

Fork of openai/codex-plugin-cc that keeps the original Claude Code plugin sources while adding a host-neutral standalone package under skills/codex-companion/.

This repository now serves two related purposes:

• preserve and sync the original Claude-oriented plugin implementation under plugins/codex/
• develop and ship the more general codex-companion skill for arbitrary agent hosts

Repository Layout

Path	Purpose
skills/codex-companion/	Host-neutral standalone skill package and its self-contained tests
plugins/codex/	Original Claude Code plugin source material kept for upstream sync and comparison
tests/	Repository-level regression coverage, including compatibility entrypoints

Which Path To Use

Generic agent hosts

Use skills/codex-companion/README.md and skills/codex-companion/SKILL.md.

That package exposes one stable wrapper surface:

node <skill-root>/scripts/codex-host.mjs <subcommand> ...

It supports:

• setup
• review
• adversarial-review
• task
• task-resume-candidate
• status
• progress
• watch
• result
• cancel

Claude Code compatibility or upstream comparison

Use the material under plugins/codex/. That path remains in the repository so upstream changes can be reviewed, ported, or compared against the standalone skill.

Recommended Entry Point

For new integrations, prefer the standalone package in skills/codex-companion/.

The design direction of this fork is:

• keep Codex workflow semantics
• remove Claude-specific packaging assumptions from the main integration path
• preserve strong observation for long-running Codex work through status, progress, watch, and callbacks

Model Configuration

Codex Companion leaves the model and reasoning effort unset unless the caller passes --model or --effort. The local Codex runtime therefore keeps ownership of defaults through ~/.codex/config.toml or a trusted repository's .codex/config.toml.

For a GPT-5.6 Sol quality-first default:

model = "gpt-5.6-sol"
model_reasoning_effort = "high"

Explicit task overrides support current Codex reasoning tiers through max and ultra; the wrapper checks explicit model-and-effort pairs against the live model catalog before creating a thread.

Validation

Standalone skill checks:

python3 <skill-creator-root>/scripts/quick_validate.py skills/codex-companion
node --test tests/skill-codex-companion.test.mjs

Full repository regression check:

node --test

Plugin-only app-server type generation and build:

npm run build:plugin

That build step is only for the preserved upstream-style plugin material under plugins/codex/.

Upstream Sync

Recommended git remote layout:

• origin: this fork
• upstream: the original OpenAI repository

When upstream changes land, inspect plugins/codex/ first, then port only the behavior that still makes sense for the standalone skill.

License

This fork remains under Apache-2.0. Keep LICENSE and NOTICE with derived or redistributed material, including the standalone skill subset.