claude-flow

Stable Codex integration for Ruflo

Ruflo v3.32.1 fixes the Codex integration failures that appeared as hook JSON parse errors, incomplete MCP startup, and 30-second startup timeouts?particularly on Windows.

Detailed technical write-up, troubleshooting notes, and verification guide: Ruflo v3.32.1 Codex integration Gist

The problems fixed

Users could encounter errors such as:

failed to parse plugin hooks config .../hooks/hooks.json:
expected value at line 1 column 1

MCP startup incomplete (failed: ruflo)
MCP client for `ruflo` timed out after 30 seconds

This release addresses the underlying causes rather than only increasing a timeout:

• affected cached hooks.json files could start with a UTF-8 byte-order mark, causing strict JSON parsing to fail at byte one;
• Windows npm shims require cmd /c instead of being launched like native executables;
• cold npm resolution can exceed Codex's previous 30-second MCP startup window;
• an existing MCP server name could be accepted even when its command, package reference, or timeout was stale;
• Windows shell execution could strip quotes from JSON arguments used by cost-tracker memory operations;
• publication from a clean checkout could omit generated shared or guidance output.

What changed

Canonical, platform-aware MCP registration

On Windows, ruflo init --codex now creates or repairs this registration:

[mcp_servers.ruflo]
command = "cmd"
args = ["/c", "npx", "-y", "ruflo@latest", "mcp", "start"]
startup_timeout_sec = 120

On macOS and Linux, Ruflo invokes npx directly.

The shared configuration implementation now:

• validates the full transport and command, not only the MCP server name;
• upgrades legacy claude-flow and prerelease command forms;
• raises timeouts below 120 seconds;
• preserves user-configured timeouts of 120 seconds or greater;
• preserves inline TOML comments and unrelated MCP servers;
• works with CODEX_HOME and global Codex configuration;
• prefers native Codex executables and safely handles Windows npm shims.

Existing projects are repaired

ruflo init --codex no longer stops just because a project is already initialized. It checks and repairs stale Codex integration state while leaving unrelated project configuration intact.

For cold-start performance, @claude-flow/codex is not added to the CLI's optional dependency graph. An explicit Codex initialization fetches stable @claude-flow/codex@latest on demand when the adapter is not already available.

Hook JSON and plugin cache fixes

Release auditing now rejects:

• empty hook configuration files;
• malformed JSON;
• UTF-8 BOM-prefixed JSON.

The affected plugin cache versions were advanced:

• ruflo-core: 0.2.3
• ruflo-cost-tracker: 0.26.1

This ensures corrected hook configurations replace stale cached copies.

Windows-safe cost tracking

Cost-tracker subprocesses now invoke npm's JavaScript npx entry point on Windows. This preserves argument boundaries and JSON quotes without relying on shell parsing.

Memory retrieval was also migrated to the supported --value-only interface, making budget, federation, tracking, and health-check data machine-readable and consistent across platforms.

Reproducible publication

Publishing is now cross-platform and fail-closed:

• Windows-incompatible cp, rm, and mkdir publish commands were replaced with Node scripts;
• CLI helper manifests are generated, signed, and verified before publication;
• root publication rebuilds required hooks, shared, and guidance output;
• package dry-runs validate the same lifecycle used by the real publish;
• the default release path publishes only to npm's stable latest tag.

No prerelease version or alpha tag was created or moved by this release. Historical alpha and v3alpha tags remain on their previous versions.

Published packages

| Package | Version | npm tag |
|---|---:|---|
| ruflo | 3.32.1 | latest |
| claude-flow | 3.32.1 | latest |
| @claude-flow/cli | 3.32.1 | latest |
| @claude-flow/codex | 3.0.1 | latest |

Install or upgrade

Ruflo v3.32.1 requires Node.js 20 or newer.

npm install -g [email protected]
ruflo init --codex
codex mcp list

Without a global installation:

npx -y ruflo@latest init --codex

Install the complete Codex skill set:

ruflo init --codex --full

Existing projects can safely rerun initialization. It normalizes the Ruflo MCP block while preserving unrelated Codex configuration.

Expected result

On Windows, codex mcp list should show Ruflo enabled with:

cmd /c npx -y ruflo@latest mcp start

The global Codex configuration should include:

startup_timeout_sec = 120

You can also test server startup directly:

npx -y ruflo@latest mcp start --test

Verification completed

The release was verified with:

• 121 successful GitHub checks;
• 3 intentionally skipped checks;
• 0 failed checks;
• 196/196 Codex package tests;
• 67/67 Windows hook initialization smoke assertions;
• 18/18 targeted CLI initialization tests;
• strict parsing and zero-BOM validation for affected hook JSON;
• package builds and publication checks across Ubuntu, macOS, and Windows;
• clean npm lifecycle dry-runs for CLI, umbrella, and Ruflo packages;
• a clean Windows install of [email protected];
• successful on-demand installation of @claude-flow/codex@latest;
• creation of AGENTS.md, Codex config, and two minimal skills;
• verification of the exact Windows command and 120-second timeout;
• a live MCP JSON-RPC initialize handshake against ruflo@latest.

Compatibility and migration

This patch release has no intentional breaking API change and requires no manual migration. Rerun:

ruflo init --codex

to repair an older MCP registration.

If Codex still reports a cached hook error after upgrading, restart Codex after initialization so it reloads the corrected plugin cache and MCP configuration.

Development and release links

• Merged implementation: PR #2698
• Detailed guide: public Gist
• Full changes: v3.30.2...v3.32.1