Codex CLI Integration Reference

OpenAI Codex CLI (github.com/openai/codex) - Terminal-native AI coding tool Written in Rust (codex-rs), with TypeScript SDK available

Executive Summary

Codex CLI is OpenAI's terminal-based AI coding assistant with unique features:

• OS-level sandboxing (Apple Seatbelt on macOS, Docker on Linux)
• TOML configuration in ~/.codex/config.toml
• Skill system with $skill-name invocation
• MCP server mode where Codex itself can be a tool for other agents
• Multi-provider support (OpenAI, Anthropic, Google, Ollama, etc.)
• Approval policies (suggest, auto-edit, full-auto)

---

Quick Facts

---

What Our Installer Does

When user runs agentsys and selects Codex:

~/.agentsys/           # Full package copy

~/.codex/skills/            # 24 skills installed
├── next-task/SKILL.md
├── deslop/SKILL.md
├── enhance/SKILL.md
├── ship/SKILL.md
├── audit-project/SKILL.md
├── drift-detect/SKILL.md
├── repo-intel/SKILL.md
├── sync-docs/SKILL.md
├── perf/SKILL.md
└── ... (15 more internal skills)

Skills are invoked with $ prefix: $next-task, $ship, etc.

---

Model Selection

Codex Model Format

Default model: o4-mini

Built-in Models:

• o3, o4-mini, gpt-5.1, gpt-5.1-codex

Provider Format:

provider/model

Examples:

• openai/gpt-4o - OpenAI
• anthropic/claude-sonnet-4 - Anthropic
• google/gemini-pro - Google
• ollama/llama-3 - Local Ollama

Configuring Providers

# ~/.codex/config.toml

[providers.anthropic]
name = "anthropic"
baseURL = "https://api.anthropic.com"
envKey = "ANTHROPIC_API_KEY"

[providers.openrouter]
name = "openrouter"
baseURL = "https://openrouter.ai/api/v1"
envKey = "OPENROUTER_API_KEY"

---

User Interaction

Question Format

Codex uses request_user_input tool with a JSON schema:

{
  "questions": [
    {
      "id": "task_selection",
      "header": "Select Task",
      "question": "Which task should I work on?",
      "options": [
        {
          "label": "Option A (Recommended)",
          "description": "Explanation of this choice"
        },
        {
          "label": "Option B",
          "description": "Another option"
        },
        {
          "label": "Other",
          "description": "Provide custom input"
        }
      ]
    }
  ]
}

Question Constraints

Key Differences from Claude Code

Implication for AgentSys

The gen-adapters script automatically transforms AskUserQuestion to request_user_input when generating Codex adapter files. It also removes multiSelect lines (unsupported in Codex) and injects a note about the required id field. Source files use AskUserQuestion as the canonical format; Codex compatibility is handled at build time.

---

Skill System

Skill Structure

~/.codex/skills/
└── skill-name/
    ├── SKILL.md (required)
    │   ├── YAML frontmatter (name, description)
    │   └── Markdown instructions
    └── Bundled Resources (optional)
        ├── scripts/
        ├── references/
        └── assets/

SKILL.md Format

---
name: skill-name
description: "Use when user asks to \\"trigger phrase 1\\", \\"trigger phrase 2\\". Description of what it does and key capabilities."
---

# Skill Instructions

Content and procedures...

Description Best Practices

Critical: The description is the PRIMARY triggering mechanism. It must include:

1. Specific trigger phrases - "Use when user asks to..."
2. What the skill does - Brief explanation of capabilities
3. Proper YAML escaping - Wrap in quotes, escape internal quotes

Good Example:

description: "Use when user asks to \\"find next task\\", \\"what should I work on\\", \\"automate workflow\\". Orchestrates complete task-to-production workflow."

Bad Example:

description: Master workflow orchestrator  # No trigger phrases!

Progressive Disclosure

Note: Some AgentSys skills exceed 500 lines. Future improvement: split into references/.

Invoking Skills

# In Codex session
$skill-name

# Or reference in chat
"Use $next-task to find my next task"

Apps Integration

Codex has an "apps" system for connectors:

# List available apps
/apps

# Insert app in composer
$app-name

---

Configuration

Config File Location

~/.codex/config.toml (TOML format)

Key Settings

# Model selection
model = "o4-mini"

# Approval mode: suggest | auto-edit | full-auto
approvalMode = "suggest"

# Error handling in full-auto mode
fullAutoErrorMode = "ask-user"

# Desktop notifications
notify = true

# History settings
[history]
maxSize = 100
saveHistory = true
sensitivePatterns = ["password", "secret", "api_key"]

Approval Policies

Runtime Approval Policies

When using Codex as MCP server:

---

MCP Integration

Codex MCP Support

Codex supports MCP (Model Context Protocol) for tool integration.

Codex as MCP Server:

# Start Codex as MCP server
codex mcp-server

# Inspect with MCP inspector
npx @modelcontextprotocol/inspector codex mcp-server

Managing MCP Servers:

codex mcp add my-server
codex mcp list
codex mcp get my-server
codex mcp remove my-server

Note: AgentSys uses native Codex skills (in ~/.codex/skills/) instead of MCP for better integration.

---

Project Instructions

AGENTS.md

Codex reads AGENTS.md files hierarchically:

1. ~/.codex/AGENTS.md (global)
2. Repository root AGENTS.md
3. Current directory AGENTS.md

Example AGENTS.md

# Project Guidelines

## Code Style
- Use TypeScript strict mode
- Prefer async/await over callbacks
- All functions must have JSDoc comments

## Testing
- Run `npm test` before committing
- Maintain >80% code coverage

## Git Conventions
- Use conventional commits (feat:, fix:, docs:)
- Never force push to main

Compatibility with CLAUDE.md

Codex primarily reads AGENTS.md, but our MCP server sets AI_STATE_DIR=.codex to ensure state files are written to the correct location.

---

Sandbox Security

macOS (Seatbelt)

• Apple's Seatbelt wraps all commands
• Network fully blocked by default
• Confined to working directory + temp storage

Linux (Docker)

• Optional Docker containerization
• iptables firewall denies all egress except API
• Full filesystem isolation

Full-Auto Mode Safety

In full-auto mode:

• All commands run network-disabled
• Confined to working directory
• Temporary storage allowed
• Cannot access other directories

---

Session Management

Conversation State

# Sessions stored in
~/.codex/sessions/

# Each session has
session_id/
├── history.json
└── metadata.json

Thread-Based Architecture

Codex uses threads for conversation management:

const codex = new Codex();
const thread = codex.startThread({
  workingDirectory: "/path/to/project"
});

await thread.run("Find and fix bugs");

Compaction

Codex automatically compacts long sessions:

• Monitors token usage vs context limit
• Prunes old tool outputs
• Creates summary of conversation
• Continues transparently

---

Multi-Agent Architecture

Codex as Agent Tool

Other agents can spawn Codex:

{
  "jsonrpc": "2.0",
  "method": "newConversation",
  "params": {
    "model": "o3",
    "cwd": "/home/user/project",
    "approvalPolicy": "on-request",
    "sandbox": "workspace-write"
  }
}

Hierarchical Agent Chains

Parent Agent (orchestrator)
    └── Codex (MCP server mode)
            └── Execute coding tasks

Agent Communication

// Send turn to conversation
{
  "method": "sendUserTurn",
  "params": {
    "conversationId": "conv-123",
    "input": [{ "type": "text", "text": "Run tests" }]
  }
}

---

Known Limitations

Functional Differences

1. No subagent spawning - Codex uses MCP server mode instead of Task tool
2. Skills are global - Installed to ~/.codex/skills/, not per-project
3. TOML config - Different format from JSON

State Directory

Codex uses .codex/ in projects. Our MCP server is configured with AI_STATE_DIR=.codex to write state files correctly.

Question Format

Native Codex uses request_user_input. The gen-adapters script automatically transforms AskUserQuestion → request_user_input in all Codex adapter files, removes unsupported multiSelect lines, and adds notes about the required id field.

---

Testing Codex Integration

Verify MCP Connection

# In Codex session
# Use any MCP tool
workflow_status

Verify Skills

# Should list installed skills
$next-task
$deslop
$ship

Verify State Directory

# After running workflow
ls .codex/
# Should see: tasks.json, flow.json (in worktree)

---

Improvement Opportunities

Short Term

1. Test question format - Verify AskUserQuestion works via MCP
2. Skill descriptions - Ensure skills have good trigger descriptions
3. Document $skill invocation - Add to user docs

Medium Term

1. Native Codex agents - Create Codex-native agent definitions
2. Approval policy hints - Recommend on-request for workflows
3. Sandbox configuration - Document recommended sandbox settings

Long Term

1. Codex MCP server integration - Use Codex as a tool from Claude
2. Cross-platform state sync - Share state between tools
3. TypeScript SDK integration - Programmatic Codex usage

---

TypeScript SDK

Installation

npm install @openai/codex-sdk

Basic Usage

const codex = new Codex();
const thread = codex.startThread({
  workingDirectory: process.cwd()
});

const turn = await thread.run("Find and fix bugs");
console.log(turn.finalResponse);

Structured Output

const ReviewSchema = z.object({
  approved: z.boolean(),
  score: z.number().min(0).max(100),
  feedback: z.array(z.object({
    category: z.enum(["style", "performance", "security"]),
    comment: z.string()
  }))
});

const turn = await thread.run("Review the code", {
  outputSchema: zodToJsonSchema(ReviewSchema)
});

const review = ReviewSchema.parse(JSON.parse(turn.finalResponse));

---

Resources

• GitHub: https://github.com/openai/codex
• Rust CLI: codex-rs/ directory
• TypeScript SDK: sdk/typescript/
• Docs: docs/ directory in repo
• MCP Interface: codex-rs/docs/codex_mcp_interface.md