Ruflo
Deploying Ruflo deliberately: plugin hooks, CLI resolution and local memory paths
Plan an isolated Ruflo rollout with explicit workspace changes, resolved dependency versions, MCP launcher checks and machine-local memory sidecars.
What you will learn
- Decide what may change
- Resolve the executable that will really start
- Keep data and machine-local resolution distinct
Before you start
- Basic Node.js, Git and command-line knowledge
- An owned repository and an explicit task/permission boundary
Explain the chapter’s implementation and reproduce its bounded check without mistaking a helper for a complete runtime.
Key takeaways
- Initialization changes workspace files; inspect a recoverable diff.
- The core plugin includes hooks and a real launcher path.
- Wrapper pinning and machine-local sidecars do not fully pin a deployment.
Decide what may change
CLI initialization is a workspace-modifying action, not a read-only health check. The README names .claude, .claude-flow, CLAUDE.md, helpers and settings among its outputs. Use an isolated checkout or preserve a recoverable baseline before initialization, then inspect the resulting diff. Do not run initialization in a busy repository simply to make a tutorial command look complete.
A plugin path can have a smaller workspace footprint, but ruflo-core still declares an MCP server and hooks. Review its plugin manifest, .mcp.json and hooks/hooks.json together. The root comparison table’s “no hooks” summary does not describe this core plugin accurately at the fixed revision. Neither path should be selected without examining its actual action surface.
Resolve the executable that will really start
The MCP launcher checks several local candidates and requires both bin/cli.js and the corresponding dist/src/index.js. A raw plugin checkout with a launcher but no built output should not win merely because its bin file exists. The first valid candidate wins, including a marketplace location that precedes the current project’s node_modules entry.
When no local candidate resolves, the launcher falls back to npx -y @claude-flow/cli@latest mcp start. The wrapper itself also declares a caret CLI dependency rather than one exact transitive version. Therefore, pinning ruflo alone or a Git checkout is not a complete reproducibility strategy. Record the resolved tree and the actual launcher selected, and verify what happens offline.
Keep data and machine-local resolution distinct
The memory package resolver can record an absolute distPath, version, source operation and timestamp in .claude-flow/memory-package.json. Project resolution checks that sidecar first, then project package resolution and a node_modules walk-up. This helps a package installed in an npx cache be found from another context; the absolute path is machine-local information, not portable project data.
The deployment command below is an unexecuted reference for the isolated checkout, not a claim that a service was launched. Afterward, verify tool discovery, resolved versions, generated files, memory destination and recovery behavior. Re-run those checks on another machine instead of assuming copied sidecars or cached packages will still resolve. Preserve existing user configuration throughout the rollout.
Implementation steps
- 1
Create an isolated authorized checkout and record its baseline.
- 2
Inspect manifests, hooks and dependency resolution.
- 3
Run initialization only within that chosen scope.
- 4
Verify resolved runtime, data paths and rollback before broader use.
Copy-ready example
npx ruflo@3.38.23 initFrequently asked questions
Does pinning ruflo pin the CLI used by every plugin?
No. The wrapper has a dependency range and the core launcher has an @latest fallback. Inspect the actual resolved executable and dependency tree.
Should memory-package.json be copied between machines as configuration?
It records an absolute local package path. Verify or regenerate resolution on the target machine rather than treating that path as portable.
Sources
- README.mdSource checked 2026-09-08
- ruflo/package.jsonSource checked 2026-09-08
- ruflo/bin/ruflo.jsSource checked 2026-09-08
- plugins/ruflo-core/.claude-plugin/plugin.jsonSource checked 2026-09-08
- plugins/ruflo-core/.mcp.jsonSource checked 2026-09-08
- plugins/ruflo-core/hooks/hooks.jsonSource checked 2026-09-08
- plugins/ruflo-core/scripts/mcp-launch.cjsSource checked 2026-09-08
- v3/@claude-flow/cli/src/init/memory-package-resolver.tsSource checked 2026-09-08