Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ruvnet/ruflo/llms.txt

Use this file to discover all available pages before exploring further.

When you pair Ruflo with OpenAI Codex, the two systems split responsibility cleanly: Codex executes — it writes files, runs commands, creates code, and produces output. Ruflo orchestrates — it tracks state, stores memory, coordinates agents, and makes every subsequent task smarter by learning from what worked. Neither system does the other’s job. This division is the key insight from AGENTS.md, Ruflo’s native Codex configuration file:
╔═══════════════════════════════════════════════════════════════════════════╗
║  1. claude-flow = LEDGER (tracks state, stores memory, coordinates)       ║
║  2. Codex = EXECUTOR (writes code, runs commands, creates files)          ║
║  3. NEVER stop after calling claude-flow - IMMEDIATELY continue working   ║
║  4. If you need something BUILT/EXECUTED, YOU do it, not claude-flow      ║
║  5. ALWAYS search memory BEFORE starting: memory search --query "task"    ║
║  6. ALWAYS store patterns AFTER success: memory store --namespace patterns║
╚═══════════════════════════════════════════════════════════════════════════╝
ComponentRoleExamples
CodexEXECUTESWrite files, run tests, create code, shell commands
RufloORCHESTRATESTrack agents, store memory, coordinate tasks

Setup

1

Initialize Ruflo with the Codex flag

Running init --codex creates AGENTS.md (the Codex equivalent of CLAUDE.md), places skills in .agents/skills/, and writes config.toml in the Codex config directory. The setup wizard auto-detects Codex if it is already installed.
# Initialize for Codex
npx ruflo@latest init --codex

# Full Codex setup with all 137+ skills
npx ruflo@latest init --codex --full

# Initialize for both Claude Code and Codex simultaneously
npx ruflo@latest init --dual
2

Configure MCP for Codex

When you run init --codex, the MCP server is automatically registered with Codex. Verify it is present:
codex mcp list
# Expected output:
# Name         Command  Args                   Status
# claude-flow  npx      claude-flow mcp start  enabled
If it is not present, add it manually:
codex mcp add claude-flow -- npx claude-flow mcp start
You can also configure it directly in ~/.codex/config.toml:
[mcp_servers.claude-flow]
command = "npx"
args = ["claude-flow", "mcp", "start"]
enabled = true
Test the MCP connection:
npx ruflo@latest mcp start --test
3

Follow the recommended workflow

The self-learning workflow has four steps. Ruflo handles steps 1, 2, and 4. Codex handles step 3 — the actual work.
  1. Search memory for existing patterns before starting
  2. Init coordination record (instant, just tracking)
  3. YOU write the code — this is where work happens
  4. Store what worked so future tasks can reuse the pattern

The Correct Codex Workflow Pattern

The most important thing to understand: Ruflo commands return instantly. They create coordination records. They do not build, run, or execute anything. After any Ruflo call, Codex must immediately continue with its own execution.
# 1. Search memory for existing patterns
memory_search(query="task keywords")  # score > 0.7 = use the pattern

# 2. Init coordination record
swarm_init(topology="hierarchical")  # instant, just tracking

# 3. YOU write the code
mkdir -p src && cat > src/api.ts << 'EOF'
export function hello() { return "Hello World"; }
EOF

# 4. Store what worked
memory_store(key="api-created", value="src/api.ts", namespace="results")

Full example with MCP tools

STEP 1 — LEARN:
  Use tool: memory_search
    query: "validation utility function"
    namespace: "patterns"
  → Found: pattern-email-validator (score: 0.82)
  → Use this pattern as reference!

STEP 2 — COORDINATE:
  Use tool: swarm_init
    topology: "hierarchical"
    maxAgents: 3

STEP 3 — EXECUTE (Codex does the real work):
  echo 'export function validate(x) { ... }' > src/validator.ts
  node --test src/validator.ts

STEP 4 — REMEMBER:
  Use tool: memory_store
    key: "pattern-phone-validator"
    value: "Phone validation: regex /^\+?[\d\s-]{10,}$/, normalize first, test edge cases"
    namespace: "patterns"
Wrong pattern: spawning Ruflo and waiting for it to build something.
# ❌ WRONG — claude-flow does NOT execute code
npx claude-flow swarm start --objective "Build API"
# Waiting here accomplishes nothing. Ruflo is a ledger, not an executor.
# ✅ CORRECT — Codex executes, Ruflo tracks
npx claude-flow swarm init --topology hierarchical --max-agents 1
# IMMEDIATELY continue — don't wait:
mkdir -p src
cat > src/api.ts << 'EOF'
export function hello() { return "Hello World"; }
EOF
npx claude-flow memory store --key "api-created" --value "src/api.ts" --namespace results
Every Ruflo command returns instantly and creates a record. The rule: after any Ruflo call, immediately continue with your own work.

Vector Search Scoring

Ruflo’s memory_search uses HNSW semantic search with a 0–1 similarity score:
Score RangeMeaningAction
> 0.7Strong matchUse the stored pattern directly
0.5–0.7Partial matchAdapt the pattern as needed
< 0.5Weak matchCreate a new pattern from scratch

MCP Tools for Codex

Once Ruflo is registered as an MCP server, Codex can call these tools directly: Learning & Memory (use these on every task):
ToolPurposeWhen
memory_searchSemantic vector searchBEFORE every task
memory_storeSave patterns with embeddingsAFTER success
memory_retrieveGet by exact keyWhen key is known
neural_trainTrain on patternsPeriodic improvement
Coordination:
ToolPurpose
swarm_initInitialize a swarm topology (returns instantly)
agent_spawnRegister an agent role (returns instantly)
task_orchestrateCoordinate multi-agent task records
swarm_statusCheck swarm state

Pre-Built Collaboration Templates

The @claude-flow/codex dual-mode CLI ships three ready-made collaboration templates that combine Claude Code and Codex workers:
# List available templates
npx @claude-flow/codex dual templates

# Feature development: architect → coder → tester → reviewer
npx @claude-flow/codex dual run --template feature --task "Add user auth"

# Security audit: scanner → analyzer → fixer
npx @claude-flow/codex dual run --template security --task "src/auth/"

# Refactoring: analyzer → planner → refactorer → validator
npx @claude-flow/codex dual run --template refactor --task "src/legacy/"
TemplatePipelinePlatforms
featurearchitect → coder → tester → reviewerClaude + Codex
securityscanner → analyzer → fixerCodex + Claude
refactoranalyzer → planner → refactorer → validatorClaude + Codex

Dual-Mode Skills

The following skills are available for Codex when running in dual-mode (init --dual). Invoke them with the $ prefix:
SkillPurpose
$dual-spawnSpawn parallel Claude Code and Codex workers
$dual-coordinateCoordinate work across both platforms via shared memory
$dual-collectCollect and merge results from parallel workers
$swarm-orchestrationMulti-agent swarm coordination
$memory-managementPattern storage and retrieval
$github-automationCI/CD and PR management

Platform Comparison

FeatureClaude CodeOpenAI Codex
Config fileCLAUDE.mdAGENTS.md
Skills directory.claude/skills/.agents/skills/
Skill syntax/skill-name$skill-name
Settingssettings.jsonconfig.toml
MCPNativeVia codex mcp add
Default modelclaude-sonnetgpt-5.3
Both platforms share the same Ruflo memory namespace when initialized with --dual, so patterns learned in a Claude Code session are immediately available in Codex sessions and vice versa. For the full Codex workflow specification, see AGENTS.md in the source repository.

Build docs developers (and LLMs) love