@claude-flow/codex 3.0.0-alpha.2 → 3.0.0-alpha.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +692 -75
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # @claude-flow/codex
2
2
 
3
- OpenAI Codex CLI adapter for Claude Flow V3. Enables multi-agent orchestration with **self-learning capabilities** for OpenAI Codex CLI following the [Agentic AI Foundation](https://agenticfoundation.org) standard.
3
+ OpenAI Codex CLI adapter for Claude Flow V3. Enables multi-agent orchestration with **self-learning capabilities** for OpenAI Codex CLI following the [Agentics Foundation](https://agentics.org) standard.
4
4
 
5
5
  ## Key Concept: Execution Model
6
6
 
@@ -13,19 +13,10 @@ OpenAI Codex CLI adapter for Claude Flow V3. Enables multi-agent orchestration w
13
13
 
14
14
  **Codex does the work. Claude-flow coordinates and learns.**
15
15
 
16
- ## Features
17
-
18
- - **AGENTS.md Generation** - Creates project instructions for Codex
19
- - **MCP Integration** - Self-learning via memory and vector search
20
- - **137+ Skills** - Invoke with `$skill-name` syntax
21
- - **Vector Memory** - Semantic pattern search (384-dim embeddings)
22
- - **Dual Platform** - Supports both Claude Code and Codex
23
- - **Auto-Registration** - MCP server registered during init
24
-
25
- ## Installation
16
+ ## Quick Start
26
17
 
27
18
  ```bash
28
- # Via claude-flow CLI (recommended)
19
+ # Initialize for Codex (recommended)
29
20
  npx claude-flow@alpha init --codex
30
21
 
31
22
  # Full setup with all 137+ skills
@@ -35,7 +26,30 @@ npx claude-flow@alpha init --codex --full
35
26
  npx claude-flow@alpha init --dual
36
27
  ```
37
28
 
38
- ## MCP Integration (Self-Learning)
29
+ ---
30
+
31
+ <details>
32
+ <summary><b>Features</b></summary>
33
+
34
+ | Feature | Description |
35
+ |---------|-------------|
36
+ | **AGENTS.md Generation** | Creates project instructions for Codex |
37
+ | **MCP Integration** | Self-learning via memory and vector search |
38
+ | **137+ Skills** | Invoke with `$skill-name` syntax |
39
+ | **Vector Memory** | Semantic pattern search (384-dim embeddings) |
40
+ | **Dual Platform** | Supports both Claude Code and Codex |
41
+ | **Auto-Registration** | MCP server registered during init |
42
+ | **HNSW Search** | 150x-12,500x faster pattern matching |
43
+ | **Self-Learning** | Learn from successes, remember patterns |
44
+
45
+ </details>
46
+
47
+ ---
48
+
49
+ <details>
50
+ <summary><b>MCP Integration (Self-Learning)</b></summary>
51
+
52
+ ### Automatic Registration
39
53
 
40
54
  When you run `init --codex`, the MCP server is **automatically registered** with Codex:
41
55
 
@@ -43,34 +57,76 @@ When you run `init --codex`, the MCP server is **automatically registered** with
43
57
  # Verify MCP is registered
44
58
  codex mcp list
45
59
 
46
- # Expected:
60
+ # Expected output:
47
61
  # Name Command Args Status
48
62
  # claude-flow npx claude-flow mcp start enabled
63
+ ```
49
64
 
50
- # If not present, add manually:
65
+ ### Manual Registration
66
+
67
+ If MCP is not present, add manually:
68
+
69
+ ```bash
51
70
  codex mcp add claude-flow -- npx claude-flow mcp start
52
71
  ```
53
72
 
54
- ### MCP Tools for Learning
73
+ ### MCP Tools Reference
55
74
 
56
75
  | Tool | Purpose | When to Use |
57
76
  |------|---------|-------------|
58
- | `memory_search` | Semantic vector search | BEFORE starting any task |
59
- | `memory_store` | Save patterns with embeddings | AFTER completing successfully |
77
+ | `memory_search` | Semantic vector search | **BEFORE** starting any task |
78
+ | `memory_store` | Save patterns with embeddings | **AFTER** completing successfully |
60
79
  | `swarm_init` | Initialize coordination | Start of complex tasks |
61
80
  | `agent_spawn` | Register agent roles | Multi-agent workflows |
62
81
  | `neural_train` | Train on patterns | Periodic improvement |
63
82
 
64
- ## Self-Learning Workflow
83
+ ### Tool Parameters
84
+
85
+ **memory_search**
86
+ ```json
87
+ {
88
+ "query": "search terms",
89
+ "namespace": "patterns",
90
+ "limit": 5
91
+ }
92
+ ```
93
+
94
+ **memory_store**
95
+ ```json
96
+ {
97
+ "key": "pattern-name",
98
+ "value": "what worked",
99
+ "namespace": "patterns",
100
+ "upsert": true
101
+ }
102
+ ```
103
+
104
+ **swarm_init**
105
+ ```json
106
+ {
107
+ "topology": "hierarchical",
108
+ "maxAgents": 5,
109
+ "strategy": "specialized"
110
+ }
111
+ ```
112
+
113
+ </details>
114
+
115
+ ---
116
+
117
+ <details>
118
+ <summary><b>Self-Learning Workflow</b></summary>
119
+
120
+ ### The 4-Step Pattern
65
121
 
66
122
  ```
67
- 1. LEARN: memory_search(query="task keywords") → Find similar patterns
68
- 2. COORD: swarm_init(topology="hierarchical") → Set up coordination
69
- 3. EXECUTE: YOU write code, run commands → Codex does real work
70
- 4. REMEMBER: memory_store(key, value, namespace="patterns") → Save for future
123
+ 1. LEARN: memory_search(query="task keywords") → Find similar patterns
124
+ 2. COORD: swarm_init(topology="hierarchical") → Set up coordination
125
+ 3. EXECUTE: YOU write code, run commands → Codex does real work
126
+ 4. REMEMBER: memory_store(key, value, upsert=true) → Save for future
71
127
  ```
72
128
 
73
- ### Example Prompt for Codex
129
+ ### Complete Example Prompt
74
130
 
75
131
  ```
76
132
  Build an email validator using a learning-enabled swarm.
@@ -85,7 +141,7 @@ STEP 2 - COORDINATE (use MCP tools):
85
141
  Use tool: swarm_init with topology="hierarchical", maxAgents=3
86
142
  Use tool: agent_spawn with type="coder", name="validator"
87
143
 
88
- STEP 3 - EXECUTE (YOU do this):
144
+ STEP 3 - EXECUTE (YOU do this - DON'T STOP HERE):
89
145
  Create /tmp/validator/email.js with validateEmail() function
90
146
  Create /tmp/validator/test.js with test cases
91
147
  Run the tests
@@ -95,53 +151,146 @@ Use tool: memory_store
95
151
  key: "pattern-email-validator"
96
152
  value: "Email validation: regex, returns boolean, test cases"
97
153
  namespace: "patterns"
154
+ upsert: true
98
155
 
99
- YOU execute all code. Use MCP tools for learning.
156
+ YOU execute all code. MCP tools are for learning only.
100
157
  ```
101
158
 
102
- ## Directory Structure
159
+ ### Similarity Score Guide
160
+
161
+ | Score | Meaning | Action |
162
+ |-------|---------|--------|
163
+ | > 0.7 | Strong match | Use the pattern directly |
164
+ | 0.5 - 0.7 | Partial match | Adapt and modify |
165
+ | < 0.5 | Weak match | Create new approach |
166
+
167
+ </details>
168
+
169
+ ---
170
+
171
+ <details>
172
+ <summary><b>Directory Structure</b></summary>
103
173
 
104
174
  ```
105
175
  project/
106
- ├── AGENTS.md # Main project instructions (Codex format)
176
+ ├── AGENTS.md # Main project instructions (Codex format)
107
177
  ├── .agents/
108
- │ ├── config.toml # Project configuration
109
- │ ├── skills/ # 137+ skills
178
+ │ ├── config.toml # Project configuration
179
+ │ ├── skills/ # 137+ skills
110
180
  │ │ ├── swarm-orchestration/
111
181
  │ │ │ └── SKILL.md
112
182
  │ │ ├── memory-management/
113
183
  │ │ │ └── SKILL.md
184
+ │ │ ├── sparc-methodology/
185
+ │ │ │ └── SKILL.md
114
186
  │ │ └── ...
115
- │ └── README.md # Directory documentation
116
- ├── .codex/
117
- │ ├── config.toml # Local overrides (gitignored)
118
- │ └── AGENTS.override.md # Local instruction overrides
119
- └── .claude-flow/
120
- ├── config.yaml # Runtime configuration
121
- ├── data/ # Memory and cache
122
- └── logs/ # Log files
187
+ │ └── README.md # Directory documentation
188
+ ├── .codex/ # Local overrides (gitignored)
189
+ │ ├── config.toml # Local development settings
190
+ │ └── AGENTS.override.md # Local instruction overrides
191
+ └── .claude-flow/ # Runtime data
192
+ ├── config.yaml # Runtime configuration
193
+ ├── data/ # Memory and cache
194
+ │ └── memory.db # SQLite with vector embeddings
195
+ └── logs/ # Log files
123
196
  ```
124
197
 
125
- ## Templates
198
+ ### Key Files
199
+
200
+ | File | Purpose |
201
+ |------|---------|
202
+ | `AGENTS.md` | Main instructions for Codex (required) |
203
+ | `.agents/config.toml` | Project-wide configuration |
204
+ | `.codex/config.toml` | Local overrides (gitignored) |
205
+ | `.claude-flow/data/memory.db` | Vector memory database |
206
+
207
+ </details>
208
+
209
+ ---
210
+
211
+ <details>
212
+ <summary><b>Templates</b></summary>
213
+
214
+ ### Available Templates
215
+
216
+ | Template | Skills | Learning | Best For |
217
+ |----------|--------|----------|----------|
218
+ | `minimal` | 2 | Basic | Quick prototypes |
219
+ | `default` | 4 | Yes | Standard projects |
220
+ | `full` | 137+ | Yes | Full-featured development |
221
+ | `enterprise` | 137+ | Advanced | Team environments |
222
+
223
+ ### Usage
224
+
225
+ ```bash
226
+ # Minimal (fastest init)
227
+ npx claude-flow@alpha init --codex --minimal
228
+
229
+ # Default
230
+ npx claude-flow@alpha init --codex
231
+
232
+ # Full (all skills)
233
+ npx claude-flow@alpha init --codex --full
234
+ ```
235
+
236
+ ### Template Contents
237
+
238
+ **Minimal:**
239
+ - Core swarm orchestration
240
+ - Basic memory management
126
241
 
127
- | Template | Skills | Learning | Description |
128
- |----------|--------|----------|-------------|
129
- | `minimal` | 2 | Basic | Core skills only |
130
- | `default` | 4 | Yes | Standard setup |
131
- | `full` | 137+ | Yes | All available skills |
132
- | `enterprise` | 137+ | Advanced | Full + governance |
242
+ **Default:**
243
+ - Swarm orchestration
244
+ - Memory management
245
+ - SPARC methodology
246
+ - Basic coding patterns
133
247
 
134
- ## Platform Comparison
248
+ **Full:**
249
+ - All 137+ skills
250
+ - GitHub integration
251
+ - Security scanning
252
+ - Performance optimization
253
+ - AgentDB vector search
254
+ - Neural pattern training
255
+
256
+ </details>
257
+
258
+ ---
259
+
260
+ <details>
261
+ <summary><b>Platform Comparison (Claude Code vs Codex)</b></summary>
135
262
 
136
263
  | Feature | Claude Code | OpenAI Codex |
137
264
  |---------|-------------|--------------|
138
- | Config File | CLAUDE.md | AGENTS.md |
139
- | Skills Dir | .claude/skills/ | .agents/skills/ |
265
+ | Config File | `CLAUDE.md` | `AGENTS.md` |
266
+ | Skills Dir | `.claude/skills/` | `.agents/skills/` |
140
267
  | Skill Syntax | `/skill-name` | `$skill-name` |
141
- | Settings | settings.json | config.toml |
268
+ | Settings | `settings.json` | `config.toml` |
142
269
  | MCP | Native | Via `codex mcp add` |
270
+ | Overrides | `.claude.local.md` | `.codex/config.toml` |
271
+
272
+ ### Dual Mode
273
+
274
+ Run `init --dual` to set up both platforms:
275
+
276
+ ```bash
277
+ npx claude-flow@alpha init --dual
278
+ ```
279
+
280
+ This creates:
281
+ - `CLAUDE.md` for Claude Code users
282
+ - `AGENTS.md` for Codex users
283
+ - Shared `.claude-flow/` runtime
284
+ - Cross-compatible skills
285
+
286
+ </details>
287
+
288
+ ---
143
289
 
144
- ## Skill Invocation
290
+ <details>
291
+ <summary><b>Skill Invocation</b></summary>
292
+
293
+ ### Syntax
145
294
 
146
295
  In OpenAI Codex CLI, invoke skills with `$` prefix:
147
296
 
@@ -152,22 +301,308 @@ $sparc-methodology
152
301
  $security-audit
153
302
  $agent-coder
154
303
  $agent-tester
304
+ $github-workflow
305
+ $performance-optimization
306
+ ```
307
+
308
+ ### Complete Skills Table (137+ Skills)
309
+
310
+ #### V3 Core Skills
311
+
312
+ | Skill | Syntax | Description |
313
+ |-------|--------|-------------|
314
+ | V3 Security Overhaul | `$v3-security-overhaul` | Complete security architecture with CVE remediation |
315
+ | V3 Memory Unification | `$v3-memory-unification` | Unify 6+ memory systems into AgentDB with HNSW |
316
+ | V3 Integration Deep | `$v3-integration-deep` | Deep agentic-flow@alpha integration (ADR-001) |
317
+ | V3 Performance Optimization | `$v3-performance-optimization` | Achieve 2.49x-7.47x speedup targets |
318
+ | V3 Swarm Coordination | `$v3-swarm-coordination` | 15-agent hierarchical mesh coordination |
319
+ | V3 DDD Architecture | `$v3-ddd-architecture` | Domain-Driven Design architecture |
320
+ | V3 Core Implementation | `$v3-core-implementation` | Core module implementation |
321
+ | V3 MCP Optimization | `$v3-mcp-optimization` | MCP server optimization and transport |
322
+ | V3 CLI Modernization | `$v3-cli-modernization` | CLI modernization and hooks enhancement |
323
+
324
+ #### AgentDB & Memory Skills
325
+
326
+ | Skill | Syntax | Description |
327
+ |-------|--------|-------------|
328
+ | AgentDB Advanced | `$agentdb-advanced` | Advanced QUIC sync, distributed coordination |
329
+ | AgentDB Memory Patterns | `$agentdb-memory-patterns` | Persistent memory patterns for AI agents |
330
+ | AgentDB Learning | `$agentdb-learning` | AI learning plugins with AgentDB |
331
+ | AgentDB Optimization | `$agentdb-optimization` | Quantization (4-32bit), performance tuning |
332
+ | AgentDB Vector Search | `$agentdb-vector-search` | Semantic vector search with HNSW |
333
+ | ReasoningBank AgentDB | `$reasoningbank-agentdb` | ReasoningBank with AgentDB integration |
334
+ | ReasoningBank Intelligence | `$reasoningbank-intelligence` | Adaptive learning with ReasoningBank |
335
+
336
+ #### Swarm & Coordination Skills
337
+
338
+ | Skill | Syntax | Description |
339
+ |-------|--------|-------------|
340
+ | Swarm Orchestration | `$swarm-orchestration` | Multi-agent swarms with agentic-flow |
341
+ | Swarm Advanced | `$swarm-advanced` | Advanced swarm patterns for research/analysis |
342
+ | Hive Mind Advanced | `$hive-mind-advanced` | Collective intelligence system |
343
+ | Stream Chain | `$stream-chain` | Stream-JSON chaining for multi-agent pipelines |
344
+ | Worker Integration | `$worker-integration` | Background worker integration |
345
+ | Worker Benchmarks | `$worker-benchmarks` | Worker performance benchmarks |
346
+
347
+ #### GitHub Integration Skills
348
+
349
+ | Skill | Syntax | Description |
350
+ |-------|--------|-------------|
351
+ | GitHub Code Review | `$github-code-review` | AI-powered code review swarms |
352
+ | GitHub Project Management | `$github-project-management` | Swarm-coordinated project management |
353
+ | GitHub Multi-Repo | `$github-multi-repo` | Multi-repository coordination |
354
+ | GitHub Release Management | `$github-release-management` | Release orchestration with AI swarms |
355
+ | GitHub Workflow Automation | `$github-workflow-automation` | GitHub Actions automation |
356
+
357
+ #### SPARC Methodology Skills (30+)
358
+
359
+ | Skill | Syntax | Description |
360
+ |-------|--------|-------------|
361
+ | SPARC Methodology | `$sparc-methodology` | Full SPARC workflow orchestration |
362
+ | SPARC Specification | `$sparc:spec-pseudocode` | Capture full project context |
363
+ | SPARC Architecture | `$sparc:architect` | System architecture design |
364
+ | SPARC Coder | `$sparc:coder` | Clean, efficient code generation |
365
+ | SPARC Tester | `$sparc:tester` | Comprehensive testing |
366
+ | SPARC Reviewer | `$sparc:reviewer` | Code review and quality |
367
+ | SPARC Debugger | `$sparc:debugger` | Runtime bug troubleshooting |
368
+ | SPARC Optimizer | `$sparc:optimizer` | Refactor and modularize |
369
+ | SPARC Documenter | `$sparc:documenter` | Documentation generation |
370
+ | SPARC DevOps | `$sparc:devops` | DevOps automation |
371
+ | SPARC Security Review | `$sparc:security-review` | Static/dynamic security analysis |
372
+ | SPARC Integration | `$sparc:integration` | System integration |
373
+ | SPARC MCP | `$sparc:mcp` | MCP integration management |
374
+
375
+ #### Flow Nexus Skills
376
+
377
+ | Skill | Syntax | Description |
378
+ |-------|--------|-------------|
379
+ | Flow Nexus Neural | `$flow-nexus-neural` | Neural network training in E2B sandboxes |
380
+ | Flow Nexus Platform | `$flow-nexus-platform` | Platform management and authentication |
381
+ | Flow Nexus Swarm | `$flow-nexus-swarm` | Cloud-based AI swarm deployment |
382
+ | Flow Nexus Payments | `$flow-nexus:payments` | Credit management and billing |
383
+ | Flow Nexus Challenges | `$flow-nexus:challenges` | Coding challenges and achievements |
384
+ | Flow Nexus Sandbox | `$flow-nexus:sandbox` | E2B sandbox management |
385
+ | Flow Nexus App Store | `$flow-nexus:app-store` | App publishing and deployment |
386
+ | Flow Nexus Workflow | `$flow-nexus:workflow` | Event-driven workflow automation |
387
+
388
+ #### Development Skills
389
+
390
+ | Skill | Syntax | Description |
391
+ |-------|--------|-------------|
392
+ | Pair Programming | `$pair-programming` | AI-assisted pair programming |
393
+ | Skill Builder | `$skill-builder` | Create new Claude Code Skills |
394
+ | Verification Quality | `$verification-quality` | Truth scoring and quality verification |
395
+ | Performance Analysis | `$performance-analysis` | Bottleneck detection and optimization |
396
+ | Agentic Jujutsu | `$agentic-jujutsu` | Quantum-resistant version control |
397
+ | Hooks Automation | `$hooks-automation` | Automated coordination and learning |
398
+
399
+ #### Memory Management Skills
400
+
401
+ | Skill | Syntax | Description |
402
+ |-------|--------|-------------|
403
+ | Memory Neural | `$memory:neural` | Neural pattern training |
404
+ | Memory Usage | `$memory:memory-usage` | Memory usage analysis |
405
+ | Memory Search | `$memory:memory-search` | Semantic memory search |
406
+ | Memory Persist | `$memory:memory-persist` | Memory persistence |
407
+
408
+ #### Monitoring & Analysis Skills
409
+
410
+ | Skill | Syntax | Description |
411
+ |-------|--------|-------------|
412
+ | Real-Time View | `$monitoring:real-time-view` | Real-time monitoring |
413
+ | Agent Metrics | `$monitoring:agent-metrics` | Agent performance metrics |
414
+ | Swarm Monitor | `$monitoring:swarm-monitor` | Swarm activity monitoring |
415
+ | Token Usage | `$analysis:token-usage` | Token usage optimization |
416
+ | Performance Report | `$analysis:performance-report` | Performance reporting |
417
+ | Bottleneck Detect | `$analysis:bottleneck-detect` | Bottleneck detection |
418
+
419
+ #### Training Skills
420
+
421
+ | Skill | Syntax | Description |
422
+ |-------|--------|-------------|
423
+ | Specialization | `$training:specialization` | Agent specialization training |
424
+ | Neural Patterns | `$training:neural-patterns` | Neural pattern training |
425
+ | Pattern Learn | `$training:pattern-learn` | Pattern learning |
426
+ | Model Update | `$training:model-update` | Model updates |
427
+
428
+ #### Automation & Optimization Skills
429
+
430
+ | Skill | Syntax | Description |
431
+ |-------|--------|-------------|
432
+ | Self-Healing | `$automation:self-healing` | Self-healing workflows |
433
+ | Smart Agents | `$automation:smart-agents` | Smart agent auto-spawning |
434
+ | Session Memory | `$automation:session-memory` | Cross-session memory |
435
+ | Cache Manage | `$optimization:cache-manage` | Cache management |
436
+ | Parallel Execute | `$optimization:parallel-execute` | Parallel task execution |
437
+ | Topology Optimize | `$optimization:topology-optimize` | Automatic topology selection |
438
+
439
+ #### Hooks Skills (17 Hooks + 12 Workers)
440
+
441
+ | Skill | Syntax | Description |
442
+ |-------|--------|-------------|
443
+ | Pre-Edit | `$hooks:pre-edit` | Context before editing |
444
+ | Post-Edit | `$hooks:post-edit` | Record editing outcome |
445
+ | Pre-Task | `$hooks:pre-task` | Record task start |
446
+ | Post-Task | `$hooks:post-task` | Record task completion |
447
+ | Session End | `$hooks:session-end` | End session and persist |
448
+
449
+ #### Dual-Mode Skills (NEW)
450
+
451
+ | Skill | Syntax | Description |
452
+ |-------|--------|-------------|
453
+ | Dual Spawn | `$dual-spawn` | Spawn parallel Codex workers from Claude Code |
454
+ | Dual Coordinate | `$dual-coordinate` | Coordinate Claude Code + Codex execution |
455
+ | Dual Collect | `$dual-collect` | Collect results from parallel Codex instances |
456
+
457
+ ### Custom Skills
458
+
459
+ Create custom skills in `.agents/skills/`:
460
+
461
+ ```
462
+ .agents/skills/my-skill/
463
+ └── SKILL.md
155
464
  ```
156
465
 
157
- ## Configuration
466
+ **SKILL.md format:**
467
+ ```markdown
468
+ # My Custom Skill
469
+
470
+ Instructions for what this skill does...
471
+
472
+ ## Usage
473
+ Invoke with `$my-skill`
474
+ ```
475
+
476
+ </details>
477
+
478
+ ---
479
+
480
+ <details>
481
+ <summary><b>Dual-Mode Integration (Claude Code + Codex)</b></summary>
482
+
483
+ ### Hybrid Execution Model
484
+
485
+ Run Claude Code for interactive development and spawn headless Codex workers for parallel background tasks:
486
+
487
+ ```
488
+ ┌─────────────────────────────────────────────────────────────────┐
489
+ │ CLAUDE CODE (interactive) ←→ CODEX WORKERS (headless) │
490
+ │ - Main conversation - Parallel background execution │
491
+ │ - Complex reasoning - Bulk code generation │
492
+ │ - Architecture decisions - Test execution │
493
+ │ - Final integration - File processing │
494
+ └─────────────────────────────────────────────────────────────────┘
495
+ ```
496
+
497
+ ### Setup
498
+
499
+ ```bash
500
+ # Initialize dual-mode
501
+ npx claude-flow@alpha init --dual
502
+
503
+ # Creates both:
504
+ # - CLAUDE.md (Claude Code configuration)
505
+ # - AGENTS.md (Codex configuration)
506
+ # - Shared .claude-flow/ runtime
507
+ ```
508
+
509
+ ### Spawning Parallel Codex Workers
510
+
511
+ From Claude Code, spawn headless Codex instances:
512
+
513
+ ```bash
514
+ # Spawn workers in parallel (each runs independently)
515
+ claude -p "Analyze src/auth/ for security issues" --session-id "task-1" &
516
+ claude -p "Write unit tests for src/api/" --session-id "task-2" &
517
+ claude -p "Optimize database queries in src/db/" --session-id "task-3" &
518
+ wait # Wait for all to complete
519
+ ```
520
+
521
+ ### Dual-Mode Skills
522
+
523
+ | Skill | Platform | Description |
524
+ |-------|----------|-------------|
525
+ | `$dual-spawn` | Codex | Spawn parallel workers from orchestrator |
526
+ | `$dual-coordinate` | Both | Coordinate cross-platform execution |
527
+ | `$dual-collect` | Claude Code | Collect results from Codex workers |
528
+
529
+ ### Dual-Mode Agents
530
+
531
+ | Agent | Type | Execution |
532
+ |-------|------|-----------|
533
+ | `codex-worker` | Worker | Headless background execution |
534
+ | `codex-coordinator` | Coordinator | Manage parallel worker pool |
535
+ | `dual-orchestrator` | Orchestrator | Route tasks to appropriate platform |
536
+
537
+ ### Task Routing Rules
538
+
539
+ | Task Complexity | Platform | Reason |
540
+ |----------------|----------|--------|
541
+ | Simple (1-2 files) | Codex Headless | Fast, parallel |
542
+ | Medium (3-5 files) | Claude Code | Needs context |
543
+ | Complex (architecture) | Claude Code | Reasoning required |
544
+ | Bulk operations | Codex Workers | Parallelize |
545
+ | Final review | Claude Code | Integration |
546
+
547
+ ### Example Workflow
548
+
549
+ ```
550
+ 1. Claude Code receives complex feature request
551
+ 2. Designs architecture and creates plan
552
+ 3. Spawns 4 Codex workers:
553
+ - Worker 1: Implement data models
554
+ - Worker 2: Create API endpoints
555
+ - Worker 3: Write unit tests
556
+ - Worker 4: Generate documentation
557
+ 4. Workers execute in parallel (headless)
558
+ 5. Claude Code collects and integrates results
559
+ 6. Final review and refinement in Claude Code
560
+ ```
561
+
562
+ ### Memory Sharing
563
+
564
+ Both platforms share the same `.claude-flow/` runtime:
565
+
566
+ ```
567
+ .claude-flow/
568
+ ├── data/
569
+ │ └── memory.db # Shared vector memory
570
+ ├── config.yaml # Shared configuration
571
+ └── sessions/ # Cross-platform sessions
572
+ ```
573
+
574
+ ### Benefits
575
+
576
+ | Feature | Benefit |
577
+ |---------|---------|
578
+ | **Parallel Execution** | 4-8x faster for bulk tasks |
579
+ | **Cost Optimization** | Route simple tasks to cheaper workers |
580
+ | **Context Preservation** | Shared memory across platforms |
581
+ | **Best of Both** | Interactive + batch processing |
582
+ | **Unified Learning** | Patterns learned by both platforms |
583
+
584
+ </details>
585
+
586
+ ---
587
+
588
+ <details>
589
+ <summary><b>Configuration</b></summary>
158
590
 
159
591
  ### .agents/config.toml
160
592
 
161
593
  ```toml
162
594
  # Model configuration
163
- model = "gpt-4"
595
+ model = "gpt-5.3"
164
596
 
165
- # Approval policy
597
+ # Approval policy: "always" | "on-request" | "never"
166
598
  approval_policy = "on-request"
167
599
 
168
- # Sandbox mode
600
+ # Sandbox mode: "read-only" | "workspace-write" | "danger-full-access"
169
601
  sandbox_mode = "workspace-write"
170
602
 
603
+ # Web search: "off" | "cached" | "live"
604
+ web_search = "cached"
605
+
171
606
  # MCP Servers
172
607
  [mcp_servers.claude-flow]
173
608
  command = "npx"
@@ -182,31 +617,117 @@ enabled = true
182
617
  [[skills]]
183
618
  path = ".agents/skills/memory-management"
184
619
  enabled = true
620
+
621
+ [[skills]]
622
+ path = ".agents/skills/sparc-methodology"
623
+ enabled = true
185
624
  ```
186
625
 
187
- ### .codex/config.toml (Local)
626
+ ### .codex/config.toml (Local Overrides)
188
627
 
189
628
  ```toml
190
629
  # Local development overrides (gitignored)
630
+ # These settings override .agents/config.toml
631
+
191
632
  approval_policy = "never"
192
633
  sandbox_mode = "danger-full-access"
193
634
  web_search = "live"
635
+
636
+ # Disable MCP in local if needed
637
+ [mcp_servers.claude-flow]
638
+ enabled = false
194
639
  ```
195
640
 
196
- ## API Reference
641
+ ### Environment Variables
197
642
 
198
- ### CodexInitializer
643
+ ```bash
644
+ # Configuration paths
645
+ CLAUDE_FLOW_CONFIG=./claude-flow.config.json
646
+ CLAUDE_FLOW_MEMORY_PATH=./.claude-flow/data
647
+
648
+ # Provider keys
649
+ ANTHROPIC_API_KEY=sk-ant-...
650
+ OPENAI_API_KEY=sk-...
651
+
652
+ # MCP settings
653
+ CLAUDE_FLOW_MCP_PORT=3000
654
+ ```
655
+
656
+ </details>
657
+
658
+ ---
659
+
660
+ <details>
661
+ <summary><b>Vector Search Details</b></summary>
662
+
663
+ ### Specifications
664
+
665
+ | Property | Value |
666
+ |----------|-------|
667
+ | Embedding Dimensions | 384 |
668
+ | Search Algorithm | HNSW |
669
+ | Speed Improvement | 150x-12,500x faster |
670
+ | Similarity Range | 0.0 - 1.0 |
671
+ | Storage | SQLite with vector extension |
672
+ | Model | all-MiniLM-L6-v2 |
673
+
674
+ ### Namespaces
675
+
676
+ | Namespace | Purpose |
677
+ |-----------|---------|
678
+ | `patterns` | Successful code patterns |
679
+ | `solutions` | Bug fixes and solutions |
680
+ | `tasks` | Task completion records |
681
+ | `coordination` | Swarm state |
682
+ | `results` | Worker results |
683
+ | `default` | General storage |
684
+
685
+ ### Example Searches
686
+
687
+ ```javascript
688
+ // Find auth patterns
689
+ memory_search({ query: "authentication JWT patterns", namespace: "patterns" })
690
+
691
+ // Find bug solutions
692
+ memory_search({ query: "null pointer fix", namespace: "solutions" })
693
+
694
+ // Find past tasks
695
+ memory_search({ query: "user profile API", namespace: "tasks" })
696
+ ```
697
+
698
+ </details>
699
+
700
+ ---
701
+
702
+ <details>
703
+ <summary><b>API Reference</b></summary>
704
+
705
+ ### CodexInitializer Class
199
706
 
200
707
  ```typescript
708
+ import { CodexInitializer } from '@claude-flow/codex';
709
+
201
710
  class CodexInitializer {
711
+ /**
712
+ * Initialize a Codex project
713
+ */
202
714
  async initialize(options: CodexInitOptions): Promise<CodexInitResult>;
715
+
716
+ /**
717
+ * Preview what would be created without writing files
718
+ */
203
719
  async dryRun(options: CodexInitOptions): Promise<string[]>;
204
720
  }
205
721
  ```
206
722
 
207
- ### initializeCodexProject
723
+ ### initializeCodexProject Function
208
724
 
209
725
  ```typescript
726
+ import { initializeCodexProject } from '@claude-flow/codex';
727
+
728
+ /**
729
+ * Quick initialization helper
730
+ */
210
731
  async function initializeCodexProject(
211
732
  projectPath: string,
212
733
  options?: Partial<CodexInitOptions>
@@ -217,24 +738,35 @@ async function initializeCodexProject(
217
738
 
218
739
  ```typescript
219
740
  interface CodexInitOptions {
741
+ /** Project directory path */
220
742
  projectPath: string;
743
+ /** Template to use */
221
744
  template?: 'minimal' | 'default' | 'full' | 'enterprise';
745
+ /** Specific skills to include */
222
746
  skills?: string[];
747
+ /** Overwrite existing files */
223
748
  force?: boolean;
749
+ /** Enable dual mode (Claude Code + Codex) */
224
750
  dual?: boolean;
225
751
  }
226
752
 
227
753
  interface CodexInitResult {
754
+ /** Whether initialization succeeded */
228
755
  success: boolean;
756
+ /** List of files created */
229
757
  filesCreated: string[];
758
+ /** List of skills generated */
230
759
  skillsGenerated: string[];
760
+ /** Whether MCP was registered */
231
761
  mcpRegistered?: boolean;
762
+ /** Non-fatal warnings */
232
763
  warnings?: string[];
764
+ /** Fatal errors */
233
765
  errors?: string[];
234
766
  }
235
767
  ```
236
768
 
237
- ## Programmatic Usage
769
+ ### Programmatic Usage
238
770
 
239
771
  ```typescript
240
772
  import { CodexInitializer, initializeCodexProject } from '@claude-flow/codex';
@@ -246,32 +778,33 @@ const result = await initializeCodexProject('/path/to/project', {
246
778
  dual: false,
247
779
  });
248
780
 
781
+ console.log(`Files created: ${result.filesCreated.length}`);
782
+ console.log(`Skills: ${result.skillsGenerated.length}`);
783
+ console.log(`MCP registered: ${result.mcpRegistered}`);
784
+
249
785
  // Or use the class directly
250
786
  const initializer = new CodexInitializer();
251
787
  const result = await initializer.initialize({
252
788
  projectPath: '/path/to/project',
253
789
  template: 'enterprise',
254
- skills: ['swarm-orchestration', 'memory-management'],
790
+ skills: ['swarm-orchestration', 'memory-management', 'security-audit'],
255
791
  force: false,
256
792
  dual: true,
257
793
  });
258
794
 
259
- console.log(`MCP registered: ${result.mcpRegistered}`);
260
- console.log(`Skills created: ${result.skillsGenerated.length}`);
795
+ if (result.warnings?.length) {
796
+ console.warn('Warnings:', result.warnings);
797
+ }
261
798
  ```
262
799
 
263
- ## Vector Search Details
800
+ </details>
264
801
 
265
- - **Embedding Dimensions**: 384
266
- - **Search Algorithm**: HNSW (150x-12,500x faster)
267
- - **Similarity Scoring**: 0-1 (higher = better match)
268
- - Score > 0.7: Strong match, use pattern
269
- - Score 0.5-0.7: Partial match, adapt
270
- - Score < 0.5: Weak match, create new
802
+ ---
271
803
 
272
- ## Migration
804
+ <details>
805
+ <summary><b>Migration from Claude Code</b></summary>
273
806
 
274
- Convert an existing CLAUDE.md project to Codex format:
807
+ ### Convert CLAUDE.md to AGENTS.md
275
808
 
276
809
  ```typescript
277
810
  import { migrate } from '@claude-flow/codex';
@@ -282,14 +815,98 @@ const result = await migrate({
282
815
  preserveComments: true,
283
816
  generateSkills: true,
284
817
  });
818
+
819
+ console.log(`Migrated: ${result.success}`);
820
+ console.log(`Skills generated: ${result.skillsGenerated.length}`);
285
821
  ```
286
822
 
823
+ ### Manual Migration Checklist
824
+
825
+ 1. **Rename config file**: `CLAUDE.md` → `AGENTS.md`
826
+ 2. **Move skills**: `.claude/skills/` → `.agents/skills/`
827
+ 3. **Update syntax**: `/skill-name` → `$skill-name`
828
+ 4. **Convert settings**: `settings.json` → `config.toml`
829
+ 5. **Register MCP**: `codex mcp add claude-flow -- npx claude-flow mcp start`
830
+
831
+ ### Dual Mode Alternative
832
+
833
+ Instead of migrating, use dual mode to support both:
834
+
835
+ ```bash
836
+ npx claude-flow@alpha init --dual
837
+ ```
838
+
839
+ This keeps both `CLAUDE.md` and `AGENTS.md` in sync.
840
+
841
+ </details>
842
+
843
+ ---
844
+
845
+ <details>
846
+ <summary><b>Troubleshooting</b></summary>
847
+
848
+ ### MCP Not Working
849
+
850
+ ```bash
851
+ # Check if registered
852
+ codex mcp list
853
+
854
+ # Re-register
855
+ codex mcp remove claude-flow
856
+ codex mcp add claude-flow -- npx claude-flow mcp start
857
+
858
+ # Test connection
859
+ npx claude-flow mcp test
860
+ ```
861
+
862
+ ### Memory Search Returns Empty
863
+
864
+ ```bash
865
+ # Initialize memory database
866
+ npx claude-flow memory init --force
867
+
868
+ # Check if entries exist
869
+ npx claude-flow memory list
870
+
871
+ # Manually add a test pattern
872
+ npx claude-flow memory store --key "test" --value "test pattern" --namespace patterns
873
+ ```
874
+
875
+ ### Skills Not Loading
876
+
877
+ ```bash
878
+ # Verify skill directory
879
+ ls -la .agents/skills/
880
+
881
+ # Check config.toml for skill registration
882
+ cat .agents/config.toml | grep skills
883
+
884
+ # Rebuild skills
885
+ npx claude-flow@alpha init --codex --force
886
+ ```
887
+
888
+ ### Vector Search Slow
889
+
890
+ ```bash
891
+ # Check HNSW index
892
+ npx claude-flow memory stats
893
+
894
+ # Rebuild index
895
+ npx claude-flow memory optimize --rebuild-index
896
+ ```
897
+
898
+ </details>
899
+
900
+ ---
901
+
287
902
  ## Related Packages
288
903
 
289
- - [@claude-flow/cli](https://www.npmjs.com/package/@claude-flow/cli) - Main CLI
290
- - [claude-flow](https://www.npmjs.com/package/claude-flow) - Umbrella package
291
- - [@claude-flow/memory](https://www.npmjs.com/package/@claude-flow/memory) - AgentDB memory with vector search
292
- - [@claude-flow/security](https://www.npmjs.com/package/@claude-flow/security) - Security module
904
+ | Package | Description |
905
+ |---------|-------------|
906
+ | [@claude-flow/cli](https://www.npmjs.com/package/@claude-flow/cli) | Main CLI (26 commands, 140+ subcommands) |
907
+ | [claude-flow](https://www.npmjs.com/package/claude-flow) | Umbrella package |
908
+ | [@claude-flow/memory](https://www.npmjs.com/package/@claude-flow/memory) | AgentDB with HNSW vector search |
909
+ | [@claude-flow/security](https://www.npmjs.com/package/@claude-flow/security) | Security module |
293
910
 
294
911
  ## License
295
912
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@claude-flow/codex",
3
- "version": "3.0.0-alpha.2",
3
+ "version": "3.0.0-alpha.4",
4
4
  "description": "Codex CLI integration for Claude Flow - OpenAI Codex platform adapter",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",