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

rUvf5988e6f0375
diff --git a/v3/@claude-flow/codex/README.md b/v3/@claude-flow/codex/README.md
index aee4c602b4..cbb64affc4 100644
--- a/v3/@claude-flow/codex/README.md
+++ b/v3/@claude-flow/codex/README.md
@@ -1,14 +1,26 @@
# @claude-flow/codex
-OpenAI Codex CLI adapter for Claude Flow V3. Enables multi-agent orchestration for OpenAI Codex CLI following the [Agentic AI Foundation](https://agenticfoundation.org) standard.
+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.
+
+## 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.**
## Features
-- **AGENTS.md Generation** - Creates project instructions in Codex format
-- **Skill Management** - 137+ skills with `$skill-name` invocation
-- **Config Generation** - `.agents/config.toml` for Codex configuration
-- **Dual Platform** - Supports both Claude Code and Codex simultaneously
-- **Migration** - Convert CLAUDE.md to AGENTS.md format
+- **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
@@ -16,46 +28,75 @@ OpenAI Codex CLI adapter for Claude Flow V3. Enables multi-agent orchestration f
# Via claude-flow CLI (recommended)
npx claude-flow@alpha init --codex
-# Or install package directly
-npm install @claude-flow/codex
+# Full setup with all 137+ skills
+npx claude-flow@alpha init --codex --full
+
+# Dual mode (both Claude Code and Codex)
+npx claude-flow@alpha init --dual
```
-## Quick Start
+## MCP Integration (Self-Learning)
-### Using the CLI
+When you run `init --codex`, the MCP server is **automatically registered** with Codex:
```bash
-# Initialize for Codex
-npx claude-flow@alpha init --codex
+# Verify MCP is registered
+codex mcp list
-# Full setup with all 137+ skills
-npx claude-flow@alpha init --codex --full
+# Expected:
+# Name Command Args Status
+# claude-flow npx claude-flow mcp start enabled
-# Dual mode (both Claude Code and Codex)
-npx claude-flow@alpha init --dual
+# If not present, add manually:
+codex mcp add claude-flow -- npx claude-flow mcp start
```
-### Programmatic Usage
+### MCP Tools for Learning
-```typescript
-import { CodexInitializer, initializeCodexProject } from '@claude-flow/codex';
+| 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 |
-// Quick initialization
-const result = await initializeCodexProject('/path/to/project', {
- template: 'full',
- force: true,
- dual: false,
-});
+## Self-Learning Workflow
-// 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'],
- force: false,
- dual: true,
-});
+```
+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
+```
+
+### 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.
```
## Directory Structure
@@ -83,12 +124,12 @@ project/
## Templates
-| Template | Skills | Description |
-|----------|--------|-------------|
-| `minimal` | 2 | Core skills only |
-| `default` | 4 | Standard setup |
-| `full` | 137+ | All available skills |
-| `enterprise` | 137+ | Full + governance |
+| 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 |
## Platform Comparison
@@ -98,7 +139,7 @@ project/
| Skills Dir | .claude/skills/ | .agents/skills/ |
| Skill Syntax | `/skill-name` | `$skill-name` |
| Settings | settings.json | config.toml |
-| Approval | 3 levels | 4 levels |
+| MCP | Native | Via `codex mcp add` |
## Skill Invocation
@@ -127,6 +168,12 @@ approval_policy = "on-request"
# Sandbox mode
sandbox_mode = "workspace-write"
+# MCP Servers
+[mcp_servers.claude-flow]
+command = "npx"
+args = ["claude-flow", "mcp", "start"]
+enabled = true
+
# Skills
[[skills]]
path = ".agents/skills/swarm-orchestration"
@@ -181,11 +228,47 @@ interface CodexInitResult {
success: boolean;
filesCreated: string[];
skillsGenerated: string[];
+ mcpRegistered?: boolean;
warnings?: string[];
errors?: string[];
}
```
+## Programmatic Usage
+
+```typescript
+import { CodexInitializer, initializeCodexProject } from '@claude-flow/codex';
+
+// Quick initialization
+const result = await initializeCodexProject('/path/to/project', {
+ template: 'full',
+ force: true,
+ dual: false,
+});
+
+// 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'],
+ force: false,
+ dual: true,
+});
+
+console.log(`MCP registered: ${result.mcpRegistered}`);
+console.log(`Skills created: ${result.skillsGenerated.length}`);
+```
+
+## Vector Search 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
Convert an existing CLAUDE.md project to Codex format:
@@ -205,7 +288,7 @@ const result = await migrate({
- [@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
+- [@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
## License
diff --git a/docs/adr/ADR-027-codex-ddd.md b/v3/implementation/adrs/ADR-027-codex-ddd.md
similarity index 100%
rename from docs/adr/ADR-027-codex-ddd.md
rename to v3/implementation/adrs/ADR-027-codex-ddd.md
diff --git a/docs/adr/ADR-027-codex-integration.md b/v3/implementation/adrs/ADR-027-codex-integration.md
similarity index 100%
rename from docs/adr/ADR-027-codex-integration.md
rename to v3/implementation/adrs/ADR-027-codex-integration.md
diff --git a/docs/adr/ADR-027-codex-package-analysis.md b/v3/implementation/adrs/ADR-027-codex-package-analysis.md
similarity index 100%
rename from docs/adr/ADR-027-codex-package-analysis.md
rename to v3/implementation/adrs/ADR-027-codex-package-analysis.md
diff --git a/docs/adr/ADR-027-codex-templates.md b/v3/implementation/adrs/ADR-027-codex-templates.md
similarity index 100%
rename from docs/adr/ADR-027-codex-templates.md
rename to v3/implementation/adrs/ADR-027-codex-templates.md