How i-am-bee/beekeeper works
Project type and purpose
• This is a TypeScript-based, full-stack (CLI + backend) application called Beekeeper.
• Purpose: orchestrate multi-agent AI systems via a central supervisor agent and a conversational (terminal/UI) interface, dynamically allocating and coordinating specialized agents to tackle user-defined objectives.
File structure
Top-level directories and roles:
• src/ui → presentation layer (interactive/autonomous CLI UI, monitors)
• src/runtime → core engine that boots the supervisor, agents, task manager
• src/agents → agent definitions, factories, registry, state management
• src/tasks → task management (breaking down high-level objectives, tracking state)
• src/tools → external tool integrations (e.g., Tavily search client)
• src/workspaces → persistence of agent/task configurations
• src/access-control, src/base, src/helpers, src/utils → cross-cutting concerns (RBAC, DTOs, factories, service locator, misc helpers)
Configuration & orchestration:
• .env.template → environment variables (LLM backend, tools)
• mise.toml → tool-version manager and build orchestrator
• GitHub workflows → CI/CD for build and release
• package.json → dependencies (BeeAI framework, blessed UI, LLM SDKs, etc.)
Key architectural insights from README
• Core components: Supervision (central agent), Agent Registry, Task Management
• Interaction modes: Interactive (real-time CLI UI) vs. Autonomous (one-shot, batch)
• Persistence layer: workspaces under ./outputs/workspaces
• External dependencies: LLM backends (OpenAI/Ollama), search tools (Tavily, DuckDuckGo)
Main components and relationships
1. CLI/UI Layer
• Chat Monitor, Agent Monitor, Task Monitor (src/ui)
2. Runtime Engine
• Entry points (src/index.ts, src/main.ts)
• Runtime factory & orchestrator (src/runtime)
3. Supervisor Agent
• Orchestrates specialized agents; central coordinator
4. Agent Registry
• Repository of available agents, metadata, DTOs, factory (src/agents/registry)
5. Task Manager
• Splits objectives into sub-tasks, tracks state (src/tasks/manager)
6. Workspace Manager
• Persists and restores workspace state (src/workspaces)
7. Access Control
• RBAC for resources and actions (src/access-control)
8. Tools Factory & Integrations
• LLM helper (src/helpers/llm.ts)
• Search client (Tavily, DuckDuckGo)
9. External Services
• LLM API (OpenAI or Ollama)
• Search API (Tavily, DuckDuckGo)
10. Persistent Storage
• Filesystem workspace outputs, .env config
• User → CLI/UI Layer (input commands or prompts)
• CLI/UI Layer → Runtime Engine (RPC or function calls)
• Runtime Engine → Supervisor Agent (initialize & delegate)
• Supervisor Agent ↔ Agent Registry (look up or spin up specialized agents)
• Supervisor Agent → Task Manager (submit high-level goals)
• Task Manager → Supervisor Agent (return sub-tasks)
• Supervisor Agent → Agents (Operator, specialized agents via Agent Factory)
• Agents → Tools Factory → External Services (LLM API, search API)
• Agents/Task Manager → Workspace Manager (save state, logs)
• Workspace Manager ↔ Persistent Storage (read/write workspace files)
• Access Control enforces permissions on calls between components
c. Architectural patterns & principles:
• Factory Pattern – agent and runtime instantiation (src/agents/factory, src/runtime/factory)
• Builder Pattern – state builders for agents/tasks (src/agents/state/builder, src/tasks/state/builder)
• Service Locator – centralized DI for utils, config, services (src/utils/service-locator)
• DTOs – data transfer objects define messaging contracts across modules
• Observer/Logger – state loggers track lifecycle events for debugging/monitoring
d. Key technologies & frameworks:
• Node.js + TypeScript, PNPM for package management
• Mise for tool versioning and build
• neo-blessed terminal UI library (types/neo-blessed)
• OpenAI/Ollama SDKs for LLM calls
• Tavily client for search
• GitHub Actions for CI/CD
Diagramming conventions
• Rectangles for internal modules/components
• Clouds for external services/APIs
• Blue for core orchestration modules (Runtime, Supervisor, Task Manager)
• Green for extension/plugin modules (Agents, Tools, Registry)
• Orange for UI components
• Gray for utilities/cross-cutting concerns