🐝 HIVEMIND

Multi-agent AI orchestration with 24 specialists across Development, Security, Infrastructure, and QA. HEAD_CODEX analyzes your request, creates a plan for approval, then coordinates Claude agents—every task passes quality gates before shipping a report.

Why HIVEMIND

• Codex-first planning: Codex thinks alone first, creates a plan, then optionally consults Claude.
• Interactive planning: Review and refine plans before execution—say "proceed" or provide feedback.
• 24 agents / 4 teams with clear roles (architecture → security → infra → QA).
• 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

Codex-First Planning Flow

HIVEMIND uses a Codex-first architecture where Codex analyzes your request and creates a plan before execution:

You: Build a REST API with authentication

┌─────────────────────────────────────────────┐
│ [CODEX] Analyzing request...                │
│ [CODEX] Creating plan...                    │
├─────────────────────────────────────────────┤
│ ## Codex Plan                               │
│ **Task:** Build REST API with auth          │
│ **Complexity:** COMPLEX                     │
│                                             │
│ ### Agents (4)                              │
│ - DEV-001 (Architect)                       │
│ - SEC-001 (Security Architect)              │
│ - DEV-002 (Backend Developer)               │
│ - QA-002 (Test Automation)                  │
│                                             │
│ ---                                         │
│ **Codex:** Should I proceed?                │
│ - Say `proceed` to execute                  │
│ - Provide feedback to refine                │
│ - Say `cancel` to start over                │
└─────────────────────────────────────────────┘

You: add SEC-002 for penetration testing
     → Codex refines the plan

You: proceed
     → Agents execute, gates checked, report generated

Complexity Levels:

Level	Behavior
TRIVIAL	Direct response (help, status, greetings)
SIMPLE	Codex answers directly, no agents
MEDIUM	Codex plans alone, presents for approval
COMPLEX	Codex plans, may consult Claude, presents for approval
CRITICAL	Full Codex-Claude dialogue before execution

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

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

[CODEX] Analyzing request...
[CODEX] Creating plan...

## Codex Plan
**Task:** REST API with JWT + K8s deployment
**Complexity:** CRITICAL
**Agents:** DEV-001, SEC-001, DEV-002, DEV-004, QA-002, QA-003, INF-001, INF-005, INF-006

You: proceed

[CODEX] Plan approved. Proceeding...
[CODEX] Consulting Claude...

[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

[GATE] G1-DESIGN: PASSED
[GATE] G2-SECURITY: PASSED
[GATE] G3-CODE: PASSED
[GATE] G4-TEST: PASSED
[GATE] G5-DEPLOY: READY

## HIVEMIND EXECUTION REPORT
- Task: REST API with JWT Auth + Kubernetes Deployment
- Status: COMPLETE
- Agents: 9 engaged
- Deliverables: API, JWT auth, K8s manifests, Helm chart, CI/CD, 0 critical vulns

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