cf-doctor

Setup validator, auto-fixer, and learning persistence for claude-flow + ruvector integration.

Fixes the top integration-layer bugs that prevent claude-flow and ruvector from working together on Linux/Ubuntu.

Features

• Environment validation — Checks Node.js, pnpm, Rust, @claude-flow/cli, MCP handshake, @ruvector packages, database drivers
• Auto-fix mode — Installs missing packages, creates directories, generates config
• Learning persistence — Q-learning tables, SONA patterns, and episode history survive restarts
• MCP server — Use as a Claude Code MCP server for integrated tooling
• Git patches — Ready-to-apply fixes for broken @ruvector imports in claude-flow

Quick Start

CLI

# Install globally
npm install -g cf-doctor

# Run diagnostic
cf-doctor

# Auto-fix issues
cf-doctor --fix

# JSON output (for CI)
cf-doctor --json

As MCP Server (Claude Code)

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "cf-doctor": {
      "command": "node",
      "args": ["node_modules/cf-doctor/dist/mcp-server.js"]
    }
  }
}

This exposes 5 tools to Claude:

• cf_doctor_check — Run environment validation
• cf_doctor_fix — Auto-fix environment issues
• cf_recall_episodes — Search past agent episodes by similarity
• cf_store_episode — Store agent episode for future recall
• cf_q_update — Update Q-learning state

As Library

import { runDoctor, recallRelevantEpisodes, PersistentSonaEngine } from 'cf-doctor';

// Run diagnostic programmatically
const result = runDoctor();
console.log(result.counts); // { green: 7, yellow: 1, red: 1 }

// Recall relevant past episodes
const episodes = recallRelevantEpisodes('fix authentication bug', 3);

// Persistent SONA engine
const sona = new PersistentSonaEngine();
await sona.store('auth-pattern', { type: 'jwt', refresh: true });

One-liner Install

curl -fsSL https://raw.githubusercontent.com/foxflow/cf-doctor/main/install.sh | bash

What It Fixes

| Bug | Impact | Fix | |-----|--------|-----| | @ruvector/sona static import crashes | Neural module unusable without WASM | Dynamic import + mock fallback | | @ruvector/attention static import | Performance tests crash | Dynamic import + mock | | claude-flow v2/v3 version mismatch | ruvector hooks fail silently | Auto-detect version, adjust CLI args | | Q-learning state lost on restart | Agents don't learn from experience | File-based persistence with atomic writes | | SONA patterns lost on restart | Pattern recognition resets every session | JSON persistence with debounced saves | | No episode recall | New agents start from scratch | TF-IDF similarity search over past episodes |

Applying Git Patches

To fix the source imports directly in your clone:

# claude-flow patches
cd claude-flow
git apply node_modules/cf-doctor/patches/sona-integration.patch
git apply node_modules/cf-doctor/patches/neural-index.patch
git apply node_modules/cf-doctor/patches/quick-test.patch

# ruvector patch
cd ruvector
git apply node_modules/cf-doctor/patches/version-bridge.patch

Or programmatically:

import { applyPatches } from 'cf-doctor/patches';
const results = applyPatches('/path/to/claude-flow', 'claude-flow');

Traffic Light Output

cf-doctor — claude-flow + ruvector installation validator

── Prerequisites ──
  ✅ Node.js 22.11.0
  ✅ pnpm 9.15.0
  ⚠️  Rust not installed (optional)

── Installation Validation ──
  ✅ @claude-flow/cli v3.1.0
  ✅ MCP handshake OK

── @ruvector Packages ──
  ⚠️  0/8 installed (all using mock fallback)

── Environment ──
  ✅ Directories OK
  ✅ Database: sql.js (WASM)
  ✅ Config generated

╔═══════════════════════════════════╗
║ Result: READY (2 warnings)        ║
╚═══════════════════════════════════╝

Claude Code Skills

Drop the skills into your project:

cp -r node_modules/cf-doctor/skills/ .claude/skills/

Then use /cf-doctor, /cf-patch, or /cf-learn in Claude Code.

Development

git clone https://github.com/foxflow/cf-doctor
cd cf-doctor
npm install
npm run build
npm test

License

MIT