{"id":43899150,"url":"https://github.com/nikrich/hungry-ghost-hive","last_synced_at":"2026-03-08T09:06:53.957Z","repository":{"id":336407738,"uuid":"1149506210","full_name":"nikrich/hungry-ghost-hive","owner":"nikrich","description":"Hive is a Multi Agent Orchestrator modelled after Agile Teams","archived":false,"fork":false,"pushed_at":"2026-02-23T22:14:18.000Z","size":2780,"stargazers_count":9,"open_issues_count":4,"forks_count":4,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-02-24T02:03:42.778Z","etag":null,"topics":["agent-integration","agent-workflow","agents","llm","multi-agent","multi-agent-systems"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nikrich.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-04T07:32:05.000Z","updated_at":"2026-02-23T22:13:45.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/nikrich/hungry-ghost-hive","commit_stats":null,"previous_names":["nikrich/hungry-ghost-hive"],"tags_count":84,"template":false,"template_full_name":null,"purl":"pkg:github/nikrich/hungry-ghost-hive","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nikrich%2Fhungry-ghost-hive","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nikrich%2Fhungry-ghost-hive/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nikrich%2Fhungry-ghost-hive/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nikrich%2Fhungry-ghost-hive/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nikrich","download_url":"https://codeload.github.com/nikrich/hungry-ghost-hive/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nikrich%2Fhungry-ghost-hive/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30014188,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-02T17:00:27.440Z","status":"ssl_error","status_checked_at":"2026-03-02T17:00:03.402Z","response_time":60,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-integration","agent-workflow","agents","llm","multi-agent","multi-agent-systems"],"created_at":"2026-02-06T18:13:06.860Z","updated_at":"2026-03-08T09:06:53.950Z","avatar_url":"https://github.com/nikrich.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Hive - AI Agent Orchestrator\n\n[![CI](https://img.shields.io/github/actions/workflow/status/nikrich/hungry-ghost-hive/ci.yml?branch=main\u0026style=flat-square)](https://github.com/nikrich/hungry-ghost-hive/actions/workflows/ci.yml)\n[![npm](https://img.shields.io/npm/v/hungry-ghost-hive?style=flat-square)](https://www.npmjs.com/package/hungry-ghost-hive)\n[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen?style=flat-square)](https://nodejs.org/)\n[![License](https://img.shields.io/badge/license-Restricted-blue?style=flat-square)](LICENSE)\n[![TypeScript](https://img.shields.io/badge/language-TypeScript-blue?style=flat-square)](https://www.typescriptlang.org/)\n[![Codecov](https://img.shields.io/codecov/c/github/nikrich/hungry-ghost-hive?style=flat-square)](https://codecov.io/gh/nikrich/hungry-ghost-hive)\n\n\u003cimg width=\"1263\" height=\"651\" alt=\"image\" src=\"https://github.com/user-attachments/assets/76eb8bd9-d5ec-45b7-9ee2-b7ef910f3e88\" /\u003e\n\nHive 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.\n\n## Key Features\n\n- **AI-Powered Team Management**: Orchestrate autonomous teams of AI agents across multiple repositories\n- **Agile Workflow**: Natural hierarchy mirrors real development teams with Tech Lead, Seniors, Intermediates, Juniors, and QA agents\n- **Requirement to PR Automation**: From initial requirements to merged pull requests, fully automated\n- **Intelligent Task Distribution**: Stories automatically routed to appropriate skill levels based on complexity scoring\n- **QA Review Agents**: Dedicated QA agents auto-spawn to review PRs, run quality checks, and enforce acceptance criteria\n- **Feature Sign-Off**: Automated E2E test execution when all stories for a requirement are merged\n- **Real-Time Dashboard**: Interactive TUI dashboard with pipeline visualization, agent monitoring, PR review, and messaging\n- **Multi-Repository Support**: Manage related services and libraries as coordinated git submodules with per-agent worktree isolation\n- **Story Dependencies**: Topological dependency resolution ensures stories are completed in the right order\n- **Escalation Handling**: Built-in escalation protocol when agents need guidance or hit blockers\n- **PR Merge Queue**: Automated merge queue with QA gating, auto-merge, and duplicate PR detection\n- **Jira Integration**: Two-way sync with Jira — epics, stories, subtasks, story points, sprint assignment, and status transitions\n- **Multi-CLI Support**: Agents can use Claude Code, Codex, or Gemini CLI as their runtime\n- **Distributed Mode**: Cluster support with RAFT-based leader election, peer replication, and duplicate story detection\n- **Godmode**: Override complexity routing to use the most powerful models for all agents on a requirement\n- **Manager Intelligence**: AI-powered stuck detection, automatic permission bypass, plan mode escape, and orphan recovery\n\n## Installation\n\n### Via npm (Recommended)\n\n```bash\nnpm install -g hungry-ghost-hive\n```\n\n### For Contributors (Development Setup)\n\nIf you want to contribute or run from source:\n\n```bash\n# Clone the repository\ngit clone https://github.com/nikrich/hungry-ghost-hive.git\ncd hungry-ghost-hive\n\n# Install dependencies\nnpm ci\n\n# Build the project\nnpm run build\n\n# Create a symlink\nnpm link\n```\n\n## Quick Start\n\n```bash\n# Initialize a workspace\nhive init\n\n# Add a repository with a team\nhive add-repo --url git@github.com:org/my-service.git --team my-team\n\n# Submit a requirement (this kicks off the entire workflow)\nhive req \"Add user authentication with OAuth2 support\"\n\n# Watch the magic happen\nhive dashboard\n```\n\n### Basic Usage Examples\n\nAfter installation, you can:\n\n```bash\n# Check overall status\nhive status\n\n# View all stories\nhive stories list\n\n# Check your team's active agents\nhive agents list --active\n\n# Monitor progress in real-time\nhive dashboard\n\n# Check for escalations (agents asking for help)\nhive escalations list\n\n# Single queue for human approval requests\nhive approvals list\n```\n\n## How It Works\n\n### Your Role: Product Owner\n\nYou provide high-level requirements. The AI team handles everything else:\n\n```mermaid\ngraph TD\n    A[\"YOU (Product Owner)\u003cbr/\u003eAdd feature X to the system\"] --\u003e B[\"TECH LEAD (Opus)\u003cbr/\u003eAnalyzes requirement\u003cbr/\u003eBreaks it into stories\u003cbr/\u003eCoordinates teams\"]\n    B --\u003e C[\"TEAM: Alpha\u003cbr/\u003eSenior (Opus)\"]\n    B --\u003e D[\"TEAM: Beta\u003cbr/\u003eSenior (Opus)\"]\n    C --\u003e C1[\"Intermediate (Sonnet)\"]\n    C --\u003e C2[\"Junior (Haiku)\"]\n    C --\u003e C3[\"QA (Sonnet)\"]\n    D --\u003e D1[\"Intermediate (Sonnet)\"]\n    D --\u003e D2[\"Junior (Haiku)\"]\n    D --\u003e D3[\"QA (Sonnet)\"]\n```\n\n### The Workflow\n\n1. **You submit a requirement** → `hive req \"Your feature request\"`\n2. **Tech Lead analyzes** → Identifies affected repos, creates stories with dependencies\n3. **Stories are estimated** → Complexity scores assigned (Fibonacci 1-13)\n4. **Work is assigned** → Based on complexity:\n   - Simple (1-3 points) → Junior\n   - Medium (4-5 points) → Intermediate\n   - Complex (6+ points) → Senior\n   - Blocker stories (depended on by others) → always Senior\n5. **Developers implement** → Each agent gets an isolated git worktree, writes code, runs tests\n6. **PRs submitted** → Added to merge queue with automatic duplicate detection\n7. **QA reviews** → QA agents auto-spawn, run lint/type-check/tests, validate acceptance criteria\n8. **Auto-merged** → Approved PRs are automatically merged\n9. **Feature sign-off** → When all stories are merged, E2E tests run automatically\n\n### QA Review Agents\n\nWhen a developer submits a PR to the merge queue, the manager automatically spawns a QA agent to review it:\n\n- Checks out the PR branch and runs configurable quality checks (`npm run lint`, `npm run type-check`, etc.)\n- Runs the build command and test suite\n- Validates that acceptance criteria from the story are met\n- Approves and auto-merges passing PRs, or rejects with detailed feedback\n- After 3+ QA failures on the same story, escalates to a Senior agent\n\n### Feature Sign-Off\n\nWhen all stories for a requirement reach `merged` status:\n\n1. The manager detects the completed requirement\n2. A feature test agent is spawned to run E2E tests (configured via `e2e_test_path`)\n3. Results are posted to Jira as a sign-off report\n4. Requirement transitions to `sign_off_passed` or `sign_off_failed`\n\n### The Manager (Micromanager Daemon)\n\nThe Manager ensures agents stay productive:\n\n- **Auto-starts** when work begins\n- **Configurable intervals** — fast poll for active work, slow poll when idle\n- **Health checks** sync agent status with tmux sessions\n- **AI-powered done detection** — uses heuristics and LLM classification to determine if agents have finished\n- **Stuck detection** — monitors screen output fingerprints to identify frozen agents\n- **Permission bypass** — automatically handles permission prompts that block agent progress\n- **Plan mode escape** — detects agents stuck in interactive plan mode and sends escape sequences\n- **Orphan recovery** — detects stories left `in_progress` by terminated agents and resets them for reassignment\n- **QA spawning** — automatically creates QA agents when PRs enter the merge queue\n- **Context freshness** — restarts long-running tech lead sessions to maintain fresh context\n- **Nudges idle agents** to check for work\n- **Forwards messages** between agents\n\n### Story Dependencies\n\nStories can depend on other stories. The scheduler uses topological sorting (Kahn's algorithm) to ensure:\n\n- Stories with unresolved dependencies are skipped during assignment\n- Blocker stories (that others depend on) are routed to Senior agents for priority completion\n- Circular dependencies are detected and flagged\n\n## Commands Reference\n\n### For You (Product Owner)\n\n```bash\n# Submit a new requirement\nhive req \"Implement user authentication\"\nhive req --file requirements.md\nhive req --godmode \"Critical security fix\"     # Force Opus for all agents\nhive req --target-branch develop \"My feature\"  # Target a specific branch\nhive req --dry-run \"Test requirement\"          # Plan without spawning agents\n\n# Import from Jira epic\nhive req \"https://mycompany.atlassian.net/browse/PROJ-100\"\n\n# Check overall status\nhive status\nhive status --json\n\n# Open the dashboard\nhive dashboard\n\n# Dashboard controls:\n#   Up/Down   Navigate agents list\n#   Enter     Attach to selected agent's tmux session\n#   Ctrl+B,D  Detach from tmux (returns to dashboard)\n#   Tab       Switch between panels\n#   Q/Ctrl+C  Exit dashboard\n\n# View escalations (agents asking for help)\nhive escalations list\nhive escalations resolve \u003cid\u003e --message \"Here's what to do...\"\nhive escalations acknowledge \u003cid\u003e\n\n# View/handle human approval requests\nhive approvals list\nhive approvals approve \u003cid\u003e -m \"Proceed\"\nhive approvals deny \u003cid\u003e -m \"Do not run that\"\n```\n\n### Workflow Management\n\n```bash\n# Assign stories to agents (triggers work)\nhive assign\nhive assign --dry-run  # Preview assignments without spawning\n\n# View stories\nhive stories list\nhive stories show \u003cstory-id\u003e\n\n# View agents\nhive agents list\nhive agents list --active\nhive agents inspect \u003cagent-id\u003e   # Detailed agent state\nhive agents logs \u003cagent-id\u003e      # View agent event logs\nhive agents cleanup              # Clean up dead agent resources\n\n# Resume agents from saved state\nhive resume --all\nhive resume --agent \u003cagent-id\u003e\n\n# Clean up orphaned resources (worktrees, lock files, dead sessions)\nhive cleanup\n```\n\n### Merge Queue \u0026 QA\n\n```bash\n# View the merge queue\nhive pr queue\nhive pr queue --json\n\n# Submit a PR to the merge queue\nhive pr submit --story \u003cstory-id\u003e --branch \u003cbranch-name\u003e\n\n# Sync open GitHub PRs into the merge queue\nhive pr sync\n\n# Manually trigger QA review\nhive pr review --from \u003cqa-session\u003e\n\n# Approve/reject PRs\nhive pr approve \u003cpr-id\u003e\nhive pr approve \u003cpr-id\u003e --no-merge     # Approve without auto-merging\nhive pr reject \u003cpr-id\u003e --reason \"Tests failing\"\n\n# View closed/merged PRs\nhive pr closed\n```\n\n### Manager (Micromanager)\n\n```bash\n# Check manager status\nhive manager status\n\n# Manually start/stop\nhive manager start\nhive manager start -i 30  # Check every 30 seconds\nhive manager stop\n\n# Run single check\nhive manager check\n\n# Sync agent status with tmux\nhive manager health\n\n# Nudge a specific agent\nhive manager nudge \u003csession\u003e\nhive manager nudge hive-senior-alpha -m \"Check the failing tests\"\n```\n\n### Project Management Integration\n\n```bash\n# Provider-agnostic commands (works with Jira or other configured providers)\nhive pm fetch HIVE-42\nhive pm fetch https://mycompany.atlassian.net/browse/HIVE-42\nhive pm search \"project = HIVE AND status = 'In Progress'\"\nhive pm search \"sprint in openSprints()\" --max 20 --json\n\n# Jira-specific (legacy alias, delegates to hive pm)\nhive jira fetch HIVE-42\nhive jira search \"assignee = currentUser()\"\n```\n\n### Communication\n\n```bash\n# Send message to an agent\nhive msg send hive-senior-alpha \"Please prioritize STORY-001\"\n\n# Check messages\nhive msg inbox\nhive msg inbox hive-tech-lead      # Check specific agent's inbox\nhive msg read \u003cmsg-id\u003e             # Read a specific message\nhive msg reply \u003cmsg-id\u003e \"response\" # Reply to a message\nhive msg outbox\n```\n\n### Authentication\n\n```bash\n# Re-authenticate with providers\nhive auth --provider github  # GitHub OAuth Device Flow\nhive auth --provider jira    # Jira OAuth 2.0 (3LO)\n```\n\n### Configuration\n\n```bash\n# View/modify configuration\nhive config show\nhive config get models.senior.model\nhive config set scaling.junior_max_complexity 4\n\n# Manage teams\nhive teams list\nhive teams show \u003cname\u003e\nhive teams remove \u003cname\u003e\n```\n\n### Cluster (Distributed Mode)\n\n```bash\nhive cluster status\nhive cluster status --json\n```\n\n### Agent-Only Commands\n\nThese commands are used by agents during their work sessions:\n\n```bash\n# Story management\nhive my-stories claim \u003cstory-id\u003e\nhive my-stories complete \u003cstory-id\u003e\nhive my-stories refactor --title \"Simplify auth\" --description \"...\" --points 2\n\n# Progress reporting (posts to Jira subtask)\nhive progress -m \"Implemented auth middleware\" --from \u003csession\u003e\nhive progress -m \"All tests passing\" --from \u003csession\u003e --done\n\n# Post implementation approach comment\nhive approach --from \u003csession\u003e\n```\n\n## Architecture\n\n### Directory Structure\n\n```\nmy-workspace/\n├── .hive/\n│   ├── hive.db              # SQLite database (all state)\n│   ├── hive.config.yaml     # Configuration\n│   ├── .env                 # OAuth credentials (auto-managed)\n│   ├── agents/              # Agent session states\n│   └── logs/                # Conversation logs\n├── repos/\n│   ├── service-a/           # Git submodule (shared repo)\n│   ├── team-abc-senior-1/   # Agent worktree (isolated copy)\n│   ├── team-abc-junior-1/   # Agent worktree (isolated copy)\n│   └── team-abc-qa-1/       # Agent worktree (isolated copy)\n└── README.md\n```\n\n### Git Worktree Isolation\n\nEach agent gets its own git worktree to prevent branch conflicts when multiple agents work on the same repository simultaneously. Worktrees are created automatically during story assignment and cleaned up when agents terminate.\n\n### Agent Sessions\n\nEach agent runs in a tmux session:\n\n```\nhive-tech-lead          # Tech Lead (Opus)\nhive-senior-alpha       # Senior for team \"alpha\"\nhive-intermediate-alpha-1\nhive-junior-alpha-1\nhive-qa-alpha           # QA for team \"alpha\"\nhive-manager            # The micromanager daemon\n```\n\n### Agent Types\n\n| Type         | Default Model | CLI Tool | Role                                                          |\n| ------------ | ------------- | -------- | ------------------------------------------------------------- |\n| Tech Lead    | Claude Opus   | claude   | Requirement analysis, story creation, cross-team coordination |\n| Senior       | Claude Opus   | claude   | Complex stories (6+), estimation, team leadership, blockers   |\n| Intermediate | Claude Sonnet | claude   | Medium stories (4-5), implementation and testing              |\n| Junior       | Claude Haiku  | claude   | Simple stories (1-3), supervised implementation               |\n| QA           | Claude Sonnet | claude   | PR review, quality checks, acceptance criteria validation     |\n| Feature Test | Claude Sonnet | claude   | E2E test execution for feature sign-off                       |\n\n### Story States\n\n```mermaid\nstateDiagram-v2\n    [*] --\u003e draft\n    draft --\u003e estimated\n    estimated --\u003e planned\n    planned --\u003e in_progress\n    in_progress --\u003e review\n    review --\u003e qa\n    qa --\u003e pr_submitted: All checks pass\n    qa --\u003e qa_failed: Failed checks\n    qa_failed --\u003e in_progress: Returns to developer\n    pr_submitted --\u003e merged\n    merged --\u003e [*]\n```\n\n### Requirement States\n\n```mermaid\nstateDiagram-v2\n    [*] --\u003e pending\n    pending --\u003e planning\n    planning --\u003e planned\n    planned --\u003e in_progress\n    in_progress --\u003e completed: All stories merged\n    completed --\u003e sign_off: E2E tests configured\n    sign_off --\u003e sign_off_passed: Tests pass\n    sign_off --\u003e sign_off_failed: Tests fail\n    sign_off_passed --\u003e [*]\n    completed --\u003e [*]\n```\n\n## Configuration\n\nEdit `.hive/hive.config.yaml`:\n\n```yaml\n# Model assignments (all roles configurable)\nmodels:\n  tech_lead:\n    provider: anthropic\n    model: claude-opus-4-20250514\n    cli_tool: claude # claude | codex | gemini\n    safety_mode: unsafe # safe = human approvals, unsafe = full automation\n  senior:\n    provider: anthropic\n    model: claude-opus-4-20250514\n    cli_tool: claude\n    safety_mode: unsafe\n  intermediate:\n    provider: anthropic\n    model: claude-sonnet-4-20250514\n    cli_tool: claude\n    safety_mode: unsafe\n  junior:\n    provider: anthropic\n    model: claude-haiku-4-5-20251001\n    cli_tool: claude\n    safety_mode: unsafe\n  qa:\n    provider: anthropic\n    model: claude-sonnet-4-20250514\n    cli_tool: claude\n    safety_mode: unsafe\n  feature_test:\n    provider: anthropic\n    model: claude-sonnet-4-20250514\n    cli_tool: claude\n    safety_mode: unsafe\n\n# Complexity thresholds for delegation\nscaling:\n  junior_max_complexity: 3 # 1-3 -\u003e Junior\n  intermediate_max_complexity: 5 # 4-5 -\u003e Intermediate\n  senior_capacity: 20 # Story points before scaling up\n  refactor:\n    enabled: true\n    capacity_percent: 10 # Reserve up to 10% of feature capacity for refactor stories\n    allow_without_feature_work: true\n\n# QA configuration\nqa:\n  quality_checks:\n    - npm run lint\n    - npm run type-check\n  build_command: npm run build\n  test_command: npm test\n  scaling:\n    pending_per_agent: 2.5 # PRs per QA agent before scaling\n    max_agents: 5 # Maximum concurrent QA agents\n\n# Manager daemon tuning\nmanager:\n  stuck_threshold: 300000 # 5 min before stuck detection\n  nudge_cooldown: 600000 # 10 min between nudges\n  max_stuck_nudges_per_story: 1\n  screen_static_inactivity_threshold: 600000\n\n# Merge queue\nmerge_queue:\n  max_age_hours: 1 # Stale PR threshold\n\n# E2E testing for feature sign-off\ne2e_test_path: tests/e2e # Optional: enables feature sign-off\n\n# Optional distributed mode (HTTP + peer replication)\ncluster:\n  enabled: false\n  node_id: node-a\n  listen_host: 127.0.0.1\n  listen_port: 8787\n  public_url: http://203.0.113.10:8787\n  # auth_token: replace-with-strong-shared-secret\n  peers:\n    - id: node-b\n      url: http://198.51.100.20:8787\n  heartbeat_interval_ms: 2000\n  election_timeout_min_ms: 3000\n  election_timeout_max_ms: 6000\n  sync_interval_ms: 5000\n  story_similarity_threshold: 0.92\n```\n\n### Jira Integration\n\nWhen you select Jira during `hive init`, the setup wizard will:\n\n1. **Authenticate** via OAuth 2.0 (3LO) — you'll need a Jira OAuth app from the [Atlassian Developer Console](https://developer.atlassian.com/console/myapps/)\n2. **Select your project** from available Jira projects\n3. **Map statuses** — auto-detects Jira workflow statuses and maps them to Hive statuses (draft, planned, in_progress, etc.)\n4. **Select a board** — picks the board used for sprint operations\n5. **Detect story points field** — auto-detects the correct custom field for story points (varies between classic and next-gen projects)\n\n#### Setting up your Atlassian OAuth app\n\nBefore running `hive init`, you must configure an OAuth 2.0 (3LO) app in the Atlassian Developer Console:\n\n1. Go to [developer.atlassian.com/console/myapps](https://developer.atlassian.com/console/myapps/) and create a new app\n2. Under **Authorization** → **OAuth 2.0 (3LO)**, add the following callback URL:\n   ```\n   http://127.0.0.1:9876/callback\n   ```\n   \u003e **Important:** Use `127.0.0.1` — not `localhost`. Hive constructs the redirect URI with `127.0.0.1` explicitly, and Atlassian validates it character-for-character.\n3. Under **Permissions**, add the following scopes:\n\n   | API               | Scopes                                                                                                                         |\n   | ----------------- | ------------------------------------------------------------------------------------------------------------------------------ |\n   | Jira API          | `read:jira-work`, `write:jira-work`, `read:jira-user`                                                                          |\n   | Jira Software API | `read:board-scope:jira-software`, `write:board-scope:jira-software`, `read:sprint:jira-software`, `write:sprint:jira-software` |\n   | Confluence API    | `read:confluence-content.all`                                                                                                  |\n   | User Identity API | `offline_access`                                                                                                               |\n\n4. Save your changes, then copy the **Client ID** and **Client Secret** from the app's settings page — the `hive init` wizard will prompt you for these\n\n\u003e **Prerequisite:** Your Atlassian account must have an active Jira Cloud site. If you don't have one, create a free site at [atlassian.com](https://www.atlassian.com) before proceeding.\n\nConfiguration is saved to `.hive/hive.config.yaml`:\n\n```yaml\nintegrations:\n  project_management:\n    provider: jira\n    jira:\n      project_key: HIVE\n      site_url: https://mycompany.atlassian.net\n      board_id: '3'\n      story_type: Story\n      subtask_type: Subtask\n      story_points_field: customfield_10016 # auto-detected\n      status_mapping:\n        To Do: draft\n        In Progress: in_progress\n        Done: merged\n```\n\nOAuth credentials are stored in `.hive/.env` (auto-refreshed):\n\n```bash\nJIRA_ACCESS_TOKEN=...\nJIRA_REFRESH_TOKEN=...\nJIRA_CLOUD_ID=...\nJIRA_SITE_URL=...\nJIRA_CLIENT_ID=...\nJIRA_CLIENT_SECRET=...\n```\n\nWhen a requirement is synced to Jira, Hive will:\n\n- Create or reuse a Jira Epic for the requirement\n- Create Stories under the epic with descriptions and acceptance criteria\n- Set story points using the detected field\n- Create subtasks under stories when applicable\n- Move stories into the active sprint on the configured board\n- Create issue links for story dependencies\n- Transition stories through statuses as agents complete work\n- Post lifecycle comments (progress updates, sign-off reports)\n\n### Distributed Mode\n\n- Run `hive manager start` on every host in the same cluster.\n- Each host runs manager/scheduler runtime, but only one node is elected leader at a time (RAFT consensus).\n- Leader is the only node allowed to run orchestration decisions (`assign`, scheduler loops, tech lead spawn).\n- Followers stay in sync and do not schedule work.\n- State replication is logical row/event sync over HTTP (no centralized DB).\n- Duplicate story detection across nodes using configurable similarity threshold.\n\n## Escalation Protocol\n\nWhen agents get stuck, they escalate:\n\n```mermaid\ngraph LR\n    A[\"Junior\u003cbr/\u003eStuck on issue\"] --\u003e B[\"Senior\u003cbr/\u003eCannot resolve\"]\n    B --\u003e C[\"Tech Lead\u003cbr/\u003eEscalates higher\"]\n    C --\u003e D[\"YOU\u003cbr/\u003eHuman guidance\"]\n```\n\nQA agents escalate to Seniors after 3+ review failures on the same story.\n\nCheck escalations:\n\n```bash\nhive escalations list\n```\n\nResolve with guidance:\n\n```bash\nhive escalations resolve ESC-001 --message \"Use OAuth2 with PKCE flow\"\n```\n\n## Tips for Product Owners\n\n1. **Be specific in requirements** - The more detail, the better the stories\n2. **Check the dashboard** - `hive dashboard` shows real-time progress\n3. **Monitor escalations** - Agents will ask when they need guidance\n4. **Use godmode for critical work** - `hive req --godmode` uses top-tier models across the board\n5. **Import from Jira** - Pass a Jira epic URL to `hive req` to import directly\n6. **Trust the process** - Let agents work, they'll handle the details\n\n## Troubleshooting\n\n### Agents seem stuck\n\n```bash\nhive manager check   # Nudge all agents\nhive manager health  # Sync status with tmux\n```\n\n### Agent session died\n\n```bash\nhive manager health  # Cleans up dead agents, respawns as needed\n```\n\n### Orphaned resources (stale worktrees, lock files)\n\n```bash\nhive cleanup         # Cleans up worktrees, lock files, dead sessions, orphaned stories\n```\n\n### View agent logs\n\n```bash\ntmux attach -t hive-senior-alpha  # Attach to see what agent is doing\n# Detach with Ctrl+B, D\n```\n\n### Resume interrupted agents\n\n```bash\nhive resume --all           # Resume all agents from saved state\nhive resume --agent \u003cid\u003e    # Resume a specific agent\n```\n\n### Reset everything\n\n```bash\nhive nuke --all  # WARNING: Deletes all data including worktrees\n```\n\n## Contributors\n\nWe appreciate contributions from everyone! This project is built and maintained by:\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --\u003e\n\u003c!-- prettier-ignore-start --\u003e\n\u003c!-- markdownlint-disable --\u003e\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"https://github.com/nikrich\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/8254123?v=4?s=100\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003enikrich\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/nikrich/hungry-ghost-hive/commits?author=nikrich\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"https://github.com/nikrich/hungry-ghost-hive/commits?author=nikrich\" title=\"Documentation\"\u003e📖\u003c/a\u003e \u003ca href=\"#infra-nikrich\" title=\"Infrastructure\"\u003e🚀\u003c/a\u003e \u003ca href=\"#maintenance-nikrich\" title=\"Maintenance\"\u003e🚧\u003c/a\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"https://github.com/aleeuwen73\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/73424841?v=4?s=100\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eAlastair van Leeuwen\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/nikrich/hungry-ghost-hive/commits?author=aleeuwen73\" title=\"Code\"\u003e💻\u003c/a\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"https://github.com/tzone85\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/6205552?v=4?s=100\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eThando Mini\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/nikrich/hungry-ghost-hive/commits?author=tzone85\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"https://github.com/nikrich/hungry-ghost-hive/commits?author=tzone85\" title=\"Security\"\u003e🛡️\u003c/a\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"https://github.com/verigateart\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/219031990?v=4?s=100\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eArthur\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/nikrich/hungry-ghost-hive/commits?author=verigateart\" title=\"Code\"\u003e💻\u003c/a\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n\u003c!-- markdownlint-restore --\u003e\n\u003c!-- prettier-ignore-end --\u003e\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:END --\u003e\n\n## Code Quality\n\nHive is built with production-grade quality standards:\n\n- **Comprehensive Testing**: 1700+ test cases with automated test execution\n- **Strict TypeScript**: Full type safety with no implicit any\n- **Code Linting**: ESLint configuration enforces consistent code style\n- **Conventional Commits**: Commit messages follow the conventional commits specification for automatic changelog generation\n- **Automated Releases**: Release Please integration for semantic versioning and automated npm publishing\n\n## Contributing\n\nWe welcome contributions! Here's how to get started:\n\n### Development Setup\n\n1. **Clone and Install**:\n\n   ```bash\n   git clone https://github.com/nikrich/hungry-ghost-hive.git\n   cd hungry-ghost-hive\n   npm ci\n   ```\n\n2. **Run Tests**:\n\n   ```bash\n   npm test              # Run all tests\n   npm run test:watch   # Watch mode\n   ```\n\n3. **Build and Lint**:\n   ```bash\n   npm run build         # Build the project\n   npm run lint          # Check code style\n   npm run type-check    # TypeScript type checking\n   ```\n\n### Pull Request Guidelines\n\n- Create a feature branch: `git checkout -b feature/your-feature-name`\n- Follow the existing code style and patterns\n- Add or update tests for your changes\n- Run linting and tests before committing: `npm run lint \u0026\u0026 npm test`\n- Use conventional commit messages (e.g., `feat:`, `fix:`, `docs:`, `test:`, `refactor:`)\n- Submit a pull request with a clear description of your changes\n\n## Environment Variables\n\n```bash\nANTHROPIC_API_KEY=sk-ant-...  # Required for Claude agents\nOPENAI_API_KEY=sk-...         # Required if using OpenAI-based agents\nGITHUB_TOKEN=ghp_...          # Required for PR creation\n\n# Jira (auto-managed in .hive/.env after `hive init` or `hive auth jira`)\nJIRA_CLIENT_ID=...            # OAuth 2.0 client ID\nJIRA_CLIENT_SECRET=...        # OAuth 2.0 client secret\n```\n\n## License\n\nThis project is licensed under the **Hungry Ghost Restricted License**. See the [LICENSE](./LICENSE) file for details.\n\n### License Summary\n\n- You CAN use the software for any purpose, including commercial projects\n- You CAN modify the software for your own use\n- You CAN contribute improvements via pull requests\n- You CANNOT redistribute the software to others\n- You CANNOT sell or sublicense the software itself\n\nFor more information, see the full [LICENSE](./LICENSE) file.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnikrich%2Fhungry-ghost-hive","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnikrich%2Fhungry-ghost-hive","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnikrich%2Fhungry-ghost-hive/lists"}