How codeisfire/hive works
Project Type and Purpose
• Hive is a production-grade, Python-based framework for building autonomous, self-improving AI agents.
• It provides a CLI and TUI, a graph-based execution engine, dynamic code generation via coding agents (e.g., Claude, Cursor), built-in tool integrations, human-in-the-loop nodes, observability, and failure-driven adaptation loops.
File Structure Highlights
• Top-level:
• Configuration for AI skills (.claude/, .cursor/)
• Python packaging (pyproject.toml), Node tooling (package.json)
• CLI entrypoints and scripts (Makefile, quickstart.sh, scripts/)
• Documentation (docs/), examples (examples/, core/demos/)
• Core Framework (core/framework/):
• Builder and CLI (builder/, cli.py)
• Credentials subsystem (credentials/)
• Graph executor (graph/)
• LLM provider abstraction (llm/)
• Runner/orchestrator (runner/)
• Runtime engine (runtime/): event bus, stream runtime, shared state
• Storage backends (storage/): checkpoints, sessions, conversation logs
• Testing harness (testing/) and TUI dashboard (tui/)
• Tools Module (tools/src/aden_tools/):
• A collection of standalone tools (file system, email, GitHub, Slack, etc.) packaged as MCP tools
• Tool registry and credentials adapters
• Examples and Templates (examples/templates/): sample agents and node definitions
Main Architectural Components
a. Developer Interfaces
• Coding Agent Clients (Claude, Cursor) – initiate goal conversations
• Hive CLI (hive, claude> /hive, hive run)
• TUI Dashboard – live graph, logs, and REPL
b. Control Plane
• Agent Builder (CLI → builder/query/workflow)
• Graph Generator – produces node graph and connection code via LLM
• Test Case Generator (optional)
c. Execution Plane
• Runner / Orchestrator – dispatches nodes over MCP or in-process
• Graph Executor – walks the node graph, handles edges, parallelism, retries
• Node Runtimes – SDK-wrapped workers with tool access, local and shared memory
d. Supporting Services
• LLM Provider Layer – abstract interface to OpenAI, Anthropic, Gemini, LiteLLM
• Credentials Store – encrypted storage (vault, OAuth2, file)
• Tool Registry – service lookup for external integrations
• Storage Layer – checkpoint store, session store, conversation store, runtime logs
• Event Bus – real-time messaging for streaming observability
e. External Systems
• LLM APIs (OpenAI, Anthropic, local runtimes)
• Business Systems via tools (CRM, file systems, email, Slack, GitHub, databases)
• Human-in-the-loop interfaces (approval CLI, interactive prompts)
Relationships and Data Flows
• Developer → CLI → Coding Agent Client: “Define Goal”
• CLI calls Builder → Graph Generator → uses LLM Provider → returns node graph + code
• Runner/Orchestrator deploys graph to Graph Executor → Node Runtime
• Node Runtime calls Tool Registry → Tools → External Systems
• Runner/Executor emits events to Event Bus → TUI Dashboard & Runtime Logger → Storage
• On failure, Runtime Logger & Storage capture metrics → Coding Agent for adaptation → new graph
• Credentials Store is accessed by both Runner (for external APIs) and Builder (for test credentials)
Architectural Patterns and Principles
• Modular, plugin-based design (graph nodes as pluggable units)
• Separation of concerns: build (graph generation) vs. run (executor) vs. monitor (TUI/event bus)
• Adapter patterns for LLM providers and credentials backends
• Event-driven architecture for observability and failure handling
• Self-evolving loops: capture → evaluate → adapt → redeploy