┌─────────────────────────────────────────────────────────────────┐
│  CLAUDE-FLOW = ORCHESTRATOR (tracks state, stores memory)       │
│  CODEX = EXECUTOR (writes code, runs commands, implements)      │
└─────────────────────────────────────────────────────────────────┘

    ┌──────────────┐
    │   SEARCH     │ ──→ Find relevant patterns from past successes
    │   memory     │
    └──────┬───────┘
           │
    ┌──────▼───────┐
    │  COORDINATE  │ ──→ Initialize swarm, spawn specialized agents
    │   swarm      │
    └──────┬───────┘
           │
    ┌──────▼───────┐
    │   EXECUTE    │ ──→ Codex writes code, runs commands
    │   codex      │
    └──────┬───────┘
           │
    ┌──────▼───────┐
    │    STORE     │ ──→ Save successful patterns for future use
    │   memory     │
    └──────────────┘

# Initialize for Codex (recommended)
npx claude-flow@alpha init --codex

# Full setup with all 137+ skills
npx claude-flow@alpha init --codex --full

# Dual mode (both Claude Code and Codex)
npx claude-flow@alpha init --dual

# Verify MCP is registered
codex mcp list

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

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

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

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

{
  "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

npx claude-flow@alpha init --dual

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

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

# My Custom Skill

Instructions for what this skill does...

## Usage
Invoke with `$my-skill`

┌─────────────────────────────────────────────────────────────────┐
│  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

# 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

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

# 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

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}`);

# Model configuration
model = "gpt-5.3"

# Approval policy: "always" | "on-request" | "never"
approval_policy = "on-request"

# Sandbox mode: "read-only" | "workspace-write" | "danger-full-access"
sandbox_mode = "workspace-write"

# Web search: "off" | "cached" | "live"
web_search = "cached"

# MCP Servers
[mcp_servers.claude-flow]
command = "npx"
args = ["claude-flow", "mcp", "start"]
enabled = true

# Skills
[[skills]]
path = ".agents/skills/swarm-orchestration"
enabled = true

[[skills]]
path = ".agents/skills/memory-management"
enabled = true

[[skills]]
path = ".agents/skills/sparc-methodology"
enabled = true

# Local development overrides (gitignored)
# These settings override .agents/config.toml

approval_policy = "never"
sandbox_mode = "danger-full-access"
web_search = "live"

# Disable MCP in local if needed
[mcp_servers.claude-flow]
enabled = false

# Configuration paths
CLAUDE_FLOW_CONFIG=./claude-flow.config.json
CLAUDE_FLOW_MEMORY_PATH=./.claude-flow/data

# Provider keys
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...

# MCP settings
CLAUDE_FLOW_MCP_PORT=3000

// Find auth patterns
memory_search({ query: "authentication JWT patterns", namespace: "patterns" })

// Find bug solutions
memory_search({ query: "null pointer fix", namespace: "solutions" })

// Find past tasks
memory_search({ query: "user profile API", namespace: "tasks" })

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

class CodexInitializer {
  /**
   * Initialize a Codex project
   */
  async initialize(options: CodexInitOptions): Promise<CodexInitResult>;

  /**
   * Preview what would be created without writing files
   */
  async dryRun(options: CodexInitOptions): Promise<string[]>;
}

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

/**
 * Quick initialization helper
 */
async function initializeCodexProject(
  projectPath: string,
  options?: Partial<CodexInitOptions>
): Promise<CodexInitResult>;

interface CodexInitOptions {
  /** Project directory path */
  projectPath: string;
  /** Template to use */
  template?: 'minimal' | 'default' | 'full' | 'enterprise';
  /** Specific skills to include */
  skills?: string[];
  /** Overwrite existing files */
  force?: boolean;
  /** Enable dual mode (Claude Code + Codex) */
  dual?: boolean;
}

interface CodexInitResult {
  /** Whether initialization succeeded */
  success: boolean;
  /** List of files created */
  filesCreated: string[];
  /** List of skills generated */
  skillsGenerated: string[];
  /** Whether MCP was registered */
  mcpRegistered?: boolean;
  /** Non-fatal warnings */
  warnings?: string[];
  /** Fatal errors */
  errors?: string[];
}

import { CodexInitializer, initializeCodexProject } from '@claude-flow/codex';

// Quick initialization
const result = await initializeCodexProject('/path/to/project', {
  template: 'full',
  force: true,
  dual: false,
});

console.log(`Files created: ${result.filesCreated.length}`);
console.log(`Skills: ${result.skillsGenerated.length}`);
console.log(`MCP registered: ${result.mcpRegistered}`);

// Or use the class directly
const initializer = new CodexInitializer();
const result = await initializer.initialize({
  projectPath: '/path/to/project',
  template: 'enterprise',
  skills: ['swarm-orchestration', 'memory-management', 'security-audit'],
  force: false,
  dual: true,
});

if (result.warnings?.length) {
  console.warn('Warnings:', result.warnings);
}

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}`);

npx claude-flow@alpha init --dual

# Check if registered
codex mcp list

# Re-register
codex mcp remove claude-flow
codex mcp add claude-flow -- npx claude-flow mcp start

# Test connection
npx claude-flow mcp test

# Initialize memory database
npx claude-flow memory init --force

# Check if entries exist
npx claude-flow memory list

# Manually add a test pattern
npx claude-flow memory store --key "test" --value "test pattern" --namespace patterns

# Verify skill directory
ls -la .agents/skills/

# Check config.toml for skill registration
cat .agents/config.toml | grep skills

# Rebuild skills
npx claude-flow@alpha init --codex --force

# Check HNSW index
npx claude-flow memory stats

# Rebuild index
npx claude-flow memory optimize --rebuild-index