@claude-flow/codex
OpenAI Codex CLI Adapter for Claude Flow V3
Self-learning multi-agent orchestration following the Agentics Foundation standard
Why @claude-flow/codex?
Transform OpenAI Codex CLI into a self-improving AI development system. While Codex executes code, claude-flow orchestrates, coordinates, and learns from every interaction.
| Traditional Codex |
With Claude-Flow |
| Stateless execution |
Persistent vector memory |
| Single-agent |
Multi-agent swarms (up to 15) |
| Manual coordination |
Automatic orchestration |
| No learning |
Self-learning patterns (HNSW) |
| One platform |
Dual-mode (Claude Code + Codex) |
Key Concept: Execution Model
Codex does the work. Claude-flow coordinates and learns.
The Self-Learning Loop
Quick Start
That's it! The MCP server is auto-registered, skills are installed, and your project is ready for self-learning development.
Features
| Feature |
Description |
| AGENTS.md Generation |
Creates project instructions for Codex |
| MCP Integration |
Self-learning via memory and vector search |
| 137+ Skills |
Invoke with $skill-name syntax |
| Vector Memory |
Semantic pattern search (384-dim embeddings) |
| Dual Platform |
Supports both Claude Code and Codex |
| Auto-Registration |
MCP server registered during init |
| HNSW Search |
150x-12,500x faster pattern matching |
| Self-Learning |
Learn from successes, remember patterns |
| GPT-5.3 Support |
Optimized for latest OpenAI models |
| Neural Training |
Train patterns with SONA architecture |
MCP Integration (Self-Learning)
Automatic Registration
When you run init --codex, the MCP server is automatically registered with Codex:
Manual Registration
If MCP is not present, add manually:
MCP Tools Reference
| Tool |
Purpose |
When to Use |
memory_search |
Semantic vector search |
BEFORE starting any task |
memory_store |
Save patterns with embeddings |
AFTER completing successfully |
swarm_init |
Initialize coordination |
Start of complex tasks |
agent_spawn |
Register agent roles |
Multi-agent workflows |
neural_train |
Train on patterns |
Periodic improvement |
Tool Parameters
memory_search
memory_store
swarm_init
Self-Learning Workflow
The 4-Step Pattern
Complete Example Prompt
Similarity Score Guide
| Score |
Meaning |
Action |
| > 0.7 |
Strong match |
Use the pattern directly |
| 0.5 - 0.7 |
Partial match |
Adapt and modify |
| < 0.5 |
Weak match |
Create new approach |
Directory Structure
Key Files
| File |
Purpose |
AGENTS.md |
Main instructions for Codex (required) |
.agents/config.toml |
Project-wide configuration |
.codex/config.toml |
Local overrides (gitignored) |
.claude-flow/data/memory.db |
Vector memory database |
Templates
Available Templates
| Template |
Skills |
Learning |
Best For |
minimal |
2 |
Basic |
Quick prototypes |
default |
4 |
Yes |
Standard projects |
full |
137+ |
Yes |
Full-featured development |
enterprise |
137+ |
Advanced |
Team environments |
Usage
Template Contents
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
Platform Comparison (Claude Code vs Codex)
| Feature |
Claude Code |
OpenAI Codex |
| Config File |
CLAUDE.md |
AGENTS.md |
| Skills Dir |
.claude/skills/ |
.agents/skills/ |
| Skill Syntax |
/skill-name |
$skill-name |
| Settings |
settings.json |
config.toml |
| MCP |
Native |
Via codex mcp add |
| Overrides |
.claude.local.md |
.codex/config.toml |
Dual Mode
Run init --dual to set up both platforms:
This creates:
CLAUDE.md for Claude Code users
AGENTS.md for Codex users
- Shared
.claude-flow/ runtime
- Cross-compatible skills
Skill Invocation
Syntax
In OpenAI Codex CLI, invoke skills with $ prefix:
Complete Skills Table (137+ Skills)
V3 Core Skills
| Skill |
Syntax |
Description |
| V3 Security Overhaul |
$v3-security-overhaul |
Complete security architecture with CVE remediation |
| V3 Memory Unification |
$v3-memory-unification |
Unify 6+ memory systems into AgentDB with HNSW |
| V3 Integration Deep |
$v3-integration-deep |
Deep agentic-flow@alpha integration (ADR-001) |
| V3 Performance Optimization |
$v3-performance-optimization |
Achieve 2.49x-7.47x speedup targets |
| V3 Swarm Coordination |
$v3-swarm-coordination |
15-agent hierarchical mesh coordination |
| V3 DDD Architecture |
$v3-ddd-architecture |
Domain-Driven Design architecture |
| V3 Core Implementation |
$v3-core-implementation |
Core module implementation |
| V3 MCP Optimization |
$v3-mcp-optimization |
MCP server optimization and transport |
| V3 CLI Modernization |
$v3-cli-modernization |
CLI modernization and hooks enhancement |
AgentDB & Memory Skills
| Skill |
Syntax |
Description |
| AgentDB Advanced |
$agentdb-advanced |
Advanced QUIC sync, distributed coordination |
| AgentDB Memory Patterns |
$agentdb-memory-patterns |
Persistent memory patterns for AI agents |
| AgentDB Learning |
$agentdb-learning |
AI learning plugins with AgentDB |
| AgentDB Optimization |
$agentdb-optimization |
Quantization (4-32bit), performance tuning |
| AgentDB Vector Search |
$agentdb-vector-search |
Semantic vector search with HNSW |
| ReasoningBank AgentDB |
$reasoningbank-agentdb |
ReasoningBank with AgentDB integration |
| ReasoningBank Intelligence |
$reasoningbank-intelligence |
Adaptive learning with ReasoningBank |
Swarm & Coordination Skills
| Skill |
Syntax |
Description |
| Swarm Orchestration |
$swarm-orchestration |
Multi-agent swarms with agentic-flow |
| Swarm Advanced |
$swarm-advanced |
Advanced swarm patterns for research/analysis |
| Hive Mind Advanced |
$hive-mind-advanced |
Collective intelligence system |
| Stream Chain |
$stream-chain |
Stream-JSON chaining for multi-agent pipelines |
| Worker Integration |
$worker-integration |
Background worker integration |
| Worker Benchmarks |
$worker-benchmarks |
Worker performance benchmarks |
GitHub Integration Skills
| Skill |
Syntax |
Description |
| GitHub Code Review |
$github-code-review |
AI-powered code review swarms |
| GitHub Project Management |
$github-project-management |
Swarm-coordinated project management |
| GitHub Multi-Repo |
$github-multi-repo |
Multi-repository coordination |
| GitHub Release Management |
$github-release-management |
Release orchestration with AI swarms |
| GitHub Workflow Automation |
$github-workflow-automation |
GitHub Actions automation |
SPARC Methodology Skills (30+)
| Skill |
Syntax |
Description |
| SPARC Methodology |
$sparc-methodology |
Full SPARC workflow orchestration |
| SPARC Specification |
$sparc:spec-pseudocode |
Capture full project context |
| SPARC Architecture |
$sparc:architect |
System architecture design |
| SPARC Coder |
$sparc:coder |
Clean, efficient code generation |
| SPARC Tester |
$sparc:tester |
Comprehensive testing |
| SPARC Reviewer |
$sparc:reviewer |
Code review and quality |
| SPARC Debugger |
$sparc:debugger |
Runtime bug troubleshooting |
| SPARC Optimizer |
$sparc:optimizer |
Refactor and modularize |
| SPARC Documenter |
$sparc:documenter |
Documentation generation |
| SPARC DevOps |
$sparc:devops |
DevOps automation |
| SPARC Security Review |
$sparc:security-review |
Static/dynamic security analysis |
| SPARC Integration |
$sparc:integration |
System integration |
| SPARC MCP |
$sparc:mcp |
MCP integration management |
Flow Nexus Skills
| Skill |
Syntax |
Description |
| Flow Nexus Neural |
$flow-nexus-neural |
Neural network training in E2B sandboxes |
| Flow Nexus Platform |
$flow-nexus-platform |
Platform management and authentication |
| Flow Nexus Swarm |
$flow-nexus-swarm |
Cloud-based AI swarm deployment |
| Flow Nexus Payments |
$flow-nexus:payments |
Credit management and billing |
| Flow Nexus Challenges |
$flow-nexus:challenges |
Coding challenges and achievements |
| Flow Nexus Sandbox |
$flow-nexus:sandbox |
E2B sandbox management |
| Flow Nexus App Store |
$flow-nexus:app-store |
App publishing and deployment |
| Flow Nexus Workflow |
$flow-nexus:workflow |
Event-driven workflow automation |
Development Skills
| Skill |
Syntax |
Description |
| Pair Programming |
$pair-programming |
AI-assisted pair programming |
| Skill Builder |
$skill-builder |
Create new Claude Code Skills |
| Verification Quality |
$verification-quality |
Truth scoring and quality verification |
| Performance Analysis |
$performance-analysis |
Bottleneck detection and optimization |
| Agentic Jujutsu |
$agentic-jujutsu |
Quantum-resistant version control |
| Hooks Automation |
$hooks-automation |
Automated coordination and learning |
Memory Management Skills
| Skill |
Syntax |
Description |
| Memory Neural |
$memory:neural |
Neural pattern training |
| Memory Usage |
$memory:memory-usage |
Memory usage analysis |
| Memory Search |
$memory:memory-search |
Semantic memory search |
| Memory Persist |
$memory:memory-persist |
Memory persistence |
Monitoring & Analysis Skills
| Skill |
Syntax |
Description |
| Real-Time View |
$monitoring:real-time-view |
Real-time monitoring |
| Agent Metrics |
$monitoring:agent-metrics |
Agent performance metrics |
| Swarm Monitor |
$monitoring:swarm-monitor |
Swarm activity monitoring |
| Token Usage |
$analysis:token-usage |
Token usage optimization |
| Performance Report |
$analysis:performance-report |
Performance reporting |
| Bottleneck Detect |
$analysis:bottleneck-detect |
Bottleneck detection |
Training Skills
| Skill |
Syntax |
Description |
| Specialization |
$training:specialization |
Agent specialization training |
| Neural Patterns |
$training:neural-patterns |
Neural pattern training |
| Pattern Learn |
$training:pattern-learn |
Pattern learning |
| Model Update |
$training:model-update |
Model updates |
Automation & Optimization Skills
| Skill |
Syntax |
Description |
| Self-Healing |
$automation:self-healing |
Self-healing workflows |
| Smart Agents |
$automation:smart-agents |
Smart agent auto-spawning |
| Session Memory |
$automation:session-memory |
Cross-session memory |
| Cache Manage |
$optimization:cache-manage |
Cache management |
| Parallel Execute |
$optimization:parallel-execute |
Parallel task execution |
| Topology Optimize |
$optimization:topology-optimize |
Automatic topology selection |
Hooks Skills (17 Hooks + 12 Workers)
| Skill |
Syntax |
Description |
| Pre-Edit |
$hooks:pre-edit |
Context before editing |
| Post-Edit |
$hooks:post-edit |
Record editing outcome |
| Pre-Task |
$hooks:pre-task |
Record task start |
| Post-Task |
$hooks:post-task |
Record task completion |
| Session End |
$hooks:session-end |
End session and persist |
Dual-Mode Skills (NEW)
| Skill |
Syntax |
Description |
| Dual Spawn |
$dual-spawn |
Spawn parallel Codex workers from Claude Code |
| Dual Coordinate |
$dual-coordinate |
Coordinate Claude Code + Codex execution |
| Dual Collect |
$dual-collect |
Collect results from parallel Codex instances |
Custom Skills
Create custom skills in .agents/skills/:
SKILL.md format:
Dual-Mode Integration (Claude Code + Codex)
Hybrid Execution Model
Run Claude Code for interactive development and spawn headless Codex workers for parallel background tasks:
Setup
Spawning Parallel Codex Workers
From Claude Code, spawn headless Codex instances:
Dual-Mode Skills
| Skill |
Platform |
Description |
$dual-spawn |
Codex |
Spawn parallel workers from orchestrator |
$dual-coordinate |
Both |
Coordinate cross-platform execution |
$dual-collect |
Claude Code |
Collect results from Codex workers |
Dual-Mode Agents
| Agent |
Type |
Execution |
codex-worker |
Worker |
Headless background execution |
codex-coordinator |
Coordinator |
Manage parallel worker pool |
dual-orchestrator |
Orchestrator |
Route tasks to appropriate platform |
Task Routing Rules
| Task Complexity |
Platform |
Reason |
| Simple (1-2 files) |
Codex Headless |
Fast, parallel |
| Medium (3-5 files) |
Claude Code |
Needs context |
| Complex (architecture) |
Claude Code |
Reasoning required |
| Bulk operations |
Codex Workers |
Parallelize |
| Final review |
Claude Code |
Integration |
Example Workflow
Memory Sharing
Both platforms share the same .claude-flow/ runtime:
Benefits
| Feature |
Benefit |
| Parallel Execution |
4-8x faster for bulk tasks |
| Cost Optimization |
Route simple tasks to cheaper workers |
| Context Preservation |
Shared memory across platforms |
| Best of Both |
Interactive + batch processing |
| Unified Learning |
Patterns learned by both platforms |
CLI Commands (NEW in v3.0.0-alpha.8)
The @claude-flow/codex package now includes built-in dual-mode orchestration:
Pre-Built Templates
| Template |
Pipeline |
Platforms |
| feature |
architect → coder → tester → reviewer |
Claude (architect, reviewer) + Codex (coder, tester) |
| security |
scanner → analyzer → fixer |
Codex (scanner, fixer) + Claude (analyzer) |
| refactor |
analyzer → planner → refactorer → validator |
Claude (analyzer, planner) + Codex (refactorer, validator) |
Programmatic API
Configuration
.agents/config.toml
.codex/config.toml (Local Overrides)
Environment Variables
Vector Search Details
Specifications
| Property |
Value |
| Embedding Dimensions |
384 |
| Search Algorithm |
HNSW |
| Speed Improvement |
150x-12,500x faster |
| Similarity Range |
0.0 - 1.0 |
| Storage |
SQLite with vector extension |
| Model |
all-MiniLM-L6-v2 |
Namespaces
| Namespace |
Purpose |
patterns |
Successful code patterns |
solutions |
Bug fixes and solutions |
tasks |
Task completion records |
coordination |
Swarm state |
results |
Worker results |
default |
General storage |
Example Searches
API Reference
CodexInitializer Class
initializeCodexProject Function
Types
Programmatic Usage
Migration from Claude Code
Convert CLAUDE.md to AGENTS.md
Manual Migration Checklist
- Rename config file:
CLAUDE.md → AGENTS.md
- Move skills:
.claude/skills/ → .agents/skills/
- Update syntax:
/skill-name → $skill-name
- Convert settings:
settings.json → config.toml
- Register MCP:
codex mcp add claude-flow -- npx claude-flow mcp start
Dual Mode Alternative
Instead of migrating, use dual mode to support both:
This keeps both CLAUDE.md and AGENTS.md in sync.
Troubleshooting
MCP Not Working
Memory Search Returns Empty
Skills Not Loading
Vector Search Slow
Related Packages
License
MIT
Support