π 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
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
Checkpoint: File edits
rUvc3a0c2b0cec0
diff --git a/package-lock.json b/package-lock.jsonindex 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.jsonindex 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.mdindex 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 initnpm 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 Usagediff --git a/v3/@claude-flow/cli/package.json b/v3/@claude-flow/cli/package.jsonindex 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.mdindex 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 --fullnpx 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 RegistrationWhen 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 registeredcodex 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:++```bashcodex 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=3Use 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() functionCreate /tmp/validator/test.js with test casesRun the tests@@ -95,53 +151,146 @@ Use tool: memory_storekey: "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>++### SyntaxIn 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 configurationmodel = "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(```typescriptinterface 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```typescriptimport { 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 directlyconst 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```typescriptimport { 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