When you run init --codex, the MCP server is automatically registered with Codex:

# Verify MCP is registered
codex mcp list

# Expected output:
# Name         Command  Args                   Status
# claude-flow  npx      claude-flow mcp start  enabled

If MCP is not present, add manually:

codex mcp add claude-flow -- npx claude-flow mcp start

memory_search

{
  "query": "search terms",
  "namespace": "patterns",
  "limit": 5
}

memory_store

{
  "key": "pattern-name",
  "value": "what worked",
  "namespace": "patterns",
  "upsert": true
}

swarm_init

{
  "topology": "hierarchical",
  "maxAgents": 5,
  "strategy": "specialized"
}

1. LEARN:    memory_search(query="task keywords") → Find similar patterns
2. COORD:    swarm_init(topology="hierarchical") → Set up coordination
3. EXECUTE:  YOU write code, run commands        → Codex does real work
4. REMEMBER: memory_store(key, value, upsert=true) → Save for future

Build an email validator using a learning-enabled swarm.

STEP 1 - LEARN (use MCP tool):
Use tool: memory_search
  query: "validation utility function patterns"
  namespace: "patterns"
If score > 0.7, use that pattern as reference.

STEP 2 - COORDINATE (use MCP tools):
Use tool: swarm_init with topology="hierarchical", maxAgents=3
Use tool: agent_spawn with type="coder", name="validator"

STEP 3 - EXECUTE (YOU do this - DON'T STOP HERE):
Create /tmp/validator/email.js with validateEmail() function
Create /tmp/validator/test.js with test cases
Run the tests

STEP 4 - REMEMBER (use MCP tool):
Use tool: memory_store
  key: "pattern-email-validator"
  value: "Email validation: regex, returns boolean, test cases"
  namespace: "patterns"
  upsert: true

YOU execute all code. MCP tools are for learning only.

project/
├── AGENTS.md                    # Main project instructions (Codex format)
├── .agents/
│   ├── config.toml              # Project configuration
│   ├── skills/                  # 137+ skills
│   │   ├── swarm-orchestration/
│   │   │   └── SKILL.md
│   │   ├── memory-management/
│   │   │   └── SKILL.md
│   │   ├── sparc-methodology/
│   │   │   └── SKILL.md
│   │   └── ...
│   └── README.md                # Directory documentation
├── .codex/                      # Local overrides (gitignored)
│   ├── config.toml              # Local development settings
│   └── AGENTS.override.md       # Local instruction overrides
└── .claude-flow/                # Runtime data
    ├── config.yaml              # Runtime configuration
    ├── data/                    # Memory and cache
    │   └── memory.db            # SQLite with vector embeddings
    └── logs/                    # Log files

# Minimal (fastest init)
npx claude-flow@alpha init --codex --minimal

# Default
npx claude-flow@alpha init --codex

# Full (all skills)
npx claude-flow@alpha init --codex --full

Minimal:

• Core swarm orchestration
• Basic memory management

Default:

• Swarm orchestration
• Memory management
• SPARC methodology
• Basic coding patterns

Full:

• All 137+ skills
• GitHub integration
• Security scanning
• Performance optimization
• AgentDB vector search
• Neural pattern training

Run init --dual to set up both platforms:

npx claude-flow@alpha init --dual

This creates:

• CLAUDE.md for Claude Code users
• AGENTS.md for Codex users
• Shared .claude-flow/ runtime
• Cross-compatible skills

In OpenAI Codex CLI, invoke skills with $ prefix:

$swarm-orchestration
$memory-management
$sparc-methodology
$security-audit
$agent-coder
$agent-tester
$github-workflow
$performance-optimization

Create custom skills in .agents/skills/:

.agents/skills/my-skill/
└── SKILL.md

SKILL.md format:

# My Custom Skill

Instructions for what this skill does...

## Usage
Invoke with `$my-skill`

Run Claude Code for interactive development and spawn headless Codex workers for parallel background tasks:

┌─────────────────────────────────────────────────────────────────┐
│  CLAUDE CODE (interactive)  ←→  CODEX WORKERS (headless)        │
│  - Main conversation         - Parallel background execution    │
│  - Complex reasoning         - Bulk code generation            │
│  - Architecture decisions    - Test execution                   │
│  - Final integration         - File processing                  │
└─────────────────────────────────────────────────────────────────┘

# Initialize dual-mode
npx claude-flow@alpha init --dual

# Creates both:
# - CLAUDE.md (Claude Code configuration)
# - AGENTS.md (Codex configuration)
# - Shared .claude-flow/ runtime

From Claude Code, spawn headless Codex instances:

# Spawn workers in parallel (each runs independently)
claude -p "Analyze src/auth/ for security issues" --session-id "task-1" &
claude -p "Write unit tests for src/api/" --session-id "task-2" &
claude -p "Optimize database queries in src/db/" --session-id "task-3" &
wait  # Wait for all to complete

1. Claude Code receives complex feature request
2. Designs architecture and creates plan
3. Spawns 4 Codex workers:
   - Worker 1: Implement data models
   - Worker 2: Create API endpoints
   - Worker 3: Write unit tests
   - Worker 4: Generate documentation
4. Workers execute in parallel (headless)
5. Claude Code collects and integrates results
6. Final review and refinement in Claude Code

Both platforms share the same .claude-flow/ runtime:

.claude-flow/
├── data/
│   └── memory.db      # Shared vector memory
├── config.yaml        # Shared configuration
└── sessions/          # Cross-platform sessions

The @claude-flow/codex package now includes built-in dual-mode orchestration:

# List available collaboration templates
npx claude-flow-codex dual templates

# Run a feature development swarm
npx claude-flow-codex dual run --template feature --task "Add user authentication"

# Run a security audit swarm
npx claude-flow-codex dual run --template security --task "src/auth/"

# Run a refactoring swarm
npx claude-flow-codex dual run --template refactor --task "src/legacy/"

# Check collaboration status
npx claude-flow-codex dual status

Codex does not expose Claude Code's ScheduleWakeup, so @claude-flow/codex provides a process-based equivalent:

# Run Codex repeatedly until it creates .codex/loop/default.complete or reaches 10 iterations
npx claude-flow-codex loop run "Fix failing tests and create the completion marker when done"

# Use command mode for recurring Ruflo workers or custom scripts
npx claude-flow-codex loop run --name testgaps --interval 270 --max-iterations 0 \
  --command "npx claude-flow hooks worker dispatch --trigger testgaps"

# Inspect or stop a loop from another terminal
npx claude-flow-codex loop status --name testgaps
npx claude-flow-codex loop stop --name testgaps

Loop state is stored in .codex/loop/<name>.json; loop stop writes .codex/loop/<name>.stop, which the runner observes between iterations.

import { DualModeOrchestrator, CollaborationTemplates } from '@claude-flow/codex';

// Create orchestrator
const orchestrator = new DualModeOrchestrator({
  projectPath: process.cwd(),
  maxConcurrent: 4,
  sharedNamespace: 'collaboration',
  timeout: 300000,
});

// Listen to events
orchestrator.on('worker:started', ({ id, role }) => console.log(`Started: ${role}`));
orchestrator.on('worker:completed', ({ id }) => console.log(`Completed: ${id}`));

// Run collaboration with a template
const workers = CollaborationTemplates.featureDevelopment('Add OAuth2 login');
const result = await orchestrator.runCollaboration(workers, 'Feature: OAuth2');

console.log(`Success: ${result.success}`);
console.log(`Duration: ${result.totalDuration}ms`);
console.log(`Workers: ${result.workers.length}`);

import { migrate } from '@claude-flow/codex';

const result = await migrate({
  sourcePath: './CLAUDE.md',
  targetPath: './AGENTS.md',
  preserveComments: true,
  generateSkills: true,
});

console.log(`Migrated: ${result.success}`);
console.log(`Skills generated: ${result.skillsGenerated.length}`);

1. Rename config file: CLAUDE.md → AGENTS.md
2. Move skills: .claude/skills/ → .agents/skills/
3. Update syntax: /skill-name → $skill-name
4. Convert settings: settings.json → config.toml
5. Register MCP: codex mcp add claude-flow -- npx claude-flow mcp start

Instead of migrating, use dual mode to support both:

npx claude-flow@alpha init --dual

This keeps both CLAUDE.md and AGENTS.md in sync.