Comparison

A · CLAUDE.md · ruvnet/ruflo B · AGENTS.md · ruvnet/ruflo

What each file covers, counted
Dimension	Shared	Only in A	Only in B	Overlap
Sections	0	16	58	0%
Commands	0	10	37	0%
Section tags	6	4	3	46%

What each file covers

Sections

0 shared · 16 only in A · 58 only in B

− CLAUDE.md
− Overview
− Commands
− Running a Single Test
− Test Environments
− Architecture
− Stack
− Key Directories
− Text Generation Flow
− Model Context Protocol (MCP)
− LLM Router (Omni)
− Database Collections
− Environment Setup
− MONGODB_URL is optional; omit for in-memory DB persisted to ./db
− Code Conventions
− Feature Development Checklist
+ Claude Flow V3 - Agent Guide
+ 📢 TL;DR - READ THIS FIRST
+ Ruflo Policy-Governed Concurrent Codex Workflow
+ 🚨 CRITICAL: CODEX DOES THE WORK, CLAUDE-FLOW ORCHESTRATES
+ ❌ WRONG: Expecting claude-flow to execute tasks
+ WRONG: Waiting for claude-flow to build the API
+ Claude-flow does NOT execute code!
+ ✅ CORRECT: Codex executes, claude-flow tracks
+ 1. Tell claude-flow what you're doing (optional coordination)
+ 2. YOU (CODEX) DO THE ACTUAL WORK:
+ 3. Report to claude-flow what you did (optional)
+ The Division of Labor
+ ⛔ DON'T STOP AFTER CALLING CLAUDE-FLOW
+ ❌ WRONG Pattern (Stopping)
+ WRONG: Codex stops here and waits for something to happen
+ Nothing will happen! Claude-flow doesn't execute code!
+ ✅ CORRECT Pattern (Continue Immediately)
+ Step 1: Coordination (optional)
+ Step 2: IMMEDIATELY DO THE WORK YOURSELF - DON'T WAIT!
+ Step 3: Report what you did
+ The Rule
+ When to Use Claude-Flow Commands
+ Hello World - Correct Pattern
+ STEP 1: Optional - register with orchestrator
+ STEP 2: CODEX DOES THE WORK
+ STEP 3: Optional - report completion
+ ⚡ QUICK COMMANDS (NO DISCOVERY NEEDED)
+ Spawn N-Agent Swarm (Copy-Paste Ready)
+ 5-AGENT SWARM - Run these commands in sequence:
+ Common Swarm Patterns
+ Agent Types (Use with `--type`)
+ Task Commands
+ Memory Commands
+ 🚀 SWARM RECIPES
+ Recipe 1: Hello World Test (COMPLETE EXAMPLE)
+ ⚠️ DON'T STOP HERE - CONTINUE IMMEDIATELY TO STEP 2
+ ✅ YOU create the file
+ ✅ YOU execute it
+ Output: Hello World from Swarm!
+ Recipe 1b: 5-Agent Concurrent Hello World (COMPLETE)
+ COORDINATION (instant - creates records only)
+ ⚠️ NOW YOU DO THE ACTUAL CONCURRENT WORK:
+ REPORT (optional)
+ Recipe 1b: Hello World (Single Command Block)
+ All-in-one execution
+ Recipe 2: Feature Implementation (6 Agents)
+ Recipe 3: Bug Fix (4 Agents)
+ Recipe 4: Security Audit (3 Agents)
+ Recipe 5: V3 Full Coordination (15 Agents)
+ 📋 BEHAVIORAL RULES
+ 📁 FILE ORGANIZATION
+ 🎯 WHEN TO USE SWARMS
+ 🔧 CLI REFERENCE
+ Swarm Commands
+ Agent Commands
+ Hooks Commands
+ System Commands
+ 🔌 TOPOLOGIES

Commands

0 shared · 10 only in A · 37 only in B

− npm run dev
− npm run build
− npm run preview
− npm run check
− npm run lint
− npm run format
− npm run test
− npx vitest run path/to/file.spec.ts
− npx vitest run -t "test name"
− npx vitest --watch path/to/file.spec.ts
+ npx ruflo policy status
+ npx ruflo policy verify
+ npx ruflo metaharness flywheel status
+ npx claude-flow swarm start --objective "Build API"
+ npx claude-flow swarm init --topology hierarchical --max-agents 1
+ npx claude-flow agent spawn --type coder --name codex-worker
+ npx claude-flow memory store --key "api-created" --value "src/api.ts" --namespace results
+ npx claude-flow swarm init --topology hierarchical
+ npx claude-flow agent spawn --type coder --name worker-1
+ npx claude-flow swarm start --objective "Build hello world"
+ node hello.js
+ npx claude-flow memory store --key "result" --value "Hello World printed" --namespace results
+ npx claude-flow swarm init --topology mesh --max-agents 1
+ npx claude-flow memory store --key "hello-result" --value "printed Hello World" --namespace results
+ npx claude-flow swarm init --topology hierarchical --max-agents 8
+ npx claude-flow agent spawn --type coordinator --name coord-1
+ npx claude-flow agent spawn --type coder --name coder-1
+ npx claude-flow agent spawn --type coder --name coder-2
+ npx claude-flow agent spawn --type tester --name tester-1
+ npx claude-flow agent spawn --type reviewer --name reviewer-1
+ npx claude-flow swarm start --objective "Your task here" --strategy development
+ npx claude-flow swarm init --topology mesh --max-agents 5 && \
+ npx claude-flow agent spawn --type coder --name hello-main && \
+ node /tmp/hello-swarm.js && \
+ npx claude-flow memory store --key "hello-world-result" --value "Executed: Hello World from Swarm!" --namespace results
+ npx claude-flow swarm init --topology hierarchical --max-agents 5
+ npx claude-flow agent spawn --type coder --name "worker-$i"
+ npx claude-flow memory store --key "concurrent-result" --value "5 workers completed" --namespace results
+ npx claude-flow swarm start --objective "Print hello world" --strategy development && \
+ npx claude-flow memory store --key "hello-world-result" --value "Success" --namespace results
+ npx claude-flow agent spawn --type coordinator --name lead
+ npx claude-flow agent spawn --type architect --name arch
+ npx claude-flow agent spawn --type coder --name impl-1
+ npx claude-flow agent spawn --type coder --name impl-2
+ npx claude-flow agent spawn --type tester --name test
+ npx claude-flow agent spawn --type reviewer --name review
+ npx claude-flow swarm start --objective "Implement [feature]" --strategy development

Section tags

6 shared · 4 only in A · 3 only in B

− setup
− lint-format
− architecture
− database
+ security
+ api
+ do-not
build
test
code-style
types
performance
agent-behaviour

Line diff

+667 added−86 removed41 unchanged5.8% identical

ruvnet/ruflo · ruflo/src/ruvocal/CLAUDE.md

@@ −1 @@

1# CLAUDE.md

3This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

5## Overview

7Chat UI is a SvelteKit application that provides a chat interface for LLMs. It powers HuggingChat (hf.co/chat). The app speaks exclusively to OpenAI-compatible APIs via `OPENAI_BASE_URL`.

9## Commands

11```bash

12npm run dev # Start dev server on localhost:5173

13npm run build # Production build

14npm run preview # Preview production build

15npm run check # TypeScript validation (svelte-kit sync + svelte-check)

16npm run lint # Check formatting (Prettier) and linting (ESLint)

17npm run format # Auto-format with Prettier

18npm run test # Run all tests (Vitest)

19```

21### Running a Single Test

23```bash

24npx vitest run path/to/file.spec.ts # Run specific test file

25npx vitest run -t "test name" # Run test by name

26npx vitest --watch path/to/file.spec.ts # Watch mode for single file

27```

29### Test Environments

31Tests are split into three workspaces (configured in vite.config.ts):

33- **Client tests** (`*.svelte.test.ts`): Browser environment with Playwright

34- **SSR tests** (`*.ssr.test.ts`): Node environment for server-side rendering

35- **Server tests** (`*.test.ts`, `*.spec.ts`): Node environment for utilities

37## Architecture

39### Stack

41- **SvelteKit 2** with Svelte 5 (uses runes: `$state`, `$effect`, `$bindable`)

42- **MongoDB** for persistence (auto-fallback to in-memory with MongoMemoryServer when `MONGODB_URL` not set)

43- **TailwindCSS** for styling

45### Key Directories

47```

48src/

49├── lib/

50│ ├── components/ # Svelte components (chat/, mcp/, voice/, icons/)

51│ ├── server/

52│ │ ├── api/utils/ # Shared API helpers (auth, superjson, model/conversation resolvers)

53│ │ ├── textGeneration/ # LLM streaming pipeline

54│ │ ├── mcp/ # Model Context Protocol integration

55│ │ ├── router/ # Smart model routing (Omni)

56│ │ ├── database.ts # MongoDB collections

57│ │ ├── models.ts # Model registry from OPENAI_BASE_URL/models

58│ │ └── auth.ts # OpenID Connect authentication

59│ ├── types/ # TypeScript interfaces (Conversation, Message, User, Model, etc.)

60│ ├── stores/ # Svelte stores for reactive state

61│ └── utils/ # Helpers (tree/, marked.ts, auth.ts, etc.)

62├── routes/ # SvelteKit file-based routing

63│ ├── conversation/[id]/ # Chat page + streaming endpoint

64│ ├── settings/ # User settings pages

65│ ├── api/ # Legacy v1 API endpoints (mcp, transcribe, fetch-url)

66│ ├── api/v2/ # REST API endpoints (+server.ts)

67│ └── r/[id]/ # Shared conversation view

68```

70### Text Generation Flow

721. User sends message via `POST /conversation/[id]`

732. Server validates user, fetches conversation history

743. Builds message tree structure (see `src/lib/utils/tree/`)

754. Calls LLM endpoint via OpenAI client

765. Streams response back, stores in MongoDB

78### Model Context Protocol (MCP)

80MCP servers are configured via `MCP_SERVERS` env var. When enabled, tools are exposed as OpenAI function calls. The router can auto-select tools-capable models when `LLM_ROUTER_ENABLE_TOOLS=true`.

82### LLM Router (Omni)

84Smart routing via Arch-Router model. Configured with:

86- `LLM_ROUTER_ROUTES_PATH`: JSON file defining routes

87- `LLM_ROUTER_ARCH_BASE_URL`: Router endpoint

88- Shortcuts: multimodal routes bypass router if `LLM_ROUTER_ENABLE_MULTIMODAL=true`

90### Database Collections

92- `conversations` - Chat sessions with nested messages

93- `users` - User accounts (OIDC-backed)

94- `sessions` - Session data

95- `sharedConversations` - Public share links

96- `settings` - User preferences

98## Environment Setup

100Copy `.env` to `.env.local` and configure:

101

102```env

103OPENAI_BASE_URL=https://router.huggingface.co/v1

104OPENAI_API_KEY=hf_***

105# MONGODB_URL is optional; omit for in-memory DB persisted to ./db

106```

107

108See `.env` for full list of variables including router config, MCP servers, auth, and feature flags.

109

110## Code Conventions

111

112- TypeScript strict mode enabled

113- ESLint: no `any`, no non-null assertions

114- Prettier: tabs, 100 char width, Tailwind class sorting

115- Server vs client separation via SvelteKit conventions (`+page.server.ts` vs `+page.ts`)

116

117## Feature Development Checklist

118

119When building new features, consider:

120

1211. **HuggingChat vs self-hosted**: Wrap HuggingChat-specific features with `publicConfig.isHuggingChat`

1222. **Settings persistence**: Add new fields to `src/lib/types/Settings.ts`, update API endpoint at `src/routes/api/v2/user/settings/+server.ts`

1233. **Rich dropdowns**: Use `bits-ui` (Select, DropdownMenu) instead of native elements when you need icons/images in options

1244. **Scrollbars**: Use `scrollbar-custom` class for styled scrollbars

1255. **Icons**: Custom icons in `$lib/components/icons/`, use Carbon (`~icons/carbon/*`) or Lucide (`~icons/lucide/*`) for standard icons

1266. **Provider avatars**: Use `PROVIDERS_HUB_ORGS` from `@huggingface/inference` for HF provider avatar URLs

127

ruvnet/ruflo · AGENTS.md

@@ +1 @@

1# Claude Flow V3 - Agent Guide

3> **For OpenAI Codex CLI** - Agentic AI Foundation standard

4> Skills: `$skill-name` | Config: `.agents/config.toml`

6---

8## 📢 TL;DR - READ THIS FIRST

10```

11╔═══════════════════════════════════════════════════════════════════════════╗

12║ 1. claude-flow = LEDGER (tracks state, stores memory, coordinates) ║

13║ 2. Codex = EXECUTOR (writes code, runs commands, creates files) ║

14║ 3. NEVER stop after calling claude-flow - IMMEDIATELY continue working ║

15║ 4. If you need something BUILT/EXECUTED, YOU do it, not claude-flow ║

16║ 5. ALWAYS search memory BEFORE starting: memory search --query "task" ║

17║ 6. ALWAYS store patterns AFTER success: memory store --namespace patterns║

18╚═══════════════════════════════════════════════════════════════════════════╝

19```

21**Workflow (Use MCP Tools):**

221. `memory_search(query="task keywords")` → LEARN from past patterns (score > 0.7 = use it)

232. `swarm_init(topology="hierarchical")` → coordination record (instant)

243. **YOU write the code / run the commands** ← THIS IS WHERE WORK HAPPENS

254. `memory_store(key="pattern-x", value="what worked", namespace="patterns")` → REMEMBER for next time

27---

29## Ruflo Policy-Governed Concurrent Codex Workflow

31Ruflo is the coordination ledger and policy decision point. Codex agents are

32the executors. Coordination records do not write code or run tests.

34Use `guidance_brain({ mode: "recommend", task: "..." })` to select Ruflo

35capabilities from the live MCP registry. A registered tool is not necessarily

36configured, reachable, healthy, or authorized. If it is unavailable, continue

37with compatible guidance tools, CLI discovery, and repository instructions.

391. Recall relevant AgentDB memory and ADRs.

402. Inspect source, runtime, dependencies, policy, and health.

413. Route to the smallest capable topology, agents, skills, and tools.

424. Plan acceptance criteria, safety envelope, ownership, and validation.

435. Execute with Codex workers in isolated scopes; Ruflo records coordination.

446. Test focused, regression, and failure paths.

457. Validate types, security, policy, compatibility, and artifact integrity.

468. Benchmark a source-bound candidate against a source-bound baseline.

479. Optimize only measured bottlenecks without weakening safety.

4810. Bind claims and evidence into exact source/build receipts.

4911. Reconcile handoffs and disclose unresolved limitations.

5012. Publish only through a separately authorized release gate.

52Hard invariants:

54- Never run two writers in one worktree.

55- Delegation may only reduce tools, servers, namespaces, network, spend,

56 concurrency, expiry, and depth.

57- Policy denial cancels dependent work before side effects.

58- MetaHarness may evaluate candidates concurrently, but only ADR-322A may

59 promote them and MetaHarness may never expand its own SafetyEnvelope.

60- Do not commit, push, merge, release, or remove worktrees unless authorized.

61- Existing installations migrate in `legacy` policy mode; use `observe` before

62 switching to `enforce`.

64Repository harness integration:

66- If tracked repository instructions define a collaboration harness, start its

67 session only after assigning an isolated worktree.

68- Inspect existing claims, acquire exact paths/resources/ports, renew leases,

69 check acknowledged inbox messages at integration boundaries, and release ownership on

70 handoff or exit.

71- A repository lease coordinates ownership; it does not grant authorization.

72 Protected work still requires the ADR-324/325 action capability and current

73 fencing epoch.

74- In-memory reference adapters demonstrate semantics; they are not distributed,

75 restart-durable release authorities.

76- Heartbeats and lease expiry establish liveness; a PID is diagnostic only.

77- `HEAD` alone is not an exact source-state identity in a dirty worktree.

78 Release evidence must bind a clean commit or an immutable snapshot of tracked

79 and untracked changes.

81Useful checks:

83```bash

84npx ruflo policy status

85npx ruflo policy verify

86npx ruflo metaharness flywheel status

87```

89Repository release contract:

91- The stable public train is exactly `@claude-flow/cli`, `claude-flow`, and

92 `ruflo`; internal `@claude-flow/*` components are bundled and are not part of

93 a normal standalone publish.

94- Publish from a clean, reviewed source state in that order.

95- Only the CLI publish receives the helper-signing configuration from

96 `ruv-dev`; use the existing authenticated npm session for publication.

97- Run `node scripts/audit-umbrella-version-lockstep.mjs`, verify all three

98 registry versions, and align `latest`, `alpha`, and `v3alpha`.

100---

101

102## 🚨 CRITICAL: CODEX DOES THE WORK, CLAUDE-FLOW ORCHESTRATES

103

104```

105┌─────────────────────────────────────────────────────────────┐

106│ CLAUDE-FLOW = ORCHESTRATOR (tracks state, coordinates) │

107│ CODEX = WORKER (writes code, runs commands, implements) │

108└─────────────────────────────────────────────────────────────┘

109```

110

111### ❌ WRONG: Expecting claude-flow to execute tasks

112```bash

113npx claude-flow swarm start --objective "Build API"

114# WRONG: Waiting for claude-flow to build the API

115# Claude-flow does NOT execute code!

116```

117

118### ✅ CORRECT: Codex executes, claude-flow tracks

119```bash

120# 1. Tell claude-flow what you're doing (optional coordination)

121npx claude-flow swarm init --topology hierarchical --max-agents 1

122npx claude-flow agent spawn --type coder --name codex-worker

123

124# 2. YOU (CODEX) DO THE ACTUAL WORK:

125mkdir -p src

126cat > src/api.ts << 'EOF'

127export function hello() { return "Hello World"; }

128EOF

129

130# 3. Report to claude-flow what you did (optional)

131npx claude-flow memory store --key "api-created" --value "src/api.ts" --namespace results

132```

133

134### The Division of Labor

135

136| Component | Role | Examples |

137|-----------|------|----------|

138| **CODEX** | EXECUTES | Write files, run tests, create code, shell commands |

139| **claude-flow** | ORCHESTRATES | Track agents, store memory, coordinate tasks |

140

141---

142

143## ⛔ DON'T STOP AFTER CALLING CLAUDE-FLOW

144

145```

146┌─────────────────────────────────────────────────────────────────────────┐

147│ ❌ WRONG: Call claude-flow → STOP → Wait for results │

148│ ✅ RIGHT: Call claude-flow → IMMEDIATELY continue → YOU do the work │

149└─────────────────────────────────────────────────────────────────────────┘

150```

151

152### ❌ WRONG Pattern (Stopping)

153```bash

154npx claude-flow swarm init --topology hierarchical

155npx claude-flow agent spawn --type coder --name worker-1

156npx claude-flow swarm start --objective "Build hello world"

157# WRONG: Codex stops here and waits for something to happen

158# Nothing will happen! Claude-flow doesn't execute code!

159```

160

161### ✅ CORRECT Pattern (Continue Immediately)

162```bash

163# Step 1: Coordination (optional)

164npx claude-flow swarm init --topology hierarchical

165npx claude-flow agent spawn --type coder --name worker-1

166

167# Step 2: IMMEDIATELY DO THE WORK YOURSELF - DON'T WAIT!

168echo 'console.log("Hello World!");' > hello.js

169node hello.js

170

171# Step 3: Report what you did

172npx claude-flow memory store --key "result" --value "Hello World printed" --namespace results

173```

174

175### The Rule

176**After ANY claude-flow command, IMMEDIATELY continue with your own work.**

177

178Claude-flow commands return instantly. They create coordination RECORDS only.

179You must ALWAYS follow up with YOUR OWN execution.

180

181| After This... | IMMEDIATELY Do This... |

182|---------------|----------------------|

183| `swarm init` | Start writing code |

184| `agent spawn` | Continue implementation |

185| `task create` | Execute the task yourself |

186| `swarm start` | Begin actual work |

187

188---

189

190### When to Use Claude-Flow Commands

191

192| Use Case | Claude-Flow Command | Then Codex Does |

193|----------|---------------------|-----------------|

194| Track progress | `memory store --key "step1" --value "done"` | Continue to next step |

195| Multi-step tasks | `task create --description "step 2"` | Execute step 2 |

196| Store results | `memory store --key "output" --value "..."` | Move on |

197| Coordinate | `swarm init` | Start working |

198

199### Hello World - Correct Pattern

200

201```bash

202# STEP 1: Optional - register with orchestrator

203npx claude-flow swarm init --topology mesh --max-agents 1

204

205# STEP 2: CODEX DOES THE WORK

206echo 'console.log("Hello World!");' > hello.js

207node hello.js

208

209# STEP 3: Optional - report completion

210npx claude-flow memory store --key "hello-result" --value "printed Hello World" --namespace results

211```

212

213**REMEMBER: If you need something DONE, YOU do it. Claude-flow just tracks.**

214

215---

216

217## ⚡ QUICK COMMANDS (NO DISCOVERY NEEDED)

218

219### Spawn N-Agent Swarm (Copy-Paste Ready)

220

221```bash

222# 5-AGENT SWARM - Run these commands in sequence:

223npx claude-flow swarm init --topology hierarchical --max-agents 8

224npx claude-flow agent spawn --type coordinator --name coord-1

225npx claude-flow agent spawn --type coder --name coder-1

226npx claude-flow agent spawn --type coder --name coder-2

227npx claude-flow agent spawn --type tester --name tester-1

228npx claude-flow agent spawn --type reviewer --name reviewer-1

229npx claude-flow swarm start --objective "Your task here" --strategy development

230```

231

232### Common Swarm Patterns

233

234| Task | Exact Command |

235|------|---------------|

236| Init hierarchical swarm | `npx claude-flow swarm init --topology hierarchical --max-agents 8` |

237| Init mesh swarm | `npx claude-flow swarm init --topology mesh --max-agents 5` |

238| Init V3 mode (15 agents) | `npx claude-flow swarm init --v3-mode` |

239| Spawn coder | `npx claude-flow agent spawn --type coder --name coder-1` |

240| Spawn tester | `npx claude-flow agent spawn --type tester --name tester-1` |

241| Spawn coordinator | `npx claude-flow agent spawn --type coordinator --name coord-1` |

242| Spawn architect | `npx claude-flow agent spawn --type architect --name arch-1` |

243| Spawn reviewer | `npx claude-flow agent spawn --type reviewer --name rev-1` |

244| Spawn researcher | `npx claude-flow agent spawn --type researcher --name res-1` |

245| Start swarm | `npx claude-flow swarm start --objective "task" --strategy development` |

246| Check swarm status | `npx claude-flow swarm status` |

247| List agents | `npx claude-flow agent list` |

248| Stop swarm | `npx claude-flow swarm stop` |

249

250### Agent Types (Use with `--type`)

251

252| Type | Purpose |

253|------|---------|

254| `coordinator` | Orchestrates other agents |

255| `coder` | Writes code |

256| `tester` | Writes tests |

257| `reviewer` | Reviews code |

258| `architect` | Designs systems |

259| `researcher` | Analyzes requirements |

260| `security-architect` | Security design |

261| `performance-engineer` | Optimization |

262

263### Task Commands

264

265| Action | Command |

266|--------|---------|

267| Create task | `npx claude-flow task create --type implementation --description "desc"` |

268| List tasks | `npx claude-flow task list` |

269| Assign task | `npx claude-flow task assign TASK_ID --agent AGENT_NAME` |

270| Task status | `npx claude-flow task status TASK_ID` |

271| Cancel task | `npx claude-flow task cancel TASK_ID` |

272

273### Memory Commands

274

275| Action | Command |

276|--------|---------|

277| Store | `npx claude-flow memory store --key "key" --value "value" --namespace patterns` |

278| Search | `npx claude-flow memory search --query "search terms"` |

279| List | `npx claude-flow memory list --namespace patterns` |

280| Retrieve | `npx claude-flow memory retrieve --key "key"` |

281

282---

283

284## 🚀 SWARM RECIPES

285

286### Recipe 1: Hello World Test (COMPLETE EXAMPLE)

287

288**Step 1: Setup coordination** (returns instantly - don't stop!)

289```bash

290npx claude-flow swarm init --topology mesh --max-agents 5

291npx claude-flow agent spawn --type coder --name hello-main

292# ⚠️ DON'T STOP HERE - CONTINUE IMMEDIATELY TO STEP 2

293```

294

295**Step 2: YOU (Codex) execute the task** (THIS IS THE REAL WORK)

296```bash

297# ✅ YOU create the file

298echo 'console.log("Hello World from Swarm!");' > /tmp/hello-swarm.js

299

300# ✅ YOU execute it

301node /tmp/hello-swarm.js

302# Output: Hello World from Swarm!

303```

304

305**Step 3: Report completion** (optional - store results)

306```bash

307npx claude-flow memory store --key "hello-world-result" --value "Executed: Hello World from Swarm!" --namespace results

308```

309

310### Recipe 1b: 5-Agent Concurrent Hello World (COMPLETE)

311```bash

312# COORDINATION (instant - creates records only)

313npx claude-flow swarm init --topology hierarchical --max-agents 5

314for i in 1 2 3 4 5; do

315 npx claude-flow agent spawn --type coder --name "worker-$i"

316done

317

318# ⚠️ NOW YOU DO THE ACTUAL CONCURRENT WORK:

319for i in 1 2 3 4 5; do

320 (echo "Worker $i: Hello World!" && sleep 0.$i) &

321done

322wait

323echo "All 5 workers completed!"

324

325# REPORT (optional)

326npx claude-flow memory store --key "concurrent-result" --value "5 workers completed" --namespace results

327```

328

329### Recipe 1b: Hello World (Single Command Block)

330```bash

331# All-in-one execution

332npx claude-flow swarm init --topology mesh --max-agents 5 && \

333npx claude-flow agent spawn --type coder --name hello-main && \

334npx claude-flow swarm start --objective "Print hello world" --strategy development && \

335echo 'console.log("Hello World from Swarm!");' > /tmp/hello-swarm.js && \

336node /tmp/hello-swarm.js && \

337npx claude-flow memory store --key "hello-world-result" --value "Success" --namespace results

338```

339

340### Recipe 2: Feature Implementation (6 Agents)

341```bash

342npx claude-flow swarm init --topology hierarchical --max-agents 8

343npx claude-flow agent spawn --type coordinator --name lead

344npx claude-flow agent spawn --type architect --name arch

345npx claude-flow agent spawn --type coder --name impl-1

346npx claude-flow agent spawn --type coder --name impl-2

347npx claude-flow agent spawn --type tester --name test

348npx claude-flow agent spawn --type reviewer --name review

349npx claude-flow swarm start --objective "Implement [feature]" --strategy development

350```

351

352### Recipe 3: Bug Fix (4 Agents)

353```bash

354npx claude-flow swarm init --topology hierarchical --max-agents 4

355npx claude-flow agent spawn --type coordinator --name lead

356npx claude-flow agent spawn --type researcher --name debug

357npx claude-flow agent spawn --type coder --name fix

358npx claude-flow agent spawn --type tester --name verify

359npx claude-flow swarm start --objective "Fix [bug]" --strategy development

360```

361

362### Recipe 4: Security Audit (3 Agents)

363```bash

364npx claude-flow swarm init --topology hierarchical --max-agents 4

365npx claude-flow agent spawn --type coordinator --name lead

366npx claude-flow agent spawn --type security-architect --name audit

367npx claude-flow agent spawn --type reviewer --name review

368npx claude-flow swarm start --objective "Security audit" --strategy development

369```

370

371### Recipe 5: V3 Full Coordination (15 Agents)

372```bash

373npx claude-flow swarm init --v3-mode

374npx claude-flow swarm coordinate --agents 15

375```

376

377---

378

379## 📋 BEHAVIORAL RULES

380

381- **YOU (CODEX) execute tasks** - claude-flow only orchestrates

382- Do what is asked; nothing more, nothing less

383- NEVER create files unless absolutely necessary

384- ALWAYS prefer editing existing files

385- NEVER save to root folder

386- NEVER commit secrets or .env files

387- ALWAYS read a file before editing it

388- NEVER wait for claude-flow to "do work" - it doesn't execute, YOU do

389- Use claude-flow commands to TRACK progress, not to EXECUTE tasks

390

391## 📁 FILE ORGANIZATION

392

393| Directory | Purpose |

394|-----------|---------|

395| `/src` | Source code |

396| `/tests` | Test files |

397| `/docs` | Documentation |

398| `/config` | Configuration |

399| `/scripts` | Utility scripts |

400

401## 🎯 WHEN TO USE SWARMS

402

403**USE SWARM:**

404- Multiple files (3+)

405- New feature implementation

406- Cross-module refactoring

407- API changes with tests

408- Security-related changes

409- Performance optimization

410

411**SKIP SWARM:**

412- Single file edits

413- Simple bug fixes (1-2 lines)

414- Documentation updates

415- Configuration changes

416

417---

418

419## 🔧 CLI REFERENCE

420

421### Swarm Commands

422```bash

423npx claude-flow swarm init [--topology TYPE] [--max-agents N] [--v3-mode]

424npx claude-flow swarm start --objective "task" --strategy [development|research]

425npx claude-flow swarm status [SWARM_ID]

426npx claude-flow swarm stop [SWARM_ID]

427npx claude-flow swarm scale --count N

428npx claude-flow swarm coordinate --agents N

429```

430

431### Agent Commands

432```bash

433npx claude-flow agent spawn --type TYPE --name NAME

434npx claude-flow agent list [--filter active|idle|busy]

435npx claude-flow agent status AGENT_ID

436npx claude-flow agent stop AGENT_ID

437npx claude-flow agent metrics [AGENT_ID]

438npx claude-flow agent health

439npx claude-flow agent logs AGENT_ID

440```

441

442### Task Commands

443```bash

444npx claude-flow task create --type TYPE --description "desc"

445npx claude-flow task list [--all]

446npx claude-flow task status TASK_ID

447npx claude-flow task assign TASK_ID --agent AGENT_NAME

448npx claude-flow task cancel TASK_ID

449npx claude-flow task retry TASK_ID

450```

451

452### Memory Commands

453```bash

454npx claude-flow memory store --key KEY --value VALUE [--namespace NS]

455npx claude-flow memory search --query "terms" [--namespace NS]

456npx claude-flow memory list [--namespace NS]

457npx claude-flow memory retrieve --key KEY [--namespace NS]

458npx claude-flow memory init [--force]

459```

460

461### Hooks Commands

462```bash

463npx claude-flow hooks pre-task --description "task"

464npx claude-flow hooks post-task --task-id ID --success true

465npx claude-flow hooks route --task "task"

466npx claude-flow hooks session-start --session-id ID

467npx claude-flow hooks session-end --export-metrics true

468npx claude-flow hooks worker list

469npx claude-flow hooks worker dispatch --trigger audit

470```

471

472### System Commands

473```bash

474npx claude-flow init [--wizard] [--codex] [--full]

475npx claude-flow daemon start

476npx claude-flow daemon stop

477npx claude-flow daemon status

478npx claude-flow doctor [--fix]

479npx claude-flow status

480npx claude-flow mcp start

481```

482

483---

484

485## 🔌 TOPOLOGIES

486

487| Topology | Use Case | Command Flag |

488|----------|----------|--------------|

489| `hierarchical` | Coordinated teams, anti-drift | `--topology hierarchical` |

490| `mesh` | Peer-to-peer, equal agents | `--topology mesh` |

491| `hierarchical-mesh` | Hybrid (recommended for V3) | `--topology hierarchical-mesh` |

492| `ring` | Sequential processing | `--topology ring` |

493| `star` | Central coordinator | `--topology star` |

494| `adaptive` | Dynamic switching | `--topology adaptive` |

495

496## 🤖 AGENT TYPES

497

498### Core

499`coordinator`, `coder`, `tester`, `reviewer`, `architect`, `researcher`

500

501### Specialized

502`security-architect`, `security-auditor`, `memory-specialist`, `performance-engineer`

503

504### Swarm Coordination

505`hierarchical-coordinator`, `mesh-coordinator`, `adaptive-coordinator`

506

507### Consensus

508`byzantine-coordinator`, `raft-manager`, `gossip-coordinator`

509

510---

511

512## ⚙️ CONFIGURATION

513

514### Default Swarm Config

515- Topology: `hierarchical`

516- Max Agents: 8

517- Strategy: `specialized`

518- Consensus: `raft`

519- Memory: `hybrid`

520

521### Environment Variables

522```bash

523CLAUDE_FLOW_CONFIG=./claude-flow.config.json

524CLAUDE_FLOW_LOG_LEVEL=info

525CLAUDE_FLOW_MEMORY_BACKEND=hybrid

526```

527

528---

529

530## 🔗 SKILLS

531

532Invoke with `$skill-name`:

533

534| Skill | Purpose |

535|-------|---------|

536| `$swarm-orchestration` | Multi-agent coordination |

537| `$memory-management` | Pattern storage/retrieval |

538| `$sparc-methodology` | Structured development |

539| `$security-audit` | Security scanning |

540| `$performance-analysis` | Profiling |

541| `$github-automation` | CI/CD management |

542| `$hive-mind` | Byzantine consensus |

543| `$neural-training` | Pattern learning |

544

545---

546

547---

548

549## 🔌 MCP INTEGRATION (Learning & Coordination)

550

551Codex doesn't have native hooks like Claude Code, but uses **MCP (Model Context Protocol)** for learning and coordination.

552

553### MCP Auto-Registration

554

555When you run `npx claude-flow init --codex`, the MCP server is **automatically registered** with Codex.

556

557```bash

558# Verify MCP is registered:

559codex mcp list

560

561# Expected output:

562# Name Command Args Status

563# claude-flow npx claude-flow mcp start enabled

564

565# If not present, add manually:

566codex mcp add claude-flow -- npx claude-flow mcp start

567```

568

569### Test MCP Connection

570```bash

571# Test MCP server starts correctly:

572npx claude-flow mcp start --test

573```

574

575### MCP Tools Available

576Once added, Codex can use these tools via MCP:

577

578**Coordination:**

579| Tool | Purpose |

580|------|---------|

581| `swarm_init` | Initialize swarm (topology, maxAgents) |

582| `swarm_status` | Check swarm state |

583| `agent_spawn` | Register agent roles |

584| `agent_status` | Check agent state |

585| `task_orchestrate` | Coordinate multi-agent tasks |

586

587**Learning & Memory (USE THESE!):**

588| Tool | Purpose | When |

589|------|---------|------|

590| `memory_search` | Semantic vector search | BEFORE every task |

591| `memory_store` | Store patterns with embeddings | AFTER success |

592| `memory_retrieve` | Get by exact key | When key is known |

593| `neural_train` | Train on patterns | Periodic improvement |

594| `neural_status` | Check learning state | Debugging |

595

596**Hive Mind (Advanced):**

597| Tool | Purpose |

598|------|---------|

599| `hive-mind_init` | Byzantine consensus swarm |

600| `hive-mind_spawn` | Spawn hive workers |

601| `hive-mind_broadcast` | Message all workers |

602

603### Self-Learning via MCP Tools (PREFERRED)

604

605Use MCP tools directly - faster than CLI commands:

606

607**BEFORE starting any task - SEARCH for patterns:**

608```

609Use tool: memory_search

610 query: "keywords related to your task"

611 namespace: "patterns"

612```

613

614**AFTER completing successfully - STORE the pattern:**

615```

616Use tool: memory_store

617 key: "pattern-[descriptive-name]"

618 value: "What worked: approach, code patterns, gotchas"

619 namespace: "patterns"

620```

621

622### MCP Learning Workflow (Use This!)

623

624```

6251. LEARN: memory_search(query="task keywords", namespace="patterns")

626 → If score > 0.7, USE that pattern

627

6282. COORDINATE: swarm_init(topology="hierarchical")

629 → agent_spawn(type="coder", name="worker-1")

630

6313. EXECUTE: YOU write the code, run commands, create files

632

6334. REMEMBER: memory_store(key="pattern-x", value="what worked", namespace="patterns")

634```

635

636### MCP Tools for Learning

637

638| Tool | Purpose | When to Use |

639|------|---------|-------------|

640| `memory_search` | Find similar past patterns | BEFORE starting any task |

641| `memory_store` | Save successful patterns | AFTER completing a task |

642| `memory_retrieve` | Get specific pattern by key | When you know the exact key |

643| `neural_train` | Train on successful patterns | After multiple successes |

644

645### Example: Learning-Enabled Task

646

647```

648STEP 1 - LEARN:

649Use tool: memory_search

650 query: "validation utility function"

651 namespace: "patterns"

652

653→ Found: pattern-email-validator (score: 0.82)

654→ Use this pattern as reference!

655

656STEP 2 - COORDINATE:

657Use tool: swarm_init with topology="hierarchical", maxAgents=3

658

659STEP 3 - EXECUTE:

660YOU create the files:

661 echo 'export function validate(x) { ... }' > /tmp/validator.js

662 node --test /tmp/validator.js

663

664STEP 4 - REMEMBER:

665Use tool: memory_store

666 key: "pattern-phone-validator"

667 value: "Phone validation: regex /^\+?[\d\s-]{10,}$/, normalize first, test edge cases"

668 namespace: "patterns"

669```

670

671### Vector Search Tips

672- Searches are SEMANTIC (meaning-based, not just keywords)

673- Score > 0.7 = strong match, use that pattern

674- Score 0.5-0.7 = partial match, adapt as needed

675- Store DETAILED values for better future retrieval

676

677### CLI Fallback (if MCP unavailable)

678```bash

679npx claude-flow memory search --query "keywords" --namespace patterns

680npx claude-flow memory store --key "pattern-x" --value "what worked" --namespace patterns

681```

682

683### Coordination via MCP

684

685When claude-flow is added as MCP server, Codex can call tools directly:

686```

687Use tool: swarm_init with topology="hierarchical"

688Use tool: memory_store with key="result" value="success"

689```

690

691### config.toml MCP Setup

692```toml

693# ~/.codex/config.toml

694[mcp_servers.claude-flow]

695command = "npx"

696args = ["claude-flow", "mcp", "start"]

697enabled = true

698```

699

700---

701

702## 📚 SUPPORT

703

704- Docs: https://github.com/ruvnet/claude-flow

705- Issues: https://github.com/ruvnet/claude-flow/issues

706

707**Remember: Codex executes, claude-flow orchestrates!**

708

@@ −1 +1 @@

1−# CLAUDE.md

1+# Claude Flow V3 - Agent Guide

3−This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

3+> **For OpenAI Codex CLI** - Agentic AI Foundation standard

4+> Skills: `$skill-name` | Config: `.agents/config.toml`

5−## Overview

6+---

7−Chat UI is a SvelteKit application that provides a chat interface for LLMs. It powers HuggingChat (hf.co/chat). The app speaks exclusively to OpenAI-compatible APIs via `OPENAI_BASE_URL`.

8+## 📢 TL;DR - READ THIS FIRST

9−## Commands

10+```

11+╔═══════════════════════════════════════════════════════════════════════════╗

12+║ 1. claude-flow = LEDGER (tracks state, stores memory, coordinates) ║

13+║ 2. Codex = EXECUTOR (writes code, runs commands, creates files) ║

14+║ 3. NEVER stop after calling claude-flow - IMMEDIATELY continue working ║

15+║ 4. If you need something BUILT/EXECUTED, YOU do it, not claude-flow ║

16+║ 5. ALWAYS search memory BEFORE starting: memory search --query "task" ║

17+║ 6. ALWAYS store patterns AFTER success: memory store --namespace patterns║

18+╚═══════════════════════════════════════════════════════════════════════════╝

19+```

1020

21+**Workflow (Use MCP Tools):**

22+1. `memory_search(query="task keywords")` → LEARN from past patterns (score > 0.7 = use it)

23+2. `swarm_init(topology="hierarchical")` → coordination record (instant)

24+3. **YOU write the code / run the commands** ← THIS IS WHERE WORK HAPPENS

25+4. `memory_store(key="pattern-x", value="what worked", namespace="patterns")` → REMEMBER for next time

26+

27+---

28+

29+## Ruflo Policy-Governed Concurrent Codex Workflow

30+

31+Ruflo is the coordination ledger and policy decision point. Codex agents are

32+the executors. Coordination records do not write code or run tests.

33+

34+Use `guidance_brain({ mode: "recommend", task: "..." })` to select Ruflo

35+capabilities from the live MCP registry. A registered tool is not necessarily

36+configured, reachable, healthy, or authorized. If it is unavailable, continue

37+with compatible guidance tools, CLI discovery, and repository instructions.

38+

39+1. Recall relevant AgentDB memory and ADRs.

40+2. Inspect source, runtime, dependencies, policy, and health.

41+3. Route to the smallest capable topology, agents, skills, and tools.

42+4. Plan acceptance criteria, safety envelope, ownership, and validation.

43+5. Execute with Codex workers in isolated scopes; Ruflo records coordination.

44+6. Test focused, regression, and failure paths.

45+7. Validate types, security, policy, compatibility, and artifact integrity.

46+8. Benchmark a source-bound candidate against a source-bound baseline.

47+9. Optimize only measured bottlenecks without weakening safety.

48+10. Bind claims and evidence into exact source/build receipts.

49+11. Reconcile handoffs and disclose unresolved limitations.

50+12. Publish only through a separately authorized release gate.

51+

52+Hard invariants:

53+

54+- Never run two writers in one worktree.

55+- Delegation may only reduce tools, servers, namespaces, network, spend,

56+ concurrency, expiry, and depth.

57+- Policy denial cancels dependent work before side effects.

58+- MetaHarness may evaluate candidates concurrently, but only ADR-322A may

59+ promote them and MetaHarness may never expand its own SafetyEnvelope.

60+- Do not commit, push, merge, release, or remove worktrees unless authorized.

61+- Existing installations migrate in `legacy` policy mode; use `observe` before

62+ switching to `enforce`.

63+

64+Repository harness integration:

65+

66+- If tracked repository instructions define a collaboration harness, start its

67+ session only after assigning an isolated worktree.

68+- Inspect existing claims, acquire exact paths/resources/ports, renew leases,

69+ check acknowledged inbox messages at integration boundaries, and release ownership on

70+ handoff or exit.

71+- A repository lease coordinates ownership; it does not grant authorization.

72+ Protected work still requires the ADR-324/325 action capability and current

73+ fencing epoch.

74+- In-memory reference adapters demonstrate semantics; they are not distributed,

75+ restart-durable release authorities.

76+- Heartbeats and lease expiry establish liveness; a PID is diagnostic only.

77+- `HEAD` alone is not an exact source-state identity in a dirty worktree.

78+ Release evidence must bind a clean commit or an immutable snapshot of tracked

79+ and untracked changes.

80+

81+Useful checks:

82+

1183 ```bash

12−npm run dev # Start dev server on localhost:5173

13−npm run build # Production build

14−npm run preview # Preview production build

15−npm run check # TypeScript validation (svelte-kit sync + svelte-check)

16−npm run lint # Check formatting (Prettier) and linting (ESLint)

17−npm run format # Auto-format with Prettier

18−npm run test # Run all tests (Vitest)

84+npx ruflo policy status

85+npx ruflo policy verify

86+npx ruflo metaharness flywheel status

1987 ```

2088

21−### Running a Single Test

89+Repository release contract:

2290

91+- The stable public train is exactly `@claude-flow/cli`, `claude-flow`, and

92+ `ruflo`; internal `@claude-flow/*` components are bundled and are not part of

93+ a normal standalone publish.

94+- Publish from a clean, reviewed source state in that order.

95+- Only the CLI publish receives the helper-signing configuration from

96+ `ruv-dev`; use the existing authenticated npm session for publication.

97+- Run `node scripts/audit-umbrella-version-lockstep.mjs`, verify all three

98+ registry versions, and align `latest`, `alpha`, and `v3alpha`.

99+

100+---

101+

102+## 🚨 CRITICAL: CODEX DOES THE WORK, CLAUDE-FLOW ORCHESTRATES

103+

104+```

105+┌─────────────────────────────────────────────────────────────┐

106+│ CLAUDE-FLOW = ORCHESTRATOR (tracks state, coordinates) │

107+│ CODEX = WORKER (writes code, runs commands, implements) │

108+└─────────────────────────────────────────────────────────────┘

109+```

110+

111+### ❌ WRONG: Expecting claude-flow to execute tasks

23112 ```bash

24−npx vitest run path/to/file.spec.ts # Run specific test file

25−npx vitest run -t "test name" # Run test by name

26−npx vitest --watch path/to/file.spec.ts # Watch mode for single file

113+npx claude-flow swarm start --objective "Build API"

114+# WRONG: Waiting for claude-flow to build the API

115+# Claude-flow does NOT execute code!

27116 ```

28117

29−### Test Environments

118+### ✅ CORRECT: Codex executes, claude-flow tracks

119+```bash

120+# 1. Tell claude-flow what you're doing (optional coordination)

121+npx claude-flow swarm init --topology hierarchical --max-agents 1

122+npx claude-flow agent spawn --type coder --name codex-worker

30123

31−Tests are split into three workspaces (configured in vite.config.ts):

124+# 2. YOU (CODEX) DO THE ACTUAL WORK:

125+mkdir -p src

126+cat > src/api.ts << 'EOF'

127+export function hello() { return "Hello World"; }

128+EOF

32129

33−- **Client tests** (`*.svelte.test.ts`): Browser environment with Playwright

34−- **SSR tests** (`*.ssr.test.ts`): Node environment for server-side rendering

35−- **Server tests** (`*.test.ts`, `*.spec.ts`): Node environment for utilities

130+# 3. Report to claude-flow what you did (optional)

131+npx claude-flow memory store --key "api-created" --value "src/api.ts" --namespace results

132+```

36133

37−## Architecture

134+### The Division of Labor

38135

39−### Stack

136+| Component | Role | Examples |

137+|-----------|------|----------|

138+| **CODEX** | EXECUTES | Write files, run tests, create code, shell commands |

139+| **claude-flow** | ORCHESTRATES | Track agents, store memory, coordinate tasks |

40140

41−- **SvelteKit 2** with Svelte 5 (uses runes: `$state`, `$effect`, `$bindable`)

42−- **MongoDB** for persistence (auto-fallback to in-memory with MongoMemoryServer when `MONGODB_URL` not set)

43−- **TailwindCSS** for styling

141+---

44142

45−### Key Directories

143+## ⛔ DON'T STOP AFTER CALLING CLAUDE-FLOW

46144

47145 ```

48−src/

49−├── lib/

50−│ ├── components/ # Svelte components (chat/, mcp/, voice/, icons/)

51−│ ├── server/

52−│ │ ├── api/utils/ # Shared API helpers (auth, superjson, model/conversation resolvers)

53−│ │ ├── textGeneration/ # LLM streaming pipeline

54−│ │ ├── mcp/ # Model Context Protocol integration

55−│ │ ├── router/ # Smart model routing (Omni)

56−│ │ ├── database.ts # MongoDB collections

57−│ │ ├── models.ts # Model registry from OPENAI_BASE_URL/models

58−│ │ └── auth.ts # OpenID Connect authentication

59−│ ├── types/ # TypeScript interfaces (Conversation, Message, User, Model, etc.)

60−│ ├── stores/ # Svelte stores for reactive state

61−│ └── utils/ # Helpers (tree/, marked.ts, auth.ts, etc.)

62−├── routes/ # SvelteKit file-based routing

63−│ ├── conversation/[id]/ # Chat page + streaming endpoint

64−│ ├── settings/ # User settings pages

65−│ ├── api/ # Legacy v1 API endpoints (mcp, transcribe, fetch-url)

66−│ ├── api/v2/ # REST API endpoints (+server.ts)

67−│ └── r/[id]/ # Shared conversation view

146+┌─────────────────────────────────────────────────────────────────────────┐

147+│ ❌ WRONG: Call claude-flow → STOP → Wait for results │

148+│ ✅ RIGHT: Call claude-flow → IMMEDIATELY continue → YOU do the work │

149+└─────────────────────────────────────────────────────────────────────────┘

68150 ```

69151

70−### Text Generation Flow

152+### ❌ WRONG Pattern (Stopping)

153+```bash

154+npx claude-flow swarm init --topology hierarchical

155+npx claude-flow agent spawn --type coder --name worker-1

156+npx claude-flow swarm start --objective "Build hello world"

157+# WRONG: Codex stops here and waits for something to happen

158+# Nothing will happen! Claude-flow doesn't execute code!

159+```

71160

72−1. User sends message via `POST /conversation/[id]`

73−2. Server validates user, fetches conversation history

74−3. Builds message tree structure (see `src/lib/utils/tree/`)

75−4. Calls LLM endpoint via OpenAI client

76−5. Streams response back, stores in MongoDB

161+### ✅ CORRECT Pattern (Continue Immediately)

162+```bash

163+# Step 1: Coordination (optional)

164+npx claude-flow swarm init --topology hierarchical

165+npx claude-flow agent spawn --type coder --name worker-1

77166

78−### Model Context Protocol (MCP)

167+# Step 2: IMMEDIATELY DO THE WORK YOURSELF - DON'T WAIT!

168+echo 'console.log("Hello World!");' > hello.js

169+node hello.js

79170

80−MCP servers are configured via `MCP_SERVERS` env var. When enabled, tools are exposed as OpenAI function calls. The router can auto-select tools-capable models when `LLM_ROUTER_ENABLE_TOOLS=true`.

171+# Step 3: Report what you did

172+npx claude-flow memory store --key "result" --value "Hello World printed" --namespace results

173+```

81174

82−### LLM Router (Omni)

175+### The Rule

176+**After ANY claude-flow command, IMMEDIATELY continue with your own work.**

83177

84−Smart routing via Arch-Router model. Configured with:

178+Claude-flow commands return instantly. They create coordination RECORDS only.

179+You must ALWAYS follow up with YOUR OWN execution.

85180

86−- `LLM_ROUTER_ROUTES_PATH`: JSON file defining routes

87−- `LLM_ROUTER_ARCH_BASE_URL`: Router endpoint

88−- Shortcuts: multimodal routes bypass router if `LLM_ROUTER_ENABLE_MULTIMODAL=true`

181+| After This... | IMMEDIATELY Do This... |

182+|---------------|----------------------|

183+| `swarm init` | Start writing code |

184+| `agent spawn` | Continue implementation |

185+| `task create` | Execute the task yourself |

186+| `swarm start` | Begin actual work |

89187

90−### Database Collections

188+---

91189

92−- `conversations` - Chat sessions with nested messages

93−- `users` - User accounts (OIDC-backed)

94−- `sessions` - Session data

95−- `sharedConversations` - Public share links

96−- `settings` - User preferences

190+### When to Use Claude-Flow Commands

97191

98−## Environment Setup

192+| Use Case | Claude-Flow Command | Then Codex Does |

193+|----------|---------------------|-----------------|

194+| Track progress | `memory store --key "step1" --value "done"` | Continue to next step |

195+| Multi-step tasks | `task create --description "step 2"` | Execute step 2 |

196+| Store results | `memory store --key "output" --value "..."` | Move on |

197+| Coordinate | `swarm init` | Start working |

99198

100−Copy `.env` to `.env.local` and configure:

199+### Hello World - Correct Pattern

101200

102−```env

103−OPENAI_BASE_URL=https://router.huggingface.co/v1

104−OPENAI_API_KEY=hf_***

105−# MONGODB_URL is optional; omit for in-memory DB persisted to ./db

201+```bash

202+# STEP 1: Optional - register with orchestrator

203+npx claude-flow swarm init --topology mesh --max-agents 1

204+

205+# STEP 2: CODEX DOES THE WORK

206+echo 'console.log("Hello World!");' > hello.js

207+node hello.js

208+

209+# STEP 3: Optional - report completion

210+npx claude-flow memory store --key "hello-result" --value "printed Hello World" --namespace results

106211 ```

107212

108−See `.env` for full list of variables including router config, MCP servers, auth, and feature flags.

213+**REMEMBER: If you need something DONE, YOU do it. Claude-flow just tracks.**

109214

110−## Code Conventions

215+---

111216

112−- TypeScript strict mode enabled

113−- ESLint: no `any`, no non-null assertions

114−- Prettier: tabs, 100 char width, Tailwind class sorting

115−- Server vs client separation via SvelteKit conventions (`+page.server.ts` vs `+page.ts`)

217+## ⚡ QUICK COMMANDS (NO DISCOVERY NEEDED)

116218

117−## Feature Development Checklist

219+### Spawn N-Agent Swarm (Copy-Paste Ready)

118220

119−When building new features, consider:

221+```bash

222+# 5-AGENT SWARM - Run these commands in sequence:

223+npx claude-flow swarm init --topology hierarchical --max-agents 8

224+npx claude-flow agent spawn --type coordinator --name coord-1

225+npx claude-flow agent spawn --type coder --name coder-1

226+npx claude-flow agent spawn --type coder --name coder-2

227+npx claude-flow agent spawn --type tester --name tester-1

228+npx claude-flow agent spawn --type reviewer --name reviewer-1

229+npx claude-flow swarm start --objective "Your task here" --strategy development

230+```

120231

121−1. **HuggingChat vs self-hosted**: Wrap HuggingChat-specific features with `publicConfig.isHuggingChat`

122−2. **Settings persistence**: Add new fields to `src/lib/types/Settings.ts`, update API endpoint at `src/routes/api/v2/user/settings/+server.ts`

123−3. **Rich dropdowns**: Use `bits-ui` (Select, DropdownMenu) instead of native elements when you need icons/images in options

124−4. **Scrollbars**: Use `scrollbar-custom` class for styled scrollbars

125−5. **Icons**: Custom icons in `$lib/components/icons/`, use Carbon (`~icons/carbon/*`) or Lucide (`~icons/lucide/*`) for standard icons

126−6. **Provider avatars**: Use `PROVIDERS_HUB_ORGS` from `@huggingface/inference` for HF provider avatar URLs

232+### Common Swarm Patterns

233+

234+| Task | Exact Command |

235+|------|---------------|

236+| Init hierarchical swarm | `npx claude-flow swarm init --topology hierarchical --max-agents 8` |

237+| Init mesh swarm | `npx claude-flow swarm init --topology mesh --max-agents 5` |

238+| Init V3 mode (15 agents) | `npx claude-flow swarm init --v3-mode` |

239+| Spawn coder | `npx claude-flow agent spawn --type coder --name coder-1` |

240+| Spawn tester | `npx claude-flow agent spawn --type tester --name tester-1` |

241+| Spawn coordinator | `npx claude-flow agent spawn --type coordinator --name coord-1` |

242+| Spawn architect | `npx claude-flow agent spawn --type architect --name arch-1` |

243+| Spawn reviewer | `npx claude-flow agent spawn --type reviewer --name rev-1` |

244+| Spawn researcher | `npx claude-flow agent spawn --type researcher --name res-1` |

245+| Start swarm | `npx claude-flow swarm start --objective "task" --strategy development` |

246+| Check swarm status | `npx claude-flow swarm status` |

247+| List agents | `npx claude-flow agent list` |

248+| Stop swarm | `npx claude-flow swarm stop` |

249+

250+### Agent Types (Use with `--type`)

251+

252+| Type | Purpose |

253+|------|---------|

254+| `coordinator` | Orchestrates other agents |

255+| `coder` | Writes code |

256+| `tester` | Writes tests |

257+| `reviewer` | Reviews code |

258+| `architect` | Designs systems |

259+| `researcher` | Analyzes requirements |

260+| `security-architect` | Security design |

261+| `performance-engineer` | Optimization |

262+

263+### Task Commands

264+

265+| Action | Command |

266+|--------|---------|

267+| Create task | `npx claude-flow task create --type implementation --description "desc"` |

268+| List tasks | `npx claude-flow task list` |

269+| Assign task | `npx claude-flow task assign TASK_ID --agent AGENT_NAME` |

270+| Task status | `npx claude-flow task status TASK_ID` |

271+| Cancel task | `npx claude-flow task cancel TASK_ID` |

272+

273+### Memory Commands

274+

275+| Action | Command |

276+|--------|---------|

277+| Store | `npx claude-flow memory store --key "key" --value "value" --namespace patterns` |

278+| Search | `npx claude-flow memory search --query "search terms"` |

279+| List | `npx claude-flow memory list --namespace patterns` |

280+| Retrieve | `npx claude-flow memory retrieve --key "key"` |

281+

282+---

283+

284+## 🚀 SWARM RECIPES

285+

286+### Recipe 1: Hello World Test (COMPLETE EXAMPLE)

287+

288+**Step 1: Setup coordination** (returns instantly - don't stop!)

289+```bash

290+npx claude-flow swarm init --topology mesh --max-agents 5

291+npx claude-flow agent spawn --type coder --name hello-main

292+# ⚠️ DON'T STOP HERE - CONTINUE IMMEDIATELY TO STEP 2

293+```

294+

295+**Step 2: YOU (Codex) execute the task** (THIS IS THE REAL WORK)

296+```bash

297+# ✅ YOU create the file

298+echo 'console.log("Hello World from Swarm!");' > /tmp/hello-swarm.js

299+

300+# ✅ YOU execute it

301+node /tmp/hello-swarm.js

302+# Output: Hello World from Swarm!

303+```

304+

305+**Step 3: Report completion** (optional - store results)

306+```bash

307+npx claude-flow memory store --key "hello-world-result" --value "Executed: Hello World from Swarm!" --namespace results

308+```

309+

310+### Recipe 1b: 5-Agent Concurrent Hello World (COMPLETE)

311+```bash

312+# COORDINATION (instant - creates records only)

313+npx claude-flow swarm init --topology hierarchical --max-agents 5

314+for i in 1 2 3 4 5; do

315+ npx claude-flow agent spawn --type coder --name "worker-$i"

316+done

317+

318+# ⚠️ NOW YOU DO THE ACTUAL CONCURRENT WORK:

319+for i in 1 2 3 4 5; do

320+ (echo "Worker $i: Hello World!" && sleep 0.$i) &

321+done

322+wait

323+echo "All 5 workers completed!"

324+

325+# REPORT (optional)

326+npx claude-flow memory store --key "concurrent-result" --value "5 workers completed" --namespace results

327+```

328+

329+### Recipe 1b: Hello World (Single Command Block)

330+```bash

331+# All-in-one execution

332+npx claude-flow swarm init --topology mesh --max-agents 5 && \

333+npx claude-flow agent spawn --type coder --name hello-main && \

334+npx claude-flow swarm start --objective "Print hello world" --strategy development && \

335+echo 'console.log("Hello World from Swarm!");' > /tmp/hello-swarm.js && \

336+node /tmp/hello-swarm.js && \

337+npx claude-flow memory store --key "hello-world-result" --value "Success" --namespace results

338+```

339+

340+### Recipe 2: Feature Implementation (6 Agents)

341+```bash

342+npx claude-flow swarm init --topology hierarchical --max-agents 8

343+npx claude-flow agent spawn --type coordinator --name lead

344+npx claude-flow agent spawn --type architect --name arch

345+npx claude-flow agent spawn --type coder --name impl-1

346+npx claude-flow agent spawn --type coder --name impl-2

347+npx claude-flow agent spawn --type tester --name test

348+npx claude-flow agent spawn --type reviewer --name review

349+npx claude-flow swarm start --objective "Implement [feature]" --strategy development

350+```

351+

352+### Recipe 3: Bug Fix (4 Agents)

353+```bash

354+npx claude-flow swarm init --topology hierarchical --max-agents 4

355+npx claude-flow agent spawn --type coordinator --name lead

356+npx claude-flow agent spawn --type researcher --name debug

357+npx claude-flow agent spawn --type coder --name fix

358+npx claude-flow agent spawn --type tester --name verify

359+npx claude-flow swarm start --objective "Fix [bug]" --strategy development

360+```

361+

362+### Recipe 4: Security Audit (3 Agents)

363+```bash

364+npx claude-flow swarm init --topology hierarchical --max-agents 4

365+npx claude-flow agent spawn --type coordinator --name lead

366+npx claude-flow agent spawn --type security-architect --name audit

367+npx claude-flow agent spawn --type reviewer --name review

368+npx claude-flow swarm start --objective "Security audit" --strategy development

369+```

370+

371+### Recipe 5: V3 Full Coordination (15 Agents)

372+```bash

373+npx claude-flow swarm init --v3-mode

374+npx claude-flow swarm coordinate --agents 15

375+```

376+

377+---

378+

379+## 📋 BEHAVIORAL RULES

380+

381+- **YOU (CODEX) execute tasks** - claude-flow only orchestrates

382+- Do what is asked; nothing more, nothing less

383+- NEVER create files unless absolutely necessary

384+- ALWAYS prefer editing existing files

385+- NEVER save to root folder

386+- NEVER commit secrets or .env files

387+- ALWAYS read a file before editing it

388+- NEVER wait for claude-flow to "do work" - it doesn't execute, YOU do

389+- Use claude-flow commands to TRACK progress, not to EXECUTE tasks

390+

391+## 📁 FILE ORGANIZATION

392+

393+| Directory | Purpose |

394+|-----------|---------|

395+| `/src` | Source code |

396+| `/tests` | Test files |

397+| `/docs` | Documentation |

398+| `/config` | Configuration |

399+| `/scripts` | Utility scripts |

400+

401+## 🎯 WHEN TO USE SWARMS

402+

403+**USE SWARM:**

404+- Multiple files (3+)

405+- New feature implementation

406+- Cross-module refactoring

407+- API changes with tests

408+- Security-related changes

409+- Performance optimization

410+

411+**SKIP SWARM:**

412+- Single file edits

413+- Simple bug fixes (1-2 lines)

414+- Documentation updates

415+- Configuration changes

416+

417+---

418+

419+## 🔧 CLI REFERENCE

420+

421+### Swarm Commands

422+```bash

423+npx claude-flow swarm init [--topology TYPE] [--max-agents N] [--v3-mode]

424+npx claude-flow swarm start --objective "task" --strategy [development|research]

425+npx claude-flow swarm status [SWARM_ID]

426+npx claude-flow swarm stop [SWARM_ID]

427+npx claude-flow swarm scale --count N

428+npx claude-flow swarm coordinate --agents N

429+```

430+

431+### Agent Commands

432+```bash

433+npx claude-flow agent spawn --type TYPE --name NAME

434+npx claude-flow agent list [--filter active|idle|busy]

435+npx claude-flow agent status AGENT_ID

436+npx claude-flow agent stop AGENT_ID

437+npx claude-flow agent metrics [AGENT_ID]

438+npx claude-flow agent health

439+npx claude-flow agent logs AGENT_ID

440+```

441+

442+### Task Commands

443+```bash

444+npx claude-flow task create --type TYPE --description "desc"

445+npx claude-flow task list [--all]

446+npx claude-flow task status TASK_ID

447+npx claude-flow task assign TASK_ID --agent AGENT_NAME

448+npx claude-flow task cancel TASK_ID

449+npx claude-flow task retry TASK_ID

450+```

451+

452+### Memory Commands

453+```bash

454+npx claude-flow memory store --key KEY --value VALUE [--namespace NS]

455+npx claude-flow memory search --query "terms" [--namespace NS]

456+npx claude-flow memory list [--namespace NS]

457+npx claude-flow memory retrieve --key KEY [--namespace NS]

458+npx claude-flow memory init [--force]

459+```

460+

461+### Hooks Commands

462+```bash

463+npx claude-flow hooks pre-task --description "task"

464+npx claude-flow hooks post-task --task-id ID --success true

465+npx claude-flow hooks route --task "task"

466+npx claude-flow hooks session-start --session-id ID

467+npx claude-flow hooks session-end --export-metrics true

468+npx claude-flow hooks worker list

469+npx claude-flow hooks worker dispatch --trigger audit

470+```

471+

472+### System Commands

473+```bash

474+npx claude-flow init [--wizard] [--codex] [--full]

475+npx claude-flow daemon start

476+npx claude-flow daemon stop

477+npx claude-flow daemon status

478+npx claude-flow doctor [--fix]

479+npx claude-flow status

480+npx claude-flow mcp start

481+```

482+

483+---

484+

485+## 🔌 TOPOLOGIES

486+

487+| Topology | Use Case | Command Flag |

488+|----------|----------|--------------|

489+| `hierarchical` | Coordinated teams, anti-drift | `--topology hierarchical` |

490+| `mesh` | Peer-to-peer, equal agents | `--topology mesh` |

491+| `hierarchical-mesh` | Hybrid (recommended for V3) | `--topology hierarchical-mesh` |

492+| `ring` | Sequential processing | `--topology ring` |

493+| `star` | Central coordinator | `--topology star` |

494+| `adaptive` | Dynamic switching | `--topology adaptive` |

495+

496+## 🤖 AGENT TYPES

497+

498+### Core

499+`coordinator`, `coder`, `tester`, `reviewer`, `architect`, `researcher`

500+

501+### Specialized

502+`security-architect`, `security-auditor`, `memory-specialist`, `performance-engineer`

503+

504+### Swarm Coordination

505+`hierarchical-coordinator`, `mesh-coordinator`, `adaptive-coordinator`

506+

507+### Consensus

508+`byzantine-coordinator`, `raft-manager`, `gossip-coordinator`

509+

510+---

511+

512+## ⚙️ CONFIGURATION

513+

514+### Default Swarm Config

515+- Topology: `hierarchical`

516+- Max Agents: 8

517+- Strategy: `specialized`

518+- Consensus: `raft`

519+- Memory: `hybrid`

520+

521+### Environment Variables

522+```bash

523+CLAUDE_FLOW_CONFIG=./claude-flow.config.json

524+CLAUDE_FLOW_LOG_LEVEL=info

525+CLAUDE_FLOW_MEMORY_BACKEND=hybrid

526+```

527+

528+---

529+

530+## 🔗 SKILLS

531+

532+Invoke with `$skill-name`:

533+

534+| Skill | Purpose |

535+|-------|---------|

536+| `$swarm-orchestration` | Multi-agent coordination |

537+| `$memory-management` | Pattern storage/retrieval |

538+| `$sparc-methodology` | Structured development |

539+| `$security-audit` | Security scanning |

540+| `$performance-analysis` | Profiling |

541+| `$github-automation` | CI/CD management |

542+| `$hive-mind` | Byzantine consensus |

543+| `$neural-training` | Pattern learning |

544+

545+---

546+

547+---

548+

549+## 🔌 MCP INTEGRATION (Learning & Coordination)

550+

551+Codex doesn't have native hooks like Claude Code, but uses **MCP (Model Context Protocol)** for learning and coordination.

552+

553+### MCP Auto-Registration

554+

555+When you run `npx claude-flow init --codex`, the MCP server is **automatically registered** with Codex.

556+

557+```bash

558+# Verify MCP is registered:

559+codex mcp list

560+

561+# Expected output:

562+# Name Command Args Status

563+# claude-flow npx claude-flow mcp start enabled

564+

565+# If not present, add manually:

566+codex mcp add claude-flow -- npx claude-flow mcp start

567+```

568+

569+### Test MCP Connection

570+```bash

571+# Test MCP server starts correctly:

572+npx claude-flow mcp start --test

573+```

574+

575+### MCP Tools Available

576+Once added, Codex can use these tools via MCP:

577+

578+**Coordination:**

579+| Tool | Purpose |

580+|------|---------|

581+| `swarm_init` | Initialize swarm (topology, maxAgents) |

582+| `swarm_status` | Check swarm state |

583+| `agent_spawn` | Register agent roles |

584+| `agent_status` | Check agent state |

585+| `task_orchestrate` | Coordinate multi-agent tasks |

586+

587+**Learning & Memory (USE THESE!):**

588+| Tool | Purpose | When |

589+|------|---------|------|

590+| `memory_search` | Semantic vector search | BEFORE every task |

591+| `memory_store` | Store patterns with embeddings | AFTER success |

592+| `memory_retrieve` | Get by exact key | When key is known |

593+| `neural_train` | Train on patterns | Periodic improvement |

594+| `neural_status` | Check learning state | Debugging |

595+

596+**Hive Mind (Advanced):**

597+| Tool | Purpose |

598+|------|---------|

599+| `hive-mind_init` | Byzantine consensus swarm |

600+| `hive-mind_spawn` | Spawn hive workers |

601+| `hive-mind_broadcast` | Message all workers |

602+

603+### Self-Learning via MCP Tools (PREFERRED)

604+

605+Use MCP tools directly - faster than CLI commands:

606+

607+**BEFORE starting any task - SEARCH for patterns:**

608+```

609+Use tool: memory_search

610+ query: "keywords related to your task"

611+ namespace: "patterns"

612+```

613+

614+**AFTER completing successfully - STORE the pattern:**

615+```

616+Use tool: memory_store

617+ key: "pattern-[descriptive-name]"

618+ value: "What worked: approach, code patterns, gotchas"

619+ namespace: "patterns"

620+```

621+

622+### MCP Learning Workflow (Use This!)

623+

624+```

625+1. LEARN: memory_search(query="task keywords", namespace="patterns")

626+ → If score > 0.7, USE that pattern

627+

628+2. COORDINATE: swarm_init(topology="hierarchical")

629+ → agent_spawn(type="coder", name="worker-1")

630+

631+3. EXECUTE: YOU write the code, run commands, create files

632+

633+4. REMEMBER: memory_store(key="pattern-x", value="what worked", namespace="patterns")

634+```

635+

636+### MCP Tools for Learning

637+

638+| Tool | Purpose | When to Use |

639+|------|---------|-------------|

640+| `memory_search` | Find similar past patterns | BEFORE starting any task |

641+| `memory_store` | Save successful patterns | AFTER completing a task |

642+| `memory_retrieve` | Get specific pattern by key | When you know the exact key |

643+| `neural_train` | Train on successful patterns | After multiple successes |

644+

645+### Example: Learning-Enabled Task

646+

647+```

648+STEP 1 - LEARN:

649+Use tool: memory_search

650+ query: "validation utility function"

651+ namespace: "patterns"

652+

653+→ Found: pattern-email-validator (score: 0.82)

654+→ Use this pattern as reference!

655+

656+STEP 2 - COORDINATE:

657+Use tool: swarm_init with topology="hierarchical", maxAgents=3

658+

659+STEP 3 - EXECUTE:

660+YOU create the files:

661+ echo 'export function validate(x) { ... }' > /tmp/validator.js

662+ node --test /tmp/validator.js

663+

664+STEP 4 - REMEMBER:

665+Use tool: memory_store

666+ key: "pattern-phone-validator"

667+ value: "Phone validation: regex /^\+?[\d\s-]{10,}$/, normalize first, test edge cases"

668+ namespace: "patterns"

669+```

670+

671+### Vector Search Tips

672+- Searches are SEMANTIC (meaning-based, not just keywords)

673+- Score > 0.7 = strong match, use that pattern

674+- Score 0.5-0.7 = partial match, adapt as needed

675+- Store DETAILED values for better future retrieval

676+

677+### CLI Fallback (if MCP unavailable)

678+```bash

679+npx claude-flow memory search --query "keywords" --namespace patterns

680+npx claude-flow memory store --key "pattern-x" --value "what worked" --namespace patterns

681+```

682+

683+### Coordination via MCP

684+

685+When claude-flow is added as MCP server, Codex can call tools directly:

686+```

687+Use tool: swarm_init with topology="hierarchical"

688+Use tool: memory_store with key="result" value="success"

689+```

690+

691+### config.toml MCP Setup

692+```toml

693+# ~/.codex/config.toml

694+[mcp_servers.claude-flow]

695+command = "npx"

696+args = ["claude-flow", "mcp", "start"]

697+enabled = true

698+```

699+

700+---

701+

702+## 📚 SUPPORT

703+

704+- Docs: https://github.com/ruvnet/claude-flow

705+- Issues: https://github.com/ruvnet/claude-flow/issues

706+

707+**Remember: Codex executes, claude-flow orchestrates!**

127708