# codeisfire/hive architecture

> Architecture diagram of the GitHub repository codeisfire/hive, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/codeisfire/hive
- Repository: https://github.com/codeisfire/hive

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer Interfaces
    subgraph "Developer Interfaces"
        direction TB
        CodingAgentClients["Coding Agent Clients"]:::interface
        HiveCLI["Hive CLI"]:::interface
        TUIDashboard["TUI Dashboard"]:::interface
    end

    %% Build Phase (Control Plane)
    subgraph "Build Phase"
        direction TB
        AgentBuilder["Agent Builder"]:::coreFramework
        GraphGenerator["Graph Generator"]:::coreFramework
        TestCaseGenerator["Test Case Generator"]:::coreFramework
    end

    %% Execution Plane
    subgraph "Execution Plane"
        direction TB
        Orchestrator["Runner / Orchestrator"]:::coreFramework
        GraphExecutor["Graph Executor"]:::coreFramework
        NodeRuntimes["Node Runtimes"]:::coreFramework
    end

    %% Supporting Services
    subgraph "Supporting Services"
        direction TB
        LLMProvider["LLM Provider Layer"]:::service
        CredentialsStore["Credentials Store"]:::service
        ToolRegistry["Tool Registry"]:::service
        EventBus["Event Bus"]:::service
        subgraph "Storage Layer"
            direction TB
            CheckpointStore["Checkpoint Store"]:::storage
            SessionStore["Session Store"]:::storage
            ConversationStore["Conversation Store"]:::storage
        end
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        LLMAPIs["LLM APIs"]:::external
        BusinessSystems["Business Systems"]:::external
        HumanLoop["Human-in-the-loop Interfaces"]:::external
    end

    %% Flows
    CodingAgentClients -->|"define goal"| HiveCLI
    HiveCLI -->|"buildGraph()"| AgentBuilder
    AgentBuilder -->|"generateGraph()"| GraphGenerator
    GraphGenerator -->|"callLLM()"| LLMProvider
    LLMProvider -->|"graph+code"| GraphGenerator
    GraphGenerator -->|"graphDefinition"| Orchestrator

    Orchestrator -->|"dispatchGraph()"| GraphExecutor
    GraphExecutor -->|"executeNode()"| NodeRuntimes
    NodeRuntimes -->|"lookupTool()"| ToolRegistry
    ToolRegistry -->|"invokeTool()"| BusinessSystems
    NodeRuntimes -->|"callExternalLLM()"| LLMAPIs

    NodeRuntimes -->|"emitEvent()"| EventBus
    EventBus -->|"streamEvents()"| TUIDashboard
    EventBus -->|"logEvents()"| CheckpointStore
    EventBus -->|"logEvents()"| SessionStore
    EventBus -->|"logEvents()"| ConversationStore

    SessionStore -->|"onFailure"| AgentBuilder

    HiveCLI -->|"interactive"| TUIDashboard
    HumanLoop -->|"approve/reject"| Orchestrator

    %% Click Events
    click CodingAgentClients "https://github.com/codeisfire/hive/tree/main/.claude/"
    click CodingAgentClients "https://github.com/codeisfire/hive/tree/main/.cursor/"
    click HiveCLI "https://github.com/codeisfire/hive/blob/main/core/framework/cli.py"
    click HiveCLI "https://github.com/codeisfire/hive/tree/main/Makefile"
    click HiveCLI "https://github.com/codeisfire/hive/blob/main/quickstart.sh"
    click TUIDashboard "https://github.com/codeisfire/hive/tree/main/core/framework/tui/"
    click TUIDashboard "https://github.com/codeisfire/hive/blob/main/core/framework/tui/app.py"
    click TUIDashboard "https://github.com/codeisfire/hive/tree/main/core/framework/tui/widgets/"
    click AgentBuilder "https://github.com/codeisfire/hive/tree/main/core/framework/builder/"
    click AgentBuilder "https://github.com/codeisfire/hive/blob/main/core/framework/builder/query.py"
    click AgentBuilder "https://github.com/codeisfire/hive/blob/main/core/framework/builder/workflow.py"
    click GraphGenerator "https://github.com/codeisfire/hive/tree/main/core/framework/graph/"
    click GraphGenerator "https://github.com/codeisfire/hive/blob/main/core/framework/graph/executor.py"
    click GraphGenerator "https://github.com/codeisfire/hive/blob/main/core/framework/graph/plan.py"
    click GraphGenerator "https://github.com/codeisfire/hive/blob/main/core/framework/graph/node.py"
    click TestCaseGenerator "https://github.com/codeisfire/hive/tree/main/core/framework/testing/"
    click TestCaseGenerator "https://github.com/codeisfire/hive/blob/main/core/framework/testing/test_case.py"
    click TestCaseGenerator "https://github.com/codeisfire/hive/blob/main/core/framework/testing/cli.py"
    click Orchestrator "https://github.com/codeisfire/hive/tree/main/core/framework/runner/"
    click Orchestrator "https://github.com/codeisfire/hive/blob/main/core/framework/runner/orchestrator.py"
    click Orchestrator "https://github.com/codeisfire/hive/blob/main/core/framework/runner/runner.py"
    click GraphExecutor "https://github.com/codeisfire/hive/blob/main/core/framework/graph/executor.py"
    click GraphExecutor "https://github.com/codeisfire/hive/blob/main/core/framework/graph/flexible_executor.py"
    click NodeRuntimes "https://github.com/codeisfire/hive/tree/main/core/framework/runtime/"
    click NodeRuntimes "https://github.com/codeisfire/hive/blob/main/core/framework/runtime/agent_runtime.py"
    click NodeRuntimes "https://github.com/codeisfire/hive/blob/main/core/framework/runtime/stream_runtime.py"
    click NodeRuntimes "https://github.com/codeisfire/hive/blob/main/core/framework/runtime/shared_state.py"
    click LLMProvider "https://github.com/codeisfire/hive/tree/main/core/framework/llm/"
    click LLMProvider "https://github.com/codeisfire/hive/blob/main/core/framework/llm/provider.py"
    click LLMProvider "https://github.com/codeisfire/hive/blob/main/core/framework/llm/anthropic.py"
    click LLMProvider "https://github.com/codeisfire/hive/blob/main/core/framework/llm/litellm.py"
    click CredentialsStore "https://github.com/codeisfire/hive/tree/main/core/framework/credentials/"
    click CredentialsStore "https://github.com/codeisfire/hive/blob/main/core/framework/credentials/store.py"
    click CredentialsStore "https://github.com/codeisfire/hive/blob/main/core/framework/credentials/vault/hashicorp.py"
    click CredentialsStore "https://github.com/codeisfire/hive/blob/main/core/framework/credentials/oauth2/provider.py"
    click ToolRegistry "https://github.com/codeisfire/hive/blob/main/core/framework/runner/tool_registry.py"
    click CheckpointStore "https://github.com/codeisfire/hive/blob/main/core/framework/storage/checkpoint_store.py"
    click SessionStore "https://github.com/codeisfire/hive/blob/main/core/framework/storage/session_store.py"
    click ConversationStore "https://github.com/codeisfire/hive/blob/main/core/framework/storage/conversation_store.py"
    click EventBus "https://github.com/codeisfire/hive/blob/main/core/framework/runtime/event_bus.py"
    click BusinessSystems "https://github.com/codeisfire/hive/tree/main/tools/src/aden_tools/"

    %% Styles
    classDef coreFramework fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef storage fill:#90EE90,stroke:#333,stroke-width:1px
    classDef external fill:#FFA500,stroke:#333,stroke-width:1px
    classDef interface fill:#FFFF66,stroke:#333,stroke-width:1px
    classDef service fill:#D3D3D3,stroke:#333,stroke-width:1px
```
