hungry-ghost-hive 0.3.0

package/LICENSE

@@ -0,0 +1,111 @@
+HUNGRY GHOST HIVE LICENSE
+
+Copyright (c) 2026 Hungry Ghost. All Rights Reserved.
+
+TERMS AND CONDITIONS
+
+1. DEFINITIONS
+
+"Software" refers to the Hive system, including all source code, documentation,
+and associated files in this repository.
+
+"Contribution" means any work of authorship submitted to the project for
+inclusion in the Software.
+
+"Contributor" means any individual or entity that submits a Contribution.
+
+2. GRANT OF RIGHTS
+
+Subject to the terms of this License, you are granted the following rights:
+
+a) USE: You may use the Software for any purpose, including commercial projects.
+
+b) MODIFY: You may modify, adapt, and create derivative works of the Software
+   for your own internal use.
+
+c) CONTRIBUTE: You may submit Contributions to the official repository. By
+   submitting a Contribution, you grant Hungry Ghost a perpetual, worldwide,
+   non-exclusive, royalty-free, irrevocable license to use, reproduce, modify,
+   distribute, and sublicense your Contribution as part of the Software.
+
+3. RESTRICTIONS
+
+The following actions are expressly PROHIBITED without prior written permission
+from Hungry Ghost:
+
+a) REDISTRIBUTION: You may not distribute, share, publish, or otherwise make
+   available the Software or any derivative works to any third party, whether
+   in source or binary form.
+
+b) SELLING: You may not sell, license, sublicense, lease, or otherwise
+   commercialize the Software itself or any derivative works.
+
+c) COMPETING PRODUCTS: You may not redistribute the Software, in whole or in
+   part, as part of a competing product or service.
+
+Note: You ARE permitted to use the Software internally to build and sell your
+own products and services. The restriction is on redistributing or selling the
+Software itself, not on using it as a tool in your business.
+
+4. CONTRIBUTIONS
+
+a) All Contributions must be submitted through official channels (pull requests
+   to the official repository).
+
+b) By submitting a Contribution, you represent that you have the right to grant
+   the license in Section 2(c) and that your Contribution does not violate any
+   third-party rights.
+
+c) Hungry Ghost reserves the right to accept or reject any Contribution at its
+   sole discretion.
+
+d) Accepted Contributions become part of the Software and are subject to this
+   License.
+
+5. INTELLECTUAL PROPERTY
+
+a) Hungry Ghost retains all right, title, and interest in and to the Software,
+   including all intellectual property rights.
+
+b) This License does not grant you any rights to use Hungry Ghost's trademarks,
+   service marks, or trade names.
+
+6. NO WARRANTY
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL
+HUNGRY GHOST BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY ARISING
+FROM THE USE OF THE SOFTWARE.
+
+7. TERMINATION
+
+a) This License is effective until terminated.
+
+b) Your rights under this License will terminate automatically without notice
+   if you fail to comply with any term of this License.
+
+c) Upon termination, you must destroy all copies of the Software in your
+   possession.
+
+8. GENERAL
+
+a) This License constitutes the entire agreement between you and Hungry Ghost
+   concerning the Software.
+
+b) This License shall be governed by the laws of the jurisdiction in which
+   Hungry Ghost is incorporated.
+
+c) If any provision of this License is held to be unenforceable, such provision
+   shall be reformed only to the extent necessary to make it enforceable.
+
+For permissions beyond the scope of this License, contact: legal@hungryghost.io
+
+---
+
+SUMMARY (not legally binding):
+- 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

package/README.md

@@ -0,0 +1,352 @@
+# 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.
+
+## 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
+```
+
+## How It Works
+
+### Your Role: Product Owner
+
+You provide high-level requirements. The AI team handles everything else:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    YOU (Product Owner)                       │
+│              "Add feature X to the system"                   │
+└─────────────────────┬───────────────────────────────────────┘
+                      │
+                      ▼
+┌─────────────────────────────────────────────────────────────┐
+│                  TECH LEAD (Claude Opus)                     │
+│  • Analyzes your requirement                                 │
+│  • Breaks it into stories                                    │
+│  • Coordinates teams                                         │
+└─────────────────────┬───────────────────────────────────────┘
+                      │
+          ┌───────────┴───────────┐
+          ▼                       ▼
+┌─────────────────┐     ┌─────────────────┐
+│   TEAM: Alpha    │     │   TEAM: Beta     │
+│                  │     │                  │
+│ Senior (Sonnet)  │     │ Senior (Sonnet)  │
+│      │           │     │      │           │
+│  ┌───┴───┐       │     │  ┌───┴───┐       │
+│  Int   Jr        │     │  Int   Jr        │
+│                  │     │                  │
+│ QA (Sonnet)      │     │ QA (Sonnet)      │
+└─────────────────┘     └─────────────────┘
+```
+
+### The Workflow
+
+1. **You submit a requirement** → `hive req "Your feature request"`
+2. **Tech Lead analyzes** → Identifies affected repos, creates stories
+3. **Seniors estimate** → Assign complexity scores, plan the work
+4. **Work is assigned** → Based on complexity:
+   - Simple (1-3 points) → Junior
+   - Medium (4-5 points) → Intermediate
+   - Complex (6-13 points) → Senior
+5. **Developers implement** → Create branches, write code, run tests
+6. **PRs submitted** → `hive pr submit` adds to merge queue
+7. **QA reviews** → Automated spawning, code review, approval
+8. **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)
+
+```bash
+# 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..."
+```
+
+### Workflow Management
+
+```bash
+# Assign stories to agents (triggers work)
+hive assign
+
+# View stories
+hive stories list
+hive stories show <story-id>
+
+# View agents
+hive agents list
+hive agents list --active
+```
+
+### Merge Queue & QA
+
+```bash
+# 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)
+
+```bash
+# 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"
+```
+
+### Communication
+
+```bash
+# 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
+
+```
+draft → estimated → planned → in_progress → review → qa → pr_submitted → merged
+                                              ↓
+                                          qa_failed (returns to developer)
+```
+
+## Configuration
+
+Edit `.hive/hive.config.yaml`:
+
+```yaml
+# Model assignments
+models:
+  tech_lead:
+    provider: anthropic
+    model: claude-opus-4-20250514
+  senior:
+    provider: anthropic
+    model: claude-sonnet-4-20250514
+  intermediate:
+    provider: anthropic
+    model: claude-haiku-3-5-20241022
+  junior:
+    provider: openai
+    model: gpt-4o-mini
+  qa:
+    provider: anthropic
+    model: claude-sonnet-4-20250514
+
+# 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
+
+# QA checks
+qa:
+  quality_checks:
+    - npm run lint
+    - npm run type-check
+  build_command: npm run build
+  test_command: npm test
+```
+
+## Escalation Protocol
+
+When agents get stuck, they escalate:
+
+```
+Junior → Senior → Tech Lead → YOU
+```
+
+Check escalations:
+```bash
+hive escalations list
+```
+
+Resolve with guidance:
+```bash
+hive escalations resolve ESC-001 --message "Use OAuth2 with PKCE flow"
+```
+
+## Tips for Product Owners
+
+1. **Be specific in requirements** - The more detail, the better the stories
+2. **Check the dashboard** - `hive dashboard` shows real-time progress
+3. **Monitor escalations** - Agents will ask when they need guidance
+4. **Trust the process** - Let agents work, they'll handle the details
+
+## Troubleshooting
+
+### Agents seem stuck
+```bash
+hive manager check   # Nudge all agents
+hive manager health  # Sync status with tmux
+```
+
+### Agent session died
+```bash
+hive manager health  # Cleans up dead agents, respawns as needed
+```
+
+### View agent logs
+```bash
+tmux attach -t hive-senior-alpha  # Attach to see what agent is doing
+# Detach with Ctrl+B, D
+```
+
+### Reset everything
+```bash
+hive nuke --all  # WARNING: Deletes all data
+```
+
+## Environment Variables
+
+```bash
+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
+```
+
+## License
+
+MIT

package/dist/agents/base-agent.d.ts

@@ -0,0 +1,63 @@
+import type { Database } from 'sql.js';
+import type { LLMProvider, Message } from '../llm/provider.js';
+import { type EventType } from '../db/queries/logs.js';
+import { type AgentRow, type AgentType, type AgentStatus } from '../db/queries/agents.js';
+export interface MemoryState {
+    conversationSummary: string;
+    currentTask?: {
+        storyId?: string;
+        phase: string;
+        filesModified: string[];
+        lastAction: string;
+    };
+    context: {
+        codebaseNotes?: string;
+        blockers: string[];
+        decisionsMade: string[];
+    };
+    checkpointTokens: number;
+}
+export interface AgentContext {
+    db: Database;
+    provider: LLMProvider;
+    agentRow: AgentRow;
+    workDir: string;
+    config: {
+        maxRetries: number;
+        checkpointThreshold: number;
+        pollInterval: number;
+        llmTimeoutMs: number;
+        llmMaxRetries: number;
+    };
+}
+export declare abstract class BaseAgent {
+    protected db: Database;
+    protected provider: LLMProvider;
+    protected agentId: string;
+    protected agentType: AgentType;
+    protected teamId: string | null;
+    protected workDir: string;
+    protected config: AgentContext['config'];
+    protected messages: Message[];
+    protected memoryState: MemoryState;
+    protected totalTokens: number;
+    private heartbeatInterval;
+    constructor(context: AgentContext);
+    abstract getSystemPrompt(): string;
+    private startHeartbeat;
+    private sendHeartbeat;
+    private stopHeartbeat;
+    protected log(eventType: EventType, message?: string, metadata?: Record<string, unknown>): void;
+    protected updateStatus(status: AgentStatus): void;
+    protected saveMemoryState(): void;
+    protected chat(userMessage: string): Promise<string>;
+    protected checkpoint(): Promise<void>;
+    protected addDecision(decision: string): void;
+    protected addBlocker(blocker: string): void;
+    protected removeBlocker(blocker: string): void;
+    protected setCurrentTask(storyId: string, phase: string): void;
+    protected updateTaskProgress(lastAction: string, filesModified?: string[]): void;
+    run(): Promise<void>;
+    abstract execute(): Promise<void>;
+}
+//# sourceMappingURL=base-agent.d.ts.map

package/dist/agents/base-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-agent.d.ts","sourceRoot":"","sources":["../../src/agents/base-agent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AACvC,OAAO,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAC/D,OAAO,EAAa,KAAK,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAClE,OAAO,EAAe,KAAK,QAAQ,EAAE,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAGvG,MAAM,WAAW,WAAW;IAC1B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,WAAW,CAAC,EAAE;QACZ,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,MAAM,CAAC;QACd,aAAa,EAAE,MAAM,EAAE,CAAC;QACxB,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC;IACF,OAAO,EAAE;QACP,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,QAAQ,EAAE,MAAM,EAAE,CAAC;QACnB,aAAa,EAAE,MAAM,EAAE,CAAC;KACzB,CAAC;IACF,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,QAAQ,CAAC;IACb,QAAQ,EAAE,WAAW,CAAC;IACtB,QAAQ,EAAE,QAAQ,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE;QACN,UAAU,EAAE,MAAM,CAAC;QACnB,mBAAmB,EAAE,MAAM,CAAC;QAC5B,YAAY,EAAE,MAAM,CAAC;QACrB,YAAY,EAAE,MAAM,CAAC;QACrB,aAAa,EAAE,MAAM,CAAC;KACvB,CAAC;CACH;AAED,8BAAsB,SAAS;IAC7B,SAAS,CAAC,EAAE,EAAE,QAAQ,CAAC;IACvB,SAAS,CAAC,QAAQ,EAAE,WAAW,CAAC;IAChC,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC;IAC1B,SAAS,CAAC,SAAS,EAAE,SAAS,CAAC;IAC/B,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC;IAC1B,SAAS,CAAC,MAAM,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC;IACzC,SAAS,CAAC,QAAQ,EAAE,OAAO,EAAE,CAAM;IACnC,SAAS,CAAC,WAAW,EAAE,WAAW,CAAC;IACnC,SAAS,CAAC,WAAW,SAAK;IAC1B,OAAO,CAAC,iBAAiB,CAA+B;gBAE5C,OAAO,EAAE,YAAY;IAwCjC,QAAQ,CAAC,eAAe,IAAI,MAAM;IAElC,OAAO,CAAC,cAAc;IAUtB,OAAO,CAAC,aAAa;IASrB,OAAO,CAAC,aAAa;IAOrB,SAAS,CAAC,GAAG,CACX,SAAS,EAAE,SAAS,EACpB,OAAO,CAAC,EAAE,MAAM,EAChB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACjC,IAAI;IAUP,SAAS,CAAC,YAAY,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI;IAIjD,SAAS,CAAC,eAAe,IAAI,IAAI;cAOjB,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;cA2B1C,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IA6B3C,SAAS,CAAC,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAK7C,SAAS,CAAC,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAK3C,SAAS,CAAC,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAO9C,SAAS,CAAC,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAU9D,SAAS,CAAC,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI;IAU1E,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;IAkB1B,QAAQ,CAAC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAClC"}