Add OpenAI Codex CLI integration support

[avivsinai]

Overview

Add support for OpenAI Codex CLI integration, similar to our existing Claude Code (promptcode cc) and Cursor IDE (promptcode cursor) integrations. This will allow users to leverage PromptCode presets and commands within the Codex terminal agent.

Research Summary

OpenAI Codex CLI (released 2025):

• Terminal-based coding agent built in Rust
• Native slash commands: /model, /approvals, /review, /compact, /init, /mention, /status
• Custom commands via ~/.codex/prompts/*.md files
• Uses GPT-5 and GPT-5-Codex models
• Session management with context compaction
• Three approval modes: read-only, auto (workspace), full (network)

Key difference from Claude/Cursor: Codex uses a global config directory (~/.codex/) rather than project-local directories.

Implementation Plan

Phase 1: Codex Integration Command

Create promptcode codex command similar to existing cc and cursor commands.

New files to create:

• packages/cli/src/commands/codex.ts - Main codex integration command
• packages/cli/src/utils/codex-integration.ts - Helper functions for Codex
• packages/cli/src/codex-templates/*.md - Custom command templates

Templates to create (install to ~/.codex/prompts/):

• promptcode-preset-list.md - List available presets
• promptcode-preset-info.md - Show preset details
• promptcode-preset-create.md - Create new preset
• promptcode-ask-expert.md - AI expert consultation (adapted for Codex)
• promptcode-generate.md - Generate prompt from files

Command behavior:

promptcode codex              # Install commands to ~/.codex/prompts/
promptcode codex --uninstall  # Remove PromptCode commands
promptcode codex --detect     # Check if Codex is installed

Phase 2: Codex Provider Support (Optional)

Add Codex-specific models to the AI provider system.

Files to modify:

• packages/cli/src/providers/models.ts - Add GPT-5-Codex model variant
• packages/cli/src/providers/ai-provider.ts - Handle Codex-specific API calls

Rationale: Codex uses OpenAI models (GPT-5, GPT-5-Codex), so existing OpenAI provider can be extended. GPT-5-Codex is optimized for "agentic coding" workflows.

Phase 3: Unified Integration Flow

Update promptcode integrate to auto-detect and offer Codex setup.

Files to modify:

• packages/cli/src/commands/integrate.ts - Add Codex detection
• Check for ~/.codex/ directory or codex command in PATH

Phase 4: Documentation

Files to create/update:

• packages/cli/src/codex-templates/README.md - Usage guide
• Update main documentation with Codex comparison
• Add Codex section to CLI help text

Key Design Decisions

1. Global vs Project-Local Installation

Decision: Install to ~/.codex/prompts/ (global) by default
Rationale: Codex CLI uses global config directory, unlike Claude/Cursor which are project-specific

2. Command Naming

Decision: Keep promptcode-* prefix for commands
Rationale: Maintains consistency with Claude/Cursor integrations, avoids conflicts

3. Template Format

Decision: Use Markdown (.md) format like Codex expects
Rationale: Direct compatibility with Codex CLI's custom commands system

4. Model Support

Decision: Phase 2 is optional - can use existing OpenAI provider initially
Rationale: GPT-5-Codex uses same API as GPT-5, just fine-tuned differently

Implementation Steps

1. Create integration helpers (codex-integration.ts):

   • findCodexDir() - Locate ~/.codex/prompts/
   • installCodexCommands() - Copy templates with checksum tracking
   • removeCodexCommands() - Clean up PromptCode commands

2. Create codex command (codex.ts):

   • Similar structure to cc.ts and cursor.ts
   • Handle global installation path (~/.codex/prompts/)
   • Support --uninstall, --detect, --force flags
   • Show preview before installation

3. Adapt templates (from Claude templates):

   • Convert from Claude Code syntax to Codex CLI bash syntax
   • Update instructions for Codex's terminal UI
   • Test each command with actual Codex CLI

4. Update integrate command:

   • Add detectCodexEnvironment() function
   • Check if codex binary exists in PATH
   • Offer setup if Codex detected

5. Testing:

   • Install Codex CLI locally
   • Run promptcode codex
   • Verify commands appear in Codex slash menu
   • Test each command functionality
   • Verify uninstall works cleanly

Expected File Structure After Implementation

packages/cli/src/
├── commands/
│   ├── codex.ts              # NEW
│   ├── integrate.ts          # MODIFIED
│   └── ...
├── utils/
│   ├── codex-integration.ts  # NEW
│   └── ...
├── codex-templates/          # NEW
│   ├── promptcode-ask-expert.md
│   ├── promptcode-preset-list.md
│   ├── promptcode-preset-info.md
│   ├── promptcode-preset-create.md
│   ├── promptcode-generate.md
│   └── README.md
└── index.ts                  # MODIFIED (register command)

Benefits

1. Unified workflow across Claude Code, Cursor, and Codex
2. Leverage existing preset system in all environments
3. Multi-provider flexibility - use PromptCode with any AI tool
4. Consistent developer experience regardless of IDE/CLI choice
5. Expands user base - attracts Codex CLI users

Risks & Mitigations

Risk	Mitigation
Codex custom commands may have different capabilities than Claude slash commands	Adapt templates to use bash scripts where needed, test thoroughly
Global installation may conflict with user's existing Codex setup	Use markers (like <!-- PROMPTCODE-START -->) to identify our commands, backup before overwriting
Codex CLI API may change	Use stable features (custom commands in ~/.codex/prompts/), document version compatibility

Success Criteria

• promptcode codex installs commands to ~/.codex/prompts/
• All 5 core commands work in Codex CLI
• promptcode integrate auto-detects Codex
• Uninstall cleanly removes PromptCode commands
• Documentation explains Codex integration
• Tests verify installation/uninstallation
• Works on macOS, Linux, Windows

References

• OpenAI Codex CLI: https://developers.openai.com/codex/cli/
• Codex GitHub: https://github.com/openai/codex
• PromptCode existing integrations: packages/cli/src/commands/cc.ts, packages/cli/src/commands/cursor.ts

Labels

enhancement, integration, codex, good-first-issue (for documentation parts)