npm package: @foxruv/cf-doctor
Description: Setup validator, auto-fixer, and learning persistence for claude-flow + ruvector integration on Linux/Ubuntu
Author: FoxFlow
Latest version: 1.1.0

# cf-doctor

> Setup validator, auto-fixer, and learning persistence for [claude-flow](https://github.com/ruvnet/claude-flow) + [ruvector](https://github.com/ruvnet/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

```bash
# 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`:

```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

```typescript
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

```bash
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:

```bash
# 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:

```typescript
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:

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

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

## Development

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

## License

MIT