Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

Checkpoint: File edits

rUvc3a0c2b0cec0
diff --git a/package-lock.json b/package-lock.json
index 45e70b8918..6f9d890fef 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "claude-flow",
- "version": "3.1.0-alpha.7",
+ "version": "3.1.0-alpha.8",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "claude-flow",
- "version": "3.1.0-alpha.7",
+ "version": "3.1.0-alpha.8",
"license": "MIT",
"dependencies": {
"semver": "^7.6.0",
diff --git a/package.json b/package.json
index 65d8b8fcea..3bcd4a1407 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "claude-flow",
- "version": "3.1.0-alpha.7",
+ "version": "3.1.0-alpha.8",
"description": "Enterprise AI agent orchestration for Claude Code - Deploy 60+ specialized agents in coordinated swarms with self-learning, fault-tolerant consensus, vector memory, and MCP integration",
"main": "dist/index.js",
"type": "module",
diff --git a/v3/@claude-flow/cli/README.md b/v3/@claude-flow/cli/README.md
index e8b1f42138..791381ac3d 100644
--- a/v3/@claude-flow/cli/README.md
+++ b/v3/@claude-flow/cli/README.md
@@ -497,25 +497,115 @@ bunx claude-flow@alpha init
npm install -g claude-flow@alpha --omit=optional
```
-#### OpenAI Codex CLI Support
+<details>
+<summary>πŸ€– <strong>OpenAI Codex CLI Support</strong> β€” Full Codex integration with self-learning</summary>
Claude-Flow supports both **Claude Code** and **OpenAI Codex CLI** via the [@claude-flow/codex](https://www.npmjs.com/package/@claude-flow/codex) package.
+### Quick Start for Codex
+
```bash
# Initialize for Codex CLI (creates AGENTS.md instead of CLAUDE.md)
npx claude-flow@alpha init --codex
+# Full Codex setup with all 137+ skills
+npx claude-flow@alpha init --codex --full
+
# Initialize for both platforms (dual mode)
npx claude-flow@alpha init --dual
+```
-# Full Codex setup with all 137+ skills
-npx claude-flow@alpha init --codex --full
+### Platform Comparison
+
+| 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` |
+
+### Key Concept: Execution Model
+
+```
+β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
+β”‚ CLAUDE-FLOW = ORCHESTRATOR (tracks state, stores memory) β”‚
+β”‚ CODEX = EXECUTOR (writes code, runs commands, implements) β”‚
+β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
+```
+
+**Codex does the work. Claude-flow coordinates and learns.**
+
+### MCP Integration for Codex
+
+When you run `init --codex`, the MCP server is automatically registered:
+
+```bash
+# Verify MCP is registered
+codex mcp list
+
+# If not present, add manually:
+codex mcp add claude-flow -- npx claude-flow mcp start
```
-| Platform | Config File | Skills Dir | Skill Syntax |
-|----------|-------------|------------|--------------|
-| Claude Code | `CLAUDE.md` | `.claude/skills/` | `/skill-name` |
-| OpenAI Codex | `AGENTS.md` | `.agents/skills/` | `$skill-name` |
+### Self-Learning Workflow
+
+```
+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, namespace="patterns") β†’ Save for future
+```
+
+### MCP Tools for Learning
+
+| 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 |
+
+### Example Prompt for Codex
+
+```
+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):
+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"
+
+YOU execute all code. Use MCP tools for learning.
+```
+
+### Vector Search Details
+
+- **Embedding Dimensions**: 384
+- **Search Algorithm**: HNSW (150x-12,500x faster)
+- **Similarity Scoring**: 0-1 (higher = better)
+ - Score > 0.7: Strong match, use pattern
+ - Score 0.5-0.7: Partial match, adapt
+ - Score < 0.5: Weak match, create new
+
+</details>
### Basic Usage
diff --git a/v3/@claude-flow/cli/package.json b/v3/@claude-flow/cli/package.json
index b69b641489..d806aebb9b 100644
--- a/v3/@claude-flow/cli/package.json
+++ b/v3/@claude-flow/cli/package.json
@@ -1,6 +1,6 @@
{
"name": "@claude-flow/cli",
- "version": "3.1.0-alpha.7",
+ "version": "3.1.0-alpha.8",
"type": "module",
"description": "Claude Flow CLI - Enterprise AI agent orchestration with 60+ specialized agents, swarm coordination, MCP server, self-learning hooks, and vector memory for Claude Code",
"main": "dist/src/index.js",
diff --git a/v3/@claude-flow/codex/README.md b/v3/@claude-flow/codex/README.md
index cbb64affc4..a1e884e9e1 100644
--- a/v3/@claude-flow/codex/README.md
+++ b/v3/@claude-flow/codex/README.md
@@ -13,19 +13,10 @@ OpenAI Codex CLI adapter for Claude Flow V3. Enables multi-agent orchestration w
**Codex does the work. Claude-flow coordinates and learns.**
-## Features
-
-- **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
-
-## Installation
+## Quick Start
```bash
-# Via claude-flow CLI (recommended)
+# Initialize for Codex (recommended)
npx claude-flow@alpha init --codex
# Full setup with all 137+ skills
@@ -35,7 +26,30 @@ npx claude-flow@alpha init --codex --full
npx claude-flow@alpha init --dual
```
-## MCP Integration (Self-Learning)
+---
+
+<details>
+<summary><b>Features</b></summary>
+
+| 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 |
+
+</details>
+
+---
+
+<details>
+<summary><b>MCP Integration (Self-Learning)</b></summary>
+
+### Automatic Registration
When you run `init --codex`, the MCP server is **automatically registered** with Codex:
@@ -43,34 +57,76 @@ When you run `init --codex`, the MCP server is **automatically registered** with
# Verify MCP is registered
codex mcp list
-# Expected:
+# Expected output:
# Name Command Args Status
# claude-flow npx claude-flow mcp start enabled
+```
+
+### Manual Registration
-# If not present, add manually:
+If MCP is not present, add manually:
+
+```bash
codex mcp add claude-flow -- npx claude-flow mcp start
```
-### MCP Tools for Learning
+### 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 |
+| `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 |
-## Self-Learning Workflow
+### Tool Parameters
+**memory_search**
+```json
+{
+ "query": "search terms",
+ "namespace": "patterns",
+ "limit": 5
+}
```
-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, namespace="patterns") β†’ Save for future
+
+**memory_store**
+```json
+{
+ "key": "pattern-name",
+ "value": "what worked",
+ "namespace": "patterns",
+ "upsert": true
+}
```
-### Example Prompt for Codex
+**swarm_init**
+```json
+{
+ "topology": "hierarchical",
+ "maxAgents": 5,
+ "strategy": "specialized"
+}
+```
+
+</details>
+
+---
+
+<details>
+<summary><b>Self-Learning Workflow</b></summary>
+
+### The 4-Step Pattern
+
+```
+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
+```
+
+### Complete Example Prompt
```
Build an email validator using a learning-enabled swarm.
@@ -85,7 +141,7 @@ 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):
+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
@@ -95,53 +151,146 @@ Use tool: memory_store
key: "pattern-email-validator"
value: "Email validation: regex, returns boolean, test cases"
namespace: "patterns"
+ upsert: true
-YOU execute all code. Use MCP tools for learning.
+YOU execute all code. MCP tools are for learning only.
```
-## Directory Structure
+### 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 |
+
+</details>
+
+---
+
+<details>
+<summary><b>Directory Structure</b></summary>
```
project/
-β”œβ”€β”€ AGENTS.md # Main project instructions (Codex format)
+β”œβ”€β”€ AGENTS.md # Main project instructions (Codex format)
β”œβ”€β”€ .agents/
-β”‚ β”œβ”€β”€ config.toml # Project configuration
-β”‚ β”œβ”€β”€ skills/ # 137+ skills
+β”‚ β”œβ”€β”€ config.toml # Project configuration
+β”‚ β”œβ”€β”€ skills/ # 137+ skills
β”‚ β”‚ β”œβ”€β”€ swarm-orchestration/
β”‚ β”‚ β”‚ └── SKILL.md
β”‚ β”‚ β”œβ”€β”€ memory-management/
β”‚ β”‚ β”‚ └── SKILL.md
+β”‚ β”‚ β”œβ”€β”€ sparc-methodology/
+β”‚ β”‚ β”‚ └── SKILL.md
β”‚ β”‚ └── ...
-β”‚ └── README.md # Directory documentation
-β”œβ”€β”€ .codex/
-β”‚ β”œβ”€β”€ config.toml # Local overrides (gitignored)
-β”‚ └── AGENTS.override.md # Local instruction overrides
-└── .claude-flow/
- β”œβ”€β”€ config.yaml # Runtime configuration
- β”œβ”€β”€ data/ # Memory and cache
- └── logs/ # Log files
+β”‚ └── 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
```
-## Templates
+### 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 |
+
+</details>
+
+---
-| Template | Skills | Learning | Description |
-|----------|--------|----------|-------------|
-| `minimal` | 2 | Basic | Core skills only |
-| `default` | 4 | Yes | Standard setup |
-| `full` | 137+ | Yes | All available skills |
-| `enterprise` | 137+ | Advanced | Full + governance |
+<details>
+<summary><b>Templates</b></summary>
-## Platform Comparison
+### 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
+
+```bash
+# 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
+```
+
+### 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
+
+</details>
+
+---
+
+<details>
+<summary><b>Platform Comparison (Claude Code vs Codex)</b></summary>
| Feature | Claude Code | OpenAI Codex |
|---------|-------------|--------------|
-| Config File | CLAUDE.md | AGENTS.md |
-| Skills Dir | .claude/skills/ | .agents/skills/ |
+| Config File | `CLAUDE.md` | `AGENTS.md` |
+| Skills Dir | `.claude/skills/` | `.agents/skills/` |
| Skill Syntax | `/skill-name` | `$skill-name` |
-| Settings | settings.json | config.toml |
+| 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:
+
+```bash
+npx claude-flow@alpha init --dual
+```
-## Skill Invocation
+This creates:
+- `CLAUDE.md` for Claude Code users
+- `AGENTS.md` for Codex users
+- Shared `.claude-flow/` runtime
+- Cross-compatible skills
+
+</details>
+
+---
+
+<details>
+<summary><b>Skill Invocation</b></summary>
+
+### Syntax
In OpenAI Codex CLI, invoke skills with `$` prefix:
@@ -152,9 +301,46 @@ $sparc-methodology
$security-audit
$agent-coder
$agent-tester
+$github-workflow
+$performance-optimization
+```
+
+### Skill Categories
+
+| Category | Examples |
+|----------|----------|
+| **Swarm** | `$swarm-orchestration`, `$swarm-advanced` |
+| **Memory** | `$memory-management`, `$agentdb-vector-search` |
+| **SPARC** | `$sparc-methodology`, `$specification`, `$architecture` |
+| **GitHub** | `$github-code-review`, `$github-workflow-automation` |
+| **Security** | `$security-audit`, `$security-overhaul` |
+| **Testing** | `$tdd-london-swarm`, `$production-validator` |
+
+### Custom Skills
+
+Create custom skills in `.agents/skills/`:
+
+```
+.agents/skills/my-skill/
+└── SKILL.md
```
-## Configuration
+**SKILL.md format:**
+```markdown
+# My Custom Skill
+
+Instructions for what this skill does...
+
+## Usage
+Invoke with `$my-skill`
+```
+
+</details>
+
+---
+
+<details>
+<summary><b>Configuration</b></summary>
### .agents/config.toml
@@ -162,12 +348,15 @@ $agent-tester
# Model configuration
model = "gpt-4"
-# Approval policy
+# Approval policy: "always" | "on-request" | "never"
approval_policy = "on-request"
-# Sandbox mode
+# 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"
@@ -182,31 +371,117 @@ enabled = true
[[skills]]
path = ".agents/skills/memory-management"
enabled = true
+
+[[skills]]
+path = ".agents/skills/sparc-methodology"
+enabled = true
```
-### .codex/config.toml (Local)
+### .codex/config.toml (Local Overrides)
```toml
# 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
```
-## API Reference
+### Environment Variables
+
+```bash
+# 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
+```
+
+</details>
+
+---
+
+<details>
+<summary><b>Vector Search Details</b></summary>
+
+### 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
-### CodexInitializer
+```javascript
+// 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" })
+```
+
+</details>
+
+---
+
+<details>
+<summary><b>API Reference</b></summary>
+
+### CodexInitializer Class
```typescript
+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[]>;
}
```
-### initializeCodexProject
+### initializeCodexProject Function
```typescript
+import { initializeCodexProject } from '@claude-flow/codex';
+
+/**
+ * Quick initialization helper
+ */
async function initializeCodexProject(
projectPath: string,
options?: Partial<CodexInitOptions>
@@ -217,24 +492,35 @@ async function initializeCodexProject(
```typescript
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[];
}
```
-## Programmatic Usage
+### Programmatic Usage
```typescript
import { CodexInitializer, initializeCodexProject } from '@claude-flow/codex';
@@ -246,32 +532,33 @@ const result = await initializeCodexProject('/path/to/project', {
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'],
+ skills: ['swarm-orchestration', 'memory-management', 'security-audit'],
force: false,
dual: true,
});
-console.log(`MCP registered: ${result.mcpRegistered}`);
-console.log(`Skills created: ${result.skillsGenerated.length}`);
+if (result.warnings?.length) {
+ console.warn('Warnings:', result.warnings);
+}
```
-## Vector Search Details
+</details>
-- **Embedding Dimensions**: 384
-- **Search Algorithm**: HNSW (150x-12,500x faster)
-- **Similarity Scoring**: 0-1 (higher = better match)
- - Score > 0.7: Strong match, use pattern
- - Score 0.5-0.7: Partial match, adapt
- - Score < 0.5: Weak match, create new
+---
-## Migration
+<details>
+<summary><b>Migration from Claude Code</b></summary>
-Convert an existing CLAUDE.md project to Codex format:
+### Convert CLAUDE.md to AGENTS.md
```typescript
import { migrate } from '@claude-flow/codex';
@@ -282,14 +569,98 @@ const result = await migrate({
preserveComments: true,
generateSkills: true,
});
+
+console.log(`Migrated: ${result.success}`);
+console.log(`Skills generated: ${result.skillsGenerated.length}`);
```
+### Manual Migration Checklist
+
+1. **Rename config file**: `CLAUDE.md` β†’ `AGENTS.md`
+2. **Move skills**: `.claude/skills/` β†’ `.agents/skills/`
+3. **Update syntax**: `/skill-name` β†’ `$skill-name`
+4. **Convert settings**: `settings.json` β†’ `config.toml`
+5. **Register MCP**: `codex mcp add claude-flow -- npx claude-flow mcp start`
+
+### Dual Mode Alternative
+
+Instead of migrating, use dual mode to support both:
+
+```bash
+npx claude-flow@alpha init --dual
+```
+
+This keeps both `CLAUDE.md` and `AGENTS.md` in sync.
+
+</details>
+
+---
+
+<details>
+<summary><b>Troubleshooting</b></summary>
+
+### MCP Not Working
+
+```bash
+# 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
+```
+
+### Memory Search Returns Empty
+
+```bash
+# 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
+```
+
+### Skills Not Loading
+
+```bash
+# 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
+```
+
+### Vector Search Slow
+
+```bash
+# Check HNSW index
+npx claude-flow memory stats
+
+# Rebuild index
+npx claude-flow memory optimize --rebuild-index
+```
+
+</details>
+
+---
+
## Related Packages
-- [@claude-flow/cli](https://www.npmjs.com/package/@claude-flow/cli) - Main CLI
-- [claude-flow](https://www.npmjs.com/package/claude-flow) - Umbrella package
-- [@claude-flow/memory](https://www.npmjs.com/package/@claude-flow/memory) - AgentDB memory with vector search
-- [@claude-flow/security](https://www.npmjs.com/package/@claude-flow/security) - Security module
+| Package | Description |
+|---------|-------------|
+| [@claude-flow/cli](https://www.npmjs.com/package/@claude-flow/cli) | Main CLI (26 commands, 140+ subcommands) |
+| [claude-flow](https://www.npmjs.com/package/claude-flow) | Umbrella package |
+| [@claude-flow/memory](https://www.npmjs.com/package/@claude-flow/memory) | AgentDB with HNSW vector search |
+| [@claude-flow/security](https://www.npmjs.com/package/@claude-flow/security) | Security module |
## License