https://github.com/dubsopenhub/hive1k

🐝 Hive1K — one thousand agents, one hive mind. Recursive multi-model swarm orchestration for the Copilot CLI. Launch 250–1,000+ AI agents across 16 models.
https://github.com/dubsopenhub/hive1k

ai-agents consensus copilot-cli copilot-extensions github-copilot multi-agent multi-model orchestration prompt-engineering recursive-swarm shadow-scoring swarm

Last synced: 2 days ago
JSON representation

🐝 Hive1K — one thousand agents, one hive mind. Recursive multi-model swarm orchestration for the Copilot CLI. Launch 250–1,000+ AI agents across 16 models.

• Host: GitHub
• URL: https://github.com/dubsopenhub/hive1k
• Owner: DUBSOpenHub
• License: mit
• Created: 2026-04-11T06:15:58.000Z (4 months ago)
• Default Branch: main
• Last Pushed: 2026-04-11T07:28:34.000Z (4 months ago)
• Last Synced: 2026-07-07T22:21:29.491Z (23 days ago)
• Topics: ai-agents, consensus, copilot-cli, copilot-extensions, github-copilot, multi-agent, multi-model, orchestration, prompt-engineering, recursive-swarm, shadow-scoring, swarm
• Language: Shell
• Size: 209 KB
• Stars: 1
• Watchers: 0
• Forks: 1
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • Contributing: CONTRIBUTING.md
  • License: LICENSE
  • Security: SECURITY.md
  • Agents: AGENTS.md

Awesome Lists containing this project

README

          
# 🐝 Hive1K

> *One thousand agents. One hive mind.*

You type one sentence. Behind the glass, a thousand workers fan out across 16 models, argue in cross-family review meshes, get audited by sealed judges they never knew existed, and converge back into a single answer — usually before your coffee gets cold.

It’s quieter than you’d expect.

[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE) [![Security Policy](https://img.shields.io/badge/Security-Policy-brightgreen?logo=github)](SECURITY.md)

---

## What happens when you type `hive1k`

```text

$ copilot

> hive1k h-500 "Document the auth system, add missing tests, and flag rollout risks"

[NEXUS] Booting H-500 swarm...

[NEXUS] Sealing acceptance criteria (8 checks)

[NEXUS] Deploying 2 Division Commanders...

[DIV-ALPHA] Commanding Architecture + Implementation divisions

[DIV-BETA] Commanding Testing + Documentation + Integration divisions

  [DIV-ALPHA/CMD-ARCH] Mapping auth boundaries and module ownership

  [DIV-ALPHA/CMD-IMPL] Tracing token issuance, refresh, and revocation flows

  [DIV-BETA/CMD-TEST] Enumerating missing happy-path, edge-case, and failure-path tests

  [DIV-BETA/CMD-DOCS] Drafting operator-facing docs and examples

  [DIV-BETA/CMD-INTG] Checking rollout risks across API, web, DB, and monitoring

[REVIEW] Cross-family review mesh started

[SHADOW] 1 criterion failed on first pass → hardening cycle triggered

[SHADOW] Re-validated bundle: 0 critical failures remaining

✅ Final bundle ready in 47s

Top outputs:

  1. Auth architecture brief with module boundaries

  2. Ranked test-gap list with highest-risk paths first

  3. Rollout checklist covering cookies, refresh tokens, and observability

  4. Updated docs outline for onboarding + operations

Consensus: CONSENSUS on 3/4 major findings

Shadow Score: 12.5% → hardened and accepted

```

One prompt. 625 agents worked that problem. You got one synthesized answer.

**Try it yourself:**

```text

hive1k "Map this repo, explain how the major systems fit together, and list the 5 highest-risk gaps"

```

---

## Why a thousand agents?

One model gives you one perspective. For a small task, that’s fine. For anything with real stakes — architecture that spans six services, a migration that touches every API surface, a security audit where missing one edge case matters — one perspective is a gamble.

The failure that started this project: three sealed judges scored a system design 44–46 out of 50. Shadow scoring — hidden criteria the judges never saw — caught critical arithmetic errors in the same output. **Review alone is not validation.** Confident and correct are not the same thing.

Hive1K exists because some tasks deserve more than one brain’s best guess. It turns a single request into a structured process: decompose, parallelize across model families, cross-review, validate against sealed criteria, converge. The answer you get back isn’t one model’s opinion — it’s the output that survived a gauntlet.

And it scales sub-linearly. Five times more agents costs roughly 2.2× more wall-clock time. The architecture is parallelism-first, convergence-second.

---

## The Hive

Picture it as a living organization, not a diagram.

**Nexus** sits at the top — one orchestrator running on `claude-opus-4.6` with a 128K context budget. It reads your mission, decides what divisions are needed, and seals the acceptance criteria in an envelope that no agent below will ever see.

**Division Commanders** — up to four, named DIV-ALPHA through DIV-DELTA — each own a slice of the mission. They’re the recursive layer that Hive1K’s predecessor ([Swarm Command](https://github.com/DUBSOpenHub/swarm-command)) didn’t have. This is what lets the system scale from hundreds to over a thousand agents without losing coherence.

**Commanders** (20 total, 5 per division) are domain specialists — architecture, implementation, testing, documentation, integration. They break their domain into micro-tasks.

**Squad Leads** (200 total) decompose those micro-tasks further and run canary checks before committing workers.

**Workers** (1,000 total) do the actual atomic work. They’re leaf nodes — they execute, they don’t spawn. Each gets a 128-token micro-brief and returns a 256-token atom.

**Reviewers** (20 total) form a cross-family mesh. Every review pair is intentionally split across model families — Claude reviews GPT’s work, GPT reviews Claude’s — so agreement means more than self-consistency.

Then the sealed envelope opens. **Shadow scoring** validates everything against criteria the swarm never optimized for. If the score is too high, a hardening cycle fires. Only what survives gets synthesized into your final answer.

```

                            Your question

                                 │

                                 ▼

                    ┌────────────────────────┐

                    │       NEXUS (1)        │  Decomposes mission

                    │  Seals hidden criteria │  Synthesizes final answer

                    └───────────┬────────────┘

                                │

            ┌───────────┬───────┴───────┬───────────┐

            ▼           ▼               ▼           ▼

        DIV-ALPHA   DIV-BETA      DIV-GAMMA   DIV-DELTA    4 Division

        ┌─┴─┐       ┌─┴─┐         ┌─┴─┐       ┌─┴─┐       Commanders

        │   │       │   │         │   │       │   │

       ─┴─ ─┴─    ─┴─ ─┴─      ─┴─ ─┴─    ─┴─ ─┴─        20 Commanders

       │││ │││    │││ │││      │││ │││    │││ │││          (5 per division)

       ··· ···    ··· ···      ··· ···    ··· ···

       │││ │││    │││ │││      │││ │││    │││ │││          200 Squad Leads

       ▼▼▼ ▼▼▼    ▼▼▼ ▼▼▼      ▼▼▼ ▼▼▼    ▼▼▼ ▼▼▼          (10 per commander)

      ┌──────────────────────────────────────────────┐

      │         1,000 Workers execute in parallel     │

      │     Atomic tasks · 8K context · Leaf nodes    │

      └──────────────────────┬───────────────────────┘

                             │

                             ▼

      ┌──────────────────────────────────────────────┐

      │    20 Reviewers — cross-family scoring mesh   │

      │  Claude ↔ GPT pairs · 4-axis sealed scoring  │

      └──────────────────────┬───────────────────────┘

                             │

                             ▼

                  ┌──────────────────────┐

                  │   Shadow Scoring     │  Sealed-envelope validation

                  │   Hardening cycle    │  Spec L2 conformance

                  └──────────┬───────────┘

                             │

                             ▼

                        Your answer

```

Context compresses on the way down. Results compress on the way up. A 4K-token mission becomes 128-token micro-briefs at the leaves, and 256-token atoms bubble back up through merges until Nexus holds a 4K-token final report. Nothing explodes.

For the full visual deep dive: [architecture diagrams](docs/architecture-diagrams.md) · [architecture overview](docs/architecture.md)

---

## Scale

Hive1K isn’t one size. It’s three sizes, and you pick the one that fits.

### H-250 · Scout Swarm

**~316 agents** · Fast reconnaissance. Bounded tasks where you want multi-model coverage without the full hierarchy. Good for: mapping a codebase, reviewing a design doc, triaging a bug backlog.

### H-500 · Worker Swarm

**~625 agents** · The workhorse. Most real software tasks land here — document a system, write missing tests, audit for security gaps, plan a migration. Two Division Commanders coordinate the effort.

### H-1K · Full Hive

**~1,245 agents** · Maximum coverage. Four Division Commanders, the complete hierarchy, every model family engaged. For repo-wide audits, high-stakes architecture decisions, or anything where missing a blind spot has real consequences.

```text

hive1k h-250 "Triage the open bug backlog and rank by risk"

hive1k h-500 "Document the auth system and flag rollout risks"

hive1k h-1k  "Full architecture review — find every gap, test every assumption"

```

Cost scales sub-linearly (α ≈ 0.45). Going from H-250 to H-1K is roughly 2.2× the wall-clock time, not 4×. The architecture pays for parallelism, not for waiting.

Details and cost estimates: [docs/scaling.md](docs/scaling.md)

---

## Trust

A thousand agents can produce a lot of confident nonsense if you let them. Hive1K is built around the premise that **agreement is not accuracy** — three agents saying the same wrong thing is worse than one agent saying it, because it feels more true.

### Consensus scoring

A 4-stage pipeline decides what survives:

1. **Workers self-score** — each atom ships with a confidence signal

2. **Squad Leads merge locally** — classify results as CONSENSUS / MAJORITY / CONFLICT / UNIQUE

3. **Commanders merge across squads** — trimmed mean, weighted formula:

   `0.40 × confidence + 0.30 × evidence + 0.15 × scope + 0.15 × coverage − conflict_penalty`

4. **Nexus arbitrates** — median-of-3 judging on unresolved conflicts

Disagreement isn’t suppressed. It’s scored, preserved, and surfaced. When agents conflict, you see it.

### Shadow scoring

The sealed-envelope protocol. Before any commander executes, Nexus generates acceptance criteria and locks them away. The swarm never sees them. After execution, the criteria unseal and validate the output.

| Shadow Score | What it means | What happens |

|---|---|---|

| 0% | Every criterion passed | Ship it |

| 1–15% | Minor gaps | Proceed with notes |

| 16–30% | Moderate gaps | Gap report attached, warning raised |

| 31–50% | Significant gaps | Bundle quarantined, hardening cycle |

| > 50% | Critical failure | Bundle rejected entirely |

This is why Hive1K exists as a distinct project. Its predecessor didn’t have this. The moment we saw judges rate flawed output 44/50 while hidden criteria caught the errors, shadow scoring became non-negotiable.

Full protocol: [docs/shadow-scoring.md](docs/shadow-scoring.md) · [docs/consensus.md](docs/consensus.md)

---

## Get started

### Quickstart (one command)

```bash

curl -fsSL https://raw.githubusercontent.com/DUBSOpenHub/hive1k/main/quickstart.sh | bash

```

Then open Copilot and type: `hive1k`

Prefer to inspect first?

```bash

curl -fsSL https://raw.githubusercontent.com/DUBSOpenHub/hive1k/main/quickstart.sh -o quickstart.sh

less quickstart.sh

bash quickstart.sh

```

### Manual install

```bash

mkdir -p ~/.copilot/skills/hive1k ~/.copilot/agents && \

  curl -sL https://raw.githubusercontent.com/DUBSOpenHub/hive1k/main/skills/hive1k/SKILL.md \

    -o ~/.copilot/skills/hive1k/SKILL.md && \

  curl -sL https://raw.githubusercontent.com/DUBSOpenHub/hive1k/main/agents/hive1k.agent.md \

    -o ~/.copilot/agents/hive1k.agent.md

```

### Verify your downloads

```bash

# macOS

shasum -a 256 ~/.copilot/skills/hive1k/SKILL.md

shasum -a 256 ~/.copilot/agents/hive1k.agent.md

# Linux

sha256sum ~/.copilot/skills/hive1k/SKILL.md

sha256sum ~/.copilot/agents/hive1k.agent.md

```

> **Note:** SHA hashes are published in the [latest release](https://github.com/DUBSOpenHub/hive1k/releases/latest). Compare your download hashes against the release notes before use.

### Clone the repo

```bash

git clone https://github.com/DUBSOpenHub/hive1k.git

cd hive1k

chmod +x quickstart.sh && ./quickstart.sh

```

*Requires an active [Copilot subscription](https://github.com/features/copilot/plans).*

---

## Neighbors, not competitors

Hive1K is one tool in a family. They solve different problems.

| You want to... | Use | Why |

|---|---|---|

| Get **one consensus answer** from a recursive agent hierarchy (250–1,245 agents) | [**Hive1K**](https://github.com/DUBSOpenHub/hive1k) | Recursive decomposition, cross-model review, shadow validation, one synthesized output |

| Run **parallel coding workstreams** across terminals | [**Stampede**](https://github.com/DUBSOpenHub/terminal-stampede) | Independent task lanes, execution throughput, branch-per-task |

| **Tournament-test ideas** across many models | [**Havoc Hackathon**](https://github.com/DUBSOpenHub/havoc-hackathon) | Competitive elimination rounds, sealed judge panels, ranked synthesis |

| Orchestrate **~250 agents** without the recursive layer | [**Swarm Command**](https://github.com/DUBSOpenHub/swarm-command) | Hive1K’s predecessor — same core, no Division Commanders, depth 3 instead of 4 |

**Short version:** Hive1K for consensus at scale. Stampede for parallel execution. Havoc for idea tournaments. Swarm Command if you want the simpler original.

---

## Under the hood

The sections below are for people who want to know how the gears turn. If you just want to use Hive1K, everything above is enough.

### The 16 models

| Role | Models |

|---|---|

| **Nexus** | claude-opus-4.6 |

| **Commanders** (pool of 10) | claude-opus-4.6, claude-opus-4.5, claude-opus-4.6-1m, claude-sonnet-4.6, claude-sonnet-4.5, claude-sonnet-4, gpt-5.4, gpt-5.2, gpt-5.1, goldeneye |

| **Squad Leads** | claude-haiku-4.5, gpt-5.4-mini |

| **Workers** (pool of 6) | claude-haiku-4.5, gpt-5.4-mini, gpt-5-mini, gpt-4.1, gpt-5.3-codex, gpt-5.2-codex |

| **Reviewers** (8 cross-family pairs) | claude-opus-4.6↔gpt-5.4, claude-opus-4.5↔gpt-5.2, claude-opus-4.6-1m↔gpt-5.1, claude-sonnet-4.6↔gpt-5.3-codex, claude-sonnet-4.5↔gpt-5.2-codex, claude-sonnet-4↔gpt-5.4-mini, claude-haiku-4.5↔gpt-5-mini, goldeneye↔gpt-4.1 |

Every reviewer pair intentionally crosses model families. When Claude and GPT agree, that signal is worth more than either alone.

### Configuration

All tunables live in [`config.yml`](config.yml):

```yaml

consensus:

  threshold_consensus: 0.70

  threshold_majority: 0.50

depth_guard:

  max_spawn_depth: 4

  max_workers_per_squad_lead: 5

circuit_breaker:

  timeout_cascade: [240, 150, 90, 50, 30]

shadow_scoring:

  enabled: true

  spec_version: "1.0.0"

  conformance_level: "L2"

  sealed_criteria_count: 10

  hardening:

    enabled: true

    threshold: 15

cost_ceiling:

  enabled: true

  mode: user-configurable

```

**Depth Guard** enforces 5 laws and 3 layers of protection against runaway recursion. **Circuit breaker** implements a 3-state FSM with 5-level recovery escalation. Neither is optional — at this scale, guardrails are structural.

### Safety mechanisms

- **Depth Guard** — hard limit on recursion depth (max 4), spawn budgets per layer, enforcement at every level

- **Circuit breaker** — CLOSED → OPEN → HALF-OPEN FSM with cascading timeouts

- **Token compression** — context shrinks at each layer (4K → 3K → 2K → 512 → 128 tokens), results compress on the way back up

- **Cost ceiling** — user-configurable budget cap; the swarm stops before it overspends

### Repo structure

```text

hive1k/

├── README.md                           # You are here

├── AGENTS.md                           # Agent/skill descriptions

├── CONTRIBUTING.md                     # Contribution guidelines

├── catalog.yml                         # Skill metadata

├── config.yml                          # All tunables

├── LICENSE                             # MIT

├── SECURITY.md                         # Security policy

├── quickstart.sh                       # One-line installer

├── .github/

│   ├── copilot-instructions.md         # AI agent instructions for this repo

│   ├── workflows/ci.yml                # CI validation

│   └── skills/hive1k/SKILL.md         # Skill discovery path

├── agents/

│   └── hive1k.agent.md                # Standalone agent version

├── skills/hive1k/

│   └── SKILL.md                        # Core skill definition

├── templates/

│   ├── commander.md                    # Commander prompt template

│   ├── division-commander.md           # Division Commander prompt template

│   ├── worker.md                       # Worker prompt template

│   ├── reviewer.md                     # Cross-reviewer prompt template

│   └── squad-lead.md                   # Squad lead prompt template

├── protocols/

│   ├── depth-guard.md                  # 5 Laws + 3-layer enforcement

│   ├── circuit-breaker.md              # 3-state FSM + 5-level recovery

│   ├── context-capsule.md              # JSON schemas for data structures

│   └── meta-reviewer.md               # Reviewer quality gate protocol

└── docs/

    ├── architecture.md                 # Architecture overview

    ├── architecture-diagrams.md        # Mermaid diagrams

    ├── consensus.md                    # Consensus algorithm deep dive

    ├── example-output.md               # Sample completed run output

    ├── learning-path.md                # Recommended reading order

    ├── scaling.md                      # Scale chooser + cost estimates

    ├── shadow-scoring.md               # Shadow scoring protocol

    └── use-cases.md                    # Expanded prompt gallery

```

### Go deeper

| Doc | What’s in it |

|---|---|

| [learning-path.md](docs/learning-path.md) | Beginner, operator, and architect reading tracks |

| [architecture.md](docs/architecture.md) | The full system model |

| [architecture-diagrams.md](docs/architecture-diagrams.md) | Mermaid diagrams for every layer |

| [scaling.md](docs/scaling.md) | Scale chooser, cost estimates, tuning guide |

| [use-cases.md](docs/use-cases.md) | Prompt gallery with expected outcomes |

| [consensus.md](docs/consensus.md) | The 4-stage consensus algorithm in detail |

| [shadow-scoring.md](docs/shadow-scoring.md) | The sealed-envelope protocol, hardening cycle |

| [example-output.md](docs/example-output.md) | Full transcript of a completed swarm run |

---

## Spec conformance

Hive1K implements **[Shadow Score Spec](https://github.com/DUBSOpenHub/shadow-score-spec) L2** — sealed acceptance criteria generated before execution, validated after, hardened on failure.

---

## License

[MIT](LICENSE) — use it, fork it, build on it.

---



🐝 Built by @DUBSOpenHub with the GitHub Copilot CLI