A self-bootstrapping shell script that sets up and launches a [claude-flow] hive-mind team with Claude Code.

start-hive.sh

#!/usr/bin/env bash
##############################################################################
# Project — AiDevSquad Hive-Mind Launcher
#
# Reads the hive manifest and starts Claude Code with the team already spinning.
# Check the gist https://gist.github.com/zeroows/5b86f7a38735e4719929c0e7cbbe763b
# Usage:
#   ./start-hive.sh                                    # Start hive (interactive)
#   ./start-hive.sh "add pushback notification domain" # Start hive with a task
#   ./start-hive.sh --resume                           # Resume last session
#   ./start-hive.sh --init                             # Initialize hive & MCP
##############################################################################

set -euo pipefail

PROJ_ROOT="$(cd "$(dirname "$0")" && pwd)"
cd "$PROJ_ROOT"

HIVE_CONFIG="$PROJ_ROOT/hive-manifest.json"
HIVE_NAME="AiDevSquad"
INIT_MARKER="$PROJ_ROOT/.hive-initialized"
CLAUDE_MD="$PROJ_ROOT/CLAUDE.md"

# Colors
CYAN='\033[0;36m'
GREEN='\033[0;32m'
YELLOW='\033[0;33m'
RED='\033[0;31m'
DIM='\033[2m'
RESET='\033[0m'

##############################################################################
# Helpers
##############################################################################

check_claude_flow() {
    # Check if claude-flow is installed / reachable
    if command -v claude-flow &>/dev/null; then
        return 0
    fi
    # Also accept bunx-resolvable (npx cache)
    if bunx claude-flow --version &>/dev/null; then
        return 0
    fi
    return 1
}

install_claude_flow() {
    echo -e "${CYAN}Installing claude-flow (latest)...${RESET}"
    bunx claude-flow@latest init
    echo -e "${GREEN}claude-flow installed.${RESET}"
}

check_hive_config() {
    [[ -f "$HIVE_CONFIG" ]]
}

generate_hive_config() {
    echo -e "${CYAN}Generating hive-manifest.json template...${RESET}"
    cat > "$HIVE_CONFIG" <<'MANIFEST'
{
  "hiveName": "AiDevSquad",
  "topology": "hierarchical",
  "queen": {
    "name": "ProjectDirector",
    "model": "opus",
    "role": "Orchestrating the project development pipeline",
    "config": {
      "thinking": { "type": "adaptive" }
    }
  },
  "agents": [
    {
      "name": "Architect",
      "role": "System design: domain structure, DI patterns, messaging design, state machines, and database schema",
      "model": "opus",
      "tools": ["file-reader", "web-search"]
    },
    {
      "name": "Researcher",
      "role": "Research libraries, framework patterns, best practices, and shared library usage",
      "model": "sonnet",
      "tools": ["web-search", "file-reader"]
    },
    {
      "name": "Coder",
      "role": "Implementation: handlers, services, repositories, consumers, migrations, DTOs, and registry wiring",
      "model": "sonnet",
      "tools": ["file-writer", "file-reader"]
    },
    {
      "name": "Tester",
      "role": "Writing tests: unit tests, integration tests, e2e tests, and validating state transitions",
      "model": "sonnet",
      "tools": ["file-reader", "file-writer"]
    },
    {
      "name": "Reviewer",
      "role": "Code review: verify patterns, error handling, input validation, query correctness, and naming conventions",
      "model": "sonnet",
      "tools": ["file-reader"]
    }
  ],
  "config": {
    "model": "sonnet",
    "memory": "persistent"
  }
}
MANIFEST
    echo -e "${GREEN}hive-manifest.json generated at ${HIVE_CONFIG}${RESET}"
    echo -e "${DIM}  Edit it to customize agent roles for your project.${RESET}"
}

ensure_gitignore() {
    local gitignore="$PROJ_ROOT/.gitignore"
    local entries=(".swarm/*" ".hive-mind/*" ".claude-flow/*" ".hive-initialized")

    # Create .gitignore if it doesn't exist
    [[ -f "$gitignore" ]] || touch "$gitignore"

    local added=0
    for entry in "${entries[@]}"; do
        if ! grep -qxF "$entry" "$gitignore"; then
            echo "$entry" >> "$gitignore"
            ((added++))
        fi
    done

    if [[ $added -gt 0 ]]; then
        echo -e "${GREEN}Added ${added} entries to .gitignore${RESET}"
    else
        echo -e "${DIM}  .gitignore already has hive entries — skipping.${RESET}"
    fi
}

check_claude_md() {
    # Exists AND is non-empty
    [[ -s "$CLAUDE_MD" ]]
}

generate_claude_md() {
    local file_count
    file_count=$(git ls-files 2>/dev/null | wc -l | tr -d ' ')
    echo -e "${CYAN}Generating CLAUDE.md for project context (${file_count} tracked files)...${RESET}"
    echo -e "${DIM}  This may take a moment for larger projects.${RESET}"

    # Run in background with stdin detached to prevent terminal control conflicts
    # Use haiku + restricted tools + limited turns for fast generation
    claude -p "Analyze this project and generate a CLAUDE.md file. \
Include: project overview, tech stack, directory structure, build/test/run commands, \
coding conventions, key architectural decisions, and any domain-specific notes. \
Be concise but thorough. Output ONLY the markdown content, no fences." \
        --model haiku --tools "Read,Glob,Grep" \
        < /dev/null > "$CLAUDE_MD" 2>/dev/null &
    local pid=$!
    local spin='⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏'
    local i=0
    local elapsed=0
    while kill -0 "$pid" 2>/dev/null; do
        printf "\r  ${DIM}%s  %ds elapsed${RESET}" "${spin:i++%${#spin}:1}" "$elapsed"
        sleep 1
        ((elapsed++))
    done
    printf "\r%-40s\r" " "  # clear spinner line

    wait "$pid"
    local exit_code=$?
    if [[ $exit_code -ne 0 ]] || [[ ! -s "$CLAUDE_MD" ]] || head -1 "$CLAUDE_MD" | grep -qi "^error:"; then
        echo -e "${RED}Failed to generate CLAUDE.md (exit code: ${exit_code}).${RESET}"
        [[ -s "$CLAUDE_MD" ]] && echo -e "${DIM}  Output: $(head -1 "$CLAUDE_MD")${RESET}"
        echo -e "${YELLOW}  You can create it manually or re-run '--init' later.${RESET}"
        rm -f "$CLAUDE_MD"
        return 1
    fi

    local lines
    lines=$(wc -l < "$CLAUDE_MD" | tr -d ' ')
    echo -e "${GREEN}CLAUDE.md generated (${lines} lines, ${elapsed}s) at ${CLAUDE_MD}${RESET}"
}

check_mcp() {
    # Check if the claude-flow MCP server is already registered
    if claude mcp list 2>/dev/null | grep -q "claude-flow"; then
        return 0
    fi
    return 1
}

setup_mcp() {
    echo -e "${CYAN}Setting up claude-flow MCP server...${RESET}"
    claude mcp add claude-flow -- bunx -y claude-flow mcp start
    echo -e "${GREEN}MCP server 'claude-flow' registered.${RESET}"
}

do_init() {
    echo -e "${CYAN}Initializing hive-mind...${RESET}"

    # 0. Ensure .gitignore has hive entries
    ensure_gitignore

    # 1. Ensure hive-manifest.json exists
    if check_hive_config; then
        echo -e "${DIM}  hive-manifest.json already exists — skipping.${RESET}"
    else
        generate_hive_config
    fi

    # 2. Ensure claude-flow is installed
    if check_claude_flow; then
        echo -e "${DIM}  claude-flow already available — skipping install.${RESET}"
    else
        install_claude_flow
    fi

    # 3. Ensure MCP is configured
    if check_mcp; then
        echo -e "${DIM}  MCP 'claude-flow' already registered — skipping.${RESET}"
    else
        setup_mcp
    fi

    # 4. Ensure CLAUDE.md exists
    if check_claude_md; then
        echo -e "${DIM}  CLAUDE.md already exists — skipping generation.${RESET}"
    else
        generate_claude_md
    fi

    # 5. Run hive-mind init (non-interactive, hierarchical mesh with strategic queen)
    bunx claude-flow hive-mind init --manifest hive-manifest.json \
        --topology hierarchical --queen-type strategic --consensus byzantine \
        --no-interactive

    # Mark as initialized
    date -u '+%Y-%m-%dT%H:%M:%SZ' > "$INIT_MARKER"
    echo -e "${GREEN}Hive initialized successfully.${RESET}"
}

##############################################################################
# --init flag: initialize hive + MCP and exit
##############################################################################
if [[ "${1:-}" == "--init" ]]; then
    do_init
    exit 0
fi

##############################################################################
# Pre-flight: warn if not initialized or MCP missing
##############################################################################
NEEDS_INIT=false

if ! check_hive_config; then
    echo -e "${YELLOW}hive-manifest.json not found — template will be generated.${RESET}"
    NEEDS_INIT=true
fi

if ! check_claude_flow; then
    echo -e "${YELLOW}claude-flow is not installed.${RESET}"
    NEEDS_INIT=true
fi

if ! check_claude_md; then
    echo -e "${YELLOW}CLAUDE.md not found — project context will be generated.${RESET}"
    NEEDS_INIT=true
fi

if [[ ! -f "$INIT_MARKER" ]]; then
    echo -e "${YELLOW}Hive has not been initialized yet.${RESET}"
    NEEDS_INIT=true
fi

if ! check_mcp; then
    echo -e "${YELLOW}MCP server 'claude-flow' is not registered.${RESET}"
    NEEDS_INIT=true
fi

if [[ "$NEEDS_INIT" == true ]]; then
    echo ""
    read -rp "$(echo -e "${CYAN}Run initialization now? [Y/n]: ${RESET}")" REPLY
    REPLY="${REPLY:-Y}"
    if [[ "$REPLY" =~ ^[Yy]$ ]]; then
        do_init
        echo ""
    else
        echo -e "${YELLOW}Skipping init — some features may not work.${RESET}"
        echo -e "${DIM}  You can run './start-hive.sh --init' later.${RESET}"
        echo ""
    fi
fi

##############################################################################
# Banner
##############################################################################
echo -e "${CYAN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}"
echo -e "${CYAN}  <Project Name> — ${HIVE_NAME} Hive-Mind${RESET}"
echo -e "${DIM}  Project:  $PROJ_ROOT${RESET}"
echo -e "${DIM}  Branch:   $(git branch --show-current)${RESET}"
echo -e "${DIM}  Status:   $(git status --porcelain | wc -l | tr -d ' ') uncommitted changes${RESET}"
if [[ -f "$HIVE_CONFIG" ]]; then
    AGENTS=$(python3 -c "import json; d=json.load(open('$HIVE_CONFIG')); print(', '.join(a['name'] for a in d['agents']))" 2>/dev/null || echo "unknown")
    TOPOLOGY=$(python3 -c "import json; print(json.load(open('$HIVE_CONFIG'))['topology'])" 2>/dev/null || echo "hierarchical")
    QUEEN=$(python3 -c "import json; print(json.load(open('$HIVE_CONFIG'))['queen']['name'])" 2>/dev/null || echo "ProjectDirector")
    echo -e "${DIM}  Hive:     ${HIVE_NAME} (${TOPOLOGY})${RESET}"
    echo -e "${DIM}  Queen:    ${QUEEN}${RESET}"
    echo -e "${DIM}  Agents:   ${AGENTS}${RESET}"
else
    echo -e "${RED}  Hive config not found at ${HIVE_CONFIG}${RESET}"
    echo -e "${YELLOW}  Run './start-hive.sh --init' to generate it.${RESET}"
    exit 1
fi
echo -e "${CYAN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}"
echo ""

# --resume flag: continue the last session
if [[ "${1:-}" == "--resume" ]]; then
    echo -e "${GREEN}Resuming last session...${RESET}"
    echo ""
    exec claude --resume
fi

# Build the startup prompt that tells Claude to spin up the hive
HIVE_JSON=$(cat "$HIVE_CONFIG")

# Load CLAUDE.md context if available
CLAUDE_MD_CONTENT=""
if [[ -f "$CLAUDE_MD" ]]; then
    CLAUDE_MD_CONTENT=$(cat "$CLAUDE_MD")
fi

# Optional user task appended to the hive startup
USER_TASK="${*:-}"
TASK_INSTRUCTION=""
if [[ -n "$USER_TASK" ]]; then
    TASK_INSTRUCTION="The user's task for this session is: ${USER_TASK}"
    echo -e "${GREEN}Starting hive with task: ${USER_TASK}${RESET}"
else
    echo -e "${GREEN}Starting hive (interactive)...${RESET}"
fi

echo ""

STARTUP_PROMPT=$(cat <<PROMPT
Start the ${HIVE_NAME} hive-mind team using this configuration:
\`\`\`json
${HIVE_JSON}
\`\`\`

Project context (from CLAUDE.md):
\`\`\`markdown
${CLAUDE_MD_CONTENT}
\`\`\`

Instructions:
1. Create the team "${HIVE_NAME}" with TeamCreate
2. Use the project context above — every agent should be aware of the stack, conventions, and key paths
3. Create tasks based on the current project needs
4. Spawn agents from the config above using the Task tool:
   - Queen "${QUEEN}" acts as project director (you, the lead)
   - Spawn each agent with the matching model and role from the config
   - Use background mode for agents that can work independently
5. Coordinate the pipeline: Researcher and Architect first, then Coder, then Tester, then Reviewer
6. Track progress via the task list
7. Build commands: \`go build -o service .\`, \`go test ./...\`, migrations via \`./service migrate\`
${TASK_INSTRUCTION}
PROMPT
)

# Collapse newlines to spaces so the objective is a single-line arg
STARTUP_PROMPT_ONELINE=$(echo "$STARTUP_PROMPT" | tr '\n' ' ' | sed 's/  */ /g')

exec bunx claude-flow hive-mind spawn "$STARTUP_PROMPT_ONELINE" --claude --queen-type strategic --consensus byzantine

AiDevSquad Hive-Mind Launcher

A self-bootstrapping shell script that sets up and launches a claude-flow hive-mind team with Claude Code. Drop start-hive.sh into any project, run --init, and get a fully coordinated multi-agent development squad.

Prerequisites

• Bun (for bunx)
• Claude Code CLI (claude)
• Python 3 (used to parse the manifest for the banner)
• Git

Quick Start

# 1. Copy start-hive.sh into your project root
cp start-hive.sh /path/to/your-project/
chmod +x /path/to/your-project/start-hive.sh

# 2. Initialize everything (one-time setup)
./start-hive.sh --init

# 3. Launch the hive
./start-hive.sh

That's it. The --init flag handles all setup automatically.

Usage

./start-hive.sh                                    # Start hive (interactive)
./start-hive.sh "add user authentication"          # Start hive with a task
./start-hive.sh --resume                           # Resume last session
./start-hive.sh --init                             # Initialize / repair setup

What --init Does

The init command runs a 5-step idempotent setup. Each step is skipped if already satisfied:

Step	What it checks	What it does if missing
1	hive-manifest.json exists	Generates a default template with 5 agents
2	claude-flow is installed	Runs bunx claude-flow@latest init
3	claude-flow MCP server registered	Runs claude mcp add claude-flow -- bunx -y claude-flow mcp start
4	CLAUDE.md exists	Calls claude -p to auto-generate project context
5	Hive-mind initialized	Runs bunx claude-flow hive-mind init --manifest hive-manifest.json

A .hive-initialized marker file is written on success.

Re-running init is safe

Every step checks before acting. Running ./start-hive.sh --init on an already-initialized project produces:

Initializing hive-mind...
  hive-manifest.json already exists — skipping.
  claude-flow already available — skipping install.
  MCP 'claude-flow' already registered — skipping.
  CLAUDE.md already exists — skipping generation.
Hive initialized successfully.

Pre-flight Checks

When you run ./start-hive.sh without --init, the script checks all 5 conditions before launching. If anything is missing, it prompts:

hive-manifest.json not found — template will be generated.
claude-flow is not installed.
CLAUDE.md not found — project context will be generated.
Hive has not been initialized yet.
MCP server 'claude-flow' is not registered.

Run initialization now? [Y/n]:

Accepting runs the full init inline. Declining lets you start anyway (with a warning) or bail out.

Files

File	Purpose	Git-tracked?
start-hive.sh	The launcher script	Yes
hive-manifest.json	Agent team configuration	Yes
CLAUDE.md	Auto-generated project context for agents	Yes
.hive-initialized	Marker file (timestamp of last init)	No (add to .gitignore)

.gitignore addition

.hive-initialized

Hive Manifest

The hive-manifest.json defines your agent team. The default template:

{
  "hiveName": "AiDevSquad",
  "topology": "hierarchical",
  "queen": {
    "name": "ProjectDirector",
    "model": "opus",
    "role": "Orchestrating the project development pipeline",
    "config": {
      "thinking": { "type": "adaptive" }
    }
  },
  "agents": [
    {
      "name": "Architect",
      "role": "System design: domain structure, DI patterns, messaging design, state machines, and database schema",
      "model": "opus",
      "tools": ["file-reader", "web-search"]
    },
    {
      "name": "Researcher",
      "role": "Research libraries, framework patterns, best practices, and shared library usage",
      "model": "sonnet",
      "tools": ["web-search", "file-reader"]
    },
    {
      "name": "Coder",
      "role": "Implementation: handlers, services, repositories, consumers, migrations, DTOs, and registry wiring",
      "model": "sonnet",
      "tools": ["file-writer", "file-reader"]
    },
    {
      "name": "Tester",
      "role": "Writing tests: unit tests, integration tests, e2e tests, and validating state transitions",
      "model": "sonnet",
      "tools": ["file-reader", "file-writer"]
    },
    {
      "name": "Reviewer",
      "role": "Code review: verify patterns, error handling, input validation, query correctness, and naming conventions",
      "model": "sonnet",
      "tools": ["file-reader"]
    }
  ],
  "config": {
    "model": "sonnet",
    "memory": "persistent"
  }
}

Customizing

• hiveName -- your team's display name
• queen.role -- describe what the queen orchestrates (your project's stack/domain)
• Agent roles -- tailor each agent's role to your project specifics (e.g. replace generic "handlers, services" with your actual patterns)
• Agent models -- use "opus" for complex reasoning tasks, "sonnet" for fast execution
• topology -- "hierarchical" (queen coordinates) or other claude-flow topologies

CLAUDE.md Auto-Generation

When no CLAUDE.md exists, init calls Claude to analyze the project and generate one containing:

• Project overview
• Tech stack
• Directory structure
• Build / test / run commands
• Coding conventions
• Key architectural decisions
• Domain-specific notes

This file is inlined into the startup prompt so every agent has full project context from the start.

How the Hive Launches

At launch, the script:

1. Reads hive-manifest.json and CLAUDE.md
2. Builds a startup prompt that includes both as inline context
3. Appends your task (if provided as an argument)
4. Runs bunx claude-flow hive-mind spawn --claude -o "<prompt>"

The agents follow this pipeline: Researcher & Architect (parallel) -> Coder -> Tester -> Reviewer, all coordinated by the Queen (ProjectDirector).

Banner

On launch you'll see a status banner:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  <Project Name> — AiDevSquad Hive-Mind
  Project:  /path/to/project
  Branch:   dev
  Status:   3 uncommitted changes
  Hive:     AiDevSquad (hierarchical)
  Queen:    ProjectDirector
  Agents:   Architect, Researcher, Coder, Tester, Reviewer
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Troubleshooting

Problem	Fix
claude-flow: command not found	Run ./start-hive.sh --init or bunx claude-flow@latest init
MCP server not working	Run claude mcp add claude-flow -- bunx -y claude-flow mcp start
Stale init state	Delete .hive-initialized and re-run --init
Want to regenerate CLAUDE.md	Delete CLAUDE.md and re-run --init
Want a fresh manifest	Delete hive-manifest.json and re-run --init

Adapting for Your Project

1. Copy start-hive.sh to your project root
2. Run ./start-hive.sh --init
3. Edit the generated hive-manifest.json -- update agent roles to match your stack
4. Review the generated CLAUDE.md -- tweak if needed
5. Run ./start-hive.sh to launch

The script is designed to be project-agnostic. The only project-specific parts are the manifest roles and the CLAUDE.md content, both of which are generated for you.