{"_id":"@aigentic/codex","_rev":"2-481873b1b48a5214eb1fa710a5b9443b","name":"@aigentic/codex","dist-tags":{"alpha":"3.0.0-alpha.9","latest":"3.0.0-alpha.9"},"versions":{"3.0.0-alpha.9":{"name":"@aigentic/codex","version":"3.0.0-alpha.9","keywords":["codex","openai","claude-flow","coflow","agents","skills","AGENTS.md","agentic-ai"],"author":{"name":"rUv"},"license":"MIT","_id":"@aigentic/codex@3.0.0-alpha.9","maintainers":[{"name":"aigentic","email":"engineering@aigentic.net"}],"homepage":"https://github.com/ruvnet/ruflo#readme","bugs":{"url":"https://github.com/ruvnet/ruflo/issues"},"bin":{"claude-flow-codex":"dist/cli.js"},"dist":{"shasum":"7b05ddbf3e6570f126232d643d586e807cdde6c0","tarball":"https://registry.npmjs.org/@aigentic/codex/-/codex-3.0.0-alpha.9.tgz","fileCount":66,"integrity":"sha512-2Wd12SsQ6sr0pF+FYNd//lSm1U1g3KKDWQhPnYKL/0s7ylCx6TJ/QOhhqQtyFGYWRer5Cgqs6ZQ+NgxYAU2WVw==","signatures":[{"sig":"MEQCIGZ4GxXeG367Q5quCwWjgLdKNz9YXe7SoOl2v9d8NOCPAiBl3Va2x33goBBy8ysYu9tPxH7hQwLfn1nyQiOvIs/WEQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":500917},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","default":"./dist/index.js","require":"./dist/index.js"},"./loop":{"types":"./dist/loop/index.d.ts","import":"./dist/loop/index.js","require":"./dist/loop/index.js"},"./dual-mode":{"types":"./dist/dual-mode/index.d.ts","import":"./dist/dual-mode/index.js","require":"./dist/dual-mode/index.js"},"./templates":{"types":"./dist/templates/index.d.ts","import":"./dist/templates/index.js","require":"./dist/templates/index.js"},"./generators":{"types":"./dist/generators/index.d.ts","import":"./dist/generators/index.js","require":"./dist/generators/index.js"},"./migrations":{"types":"./dist/migrations/index.d.ts","import":"./dist/migrations/index.js","require":"./dist/migrations/index.js"}},"gitHead":"e2cb6210ce8d478b39cad81872a4aef78a05ceb4","scripts":{"dev":"tsc --watch","lint":"eslint src --ext .ts","test":"vitest","build":"tsc","prepublishOnly":"npm run build"},"_npmUser":{"name":"aigentic","email":"engineering@aigentic.net"},"repository":{"url":"git+https://github.com/ruvnet/ruflo.git","type":"git","directory":"v3/@claude-flow/codex"},"_npmVersion":"11.12.0","description":"Codex CLI integration for Ruflo (claude-flow) - OpenAI Codex platform adapter","directories":{},"_nodeVersion":"22.22.1","dependencies":{"@aigentic/toml":"^2.2.5","@aigentic/yaml":"^2.4.0","@aigentic/chalk":"^5.3.0","@aigentic/fs-extra":"^11.2.0","@aigentic/inquirer":"^9.2.0","@aigentic/commander":"^12.0.0"},"_hasShrinkwrap":false,"devDependencies":{"@aigentic/node":"^20.0.0","@aigentic/eslint":"^8.57.0","@aigentic/vitest":"^4.0.16","@aigentic/fs-extra":"^11.0.4","@aigentic/typescript":"^5.4.0"},"peerDependencies":{"@aigentic/cli":"^3.0.0-alpha.1"},"peerDependenciesMeta":{"@claude-flow/cli":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/codex_3.0.0-alpha.9_1779324076737_0.14384517873077818","host":"s3://npm-registry-packages-npm-production"}}},"time":{"created":"2026-05-21T00:41:16.484Z","modified":"2026-09-13T15:30:27.332Z","3.0.0-alpha.9":"2026-05-21T00:41:16.883Z"},"bugs":{"url":"https://github.com/ruvnet/ruflo/issues"},"author":{"name":"rUv"},"license":"MIT","homepage":"https://github.com/ruvnet/ruflo#readme","keywords":["codex","openai","claude-flow","coflow","agents","skills","AGENTS.md","agentic-ai"],"repository":{"url":"git+https://github.com/ruvnet/ruflo.git","type":"git","directory":"v3/@claude-flow/codex"},"description":"Codex CLI integration for Ruflo (claude-flow) - OpenAI Codex platform adapter","maintainers":[{"email":"engineering@aigentic.net","name":"aiggy"}],"readme":"# @claude-flow/codex\n\n<p align=\"center\">\n  <strong>OpenAI Codex CLI Adapter for Claude Flow V3</strong><br/>\n  <em>Self-learning multi-agent orchestration following the <a href=\"https://agentics.org\">Agentics Foundation</a> standard</em>\n</p>\n\n<p align=\"center\">\n  <a href=\"https://www.npmjs.com/package/@claude-flow/codex\"><img src=\"https://img.shields.io/npm/v/@claude-flow/codex?label=npm&color=blue\" alt=\"npm version\"></a>\n  <a href=\"https://www.npmjs.com/package/@claude-flow/codex\"><img src=\"https://img.shields.io/npm/dm/@claude-flow/codex?label=downloads&color=cb3837\" alt=\"npm downloads\"></a>\n  <a href=\"https://github.com/ruvnet/ruflo\"><img src=\"https://img.shields.io/badge/license-MIT-green\" alt=\"license\"></a>\n  <a href=\"https://agentics.org\"><img src=\"https://img.shields.io/badge/standard-Agentics-purple\" alt=\"Agentics Standard\"></a>\n</p>\n\n---\n\n## Why @claude-flow/codex?\n\nTransform OpenAI Codex CLI into a **self-improving AI development system**. While Codex executes code, claude-flow orchestrates, coordinates, and **learns from every interaction**.\n\n| Traditional Codex | With Claude-Flow |\n|-------------------|------------------|\n| Stateless execution | Persistent vector memory |\n| Single-agent | Multi-agent swarms (up to 15) |\n| Manual coordination | Automatic orchestration |\n| No learning | Self-learning patterns (HNSW) |\n| One platform | Dual-mode (Claude Code + Codex) |\n\n## Key Concept: Execution Model\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│  CLAUDE-FLOW = ORCHESTRATOR (tracks state, stores memory)       │\n│  CODEX = EXECUTOR (writes code, runs commands, implements)      │\n└─────────────────────────────────────────────────────────────────┘\n```\n\n**Codex does the work. Claude-flow coordinates and learns.**\n\n### The Self-Learning Loop\n\n```\n    ┌──────────────┐\n    │   SEARCH     │ ──→ Find relevant patterns from past successes\n    │   memory     │\n    └──────┬───────┘\n           │\n    ┌──────▼───────┐\n    │  COORDINATE  │ ──→ Initialize swarm, spawn specialized agents\n    │   swarm      │\n    └──────┬───────┘\n           │\n    ┌──────▼───────┐\n    │   EXECUTE    │ ──→ Codex writes code, runs commands\n    │   codex      │\n    └──────┬───────┘\n           │\n    ┌──────▼───────┐\n    │    STORE     │ ──→ Save successful patterns for future use\n    │   memory     │\n    └──────────────┘\n```\n\n## Quick Start\n\n```bash\n# Initialize for Codex (recommended)\nnpx claude-flow@alpha init --codex\n\n# Full setup with all 137+ skills\nnpx claude-flow@alpha init --codex --full\n\n# Dual mode (both Claude Code and Codex)\nnpx claude-flow@alpha init --dual\n```\n\n**That's it!** The MCP server is auto-registered, skills are installed, and your project is ready for self-learning development.\n\n---\n\n<details>\n<summary><b>Features</b></summary>\n\n| Feature | Description |\n|---------|-------------|\n| **AGENTS.md Generation** | Creates project instructions for Codex |\n| **MCP Integration** | Self-learning via memory and vector search |\n| **137+ Skills** | Invoke with `$skill-name` syntax |\n| **Vector Memory** | Semantic pattern search (384-dim embeddings) |\n| **Dual Platform** | Supports both Claude Code and Codex |\n| **Auto-Registration** | MCP server registered during init |\n| **HNSW Search** | 150x-12,500x faster pattern matching |\n| **Self-Learning** | Learn from successes, remember patterns |\n| **GPT-5.3 Support** | Optimized for latest OpenAI models |\n| **Neural Training** | Train patterns with SONA architecture |\n\n</details>\n\n---\n\n<details>\n<summary><b>MCP Integration (Self-Learning)</b></summary>\n\n### Automatic Registration\n\nWhen you run `init --codex`, the MCP server is **automatically registered** with Codex:\n\n```bash\n# Verify MCP is registered\ncodex mcp list\n\n# Expected output:\n# Name         Command  Args                   Status\n# claude-flow  npx      claude-flow mcp start  enabled\n```\n\n### Manual Registration\n\nIf MCP is not present, add manually:\n\n```bash\ncodex mcp add claude-flow -- npx claude-flow mcp start\n```\n\n### MCP Tools Reference\n\n| Tool | Purpose | When to Use |\n|------|---------|-------------|\n| `memory_search` | Semantic vector search | **BEFORE** starting any task |\n| `memory_store` | Save patterns with embeddings | **AFTER** completing successfully |\n| `swarm_init` | Initialize coordination | Start of complex tasks |\n| `agent_spawn` | Register agent roles | Multi-agent workflows |\n| `neural_train` | Train on patterns | Periodic improvement |\n\n### Tool Parameters\n\n**memory_search**\n```json\n{\n  \"query\": \"search terms\",\n  \"namespace\": \"patterns\",\n  \"limit\": 5\n}\n```\n\n**memory_store**\n```json\n{\n  \"key\": \"pattern-name\",\n  \"value\": \"what worked\",\n  \"namespace\": \"patterns\",\n  \"upsert\": true\n}\n```\n\n**swarm_init**\n```json\n{\n  \"topology\": \"hierarchical\",\n  \"maxAgents\": 5,\n  \"strategy\": \"specialized\"\n}\n```\n\n</details>\n\n---\n\n<details>\n<summary><b>Self-Learning Workflow</b></summary>\n\n### The 4-Step Pattern\n\n```\n1. LEARN:    memory_search(query=\"task keywords\") → Find similar patterns\n2. COORD:    swarm_init(topology=\"hierarchical\") → Set up coordination\n3. EXECUTE:  YOU write code, run commands        → Codex does real work\n4. REMEMBER: memory_store(key, value, upsert=true) → Save for future\n```\n\n### Complete Example Prompt\n\n```\nBuild an email validator using a learning-enabled swarm.\n\nSTEP 1 - LEARN (use MCP tool):\nUse tool: memory_search\n  query: \"validation utility function patterns\"\n  namespace: \"patterns\"\nIf score > 0.7, use that pattern as reference.\n\nSTEP 2 - COORDINATE (use MCP tools):\nUse tool: swarm_init with topology=\"hierarchical\", maxAgents=3\nUse tool: agent_spawn with type=\"coder\", name=\"validator\"\n\nSTEP 3 - EXECUTE (YOU do this - DON'T STOP HERE):\nCreate /tmp/validator/email.js with validateEmail() function\nCreate /tmp/validator/test.js with test cases\nRun the tests\n\nSTEP 4 - REMEMBER (use MCP tool):\nUse tool: memory_store\n  key: \"pattern-email-validator\"\n  value: \"Email validation: regex, returns boolean, test cases\"\n  namespace: \"patterns\"\n  upsert: true\n\nYOU execute all code. MCP tools are for learning only.\n```\n\n### Similarity Score Guide\n\n| Score | Meaning | Action |\n|-------|---------|--------|\n| > 0.7 | Strong match | Use the pattern directly |\n| 0.5 - 0.7 | Partial match | Adapt and modify |\n| < 0.5 | Weak match | Create new approach |\n\n</details>\n\n---\n\n<details>\n<summary><b>Directory Structure</b></summary>\n\n```\nproject/\n├── AGENTS.md                    # Main project instructions (Codex format)\n├── .agents/\n│   ├── config.toml              # Project configuration\n│   ├── skills/                  # 137+ skills\n│   │   ├── swarm-orchestration/\n│   │   │   └── SKILL.md\n│   │   ├── memory-management/\n│   │   │   └── SKILL.md\n│   │   ├── sparc-methodology/\n│   │   │   └── SKILL.md\n│   │   └── ...\n│   └── README.md                # Directory documentation\n├── .codex/                      # Local overrides (gitignored)\n│   ├── config.toml              # Local development settings\n│   └── AGENTS.override.md       # Local instruction overrides\n└── .claude-flow/                # Runtime data\n    ├── config.yaml              # Runtime configuration\n    ├── data/                    # Memory and cache\n    │   └── memory.db            # SQLite with vector embeddings\n    └── logs/                    # Log files\n```\n\n### Key Files\n\n| File | Purpose |\n|------|---------|\n| `AGENTS.md` | Main instructions for Codex (required) |\n| `.agents/config.toml` | Project-wide configuration |\n| `.codex/config.toml` | Local overrides (gitignored) |\n| `.claude-flow/data/memory.db` | Vector memory database |\n\n</details>\n\n---\n\n<details>\n<summary><b>Templates</b></summary>\n\n### Available Templates\n\n| Template | Skills | Learning | Best For |\n|----------|--------|----------|----------|\n| `minimal` | 2 | Basic | Quick prototypes |\n| `default` | 4 | Yes | Standard projects |\n| `full` | 137+ | Yes | Full-featured development |\n| `enterprise` | 137+ | Advanced | Team environments |\n\n### Usage\n\n```bash\n# Minimal (fastest init)\nnpx claude-flow@alpha init --codex --minimal\n\n# Default\nnpx claude-flow@alpha init --codex\n\n# Full (all skills)\nnpx claude-flow@alpha init --codex --full\n```\n\n### Template Contents\n\n**Minimal:**\n- Core swarm orchestration\n- Basic memory management\n\n**Default:**\n- Swarm orchestration\n- Memory management\n- SPARC methodology\n- Basic coding patterns\n\n**Full:**\n- All 137+ skills\n- GitHub integration\n- Security scanning\n- Performance optimization\n- AgentDB vector search\n- Neural pattern training\n\n</details>\n\n---\n\n<details>\n<summary><b>Platform Comparison (Claude Code vs Codex)</b></summary>\n\n| Feature | Claude Code | OpenAI Codex |\n|---------|-------------|--------------|\n| Config File | `CLAUDE.md` | `AGENTS.md` |\n| Skills Dir | `.claude/skills/` | `.agents/skills/` |\n| Skill Syntax | `/skill-name` | `$skill-name` |\n| Settings | `settings.json` | `config.toml` |\n| MCP | Native | Via `codex mcp add` |\n| Overrides | `.claude.local.md` | `.codex/config.toml` |\n\n### Dual Mode\n\nRun `init --dual` to set up both platforms:\n\n```bash\nnpx claude-flow@alpha init --dual\n```\n\nThis creates:\n- `CLAUDE.md` for Claude Code users\n- `AGENTS.md` for Codex users\n- Shared `.claude-flow/` runtime\n- Cross-compatible skills\n\n</details>\n\n---\n\n<details>\n<summary><b>Skill Invocation</b></summary>\n\n### Syntax\n\nIn OpenAI Codex CLI, invoke skills with `$` prefix:\n\n```\n$swarm-orchestration\n$memory-management\n$sparc-methodology\n$security-audit\n$agent-coder\n$agent-tester\n$github-workflow\n$performance-optimization\n```\n\n### Complete Skills Table (137+ Skills)\n\n#### V3 Core Skills\n\n| Skill | Syntax | Description |\n|-------|--------|-------------|\n| V3 Security Overhaul | `$v3-security-overhaul` | Complete security architecture with CVE remediation |\n| V3 Memory Unification | `$v3-memory-unification` | Unify 6+ memory systems into AgentDB with HNSW |\n| V3 Integration Deep | `$v3-integration-deep` | Deep agentic-flow@alpha integration (ADR-001) |\n| V3 Performance Optimization | `$v3-performance-optimization` | Achieve 2.49x-7.47x speedup targets |\n| V3 Swarm Coordination | `$v3-swarm-coordination` | 15-agent hierarchical mesh coordination |\n| V3 DDD Architecture | `$v3-ddd-architecture` | Domain-Driven Design architecture |\n| V3 Core Implementation | `$v3-core-implementation` | Core module implementation |\n| V3 MCP Optimization | `$v3-mcp-optimization` | MCP server optimization and transport |\n| V3 CLI Modernization | `$v3-cli-modernization` | CLI modernization and hooks enhancement |\n\n#### AgentDB & Memory Skills\n\n| Skill | Syntax | Description |\n|-------|--------|-------------|\n| AgentDB Advanced | `$agentdb-advanced` | Advanced QUIC sync, distributed coordination |\n| AgentDB Memory Patterns | `$agentdb-memory-patterns` | Persistent memory patterns for AI agents |\n| AgentDB Learning | `$agentdb-learning` | AI learning plugins with AgentDB |\n| AgentDB Optimization | `$agentdb-optimization` | Quantization (4-32bit), performance tuning |\n| AgentDB Vector Search | `$agentdb-vector-search` | Semantic vector search with HNSW |\n| ReasoningBank AgentDB | `$reasoningbank-agentdb` | ReasoningBank with AgentDB integration |\n| ReasoningBank Intelligence | `$reasoningbank-intelligence` | Adaptive learning with ReasoningBank |\n\n#### Swarm & Coordination Skills\n\n| Skill | Syntax | Description |\n|-------|--------|-------------|\n| Swarm Orchestration | `$swarm-orchestration` | Multi-agent swarms with agentic-flow |\n| Swarm Advanced | `$swarm-advanced` | Advanced swarm patterns for research/analysis |\n| Hive Mind Advanced | `$hive-mind-advanced` | Collective intelligence system |\n| Stream Chain | `$stream-chain` | Stream-JSON chaining for multi-agent pipelines |\n| Worker Integration | `$worker-integration` | Background worker integration |\n| Worker Benchmarks | `$worker-benchmarks` | Worker performance benchmarks |\n\n#### GitHub Integration Skills\n\n| Skill | Syntax | Description |\n|-------|--------|-------------|\n| GitHub Code Review | `$github-code-review` | AI-powered code review swarms |\n| GitHub Project Management | `$github-project-management` | Swarm-coordinated project management |\n| GitHub Multi-Repo | `$github-multi-repo` | Multi-repository coordination |\n| GitHub Release Management | `$github-release-management` | Release orchestration with AI swarms |\n| GitHub Workflow Automation | `$github-workflow-automation` | GitHub Actions automation |\n\n#### SPARC Methodology Skills (30+)\n\n| Skill | Syntax | Description |\n|-------|--------|-------------|\n| SPARC Methodology | `$sparc-methodology` | Full SPARC workflow orchestration |\n| SPARC Specification | `$sparc:spec-pseudocode` | Capture full project context |\n| SPARC Architecture | `$sparc:architect` | System architecture design |\n| SPARC Coder | `$sparc:coder` | Clean, efficient code generation |\n| SPARC Tester | `$sparc:tester` | Comprehensive testing |\n| SPARC Reviewer | `$sparc:reviewer` | Code review and quality |\n| SPARC Debugger | `$sparc:debugger` | Runtime bug troubleshooting |\n| SPARC Optimizer | `$sparc:optimizer` | Refactor and modularize |\n| SPARC Documenter | `$sparc:documenter` | Documentation generation |\n| SPARC DevOps | `$sparc:devops` | DevOps automation |\n| SPARC Security Review | `$sparc:security-review` | Static/dynamic security analysis |\n| SPARC Integration | `$sparc:integration` | System integration |\n| SPARC MCP | `$sparc:mcp` | MCP integration management |\n\n#### Flow Nexus Skills\n\n| Skill | Syntax | Description |\n|-------|--------|-------------|\n| Flow Nexus Neural | `$flow-nexus-neural` | Neural network training in E2B sandboxes |\n| Flow Nexus Platform | `$flow-nexus-platform` | Platform management and authentication |\n| Flow Nexus Swarm | `$flow-nexus-swarm` | Cloud-based AI swarm deployment |\n| Flow Nexus Payments | `$flow-nexus:payments` | Credit management and billing |\n| Flow Nexus Challenges | `$flow-nexus:challenges` | Coding challenges and achievements |\n| Flow Nexus Sandbox | `$flow-nexus:sandbox` | E2B sandbox management |\n| Flow Nexus App Store | `$flow-nexus:app-store` | App publishing and deployment |\n| Flow Nexus Workflow | `$flow-nexus:workflow` | Event-driven workflow automation |\n\n#### Development Skills\n\n| Skill | Syntax | Description |\n|-------|--------|-------------|\n| Pair Programming | `$pair-programming` | AI-assisted pair programming |\n| Skill Builder | `$skill-builder` | Create new Claude Code Skills |\n| Verification Quality | `$verification-quality` | Truth scoring and quality verification |\n| Performance Analysis | `$performance-analysis` | Bottleneck detection and optimization |\n| Agentic Jujutsu | `$agentic-jujutsu` | Quantum-resistant version control |\n| Hooks Automation | `$hooks-automation` | Automated coordination and learning |\n\n#### Memory Management Skills\n\n| Skill | Syntax | Description |\n|-------|--------|-------------|\n| Memory Neural | `$memory:neural` | Neural pattern training |\n| Memory Usage | `$memory:memory-usage` | Memory usage analysis |\n| Memory Search | `$memory:memory-search` | Semantic memory search |\n| Memory Persist | `$memory:memory-persist` | Memory persistence |\n\n#### Monitoring & Analysis Skills\n\n| Skill | Syntax | Description |\n|-------|--------|-------------|\n| Real-Time View | `$monitoring:real-time-view` | Real-time monitoring |\n| Agent Metrics | `$monitoring:agent-metrics` | Agent performance metrics |\n| Swarm Monitor | `$monitoring:swarm-monitor` | Swarm activity monitoring |\n| Token Usage | `$analysis:token-usage` | Token usage optimization |\n| Performance Report | `$analysis:performance-report` | Performance reporting |\n| Bottleneck Detect | `$analysis:bottleneck-detect` | Bottleneck detection |\n\n#### Training Skills\n\n| Skill | Syntax | Description |\n|-------|--------|-------------|\n| Specialization | `$training:specialization` | Agent specialization training |\n| Neural Patterns | `$training:neural-patterns` | Neural pattern training |\n| Pattern Learn | `$training:pattern-learn` | Pattern learning |\n| Model Update | `$training:model-update` | Model updates |\n\n#### Automation & Optimization Skills\n\n| Skill | Syntax | Description |\n|-------|--------|-------------|\n| Self-Healing | `$automation:self-healing` | Self-healing workflows |\n| Smart Agents | `$automation:smart-agents` | Smart agent auto-spawning |\n| Session Memory | `$automation:session-memory` | Cross-session memory |\n| Cache Manage | `$optimization:cache-manage` | Cache management |\n| Parallel Execute | `$optimization:parallel-execute` | Parallel task execution |\n| Topology Optimize | `$optimization:topology-optimize` | Automatic topology selection |\n\n#### Hooks Skills (17 Hooks + 12 Workers)\n\n| Skill | Syntax | Description |\n|-------|--------|-------------|\n| Pre-Edit | `$hooks:pre-edit` | Context before editing |\n| Post-Edit | `$hooks:post-edit` | Record editing outcome |\n| Pre-Task | `$hooks:pre-task` | Record task start |\n| Post-Task | `$hooks:post-task` | Record task completion |\n| Session End | `$hooks:session-end` | End session and persist |\n\n#### Dual-Mode Skills (NEW)\n\n| Skill | Syntax | Description |\n|-------|--------|-------------|\n| Dual Spawn | `$dual-spawn` | Spawn parallel Codex workers from Claude Code |\n| Dual Coordinate | `$dual-coordinate` | Coordinate Claude Code + Codex execution |\n| Dual Collect | `$dual-collect` | Collect results from parallel Codex instances |\n\n### Custom Skills\n\nCreate custom skills in `.agents/skills/`:\n\n```\n.agents/skills/my-skill/\n└── SKILL.md\n```\n\n**SKILL.md format:**\n```markdown\n# My Custom Skill\n\nInstructions for what this skill does...\n\n## Usage\nInvoke with `$my-skill`\n```\n\n</details>\n\n---\n\n<details>\n<summary><b>Dual-Mode Integration (Claude Code + Codex)</b></summary>\n\n### Hybrid Execution Model\n\nRun Claude Code for interactive development and spawn headless Codex workers for parallel background tasks:\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│  CLAUDE CODE (interactive)  ←→  CODEX WORKERS (headless)        │\n│  - Main conversation         - Parallel background execution    │\n│  - Complex reasoning         - Bulk code generation            │\n│  - Architecture decisions    - Test execution                   │\n│  - Final integration         - File processing                  │\n└─────────────────────────────────────────────────────────────────┘\n```\n\n### Setup\n\n```bash\n# Initialize dual-mode\nnpx claude-flow@alpha init --dual\n\n# Creates both:\n# - CLAUDE.md (Claude Code configuration)\n# - AGENTS.md (Codex configuration)\n# - Shared .claude-flow/ runtime\n```\n\n### Spawning Parallel Codex Workers\n\nFrom Claude Code, spawn headless Codex instances:\n\n```bash\n# Spawn workers in parallel (each runs independently)\nclaude -p \"Analyze src/auth/ for security issues\" --session-id \"task-1\" &\nclaude -p \"Write unit tests for src/api/\" --session-id \"task-2\" &\nclaude -p \"Optimize database queries in src/db/\" --session-id \"task-3\" &\nwait  # Wait for all to complete\n```\n\n### Dual-Mode Skills\n\n| Skill | Platform | Description |\n|-------|----------|-------------|\n| `$dual-spawn` | Codex | Spawn parallel workers from orchestrator |\n| `$dual-coordinate` | Both | Coordinate cross-platform execution |\n| `$dual-collect` | Claude Code | Collect results from Codex workers |\n\n### Dual-Mode Agents\n\n| Agent | Type | Execution |\n|-------|------|-----------|\n| `codex-worker` | Worker | Headless background execution |\n| `codex-coordinator` | Coordinator | Manage parallel worker pool |\n| `dual-orchestrator` | Orchestrator | Route tasks to appropriate platform |\n\n### Task Routing Rules\n\n| Task Complexity | Platform | Reason |\n|----------------|----------|--------|\n| Simple (1-2 files) | Codex Headless | Fast, parallel |\n| Medium (3-5 files) | Claude Code | Needs context |\n| Complex (architecture) | Claude Code | Reasoning required |\n| Bulk operations | Codex Workers | Parallelize |\n| Final review | Claude Code | Integration |\n\n### Example Workflow\n\n```\n1. Claude Code receives complex feature request\n2. Designs architecture and creates plan\n3. Spawns 4 Codex workers:\n   - Worker 1: Implement data models\n   - Worker 2: Create API endpoints\n   - Worker 3: Write unit tests\n   - Worker 4: Generate documentation\n4. Workers execute in parallel (headless)\n5. Claude Code collects and integrates results\n6. Final review and refinement in Claude Code\n```\n\n### Memory Sharing\n\nBoth platforms share the same `.claude-flow/` runtime:\n\n```\n.claude-flow/\n├── data/\n│   └── memory.db      # Shared vector memory\n├── config.yaml        # Shared configuration\n└── sessions/          # Cross-platform sessions\n```\n\n### Benefits\n\n| Feature | Benefit |\n|---------|---------|\n| **Parallel Execution** | 4-8x faster for bulk tasks |\n| **Cost Optimization** | Route simple tasks to cheaper workers |\n| **Context Preservation** | Shared memory across platforms |\n| **Best of Both** | Interactive + batch processing |\n| **Unified Learning** | Patterns learned by both platforms |\n\n### CLI Commands (NEW in v3.0.0-alpha.8)\n\nThe `@claude-flow/codex` package now includes built-in dual-mode orchestration:\n\n```bash\n# List available collaboration templates\nnpx claude-flow-codex dual templates\n\n# Run a feature development swarm\nnpx claude-flow-codex dual run --template feature --task \"Add user authentication\"\n\n# Run a security audit swarm\nnpx claude-flow-codex dual run --template security --task \"src/auth/\"\n\n# Run a refactoring swarm\nnpx claude-flow-codex dual run --template refactor --task \"src/legacy/\"\n\n# Check collaboration status\nnpx claude-flow-codex dual status\n```\n\n### Codex Loop Runner\n\nCodex does not expose Claude Code's `ScheduleWakeup`, so `@claude-flow/codex` provides a process-based equivalent:\n\n```bash\n# Run Codex repeatedly until it creates .codex/loop/default.complete or reaches 10 iterations\nnpx claude-flow-codex loop run \"Fix failing tests and create the completion marker when done\"\n\n# Use command mode for recurring Ruflo workers or custom scripts\nnpx claude-flow-codex loop run --name testgaps --interval 270 --max-iterations 0 \\\n  --command \"npx claude-flow hooks worker dispatch --trigger testgaps\"\n\n# Inspect or stop a loop from another terminal\nnpx claude-flow-codex loop status --name testgaps\nnpx claude-flow-codex loop stop --name testgaps\n```\n\nLoop state is stored in `.codex/loop/<name>.json`; `loop stop` writes `.codex/loop/<name>.stop`, which the runner observes between iterations.\n\n### Pre-Built Templates\n\n| Template | Pipeline | Platforms |\n|----------|----------|-----------|\n| **feature** | architect → coder → tester → reviewer | Claude (architect, reviewer) + Codex (coder, tester) |\n| **security** | scanner → analyzer → fixer | Codex (scanner, fixer) + Claude (analyzer) |\n| **refactor** | analyzer → planner → refactorer → validator | Claude (analyzer, planner) + Codex (refactorer, validator) |\n\n### Programmatic API\n\n```typescript\nimport { DualModeOrchestrator, CollaborationTemplates } from '@claude-flow/codex';\n\n// Create orchestrator\nconst orchestrator = new DualModeOrchestrator({\n  projectPath: process.cwd(),\n  maxConcurrent: 4,\n  sharedNamespace: 'collaboration',\n  timeout: 300000,\n});\n\n// Listen to events\norchestrator.on('worker:started', ({ id, role }) => console.log(`Started: ${role}`));\norchestrator.on('worker:completed', ({ id }) => console.log(`Completed: ${id}`));\n\n// Run collaboration with a template\nconst workers = CollaborationTemplates.featureDevelopment('Add OAuth2 login');\nconst result = await orchestrator.runCollaboration(workers, 'Feature: OAuth2');\n\nconsole.log(`Success: ${result.success}`);\nconsole.log(`Duration: ${result.totalDuration}ms`);\nconsole.log(`Workers: ${result.workers.length}`);\n```\n\n</details>\n\n---\n\n<details>\n<summary><b>Configuration</b></summary>\n\n### .agents/config.toml\n\n```toml\n# Model configuration\nmodel = \"gpt-5.3\"\n\n# Approval policy: \"always\" | \"on-request\" | \"never\"\napproval_policy = \"on-request\"\n\n# Sandbox mode: \"read-only\" | \"workspace-write\" | \"danger-full-access\"\nsandbox_mode = \"workspace-write\"\n\n# Web search: \"off\" | \"cached\" | \"live\"\nweb_search = \"cached\"\n\n# MCP Servers\n[mcp_servers.claude-flow]\ncommand = \"npx\"\nargs = [\"claude-flow\", \"mcp\", \"start\"]\nenabled = true\n\n# Skills\n[[skills]]\npath = \".agents/skills/swarm-orchestration\"\nenabled = true\n\n[[skills]]\npath = \".agents/skills/memory-management\"\nenabled = true\n\n[[skills]]\npath = \".agents/skills/sparc-methodology\"\nenabled = true\n```\n\n### .codex/config.toml (Local Overrides)\n\n```toml\n# Local development overrides (gitignored)\n# These settings override .agents/config.toml\n\napproval_policy = \"never\"\nsandbox_mode = \"danger-full-access\"\nweb_search = \"live\"\n\n# Disable MCP in local if needed\n[mcp_servers.claude-flow]\nenabled = false\n```\n\n### Environment Variables\n\n```bash\n# Configuration paths\nCLAUDE_FLOW_CONFIG=./claude-flow.config.json\nCLAUDE_FLOW_MEMORY_PATH=./.claude-flow/data\n\n# Provider keys\nANTHROPIC_API_KEY=sk-ant-...\nOPENAI_API_KEY=sk-...\n\n# MCP settings\nCLAUDE_FLOW_MCP_PORT=3000\n```\n\n</details>\n\n---\n\n<details>\n<summary><b>Vector Search Details</b></summary>\n\n### Specifications\n\n| Property | Value |\n|----------|-------|\n| Embedding Dimensions | 384 |\n| Search Algorithm | HNSW |\n| Speed Improvement | 150x-12,500x faster |\n| Similarity Range | 0.0 - 1.0 |\n| Storage | SQLite with vector extension |\n| Model | all-MiniLM-L6-v2 |\n\n### Namespaces\n\n| Namespace | Purpose |\n|-----------|---------|\n| `patterns` | Successful code patterns |\n| `solutions` | Bug fixes and solutions |\n| `tasks` | Task completion records |\n| `coordination` | Swarm state |\n| `results` | Worker results |\n| `default` | General storage |\n\n### Example Searches\n\n```javascript\n// Find auth patterns\nmemory_search({ query: \"authentication JWT patterns\", namespace: \"patterns\" })\n\n// Find bug solutions\nmemory_search({ query: \"null pointer fix\", namespace: \"solutions\" })\n\n// Find past tasks\nmemory_search({ query: \"user profile API\", namespace: \"tasks\" })\n```\n\n</details>\n\n---\n\n<details>\n<summary><b>API Reference</b></summary>\n\n### CodexInitializer Class\n\n```typescript\nimport { CodexInitializer } from '@claude-flow/codex';\n\nclass CodexInitializer {\n  /**\n   * Initialize a Codex project\n   */\n  async initialize(options: CodexInitOptions): Promise<CodexInitResult>;\n\n  /**\n   * Preview what would be created without writing files\n   */\n  async dryRun(options: CodexInitOptions): Promise<string[]>;\n}\n```\n\n### initializeCodexProject Function\n\n```typescript\nimport { initializeCodexProject } from '@claude-flow/codex';\n\n/**\n * Quick initialization helper\n */\nasync function initializeCodexProject(\n  projectPath: string,\n  options?: Partial<CodexInitOptions>\n): Promise<CodexInitResult>;\n```\n\n### Types\n\n```typescript\ninterface CodexInitOptions {\n  /** Project directory path */\n  projectPath: string;\n  /** Template to use */\n  template?: 'minimal' | 'default' | 'full' | 'enterprise';\n  /** Specific skills to include */\n  skills?: string[];\n  /** Overwrite existing files */\n  force?: boolean;\n  /** Enable dual mode (Claude Code + Codex) */\n  dual?: boolean;\n}\n\ninterface CodexInitResult {\n  /** Whether initialization succeeded */\n  success: boolean;\n  /** List of files created */\n  filesCreated: string[];\n  /** List of skills generated */\n  skillsGenerated: string[];\n  /** Whether MCP was registered */\n  mcpRegistered?: boolean;\n  /** Non-fatal warnings */\n  warnings?: string[];\n  /** Fatal errors */\n  errors?: string[];\n}\n```\n\n### Programmatic Usage\n\n```typescript\nimport { CodexInitializer, initializeCodexProject } from '@claude-flow/codex';\n\n// Quick initialization\nconst result = await initializeCodexProject('/path/to/project', {\n  template: 'full',\n  force: true,\n  dual: false,\n});\n\nconsole.log(`Files created: ${result.filesCreated.length}`);\nconsole.log(`Skills: ${result.skillsGenerated.length}`);\nconsole.log(`MCP registered: ${result.mcpRegistered}`);\n\n// Or use the class directly\nconst initializer = new CodexInitializer();\nconst result = await initializer.initialize({\n  projectPath: '/path/to/project',\n  template: 'enterprise',\n  skills: ['swarm-orchestration', 'memory-management', 'security-audit'],\n  force: false,\n  dual: true,\n});\n\nif (result.warnings?.length) {\n  console.warn('Warnings:', result.warnings);\n}\n```\n\n</details>\n\n---\n\n<details>\n<summary><b>Migration from Claude Code</b></summary>\n\n### Convert CLAUDE.md to AGENTS.md\n\n```typescript\nimport { migrate } from '@claude-flow/codex';\n\nconst result = await migrate({\n  sourcePath: './CLAUDE.md',\n  targetPath: './AGENTS.md',\n  preserveComments: true,\n  generateSkills: true,\n});\n\nconsole.log(`Migrated: ${result.success}`);\nconsole.log(`Skills generated: ${result.skillsGenerated.length}`);\n```\n\n### Manual Migration Checklist\n\n1. **Rename config file**: `CLAUDE.md` → `AGENTS.md`\n2. **Move skills**: `.claude/skills/` → `.agents/skills/`\n3. **Update syntax**: `/skill-name` → `$skill-name`\n4. **Convert settings**: `settings.json` → `config.toml`\n5. **Register MCP**: `codex mcp add claude-flow -- npx claude-flow mcp start`\n\n### Dual Mode Alternative\n\nInstead of migrating, use dual mode to support both:\n\n```bash\nnpx claude-flow@alpha init --dual\n```\n\nThis keeps both `CLAUDE.md` and `AGENTS.md` in sync.\n\n</details>\n\n---\n\n<details>\n<summary><b>Troubleshooting</b></summary>\n\n### MCP Not Working\n\n```bash\n# Check if registered\ncodex mcp list\n\n# Re-register\ncodex mcp remove claude-flow\ncodex mcp add claude-flow -- npx claude-flow mcp start\n\n# Test connection\nnpx claude-flow mcp test\n```\n\n### Memory Search Returns Empty\n\n```bash\n# Initialize memory database\nnpx claude-flow memory init --force\n\n# Check if entries exist\nnpx claude-flow memory list\n\n# Manually add a test pattern\nnpx claude-flow memory store --key \"test\" --value \"test pattern\" --namespace patterns\n```\n\n### Skills Not Loading\n\n```bash\n# Verify skill directory\nls -la .agents/skills/\n\n# Check config.toml for skill registration\ncat .agents/config.toml | grep skills\n\n# Rebuild skills\nnpx claude-flow@alpha init --codex --force\n```\n\n### Vector Search Slow\n\n```bash\n# Check HNSW index\nnpx claude-flow memory stats\n\n# Rebuild index\nnpx claude-flow memory optimize --rebuild-index\n```\n\n</details>\n\n---\n\n## Related Packages\n\n| Package | Description |\n|---------|-------------|\n| [@claude-flow/cli](https://www.npmjs.com/package/@claude-flow/cli) | Main CLI (26 commands, 140+ subcommands) |\n| [claude-flow](https://www.npmjs.com/package/claude-flow) | Umbrella package |\n| [@claude-flow/memory](https://www.npmjs.com/package/@claude-flow/memory) | AgentDB with HNSW vector search |\n| [@claude-flow/security](https://www.npmjs.com/package/@claude-flow/security) | Security module |\n\n## License\n\nMIT\n\n## Support\n\n- Documentation: https://github.com/ruvnet/ruflo\n- Issues: https://github.com/ruvnet/ruflo/issues\n","readmeFilename":"README.md"}