@moojo/brain-hive

AI agent orchestration framework using the Claude Agent SDK. Coordinate multiple specialized agents through a manager that delegates tasks to the right specialists.

Installation

npm install @moojo/brain-hive

Overview

Instead of working with a single AI assistant, Brain Hive gives you a coordinated team of specialists, each optimized for specific tasks. The team composition is fully configurable—you define the specialists that make sense for your workflow.

How It Works

1. User submits a request via CLI (e.g., "Review the auth module and fix any issues")
2. Manager agent analyzes the request and breaks it into tasks
3. Manager delegates to appropriate specialists
4. Specialists execute their assigned tasks independently
5. Manager synthesizes results and reports back to user

Usage

npx brain-hive                        # Start in read-only mode
npx brain-hive --allow-writes         # Enable file modifications
npx brain-hive --config my-team.json  # Load custom team configuration
npx brain-hive --log-dir ./my-logs    # Custom log directory

CLI Options

| Option | Description | | ------------------ | ------------------------------------------------------------------------------------ | | --config <path> | Path to team configuration JSON file | | --allow-writes | Enable write operations (Edit, Write, Bash). Without this flag, agents are read-only | | --log-dir <path> | Directory for session logs (defaults to ./logs) | | --print, -p | Process a single prompt and exit (non-interactive mode) |

Team Configuration

Brain Hive is a generic orchestration framework—the team members are entirely up to you. Define specialists that match your needs: security auditors, test writers, documentation authors, data analysts, or any other role.

Teams are defined in a JSON file with the following structure:

{
  "members": [
    {
      "name": "code-reviewer",
      "description": "Expert code reviewer who analyzes code for bugs and best practices",
      "systemPrompt": "You are an expert code reviewer...",
      "tools": ["Read", "Glob", "Grep"],
      "model": "haiku"
    },
    {
      "name": "implementer",
      "description": "Senior developer who implements features and fixes",
      "systemPrompt": "You are a senior developer...",
      "tools": ["Read", "Write", "Edit", "Bash", "Glob", "Grep"],
      "model": "sonnet"
    }
  ]
}

Member Properties

| Property | Description | | -------------- | ----------------------------------------------------------------------------------------- | | name | Identifier used for delegation | | description | What the agent specializes in (shown to the manager) | | systemPrompt | Instructions for the agent's behavior | | tools | Available tools: Read, Write, Edit, Bash, Glob, Grep, WebSearch, WebFetch | | model | Claude model: haiku (fast/cheap), sonnet (balanced), opus (powerful), or inherit |

Example Teams

Code Review Team:

{
  "members": [
    { "name": "reviewer", "description": "Code reviewer", "tools": ["Read", "Glob", "Grep"], "model": "haiku" },
    { "name": "implementer", "description": "Developer", "tools": ["Read", "Write", "Edit", "Bash"], "model": "sonnet" }
  ]
}

Security Audit Team:

{
  "members": [
    {
      "name": "security-auditor",
      "description": "Security specialist",
      "tools": ["Read", "Glob", "Grep"],
      "model": "sonnet"
    },
    {
      "name": "researcher",
      "description": "Vulnerability researcher",
      "tools": ["Read", "WebSearch", "WebFetch"],
      "model": "haiku"
    }
  ]
}

Features

• Configurable teams - Define any team structure via JSON
• Safety modes - Read-only by default; opt-in to writes
• Session logging - All interactions logged to JSONL for audit/debugging
• Conversation continuity - Sessions persist for multi-turn workflows
• Visual feedback - Clear CLI output showing which agent is working

Use Cases

• Code reviews across large codebases
• Research + implement workflows (researcher gathers info, implementer acts)
• Complex refactoring where planning, review, and implementation benefit from separation
• Security audits with specialized scanning and remediation agents
• Documentation with research and writing specialists

Programmatic Usage

import { runBrainHive } from '@moojo/brain-hive'

await runBrainHive({
  configPath: './my-team.json',
  logDir: './logs',
  allowWrites: true,
})

License

MIT