Drop-in replacement for ruflo / @claude-flow/cli with 933+ unpublished upstream commits, bug fixes, and working dependency resolution.
The upstream ruvnet/ruflo ecosystem (48+ npm packages) is severely stale — 60% of @claude-flow/* packages haven't been published since January 2026, ruflo is 933 commits behind its source, and maintainers are unresponsive. ruflo forks, rebuilds, patches, and republishes the entire ecosystem under the @sparkleideas scope so you get current code from a single npx command.
npx ruflo initSame CLI, same commands, same flags — just swap ruflo for @sparkleideas/ruflo. If upstream catches up, switch back with a one-word change.
- Quick Start
- What You Get
- How It Works
- Migrating from ruflo
- Runtime Patches (Legacy)
- For Maintainers
- Project Structure
- Architecture Decisions
- Requirements
- License
# Run directly (no install needed)
npx @sparkleideas/ruflo init
# Or install globally
npm install -g @sparkleideas/rufloAll commands work exactly like ruflo:
npx @sparkleideas/ruflo agent spawn -t coder # spawn an agent
npx @sparkleideas/ruflo memory search --query "auth" # search memory
npx @sparkleideas/ruflo mcp start # start MCP server
npx @sparkleideas/ruflo doctor # diagnose issues| Feature | ruflo (upstream) |
ruflo |
|---|---|---|
| Source commits | 933 behind | Current with upstream HEAD |
@claude-flow/* packages |
Last published Jan 2026 | Rebuilt from source every 6 hours |
| MCP autostart fix (MC-001) | Broken | Fixed |
| Fallback instrumentation (FB-001/002) | Missing | Included |
| Memory ControllerRegistry shim (FB-003) | Missing | Included |
| Hash embedding threshold fix (FB-004) | Missing | Included |
Semver conflicts (@ruvector/ruvllm, agentdb) |
Broken install | Resolved |
npm install |
Fails on dependency conflicts | Clean install |
| Plugin ecosystem | Not repackaged | 14 plugins under @sparkleideas/* |
| Tier 1 routing (agent-booster) | Not available | $0, <1ms for simple edits |
42 packages are rebuilt and published under the @sparkleideas scope across 5 dependency levels. The @ruvector/* packages are used as-is from public npm (they're current).
┌─────────────────────────────────────────────────────┐
│ Build Pipeline │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ ruvnet/ │ │ ruvnet/ │ │ ruvnet/ │ │
│ │ ruflo │ │ agentic- │ │ ruv-FANN │ │
│ │ (fork) │ │ flow │ │ (fork) │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│ │ │ │ │
│ └──────────┬───┘──────────────┘ │
│ ▼ │
│ ┌────────────────┐ │
│ │ git pull │ Zero merge conflicts │
│ │ (clean mirror) │ — forks are unmodified │
│ └───────┬────────┘ │
│ ▼ │
│ ┌────────────────┐ │
│ │ Codemod │ @claude-flow/* → │
│ │ (build-time) │ @sparkleideas/* │
│ └───────┬────────┘ │
│ ▼ │
│ ┌────────────────┐ │
│ │ Apply patches │ MC-001, FB-001–004, │
│ │ │ SV-001–003 │
│ └───────┬────────┘ │
│ ▼ │
│ ┌────────────────┐ │
│ │ pnpm build │ TypeScript → JS │
│ └───────┬────────┘ │
│ ▼ │
│ ┌────────────────┐ │
│ │ npm publish │ 42 packages, │
│ │ --tag prerelease│ 5 levels, bottom-up │
│ └────────────────┘ │
└─────────────────────────────────────────────────────┘
Key design choice: The scope rename (@claude-flow/* → @sparkleideas/*) is a build-time codemod, never committed to the fork. This means git pull on the fork always produces zero merge conflicts, regardless of how much upstream changes.
The codemod transforms ~4,136 files per build:
- ~261
package.jsonfiles (name, dependencies, peerDependencies) - ~3,875 JS/TS source files (import/require statements)
All patches and fixes are baked into the published packages — no runtime patching needed.
Replace ruflo with @sparkleideas/ruflo:
# Before
npx ruflo init
npx ruflo agent spawn -t coder
npx @claude-flow/cli@latest mcp start
# After
npx @sparkleideas/ruflo init
npx @sparkleideas/ruflo agent spawn -t coder
npx @sparkleideas/ruflo mcp start "dependencies": {
- "claude-flow": "^3.5.2"
+ "@sparkleideas/cli": "^3.5.3"
}Update your .claude/settings.json:
{
"mcpServers": {
"claude-flow": {
"command": "npx",
- "args": ["-y", "@claude-flow/cli@latest", "mcp", "start"]
+ "args": ["-y", "@sparkleideas/ruflo", "mcp", "start"]
}
}
}Most users should use
npx rufloinstead — it includes all fixes permanently. Runtime patches are only needed if you must stay on the upstreamruflopackage for compatibility reasons.
This repo also maintains runtime patches that can be applied directly to the upstream ruflo npx cache. These are fragile (wiped on cache updates) but useful as a stopgap.
ruflo apply [--global] [--target <dir>] Apply all patches
ruflo check [--global] [--target <dir>] Verify patches are applied
ruflo repair [--target <dir>] Repair post-init helpers
| ID | Patch | Description |
|---|---|---|
| MC-001 | 010-MC-001-mcp-autostart |
Removes autoStart: false from MCP entry in init generator |
| FB-001 | 020-FB-001-fallback-instrumentation |
10 ops instrumenting upstream fallback paths with logging |
| FB-002 | 021-FB-002-local-helper-instrumentation |
16 ops instrumenting local helper fallback paths |
| FB-004 | 040-FB-004-search-threshold-for-hash-embeddings |
Lowers search threshold from 0.3→0.1 for hash embeddings |
| SV-001 | 050-SV-001-ruvllm-semver-fix |
Fixes @ruvector/ruvllm ^0.2.3 → ^2.5.1 |
| SV-002 | 051-SV-002-agentdb-memory-pin |
RETIRED — codemod uses * for internal deps |
| SV-003 | 052-SV-003-agentdb-agentic-range |
RETIRED — codemod uses * for internal deps |
| SG-003 | 060-SG-003-init-helpers-all-paths |
Fixes missing .claude/helpers/ for --dual, --minimal, hooks, and upgrade init paths |
Each patch is idempotent — safe to run multiple times. Adding a new patch requires no changes to any script; just create the directory with README.md, fix.py, and sentinel.
npx cache updates wipe patches. Auto-detect and reapply with a Claude Code hook:
{
"hooks": {
"session_start": [
{ "command": "ruflo check --global", "timeout": 30000 }
]
}
}The build is orchestrated by scripts/sync-and-build.sh and runs these phases:
- Load state — Read last-built commit hashes from
scripts/.last-build-state - Check upstream —
git ls-remoteagainst 3 repos (one HTTP request each) - Check local —
git logfor changes topatch/orscripts/ - Pull upstream —
git fetch && git reset --hard origin/mainon each fork - Copy to temp — Clean copy to
/tmp/ruflo-build(stable, cached across runs) - Codemod —
@claude-flow/*→@sparkleideas/*(seescripts/codemod.mjs) - Apply patches — All
patch/*/fix.pyscripts viapatch-all.sh - Build —
pnpm install && pnpm build - Test —
npm test - Compute version — per-package
bump_last_segment(max(upstream, lastPublished)) - Publish — 24 upstream packages across 5 dependency levels, bottom-up with 2s rate-limit
- Notify — GitHub prerelease (triggers email)
- Save state — Only after successful publish
If any phase fails, a GitHub Issue is created automatically. State is never updated on failure, so the next run retries.
| Command | Description |
|---|---|
npm run build |
Build artifacts (cached at /tmp/ruflo-build, skips if fresh) |
npm test |
All local tests: preflight + unit |
npm run test:unit |
Unit tests only (314 tests, ~2s) |
npm run test:verify |
Publish to Verdaccio + 38 acceptance checks |
npm run test:acceptance |
Acceptance checks (requires prior build + publish) |
npm run test:all |
All pre-publish tests: preflight + unit + acceptance |
npm run deploy |
Full pipeline: build + test + publish + promote |
npm run deploy:dry-run |
Full pipeline, stop before publish |
npm run promote |
Promote a prerelease to @latest |
npm run rollback |
Roll back @latest to previous version |
npm run preflight |
Sync generated doc tables and validate consistency |
npm run audit:imports |
Audit dynamic imports for codemod coverage |
npm run upstream-log |
Show recent upstream releases |
npm run systemd:install |
Install systemd timer and service units |
A systemd timer runs sync-and-build.sh every 6 hours:
# Install (one-time)
sudo npm run systemd:install
# View build logs
journalctl -u ruflo-sync
# Trigger manually
sudo systemctl start ruflo-sync.service
# Check timer status
systemctl list-timers ruflo-sync*The service runs as the claude user with resource limits (CPUQuota=800%, MemoryMax=32G, TimeoutStartSec=3600). Secrets (NPM_TOKEN, GH_TOKEN) are loaded from /home/claude/.config/ruflo/secrets.env.
Automated builds publish to the prerelease dist-tag. Users on @latest are unaffected until you explicitly promote:
# Review the prerelease
npx ruflo@prerelease --version
# Promote to @latest
npm run promote
# or manually:
npm dist-tag add @sparkleideas/ruflo@3.5.3 latestVersion scheme: Each package's version is computed as bump_last_segment(max(upstream, lastPublished)). For example, upstream 3.0.2 publishes as 3.0.3, then 3.0.4 on rebuild. Per-package tracking in config/published-versions.json.
If a promoted version is broken:
# Roll back @latest to the previous known-good version
npm run rollback
# Or with a specific version
bash scripts/rollback.sh 3.5.3This reassigns the latest dist-tag for ruflo and all 24 @sparkleideas/* packages. Takes effect immediately — no propagation delay.
Testing levels:
| Level | What | How to run |
|---|---|---|
| Unit | 314 tests — codemod, pipeline logic, publish order, controllers | npm run test:unit |
| Acceptance | 38 checks — publish to Verdaccio + end-to-end verification | npm run test:verify |
| All local | Preflight + unit (safe to commit?) | npm test |
| All pre-publish | Preflight + unit + acceptance | npm run test:all |
Unit tests run with node:test (no dependencies). Acceptance tests publish to local Verdaccio, install in a fresh project, and run 38 checks.
ruflo/
├── bin/ruflo.mjs CLI entry point
├── patch-all.sh Apply all patches (discovers patch/*/fix.py)
├── check-patches.sh Sentinel verification, auto-reapplies if wiped
├── repair-post-init.sh Rehydrate .claude/helpers post-init
├── lib/
│ ├── common.py patch()/patch_all() helpers + path variables
│ ├── discover.mjs Dynamic patch discovery
│ ├── discover.sh Bash install discovery (npx cache, global prefix)
│ └── categories.json Defect prefix → label mapping
├── scripts/
│ ├── sync-and-build.sh Main build pipeline orchestrator
│ ├── build.sh Standalone build wrapper (ADR-0026)
│ ├── codemod.mjs Scope-rename codemod (@claude-flow → @sparkleideas)
│ ├── publish.mjs Topological publisher (5 levels, 24 upstream packages)
│ ├── promote.sh Promote prerelease to @latest
│ ├── rollback.sh Roll back @latest to previous version
│ ├── test-runner.mjs Unit test runner
│ ├── test-acceptance.sh Acceptance tests (38 checks against Verdaccio)
│ ├── validate-ci.sh CI environment health check
│ ├── audit-dynamic-imports.sh Dynamic import inventory
│ ├── install-systemd.sh systemd unit installer
│ ├── preflight.mjs Pre-commit consistency check
│ └── upstream-log.mjs Show recent upstream releases
├── config/
│ ├── package-map.json Package name mappings (25 packages)
│ ├── publish-levels.json Topological publish order (5 levels)
│ ├── ruflo-sync.timer systemd timer unit
│ ├── ruflo-sync.service systemd service unit
│ └── verdaccio-test.yaml Isolated Verdaccio config for tests
├── patch/
│ ├── 010-MC-001-mcp-autostart/ MCP autostart fix
│ ├── 020-FB-001-fallback-*/ Fallback instrumentation (10 ops)
│ ├── 021-FB-002-local-helper-*/ Helper instrumentation (16 ops)
│ ├── 040-FB-004-search-*/ Hash embedding threshold fix
│ ├── 050-SV-001-ruvllm-*/ @ruvector/ruvllm semver fix
│ ├── 051-SV-002-agentdb-*/ agentdb memory pin (RETIRED)
│ ├── 052-SV-003-agentdb-*/ agentdb agentic range (RETIRED)
│ └── 060-SG-003-init-helpers-*/ Init helpers for all paths
├── tests/ Unit tests (node:test)
├── docs/adr/ Architecture Decision Records
└── .tool-versions nodejs 20.18.1, pnpm 9.15.4, python 3.12.8
All major decisions are documented as ADRs in docs/adr/:
| ADR | Title | Summary |
|---|---|---|
| 0001 | Remove MCP autostart false | MC-001 patch rationale |
| 0002 | Fallback instrumentation | FB-001/002 patch rationale |
| 0004 | Search threshold for hash embeddings | FB-004 threshold fix |
| 0005 | Fork + build-step rename | Core strategy: fork, codemod, publish |
| 0006 | npm scope naming | @sparkleideas scope (updated from ADR) |
| 0007 | Drop-in replacement UX | One-word swap migration |
| 0008 | Skip ruvector rebuild | Node.js-only build (no Rust) |
| 0009 | systemd timer | 6-hour automated builds |
| 0010 | Prerelease publish gate | Auto-publish to prerelease, manual promote |
| 0011 | Dual build trigger | Upstream + local change detection |
| 0012 | Version numbering | bump_last_segment(max(upstream, lastPublished)) scheme |
| 0013 | Codemod implementation | 2-phase transform, ordering rules |
| 0014 | Topological publish order | 5-level bottom-up with rate limiting |
| 0015 | First-publish bootstrap | Auto-detect never-published packages |
| 0016 | Dynamic import handling | 3-layer audit + patch strategy |
| 0017 | Semver conflict resolution | Fix inherited @ruvector/ruvllm + agentdb ranges |
| 0018 | Initial setup runbook | Server setup, secrets, disaster recovery |
| 0019 | Rollback procedure | Dist-tag reassignment, not unpublish |
| 0020 | Testing strategy | 3-layer testing + reproducibility framework |
- Node.js >= 20
- Python >= 3.8 (for runtime patch scripts)
- Bash (Linux or macOS)
- pnpm >= 8 (build pipeline only)
- gh CLI (build pipeline only — for GitHub releases and issues)
End users only need Node.js. The Python and pnpm requirements are for maintainers running the build pipeline or applying runtime patches.
MIT — same as upstream. Original LICENSE and copyright notices are preserved in every republished package.