Hive - AI Agent Orchestrator

# Hive - AI Agent Orchestrator

[![CI](https://img.shields.io/github/actions/workflow/status/nikrich/hungry-ghost-hive/ci.yml?branch=main&style=flat-square)](https://github.com/nikrich/hungry-ghost-hive/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/hungry-ghost-hive?style=flat-square)](https://www.npmjs.com/package/hungry-ghost-hive)
[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen?style=flat-square)](https://nodejs.org/)
[![License](https://img.shields.io/badge/license-Restricted-blue?style=flat-square)](LICENSE)
[![TypeScript](https://img.shields.io/badge/language-TypeScript-blue?style=flat-square)](https://www.typescriptlang.org/)
[![Codecov](https://img.shields.io/codecov/c/github/nikrich/hungry-ghost-hive?style=flat-square)](https://codecov.io/gh/nikrich/hungry-ghost-hive)

<img width="1263" height="651" alt="image" src="https://github.com/user-attachments/assets/76eb8bd9-d5ec-45b7-9ee2-b7ef910f3e88" />

Hive is a CLI tool that orchestrates AI agents modeled after agile software development teams. You act as the **Product Owner**, providing requirements. Hive's AI agents handle the rest — from planning through to merged pull requests.

## Key Features

- **AI-Powered Team Management**: Orchestrate autonomous teams of AI agents across multiple repositories
- **Agile Workflow**: Natural hierarchy mirrors real development teams with Tech Lead, Seniors, Intermediates, Juniors, and QA agents
- **Requirement to PR Automation**: From initial requirements to merged pull requests, fully automated
- **Intelligent Task Distribution**: Stories automatically routed to appropriate skill levels based on complexity scoring
- **QA Review Agents**: Dedicated QA agents auto-spawn to review PRs, run quality checks, and enforce acceptance criteria
- **Feature Sign-Off**: Automated E2E test execution when all stories for a requirement are merged
- **Real-Time Dashboard**: Interactive TUI dashboard with pipeline visualization, agent monitoring, PR review, and messaging
- **Multi-Repository Support**: Manage related services and libraries as coordinated git submodules with per-agent worktree isolation
- **Story Dependencies**: Topological dependency resolution ensures stories are completed in the right order
- **Escalation Handling**: Built-in escalation protocol when agents need guidance or hit blockers
- **PR Merge Queue**: Automated merge queue with QA gating, auto-merge, and duplicate PR detection
- **Jira Integration**: Two-way sync with Jira — epics, stories, subtasks, story points, sprint assignment, and status transitions
- **Multi-CLI Support**: Agents can use Claude Code, Codex, or Gemini CLI as their runtime
- **Distributed Mode**: Cluster support with RAFT-based leader election, peer replication, and duplicate story detection
- **Godmode**: Override complexity routing to use the most powerful models for all agents on a requirement
- **Manager Intelligence**: AI-powered stuck detection, automatic permission bypass, plan mode escape, and orphan recovery

## Installation

### Via npm (Recommended)

```bash
npm install -g hungry-ghost-hive
```

### For Contributors (Development Setup)

If you want to contribute or run from source:

```bash
# Clone the repository
git clone https://github.com/nikrich/hungry-ghost-hive.git
cd hungry-ghost-hive

# Install dependencies
npm ci

# Build the project
npm run build

# Create a symlink
npm link
```

## Quick Start

```bash
# Initialize a workspace
hive init

# Add a repository with a team
hive add-repo --url git@github.com:org/my-service.git --team my-team

# Submit a requirement (this kicks off the entire workflow)
hive req "Add user authentication with OAuth2 support"

# Watch the magic happen
hive dashboard
```

### Basic Usage Examples

After installation, you can:

```bash
# Check overall status
hive status

# View all stories
hive stories list

# Check your team's active agents
hive agents list --active

# Monitor progress in real-time
hive dashboard

# Check for escalations (agents asking for help)
hive escalations list

# Single queue for human approval requests
hive approvals list
```

## How It Works

### Your Role: Product Owner

You provide high-level requirements. The AI team handles everything else:

```mermaid
graph TD
    A["YOU (Product Owner)<br/>Add feature X to the system"] --> B["TECH LEAD (Opus)<br/>Analyzes requirement<br/>Breaks it into stories<br/>Coordinates teams"]
    B --> C["TEAM: Alpha<br/>Senior (Opus)"]
    B --> D["TEAM: Beta<br/>Senior (Opus)"]
    C --> C1["Intermediate (Sonnet)"]
    C --> C2["Junior (Haiku)"]
    C --> C3["QA (Sonnet)"]
    D --> D1["Intermediate (Sonnet)"]
    D --> D2["Junior (Haiku)"]
    D --> D3["QA (Sonnet)"]
```

### The Workflow

1. **You submit a requirement** → `hive req "Your feature request"`
2. **Tech Lead analyzes** → Identifies affected repos, creates stories with dependencies
3. **Stories are estimated** → Complexity scores assigned (Fibonacci 1-13)
4. **Work is assigned** →

... (truncated)