hungry-ghost-hive

v0.24.0

Published

10 hours ago

AI Agent Orchestrator - Manages agile software development teams of AI agents

0High
0Medium
0Low

nikrich

ai agents orchestrator cli agile development

Hive - AI Agent Orchestrator

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 PR submission.

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, and Juniors
Requirement to PR Automation: From initial requirements to merged pull requests, fully automated
Intelligent Task Distribution: Stories automatically routed to appropriate skill levels (Junior, Intermediate, Senior)
Real-Time Dashboard: Monitor team progress and agent activity with an interactive TUI dashboard
Multi-Repository Support: Manage related services and libraries as coordinated git submodules
Escalation Handling: Built-in escalation protocol when agents need guidance or hit blockers
PR Merge Queue: Automated QA checks and merge queue management for production readiness

Installation

Via npm (Recommended)

npm install -g hungry-ghost-hive

For Contributors (Development Setup)

If you want to contribute or run from source:

# 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

# Initialize a workspace
hive init

# Add a repository with a team
hive add-repo --url [email protected]: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:

# 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:

graph TD
    A["👤 YOU (Product Owner)<br/>Add feature X to the system"] --> B["🧠 TECH LEAD (Claude Opus)<br/>• Analyzes requirement<br/>• Breaks it into stories<br/>• Coordinates teams"]
    B --> C["👥 TEAM: Alpha<br/>Senior (Sonnet)"]
    B --> D["👥 TEAM: Beta<br/>Senior (Sonnet)"]
    C --> C1["📊 Intermediate (Haiku)"]
    C --> C2["🚀 Junior (GPT-4o-mini)"]
    C --> C3["✅ QA (Sonnet)"]
    D --> D1["📊 Intermediate (Haiku)"]
    D --> D2["🚀 Junior (GPT-4o-mini)"]
    D --> D3["✅ QA (Sonnet)"]

The Workflow

You submit a requirement → hive req "Your feature request"
Tech Lead analyzes → Identifies affected repos, creates stories
Seniors estimate → Assign complexity scores, plan the work
Work is assigned → Based on complexity:
- Simple (1-3 points) → Junior
- Medium (4-5 points) → Intermediate
- Complex (6-13 points) → Senior
Developers implement → Create branches, write code, run tests
PRs submitted → hive pr submit adds to merge queue
QA reviews → Automated spawning, code review, approval
Merged! → Story complete

The Manager (Micromanager Daemon)

The Manager ensures agents stay productive:

Auto-starts when work begins
Checks every 60 seconds for stuck agents
Health checks sync agent status with tmux sessions
Nudges idle agents to check for work
Forwards messages between agents
Spawns QA when PRs need review

Commands Reference

For You (Product Owner)

# Submit a new requirement
hive req "Implement user authentication"
hive req --file requirements.md

# Check overall status
hive status

# Open the dashboard
hive dashboard

# Dashboard controls:
#   ↑↓        Navigate agents list
#   Enter     Attach to selected agent's tmux session
#   Ctrl+B,D  Detach from tmux (returns to shell)
#   Tab       Switch between panels
#   Esc/Q     Exit dashboard

# View escalations (agents asking for help)
hive escalations list
hive escalations resolve <id> --message "Here's what to do..."

# View/handle human approval requests
hive approvals list
hive approvals approve <id> -m "Proceed"
hive approvals deny <id> -m "Do not run that"

Workflow Management

# Assign stories to agents (triggers work)
hive assign

# View stories
hive stories list
hive stories show <story-id>

# Engineer-discovered refactor story (from an agent session)
hive my-stories refactor --session <agent-session> --title "Simplify auth middleware" --description "Duplication and branching complexity in auth stack" --points 2

# View agents
hive agents list
hive agents list --active

Merge Queue & QA

# View the merge queue
hive pr queue

# Manually trigger QA review
hive pr review --from <qa-session>

# Approve/reject PRs
hive pr approve <pr-id>
hive pr reject <pr-id> --reason "Tests failing"

Manager (Micromanager)

# Check manager status
hive manager status

# Manually start/stop
hive manager start
hive manager start -i 30  # Check every 30 seconds
hive manager stop

# Run single check
hive manager check

# Sync agent status with tmux
hive manager health

# Nudge a specific agent
hive manager nudge <session>
hive manager nudge hive-senior-alpha -m "Check the failing tests"

# Cluster status (when cluster.enabled=true)
hive cluster status
hive cluster status --json

Communication

# Send message to an agent
hive msg send hive-senior-alpha "Please prioritize STORY-001"

# Check messages
hive msg inbox
hive msg outbox

Architecture

Directory Structure

my-workspace/
├── .hive/
│   ├── hive.db              # SQLite database (all state)
│   ├── hive.config.yaml     # Configuration
│   ├── agents/              # Agent session states
│   └── logs/                # Conversation logs
├── repos/
│   ├── service-a/           # Git submodule
│   └── service-b/           # Git submodule
└── README.md

Agent Sessions

Each agent runs in a tmux session:

hive-tech-lead          # Tech Lead (Opus)
hive-senior-alpha       # Senior for team "alpha"
hive-intermediate-alpha-1
hive-junior-alpha-1
hive-qa-alpha           # QA for team "alpha"
hive-manager            # The micromanager daemon

Story States

stateDiagram-v2
    [*] --> draft
    draft --> estimated
    estimated --> planned
    planned --> in_progress
    in_progress --> review
    review --> qa
    qa --> pr_submitted: All checks pass
    qa --> qa_failed: Failed checks
    qa_failed --> in_progress: Returns to developer
    pr_submitted --> merged
    merged --> [*]

Configuration

Edit .hive/hive.config.yaml:

# Model assignments
models:
  tech_lead:
    provider: anthropic
    model: claude-opus-4-20250514
    cli_tool: claude
    safety_mode: unsafe # safe = human approvals, unsafe = full automation
  senior:
    provider: anthropic
    model: claude-sonnet-4-20250514
    cli_tool: claude
    safety_mode: unsafe
  intermediate:
    provider: anthropic
    model: claude-haiku-3-5-20241022
    cli_tool: claude
    safety_mode: unsafe
  junior:
    provider: openai
    model: gpt-4o-mini
    cli_tool: codex
    safety_mode: unsafe
  qa:
    provider: anthropic
    model: claude-sonnet-4-20250514
    cli_tool: claude
    safety_mode: unsafe

# Complexity thresholds for delegation
scaling:
  junior_max_complexity: 3 # 1-3 → Junior
  intermediate_max_complexity: 5 # 4-5 → Intermediate
  senior_capacity: 20 # Story points before scaling up
  refactor:
    enabled: true
    capacity_percent: 10 # Reserve up to 10% of feature capacity for refactor stories
    allow_without_feature_work: true

# QA checks
qa:
  quality_checks:
    - npm run lint
    - npm run type-check
  build_command: npm run build
  test_command: npm test

# Optional distributed mode (HTTP + peer replication)
cluster:
  enabled: false
  node_id: node-a
  listen_host: 127.0.0.1
  listen_port: 8787
  public_url: http://203.0.113.10:8787
  # Required if listen_host is not loopback (127.0.0.1/localhost/::1)
  # auth_token: replace-with-strong-shared-secret
  peers:
    - id: node-b
      url: http://198.51.100.20:8787
    - id: node-c
      url: http://192.0.2.30:8787
  heartbeat_interval_ms: 2000
  election_timeout_min_ms: 3000
  election_timeout_max_ms: 6000
  sync_interval_ms: 5000
  request_timeout_ms: 5000
  story_similarity_threshold: 0.92

Distributed Mode

Run hive manager start on every host in the same cluster.
Each host runs manager/scheduler runtime, but only one node is elected leader at a time.
Leader is the only node allowed to run orchestration decisions (assign, scheduler loops, tech lead spawn).
Followers stay in sync and do not schedule work.
State replication is logical row/event sync over HTTP (no centralized DB).

Escalation Protocol

When agents get stuck, they escalate:

graph LR
    A["🚀 Junior<br/>Stuck on issue"] --> B["👔 Senior<br/>Cannot resolve"]
    B --> C["🧠 Tech Lead<br/>Escalates higher"]
    C --> D["👤 YOU<br/>Human guidance"]

Check escalations:

hive escalations list

Resolve with guidance:

hive escalations resolve ESC-001 --message "Use OAuth2 with PKCE flow"

Tips for Product Owners

Be specific in requirements - The more detail, the better the stories
Check the dashboard - hive dashboard shows real-time progress
Monitor escalations - Agents will ask when they need guidance
Trust the process - Let agents work, they'll handle the details

Troubleshooting

Agents seem stuck

hive manager check   # Nudge all agents
hive manager health  # Sync status with tmux

Agent session died

hive manager health  # Cleans up dead agents, respawns as needed

View agent logs

tmux attach -t hive-senior-alpha  # Attach to see what agent is doing
# Detach with Ctrl+B, D

Reset everything

hive nuke --all  # WARNING: Deletes all data

Contributors

We appreciate contributions from everyone! This project is built and maintained by:

Code Quality

Hive is built with production-grade quality standards:

Comprehensive Testing: 431+ test cases with automated test execution
Strict TypeScript: Full type safety with no implicit any
Code Linting: ESLint configuration enforces consistent code style
Conventional Commits: Commit messages follow the conventional commits specification for automatic changelog generation
Automated Releases: Release Please integration for semantic versioning and automated npm publishing

Contributing

We welcome contributions! Here's how to get started:

Development Setup

Clone and Install:

git clone https://github.com/nikrich/hungry-ghost-hive.git
cd hungry-ghost-hive
npm ci

Run Tests:

npm test              # Run all tests
npm run test:watch   # Watch mode

Build and Lint:

npm run build         # Build the project
npm run lint          # Check code style
npm run type-check    # TypeScript type checking

Pull Request Guidelines

Create a feature branch: git checkout -b feature/your-feature-name
Follow the existing code style and patterns
Add or update tests for your changes
Run linting and tests before committing: npm run lint && npm test
Use conventional commit messages (e.g., feat:, fix:, docs:, test:, refactor:)
Submit a pull request with a clear description of your changes

Environment Variables

ANTHROPIC_API_KEY=sk-ant-...  # Required for Claude agents
OPENAI_API_KEY=sk-...         # Required for GPT agents (juniors)
GITHUB_TOKEN=ghp_...          # Required for PR creation

Issue Tracking (Beads)

This repository uses bd (Beads) for issue tracking. Run bd onboard to get started.

Quick Reference

bd ready              # Find available work
bd show <id>          # View issue details
bd update <id> --status in_progress  # Claim work
bd close <id>         # Complete work
bd sync               # Sync with git

Session Completion (Landing the Plane)

When ending a work session, complete ALL steps below. Work is NOT complete until git push succeeds.

File issues for remaining work
Run quality gates (tests/linters/builds) if code changed
Update issue status (close finished work, update in-progress)
Push to remote:

git pull --rebase
bd sync
git push
git status  # MUST show "up to date with origin"

Clean up (stashes, prune remote branches)
Verify all changes committed AND pushed
Hand off with context for next session

License

This project is licensed under the Hungry Ghost Restricted License. See the LICENSE file for details.

License Summary

✅ You CAN use the software for any purpose, including commercial projects
✅ You CAN modify the software for your own use
✅ You CAN contribute improvements via pull requests
❌ You CANNOT redistribute the software to others
❌ You CANNOT sell or sublicense the software itself

For more information, see the full LICENSE file.