🐝 HIVEMIND

Multi-agent AI orchestration with 24 specialists across Development, Security, Infrastructure, and QA. HEAD_CODEX routes your request, Claude executes agent work, and every task passes quality gates before shipping a report.

Why HIVEMIND

• 24 agents / 4 teams with clear roles (architecture → security → infra → QA).
• Codex as orchestrator, Claude as executor; pluggable engines via config/engines.yaml. -,Quality gates (design, security, code, test, deploy) gate every run.
• Terminal-first experience with a minimal TUI and keyboard shortcuts.
• Stateless, MCP-disabled Claude invocations by default to avoid hangs; override via env.

Quick Start

git clone https://github.com/Nerds489/HIVEMIND.git
cd HIVEMIND
./install.sh
hivemind

Authenticate CLIs if prompted:

codex login --device-auth   # or set OPENAI_API_KEY
claude setup-token          # or set ANTHROPIC_API_KEY

Usage

Orchestration commands

Command	Purpose
/hivemind [task]	Full multi-agent orchestration
/dev [task], /sec [task], /infra [task], /qa [task]	Route to a team
/architect, /pentest, /sre, /reviewer	Direct to a single expert
/status	System status
/recall [query]	Query session memory
/note <msg>	Inject live notes while agents work

TUI shortcuts

Key	Action
Enter	Send quick message
C	Full chat view
M	Main view
Ctrl+O	Agent log
Ctrl+C	Cancel task
Ctrl+Enter	Send in chat
Ctrl+L	Clear history
Esc	Back
Q	Quit

Live run example

Input: Build a REST API with JWT auth and deploy to Kubernetes

[DEV-001] Designing architecture
[SEC-001] Threat modeling auth
[DEV-002] Building endpoints
[DEV-004] Reviewing code
[QA-002] Writing tests
[QA-003] Load testing
[INF-001] K8s architecture
[INF-005] Configuring deploy
[INF-006] Writing Helm charts

Gates: G1 DESIGN ✓  G2 SECURITY ✓  G3 CODE ✓  G4 TEST ✓  G5 DEPLOY ✓
Report: REST API + JWT + K8s manifests + CI/CD + 0 critical vulns + load tested

Teams & Agents

Development (DEV) — Build it right.

• DEV-001 Architect · patterns, APIs, microservices
• DEV-002 Backend · APIs, servers, databases
• DEV-003 Frontend · UI/UX, React/Vue/TS
• DEV-004 Code Reviewer · quality, PRs
• DEV-005 Technical Writer · docs, guides
• DEV-006 DevOps Liaison · CI/CD, pipelines

Security (SEC) — Break it before they do.

• SEC-001 Security Architect · threat modeling
• SEC-002 Penetration Tester · vulns, OWASP
• SEC-003 Malware Analyst · reverse engineering
• SEC-004 Wireless Security · WiFi/Bluetooth/IoT
• SEC-005 Compliance Auditor · SOC2/GDPR/PCI
• SEC-006 Incident Responder · forensics, response

Infrastructure (INF) — Run it at scale.

• INF-001 Infra Architect · AWS/GCP/Azure
• INF-002 Systems Administrator · Linux/Windows
• INF-003 Network Engineer · DNS, routing, firewalls
• INF-004 Database Administrator · SQL/NoSQL
• INF-005 Site Reliability Engineer · K8s, monitoring, SLOs
• INF-006 Automation Engineer · Terraform, Ansible

Quality Assurance (QA) — Prove it works.

• QA-001 QA Architect · strategy, coverage
• QA-002 Test Automation · Selenium/Cypress/pytest
• QA-003 Performance Tester · k6/JMeter
• QA-004 Security Tester · DAST/SAST
• QA-005 Manual QA · UAT/regression
• QA-006 Test Data Manager · fixtures, seeding

Installation

Requirement	Version
Python	3.11+
Node.js	18+
Codex CLI	npm i -g @openai/codex
Claude CLI	npm i -g @anthropic-ai/claude-code

Commands:

./install.sh   # install dependencies
hivemind       # launch TUI
./uninstall.sh # remove

Configuration

• Env vars (common):

  export OPENAI_API_KEY="sk-..."
  export ANTHROPIC_API_KEY="sk-ant-..."
  export HIVEMIND_THEME="cyberpunk-matrix"
  # CLI stability toggles (defaults shown)
  export HIVEMIND_DISABLE_CLAUDE_MCP=1
  export HIVEMIND_CLAUDE_STATELESS=1
  export HIVEMIND_CLAUDE_FLAGS=""   # additive-only extra flags

• Key files:

  config/
  ├─ hivemind.yaml   # main settings
  ├─ agents.json     # agent registry
  ├─ routing.json    # keyword routing
  └─ engines.yaml    # engine selection
  

Project Structure

HIVEMIND/
├─ agents/        # Agent definitions (24)
├─ comms/         # Inter-agent protocols
├─ config/        # System configuration
├─ core/          # Orchestrator logic
├─ memory/        # Persistent memory
├─ protocols/     # Quality gates
├─ runtime/       # Controllers
├─ teams/         # Team configurations
├─ templates/     # Output templates
├─ tests/         # Test suite
├─ tui/           # Terminal UI
├─ workflows/     # Process playbooks
└─ hivemind       # Launcher script

Troubleshooting

• CLI won’t respond / hangs: ensure MCP is disabled and sessions are stateless (defaults above). Clear stuck processes with pkill -f "claude --print".
• Auth failures: run codex login --device-auth or set OPENAI_API_KEY; run claude setup-token or set ANTHROPIC_API_KEY.
• Routing feels off: check config/routing.json keywords and restart.

License

MIT License — see LICENSE