ruvnet
Label hive-mind mode as experimental in docs and CLI
Below is a summary of what Perplexity surfaced about the current hive-mind implementation in Claude Flow. I ran into the same failures and this explains them much better than the existing docs or examples.
Based on extensive research into the Claude Flow codebase and issue tracker, your experience reflects multiple confirmed bugs that cause hive-mind sessions to break and fall back to regular Claude Code. This is a widespread, frustrating issue affecting many users, particularly in recent alpha versions. The Core Problems
- The --claude Flag Has Never Worked Properly
When you run claude-flow hive-mind resume session-xxx --claude, the --claude flag is supposed to automatically spawn a Claude Code worker process that connects to the hive-mind orchestrator. However, this implementation has been fundamentally broken since its introduction:
​
Terminal Conflict: The spawned claude process uses stdio: 'inherit', meaning it tries to share the same terminal as the parent claude-flow orchestrator process
Interactive Mode Deadlock: Since Claude Code runs interactively by default, both processes compete for terminal input/output, causing the worker to hang and never actually start
Missing Non-Interactive Flags: The spawn command lacks critical flags like -p (print mode) and --output-format stream-json that would force non-interactive operation
What you're seeing — the orchestrator displays session info and then appears to exit to regular Claude Code — is actually the system attempting to spawn the worker, failing silently, and leaving you with an orphaned process.
- Prompt File Generation Logic Is Backwards
A critical bug in the file-saving logic prevents the system from creating the essential hive-mind-prompt-....txt file:
​
javascript try { execSync('which claude'); // Check if claude is installed // If claude EXISTS, tries to spawn directly (and hangs) // BUT NEVER SAVES THE PROMPT FILE! } catch { // Only saves prompt file if claude is NOT installed // This is backwards! 🤦 }
Since having Claude Code installed is a prerequisite, the try block always succeeds, so the prompt file is never created. This means you can't even manually start the worker as a workaround.
- Session State Corruption on Resume
The resume functionality has additional fragility issues:
​
Invalid PIDs: Session state stores Process IDs that become invalid after system restarts
No Integrity Checks: The resume command doesn't validate session state before attempting to load it
Brittle State Management: Unexpected shutdowns (crashes, Ctrl+C without proper pause) corrupt the .hive-mind directory
No Graceful Shutdown Handlers: The system doesn't trap SIGINT, SIGTERM, or SIGHUP signals to save state automatically
