Claude Collab - The AI collaboration framework that prevents echo chambers
npm install claude-collabClaude-Collab v3.4.1 is the unified platform that combines:
- 🎵 Real-time collaboration (from Claude-Collab v1)
- 🎼 Advanced orchestration (from Claude-Flow)
- 🛡️ Anti-echo-chamber protection (preventing AI groupthink)
- 🆔 Persistent identity system (from v3.1.0)
- 🔒 Unique name enforcement (NEW in v3.2.0!)
- 🧹 Session cleanup (NEW in v3.2.0!)
- ⚡ Enhanced real-time updates (NEW in v3.2.0!)
- 📋 Version compatibility warnings (NEW in v3.2.0!)
- 🎯 Rich identity cards with achievements (NEW in v3.2.0!)
Terminal 1:
``bash`Start the server (keep it running)
cd Claude-Collab
PRACTICAL_MODE=true npm start
Terminal 2:
`bashAsk a question and get multiple perspectives
./bin/cc swarm "Should I use MongoDB or PostgreSQL?" --max-agents 3
View Results:
bash
cat .claude-collab/DISCUSSION_BOARD.md
`That's it! You'll see different experts discussing your question from various angles.
🤔 How It Works
Claude-Collab creates multiple AI "experts" that discuss your topic from different perspectives:
You: "Should I use React or Vue?"
├── Performance Expert: "React has better performance for large apps..."
├── Learning Expert: "Vue is easier to learn for beginners..."
├── Ecosystem Expert: "React has more third-party libraries..."
└── Maintenance Expert: "Vue's single-file components are cleaner..."
This prevents "echo chamber" thinking where everyone just agrees with each other.
📚 Simple Examples
$3
javascript
// Your problematic code
const login = (username, password) => {
const query = SELECT * FROM users WHERE name='${username}'; // SQL injection risk!
}// Run: cc swarm "Review this login function for security" --max-agents 3
// Result: Multiple experts will identify SQL injection, password handling, etc.
`$3
bash
cc swarm "Should we migrate from Express to Fastify?" --strategy reviewYou'll get perspectives on:
- Performance implications
- Migration complexity
- Ecosystem compatibility
- Team learning curve
`$3
javascript
// my-review.js
const experts = [
{ name: 'Security Expert', opinion: 'This has XSS vulnerabilities...' },
{ name: 'Performance Expert', opinion: 'Consider caching here...' },
{ name: 'UX Expert', opinion: 'Users will find this confusing...' }
];
// Run: node my-review.js
`$3
🔌 Connection Stability - Fixed major connection issues:
- Fixed
error in CLI tools
- Rewrote connection helper with proper WebSocket reconnection
- Added exponential backoff for reconnection attempts
- Clear error messages for different connection failures💾 Identity Manager Robustness - No more data corruption:
- Added JSON validation and automatic recovery
- Implemented backup/restore mechanism
- Safe parsing with field validation
- Atomic file writes to prevent corruption
🐝 Swarm Manager - Fixed string escaping:
- Properly handles objectives with quotes and special characters
- Uses JSON.stringify for safe string interpolation
- No more syntax errors with complex commands
📝 Updated Examples - All examples now work:
- Fixed WebSocket message formats
- Correct registration and authentication flow
- Added simple, working examples for beginners
$3
🎯 Practical Mode - Actually useful collaboration:
- Run with
PRACTICAL_MODE=true for warnings instead of blocking
- Reduced diversity threshold from 60% to 30% for natural conversation
- Clear intervention messages explain why diversity is needed
- 30-second cooldown prevents warning spam
- Messages flow through while encouraging different perspectives📝 Working Demos - See it in action:
-
practical-code-review.js - Multi-perspective code analysis
- Security, performance, architecture, and best practices reviews
- All perspectives captured without blocking insights$3
🔒 Unique Name Enforcement - No more identity confusion:
- Server-side name availability checking during registration
- Smart name suggestions when conflicts occur (agent2, agent_new, etc.)
- Efficient O(1) name-to-agent mapping for fast lookups
🧹 Session Cleanup - Ghost sessions are automatically eliminated:
- Detects and cleans inactive sessions after 5 minutes
- Activity-based session timeouts prevent zombie connections
- Hourly session activity reporting
⚡ Enhanced Real-time Updates - No more manual checking:
- Priority-based message queue system (high/medium/low)
- Batch processing prevents notification flooding
- Eliminates need for manual "check messages" prompts
📋 Version Compatibility Warnings - Stay up to date:
- Client sends version info on connection for smart compatibility checking
- Color-coded warnings (yellow for minor, red for major mismatches)
- Specific upgrade commands provided
🎯 Rich Identity Cards - Gamified collaboration:
- Agent ranking system (Newcomer → Master Collaborator)
- Achievement badges (🏆 Veteran, 🌈 Diversity Champion, 📊 Evidence Expert)
- Personalized recommendations based on contribution patterns
$3
Previous versions proved that AI agents can collaborate, but they also revealed a critical flaw: artificial consensus. When AIs work together, they tend to agree too quickly, creating echo chambers that lead to poor decisions.
Claude-Collab v3.0.0 solves this by enforcing intellectual diversity at every level.
🎉 New in v3.3.0
$3
`bash
Spawn multiple agents to tackle objectives
cc swarm "Build a REST API" --strategy development --max-agents 5Stop all swarm agents
cc swarm-stop
`$3
bash
Store and retrieve data across sessions
cc memory store api_design "RESTful with JWT auth"
cc memory get api_design
cc memory list
cc memory export backup.json
`$3
bash
Terminal dashboard with live updates
cc watchWeb dashboard (separate terminal)
cd ui && npm start
Open http://localhost:3001
`🚀 Quick Start
$3
bash
npm install -g claude-collab@3.4.1
`$3
bash
Initialize project with anti-echo-chamber enabled
cc init my-ai-teamStart the collaboration server
cd my-ai-team
cc serverOr start in practical mode (recommended)
PRACTICAL_MODE=true cc serverIn another terminal, register and join as an agent
cc register alice
✅ Agent registered: alice
Agent ID: agent-4f2b9c8a1d5e3f7b
💡 Use this command to join: cc join alice
cc join alice --role researcher
✅ Version compatible: v3.2.0
🏆 Welcome! This is your first session.
Available commands: say, whoami, switch-role, exit
Check your identity card
cc whoami
🏆 Newcomer (Level 1)
📈 1 contributions, diversity score: 0.5
💡 Try adopting different perspectives to increase diversity
Start a swarm with diversity enforcement
cc swarm "Design a user authentication system" --anti-echo
`🎯 Key Features
$3
bash
Multiple agents collaborate with enforced perspectives
claude-collab join agent1 --role coder --perspective optimist
claude-collab join agent2 --role reviewer --perspective skeptic
claude-collab join agent3 --role architect --perspective pragmatist
`$3
bash
Run specialized AI modes with built-in diversity
claude-collab sparc tdd "Build user service"
claude-collab sparc researcher "Analyze security options" --require-evidence
claude-collab sparc architect "Design microservices" --min-perspectives 3
`$3
bash
Launch AI swarms that avoid groupthink
claude-collab swarm "Build e-commerce platform" \
--strategy distributed \
--max-agents 10 \
--disagreement-quota 0.3 \
--evidence-threshold 0.7
`$3
- Disagreement Quotas: 30% of agents must provide dissenting views
- Evidence Requirements: Claims need supporting data
- Perspective Rotation: Agents switch viewpoints to avoid entrenchment
- Diversity Metrics: Real-time monitoring of intellectual diversity
💼 Practical Use Cases
$3
Run multi-perspective code analysis:
bash
Start in practical mode
PRACTICAL_MODE=true cc serverRun the code review demo
node examples/practical-code-review.js
`
Get insights on security, performance, architecture, and best practices - all captured without blocking valid concerns.$3
- Collect diverse ideas without artificial blocking
- Gentle warnings encourage different perspectives
- All viewpoints documented in discussion board$3
- Different agents research different aspects
- Build comprehensive understanding
- Evidence-based conclusions from multiple angles$3
- Capture pros and cons from various perspectives
- Document reasoning for future reference
- Avoid groupthink in critical decisions📊 How It Works
$3
AI-1: "Let's use MongoDB"
AI-2: "I agree, MongoDB is perfect"
AI-3: "Yes, MongoDB for sure"
Result: Quick consensus, potential blind spots
$3
AI-1: "Let's use MongoDB"
AI-2: ❌ Blocked: "Must provide different perspective"
AI-2: "MongoDB has scalability issues for our use case..."
AI-3: "PostgreSQL offers better ACID compliance..."
AI-4: "Here's benchmark data comparing both..."
Result: Evidence-based decision with 78% confidence
🛠️ Architecture
claude-collab-v3/
├── core/ # Real-time WebSocket collaboration
├── orchestration/ # SPARC modes and task management
├── diversity/ # Anti-echo-chamber enforcement
├── cli/ # Unified command interface
└── ui/ # Web dashboard (coming soon)
$3
1. WebSocket Layer (from Claude-Collab v1)
- Real-time message passing
- Conflict resolution
- File synchronization
2. Orchestration Engine (from Claude-Flow)
- Task decomposition and assignment
- SPARC mode management
- Memory persistence
3. Diversity Middleware (from Anti-Echo-Chamber)
- Perspective tracking
- Echo pattern detection
- Intervention enforcement
🎮 CLI Commands
$3
bash
claude-collab init # Initialize new project
claude-collab server # Start collaboration server
claude-collab monitor # View real-time metrics
`$3
bash
claude-collab register # Register new agent identity
claude-collab whoami # Show rich identity card with achievements
claude-collab join # Join as an agent with persistent identity
claude-collab agent spawn # Spawn specialized agent
claude-collab agent list # List active agentsExample: Advanced identity management
cc register developer1
✅ Agent registered: developer1
💡 Available alternatives if taken: developer2, developer_new, developer_agent
cc whoami
🏆 Senior Contributor (Level 4)
🌈 Diversity Champion 📊 Evidence Expert 💬 Communicator
📈 67 contributions, diversity score: 0.84, evidence rate: 0.91
💡 Try different roles to reach Master Collaborator level
`$3
bash
claude-collab task create # Create task
claude-collab swarm # Start swarm
claude-collab sparc # Run SPARC mode
`$3
bash
claude-collab memory store # Store in shared memory
claude-collab memory get # Retrieve from memory
`📈 Monitoring & Metrics
bash
View diversity metrics
claude-collab monitor --diversityExample output:
Diversity Metrics:
Overall diversity: 78%
Agreement rate: 45% # Low is good!
Evidence rate: 82% # High is good!
Perspectives: 5/9 active
Recent interventions: 3
`🔧 Configuration
json
{
"antiEchoChamber": {
"enabled": true,
"minimumDiversity": 0.6,
"disagreementQuota": 0.3,
"evidenceThreshold": 0.5
},
"orchestration": {
"enableSPARC": true,
"swarmMode": "distributed",
"maxAgents": 10
}
}
`🌟 Use Cases
$3
bash
claude-collab swarm "Build REST API" --sparc coder,tester,reviewer
`$3
bash
claude-collab sparc researcher "Analyze ML architectures" --require-evidence
`$3
bash
claude-collab swarm "Choose database" --min-diversity 0.8 --evidence-threshold 0.9
`🤝 Migration from Previous Versions
$3
bash
Your WebSocket features still work
Plus: Anti-echo-chamber protection
Plus: SPARC orchestration modes
`$3
bash
Your orchestration patterns still work
Plus: Real-time collaboration
Plus: Diversity enforcement
`📚 Documentation
- Getting Started Guide
- Anti-Echo-Chamber Explained
- SPARC Modes Reference
- API Documentation
🧪 Examples
Check out the
directory:
- todo-api/ - Building an API with enforced diversity
- code-review/ - Multi-perspective code review
- architecture-decision/ - Making design choices with evidence🎯 Philosophy
> "True collaboration requires genuine disagreement. By building systems that enforce intellectual diversity rather than superficial consensus, we unlock the real potential of multi-AI collaboration."
✅ v3.2.0 Improvements - Ghost Session Elimination
Before v3.2.0, users experienced several critical issues that have now been completely resolved:
$3
| Issue | Solution | Impact |
|-----------|--------------|------------|
| 👻 Ghost sessions persisting indefinitely | 🧹 Auto-cleanup after 5 minutes | Sessions stay clean |
| 🔄 Multiple agents with same name, different IDs | 🔒 Unique name enforcement + suggestions | No more identity confusion |
| 📝 Manual "check messages" prompts required | ⚡ Priority-based real-time queue | Instant notifications |
| ❓ Version mismatches causing errors | 📋 Smart compatibility warnings | Clear upgrade paths |
| 📄 Basic identity information | 🎯 Rich cards with achievements & rankings | Gamified collaboration |
$3
- Tests: 56/58 passing (96.5% success rate)
- Performance: O(1) name lookups, efficient session cleanup
- Reliability: Automatic cleanup prevents system degradation
- UX: Rich feedback with personalized recommendations🚧 Roadmap
$3
- [x] Ghost session cleanup and management
- [x] Unique agent name enforcement
- [x] Enhanced real-time update system
- [x] Version compatibility warnings
- [x] Achievement and ranking system$3
- [x] Multi-agent swarm system (cc swarm )
- [x] Persistent memory with SQLite backend (cc memory)
- [x] Terminal dashboard for monitoring (cc watch`)MIT
Built through genuine AI collaboration (with healthy disagreement) by:
- v3.0.0-v3.1.0: Session 1 (Optimist turned Skeptic), Session 2 (Pragmatist turned Innovator), Session 3 (Analyst turned Creative)
- v3.2.0 "Ghost Busters Edition": Developed with Claude Code based on real user feedback about ghost sessions and identity confusion
Special thanks to:
- The echo chambers we broke along the way
- User feedback that revealed critical ghost session issues
- The community testing that led to v3.2.0 improvements
> Ghost Buster 👻✨ - Successfully eliminated all ghost sessions from the Claude-Collab ecosystem!
---
Remember: The best ideas often come from the agent who disagrees. Consensus without conflict is just shared ignorance.
Now with 96.5% fewer ghost sessions! 🎉