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.

---

🎯 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:

npm install -g hivemind-mcp
claude mcp add hivemind -- npx hivemind-mcp

Codex CLI:

npm install -g hivemind-mcp
codex mcp add hivemind -- npx -y hivemind-mcp

Gemini CLI:

npm install -g hivemind-mcp
gemini mcp add hivemind npx -y hivemind-mcp

Cursor / Windsurf:

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:

{
  "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 for full privacy policy.

---

📊 Monitoring

Beta testers: We monitor usage via Supabase dashboard. You can check your own usage:

# View your recent searches (if you clone the repo)
source ~/.claude/scripts/turso-helpers.sh
db-stats

See 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 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 - Detailed installation guide
• TRIGGER_FEEDBACK_SYSTEM.md - How feedback works
• MONITORING.md - Admin monitoring guide
• ROADMAP.md - Product roadmap

---

❓ Troubleshooting

MCP not loading

# 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
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 file

---

🌟 Star History

If hivemind helped you, give it a star ⭐

---

Built with ❤️ for the AI coding community