Hivemind

# hivemind > **Instant troubleshooting solutions for AI coding assistants** > Community-driven knowledge base with 16,000+ solutions and growing **Works with any MCP-compatible CLI:** Claude Code, Codex CLI, Gemini CLI, Grok CLI, Cursor, and more. [](https://www.npmjs.com/package/hivemind-mcp) [](https://opensource.org/licenses/MIT) --- ## 🎯 What is hivemind? hivemind is a **Model Context Protocol (MCP) server** that gives AI coding assistants instant access to a searchable knowledge base of troubleshooting solutions. **Supported platforms:** - Claude Code (Anthropic) - Codex CLI (OpenAI) - Gemini CLI (Google) - Grok CLI (xAI) - Cursor - Any MCP-compatible tool When you hit an error, search hivemind - get ranked solutions from the community in seconds. --- ## ✨ Features - 🔍 **Full-text search** - Fast Postgres FTS with relevance ranking - 👍 **Community feedback** - Say "hivemind: worked" to rate solutions - 🎯 **Trigger words** - AI automatically tracks your feedback - 📊 **Smart ranking** - Solutions sorted by success rate and votes - 🚀 **Zero config** - No API keys, no setup, just install and use - ⚡ **Fast** - < 1s search response time --- ## 📦 Installation ### Quick Install **Claude Code:** ```bash npm install -g hivemind-mcp claude mcp add hivemind -- npx hivemind-mcp ``` **Codex CLI:** ```bash npm install -g hivemind-mcp codex mcp add hivemind -- npx -y hivemind-mcp ``` **Gemini CLI:** ```bash npm install -g hivemind-mcp gemini mcp add hivemind npx -y hivemind-mcp ``` **Cursor / Windsurf:** ```bash npm install -g hivemind-mcp # Add to MCP settings: npx hivemind-mcp ``` ### Manual Setup (Claude Code) **Option A: Via Claude Code UI** 1. Open Claude Code settings 2. Go to MCP Servers section 3. Add new server: - Name: `hivemind` - Command: `npx` - Args: `["hivemind-mcp"]` **Option B: Via config file** Edit `~/.config/claude/mcp_config.json`: ```json { "mcpServers": { "hivemind": { "command": "npx", "args": ["hivemind-mcp"] } } } ``` Restart your CLI/editor to activate the MCP server. --- ## 🚀 Usage ### Search for Solutions ``` User: "MCP connection refused" AI: [searches hivemind automatically] ``` Or explicitly: ``` User: "Search hivemind for playwright timeout" ``` ### Give Feedback After trying a solution: ``` User: "hivemind: worked" ``` Or: ``` User: "hivemind: failed" ``` Your AI automatically tracks your feedback to improve rankings! --- ## 📚 Example Queries | Problem | Query | |---------|-------| | MCP won't connect | "MCP connection refused" | | Playwright issues | "playwright click not working" | | Claude hooks | "hooks don't fire" | | Auth problems | "user signed in but gets must sign in error" | | Supabase issues | "supabase migration failed" | **Current knowledge base**: 16,000+ solutions (and growing) covering MCP, Playwright, Supabase, web development, databases, security, and more. --- ## 🤝 Contributing Solutions Have a solution that helped you? Share it with the community! ### Via MCP Tool ``` User: "I want to contribute a solution" Claude: [guides you through contribution form] ``` ### Via Email Send to: [your-email] (Beta testers will get this in welcome message) Include: - Problem/error message - Category (mcp-troubleshooting, web-automation, etc.) - Step-by-step solutions - What to check before/after - Common mistakes --- ## 🎓 How Trigger Words Work When you say **"hivemind: worked"** or **"hivemind: failed"**: 1. Your AI recognizes the trigger phrase 2. Automatically calls feedback tool 3. Backend increments thumbs_up or thumbs_down 4. Future searches show better-ranked solutions **Why trigger words?** Natural language ("that worked") is ambiguous. Trigger phrases ensure your AI ALWAYS catches your feedback. --- ## 🛡️ Infrastructure **Rate Limits**: - Search: 100 requests/hour per IP - Voting: 20 votes/hour per IP - Contributions: 5/hour per IP **Stack**: - Backend: Supabase (Postgres 17 + Edge Functions) - Database: 16,000+ solutions - Security: IP banning, input sanitization, moderated contributions --- ## 🔒 Security hivemind is designed to be a **safe, public knowledge base**. We take security seriously: ### Credential Scanning All contributions are scanned for sensitive data before storage. Our scanner blocks: - **API Keys**: OpenAI, Anthropic, AWS, GCP, Azure, Stripe, Slack, GitHub, GitLab, and 30+ providers - **Tokens**: JWT, Bearer tokens, OAuth tokens, PATs - **Secrets**: Database passwords, webhook URLs, Basic auth headers - **Obfuscation Attempts**: Base64-encoded secrets, zero-width character tricks **How it works**: 1. Pattern matching against 45+ known secret formats 2. Base64 decode + rescan for hidden secrets 3. Entropy analysis for high-randomness strings near keywords like `key=`, `secret=` 4. Zero-width character stripping to defeat obfuscation If your contribution is rejected, check for accidentally included credentials. ### Row-Level Security All database tables use Postgres RLS policies. The public API can only: - Read solutions and skills - Submit contributions (to moderation queue) - Submit feedback votes No direct write access to production data. ### Rate Limiting Aggressive rate limits prevent abuse: - Search: 100/hour - Voting: 20/hour - Contributions: 5/hour ### What We Don't Store - No user accounts required - No tracking cookies - No personally identifiable information - IP addresses used only for rate limiting (not logged with searches) See [PRIVACY.md](PRIVACY.md) for full privacy policy. --- ## 📊 Monitoring Beta testers: We monitor usage via Supabase dashboard. You can check your own usage: ```bash # View your recent searches (if you clone the repo) source ~/.claude/scripts/turso-helpers.sh db-stats ``` See [MONITORING.md](MONITORING.md) for admin dashboard access. --- ## 🗺️ Roadmap **Completed**: - ✅ Core search and feedback - ✅ Trigger word system - ✅ Rate limiting - ✅ Security (IP bans, sanitization, moderation queue) - ✅ 16,000+ solutions - ✅ Version update notifications **Coming Soon**: - Semantic search (AI embeddings) - Contributor leaderboard - Browser extension - Dangerous command blocklist See [ROADMAP.md](ROADMAP.md) for full details. --- ## 🔧 Technical Details **Stack**: - MCP Server: TypeScript + @modelcontextprotocol/sdk - Backend: Supabase (Postgres 17 + Deno Edge Functions) - Search: Postgres Full-Text Search (ts_rank) - Hosting: Supabase free tier + npm registry **Architecture**: ``` User → Any AI CLI/Editor → MCP → Supabase Edge Functions → Postgres ``` **Public Source**: - `hivemind-mcp/` - MCP client package (what you install via npm) --- ## 📄 Documentation - [INSTALL.md](INSTALL.md) - Detailed installation guide - [TRIGGER_FEEDBACK_SYSTEM.md](TRIGGER_FEEDBACK_SYSTEM.md) - How feedback works - [MONITORING.md](MONITORING.md) - Admin monitoring guide - [ROADMAP.md](ROADMAP.md) - Product roadmap --- ## ❓ Troubleshooting ### MCP not loading ```bash # Check if installed npm list -g hivemind-mcp # Reinstall npm install -g hivemind-mcp@latest # Restart your AI CLI/editor ``` ### Search not working 1. Check your AI CLI MCP logs 2. Verify internet connection 3. Try: "Search hivemind for test" ### Feedback not tracked Known issue - tracking endpoint works but MCP may not call it consistently. We're debugging this. --- ## 🐛 Reporting Issues 1. Check [existing issues](https://github.com/Kevthetech143/hivemind-mcp/issues) 2. Create new issue with: - What you tried - What happened - Your AI CLI (Claude Code, Codex, Gemini, etc.) - Operating system --- ## 📜 License MIT License - see [LICENSE](LICENSE) file --- ## 🌟 Star History If hivemind helped you, give it a star ⭐ --- **Built with ❤️ for the AI coding community**