beeops

3-layer multi-agent orchestration system (Queen → Leader → Worker) for Claude Code, powered by tmux.

Prerequisites

• Node.js >= 18
• git
• tmux
• python3
• Claude Code CLI (claude)
• GitHub CLI (gh)

Installation

npm install beeops
npx beeops init

Quick Start

Run /bo in Claude Code to start the Queen. She'll sync GitHub Issues, dispatch Leaders to git worktrees, and manage the full workflow — from implementation through code review and CI checks.

Queen (orchestrator)
  ├─ Leader          → decomposes issue, dispatches Workers, creates PR
  │    ├─ Worker (coder)
  │    └─ Worker (tester)
  └─ Review Leader   → dispatches review Workers, aggregates findings
       ├─ Worker (code-reviewer)
       ├─ Worker (security)
       └─ Worker (test-auditor)

Each layer runs as a separate Claude Code instance in a tmux pane. Communication flows through YAML reports and tmux wait-for signals. No external servers or databases required.

Attach with tmux attach -t bo to watch all agents work in real-time.

Architecture

• Queen (L1) — Reads GitHub Issues, builds a queue, dispatches Leaders and Review Leaders
• Leader (L2) — Decomposes an issue into subtasks, launches Workers in parallel, creates PRs
• Review Leader (L2) — Launches review Workers, aggregates findings, approves or requests fixes
• Workers (L3) — Execute a single subtask: coding, testing, or reviewing

The system includes 10 specialized skills, 1 hook (UserPromptSubmit for context injection), and locale support (en/ja) with a 4-step fallback chain.

Workers receive multi-layer context injection (base + specialization), so each role gets tailored instructions while sharing common autonomous-operation rules.

Configuration

npx beeops init [options]

| Option | Description | |--------|-------------| | --local (default) | Register hooks in .claude/settings.local.json (personal use) | | --shared | Register hooks in .claude/settings.json (team-shared, git committed) | | -g, --global | Register hooks in ~/.claude/settings.json (all projects) | | --with-contexts | Copy default context files locally for customization | | --locale <lang> | Set locale (en default, ja available) |

To customize agent behavior, run npx beeops init --with-contexts and edit files in .claude/beeops/contexts/. Delete any file to fall back to the package default.

To verify your installation:

npx beeops check

License

MIT