# agentra-labs/agcl architecture

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

- Interactive diagram: https://gitdiagram.com/agentra-labs/agcl
- Repository: https://github.com/agentra-labs/agcl

## Overview

1. **Overall shape**
   AGCL is a single Python package that exposes one core agent engine through multiple front doors: a terminal UI, a headless CLI, and an HTTP/SSE node server. The same runtime is reused across all modes, so the key architectural boundary is between the **engine** and the various **interfaces/adapters**.

2. **Entry points and packaging**
   The main executable path is `main.py`, with the CLI wiring in `agcl/cli.py` and the packaged module mirrored under `src/agcl/`. That suggests the repo supports both editable local development and standard packaging/install flows. `bin/agcl` is the shell entry wrapper.

3. **Core agent runtime**
   The central runtime appears to live across `agcl/bot_runtime.py`, `agcl/runner.py`, `agcl/context.py`, `agcl/state.py`, `agcl/config.py`, `agcl/configurator.py`, `agcl/autoconfig.py`, and `agcl/orchestrator.py`. This layer owns session state, configuration loading, execution flow, and task orchestration, and is what the CLI/TUI/node all call into.

4. **Local-first model pipeline**
   A defining subsystem is the split between `agcl/local_llm.py` and `agcl/cloud.py`. The README describes a local llama.cpp model producing the first tokens quickly, then a cloud model continuing the same open assistant turn. `agcl/pressure.py` and `agcl/usage.py` likely mediate when to stay local, escalate to cloud, and how to meter the resulting provider usage.

5. **Session, persistence, and secrets**
   Persistent runtime concerns are separated into `agcl/secrets.py`, `agcl/state.py`, and pieces of `agcl/recursive/persistence.py` and `agcl/recursive/session.py`. The README’s “idle behavior” implies sessions are flushed to disk and reloaded later, so the architecture includes durable session snapshots rather than purely in-memory chat state.

6. **Interactive surfaces**
   There are three user-facing surfaces:
   - `agcl/tui.py` for the long-running terminal app
   - `agcl/node.py` for the HTTP + SSE node with bearer auth
   - `web_socket/` for the static browser console that connects to a node
   The node is the backend for the browser UI, while the TUI bypasses HTTP entirely and talks directly to the engine.

7. **Dashboard and live observability**
   `agcl/dashboard.py` exposes a lightweight `/node/dashboard` page focused on token usage and quotas. The `web_socket/js/views/` area and `agcl/usage.py` suggest the system publishes runtime diagnostics, cost/accounting, and configuration state as part of the live UI rather than as a separate observability service.

8. **Tooling and external capabilities**
   `agcl/tools.py` and the `agcl/toolkit/` package are the boundary to external systems: LiteLLM, Ollama, vLLM, TGI, OpenAI-compatible APIs, Redis state, S3 storage, Cloudflare, WebRTC, Docker, Kubernetes, GCP, and registry/endpoints helpers. Architecturally, this is the adapter layer that turns infrastructure into callable agent tools or deployment targets.

9. **Integrations and protocol bridges**
   `agcl/integrations/` contains bridges for MCP, FastMCP, Slack Bolt, OpenAgents, OpenAPI export, and manifest generation. These adapters sit on top of the same tool registry and runtime, meaning AGCL can be embedded into other agent ecosystems without changing the core engine.

10. **Plugin boundary**
   `agcl/plugins.py` plus the sample `plugins/` directory provide a drop-in extension mechanism. Plugins can add routes, CLI commands, and tools, which makes the plugin layer a first-class architectural seam rather than a simple hook system.

11. **Recursive multi-agent subsystem**
   The `agcl/recursive/` package is a distinct subsystem for the “recursive cognition” layer described in the README. It includes agent/session/control/build/validate/persistence modules, suggesting an internal MAS pipeline with its own lifecycle, link handling, and training/validation steps. This layer is separate from the main chat runtime and appears to operate on latent representations and teacher-driven updates.

12. **Mini-model subsystem**
   `agcl/mini/` is a separate optional learning path: tokenizer, attention, model, runtime, trainer, strategies, and config. Based on the README, it trains a small local model from captured latents, so it functions as an auxiliary learner beneath the main agent loop rather than as the primary chat model.

13. **Deployment and orchestration outputs**
   `agcl/setup.py`, `agcl/setup_endpoints.py`, `agcl/templates.py`, `agcl/wizards.py`, and the toolkit emit commands support artifact generation for Docker, K8s, GCP Cloud Run, and related environments. The `agcl/orchestrator.py` and `agcl/runner.py` modules indicate the repo can both execute locally and coordinate remote AGCL nodes via playbooks or structured headless runs.

14. **Client and UI ecosystem**
   The `clients/npm/` package is a TypeScript client for the node/toolkit surfaces, while `web_socket/` is the static browser console. Together they form a second API surface around the Python backend, with SSE/HTTP as the integration contract and the node as the central server boundary.

15. **Repository role split**
   The repo is not just an agent app; it is a platform with four major layers: core runtime, extension/integration adapters, deployment/tooling emitters, and multiple operator interfaces. For an architecture diagram, the most important arrows are: **UI/CLI/node → core runtime → local/cloud model + tools → persistent state/usage**, with the recursive MAS and mini-model as sidecar learning systems and the toolkit/integrations as outward-facing adapter rings.

Main entry points: [`agcl/bot_runtime.py`](https://github.com/agentra-labs/agcl/blob/main/agcl/bot_runtime.py) (Runtime), [`agcl/runner.py`](https://github.com/agentra-labs/agcl/blob/main/agcl/runner.py) (Runner), [`agcl/node.py`](https://github.com/agentra-labs/agcl/blob/main/agcl/node.py) (Node), [`agcl/tools.py`](https://github.com/agentra-labs/agcl/blob/main/agcl/tools.py) (Tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Interfaces"]
  node_main["Main<br/>entrypoint<br/>[main.py]"]
  node_cli["CLI<br/>command router<br/>[cli.py]"]
  node_tui["TUI<br/>terminal UI<br/>[tui.py]"]
  node_node["Node<br/>http+sse server<br/>[node.py]"]
  node_web["Web console<br/>browser client<br/>[app.js]"]
  node_npm["NPM client<br/>typescript client<br/>[index.ts]"]
  node_dashboard["Dashboard<br/>usage UI<br/>[dashboard.py]"]
end

subgraph group_core["Core runtime"]
  node_runtime["Runtime<br/>agent engine<br/>[bot_runtime.py]"]
  node_runner["Runner<br/>execution flow<br/>[runner.py]"]
  node_context["Context<br/>[context.py]"]
  node_state[("State<br/>[state.py]")]
  node_config["Config<br/>settings<br/>[config.py]"]
  node_orchestrator["Orchestrator<br/>coordination<br/>[orchestrator.py]"]
end

subgraph group_models["Model pipeline"]
  node_local_llm{{"Local LLM<br/>local model<br/>[local_llm.py]"}}
  node_cloud{{"Cloud<br/>remote model<br/>[cloud.py]"}}
  node_pressure(("Pressure<br/>routing policy<br/>[pressure.py]"))
  node_usage["Usage<br/>accounting<br/>[usage.py]"]
end

subgraph group_extensions["Extensions"]
  node_toolkit["Toolkit<br/>adapter layer<br/>[__init__.py]"]
  node_tools["Tools<br/>tool registry<br/>[tools.py]"]
  node_integrations["Integrations<br/>protocol bridges<br/>[__init__.py]"]
  node_plugins["Plugins<br/>extension hooks<br/>[plugins.py]"]
end

subgraph group_learning["Learning subsystems"]
  node_recursive["Recursive<br/>multi-agent system<br/>[__init__.py]"]
  node_mini["Mini model<br/>aux learner<br/>[__init__.py]"]
end

subgraph group_tooling["Deployment tooling"]
  node_deploy["Deploy<br/>artifact generation<br/>[setup.py]"]
end

node_main -->|"invokes"| node_cli
node_cli -->|"starts"| node_runtime
node_tui -->|"drives"| node_runtime
node_node -->|"serves"| node_runtime
node_web -->|"connects"| node_node
node_npm -->|"calls"| node_node
node_runtime -->|"delegates"| node_runner
node_runner -->|"uses"| node_context
node_runner -->|"persists"| node_state
node_runner -->|"loads"| node_config
node_orchestrator -->|"coordinates"| node_runner
node_runtime -->|"generates"| node_local_llm
node_runtime -->|"continues"| node_cloud
node_pressure -->|"favors"| node_local_llm
node_pressure -->|"escalates"| node_cloud
node_usage -->|"informs"| node_pressure
node_runtime -->|"calls"| node_tools
node_tools -->|"adapts"| node_toolkit
node_tools -->|"bridges"| node_integrations
node_plugins -->|"extends"| node_tools
node_plugins -->|"extends"| node_cli
node_plugins -->|"extends"| node_node
node_recursive -->|"persists"| node_state
node_recursive -->|"feeds"| node_runtime
node_mini -->|"trains on"| node_recursive
node_deploy -->|"emits"| node_toolkit
node_dashboard -->|"renders"| node_node
node_dashboard -->|"shows"| node_usage

click node_main "https://github.com/agentra-labs/agcl/blob/main/main.py"
click node_cli "https://github.com/agentra-labs/agcl/blob/main/agcl/cli.py"
click node_tui "https://github.com/agentra-labs/agcl/blob/main/agcl/tui.py"
click node_node "https://github.com/agentra-labs/agcl/blob/main/agcl/node.py"
click node_web "https://github.com/agentra-labs/agcl/blob/main/web_socket/js/app.js"
click node_npm "https://github.com/agentra-labs/agcl/blob/main/clients/npm/src/index.ts"
click node_runtime "https://github.com/agentra-labs/agcl/blob/main/agcl/bot_runtime.py"
click node_runner "https://github.com/agentra-labs/agcl/blob/main/agcl/runner.py"
click node_context "https://github.com/agentra-labs/agcl/blob/main/agcl/context.py"
click node_state "https://github.com/agentra-labs/agcl/blob/main/agcl/state.py"
click node_config "https://github.com/agentra-labs/agcl/blob/main/agcl/config.py"
click node_orchestrator "https://github.com/agentra-labs/agcl/blob/main/agcl/orchestrator.py"
click node_local_llm "https://github.com/agentra-labs/agcl/blob/main/agcl/local_llm.py"
click node_cloud "https://github.com/agentra-labs/agcl/blob/main/agcl/cloud.py"
click node_pressure "https://github.com/agentra-labs/agcl/blob/main/agcl/pressure.py"
click node_usage "https://github.com/agentra-labs/agcl/blob/main/agcl/usage.py"
click node_toolkit "https://github.com/agentra-labs/agcl/blob/main/agcl/toolkit/__init__.py"
click node_tools "https://github.com/agentra-labs/agcl/blob/main/agcl/tools.py"
click node_integrations "https://github.com/agentra-labs/agcl/blob/main/agcl/integrations/__init__.py"
click node_plugins "https://github.com/agentra-labs/agcl/blob/main/agcl/plugins.py"
click node_recursive "https://github.com/agentra-labs/agcl/blob/main/agcl/recursive/__init__.py"
click node_mini "https://github.com/agentra-labs/agcl/blob/main/agcl/mini/__init__.py"
click node_deploy "https://github.com/agentra-labs/agcl/blob/main/agcl/setup.py"
click node_dashboard "https://github.com/agentra-labs/agcl/blob/main/agcl/dashboard.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_cli,node_tui,node_node,node_web,node_npm,node_dashboard toneBlue
class node_runtime,node_runner,node_context,node_state,node_config,node_orchestrator toneAmber
class node_local_llm,node_cloud,node_pressure,node_usage toneMint
class node_toolkit,node_tools,node_integrations,node_plugins toneRose
class node_recursive,node_mini toneIndigo
class node_deploy toneTeal
```

## Components

### Interfaces

User-facing entry points and clients

- [Main](https://github.com/agentra-labs/agcl/blob/main/main.py): entrypoint · Top-level executable path · `main.py`
- [CLI](https://github.com/agentra-labs/agcl/blob/main/agcl/cli.py): command router · Headless command-line interface · `agcl/cli.py`
- [TUI](https://github.com/agentra-labs/agcl/blob/main/agcl/tui.py): terminal UI · Long-running interactive terminal app · `agcl/tui.py`
- [Node](https://github.com/agentra-labs/agcl/blob/main/agcl/node.py): http+sse server · Bearer-auth backend for browser clients · `agcl/node.py`
- [Web console](https://github.com/agentra-labs/agcl/blob/main/web_socket/js/app.js): browser client · Static browser UI for a node · `web_socket/js/app.js`
- [NPM client](https://github.com/agentra-labs/agcl/blob/main/clients/npm/src/index.ts): typescript client · Typed client for node and toolkit surfaces · `clients/npm/src/index.ts`
- [Dashboard](https://github.com/agentra-labs/agcl/blob/main/agcl/dashboard.py): usage UI · Lightweight runtime and quota dashboard · `agcl/dashboard.py`

### Core runtime

Main agent engine, state, and control flow

- [Runtime](https://github.com/agentra-labs/agcl/blob/main/agcl/bot_runtime.py): agent engine · Core execution engine reused by all front doors · `agcl/bot_runtime.py`
- [Runner](https://github.com/agentra-labs/agcl/blob/main/agcl/runner.py): execution flow · Coordinates runs and task execution · `agcl/runner.py`
- [Context](https://github.com/agentra-labs/agcl/blob/main/agcl/context.py): session context · Conversation and working context · `agcl/context.py`
- [State](https://github.com/agentra-labs/agcl/blob/main/agcl/state.py): persistence state · Durable runtime state and snapshots · `agcl/state.py`
- [Config](https://github.com/agentra-labs/agcl/blob/main/agcl/config.py): settings · Configuration loading and normalized settings · `agcl/config.py`
- [Orchestrator](https://github.com/agentra-labs/agcl/blob/main/agcl/orchestrator.py): coordination · Higher-level task and session coordination · `agcl/orchestrator.py`

### Model pipeline

Local/cloud generation and routing

- [Local LLM](https://github.com/agentra-labs/agcl/blob/main/agcl/local_llm.py): local model · Fast local first-token generation path · `agcl/local_llm.py`
- [Cloud](https://github.com/agentra-labs/agcl/blob/main/agcl/cloud.py): remote model · Cloud continuation and provider-backed generation · `agcl/cloud.py`
- [Pressure](https://github.com/agentra-labs/agcl/blob/main/agcl/pressure.py): routing policy · Decides when to stay local or escalate · `agcl/pressure.py`
- [Usage](https://github.com/agentra-labs/agcl/blob/main/agcl/usage.py): accounting · Token, quota, and cost accounting · `agcl/usage.py`

### Extensions

Plugins, integrations, and external adapters

- [Toolkit](https://github.com/agentra-labs/agcl/blob/main/agcl/toolkit/__init__.py): adapter layer · External capability and deployment adapters · `agcl/toolkit/__init__.py`
- [Tools](https://github.com/agentra-labs/agcl/blob/main/agcl/tools.py): tool registry · Tool boundary exposed to the agent runtime · `agcl/tools.py`
- [Integrations](https://github.com/agentra-labs/agcl/blob/main/agcl/integrations/__init__.py): protocol bridges · MCP, Slack, OpenAPI, and manifest bridges · `agcl/integrations/__init__.py`
- [Plugins](https://github.com/agentra-labs/agcl/blob/main/agcl/plugins.py): extension hooks · Drop-in extension mechanism for routes, commands, and tools · `agcl/plugins.py`

### Learning subsystems

Recursive cognition and mini-model training paths

- [Recursive](https://github.com/agentra-labs/agcl/blob/main/agcl/recursive/__init__.py): multi-agent system · Recursive cognition and session subsystem · `agcl/recursive/__init__.py`
- [Mini model](https://github.com/agentra-labs/agcl/blob/main/agcl/mini/__init__.py): aux learner · Small local model training and runtime path · `agcl/mini/__init__.py`

### Deployment tooling

Commands and artifact generation for deployment

- [Deploy](https://github.com/agentra-labs/agcl/blob/main/agcl/setup.py): artifact generation · Wizards and endpoint/setup emitters · `agcl/setup.py`

## Connections

- Main → CLI: invokes · Executable entry dispatches into CLI wiring
- CLI → Runtime: starts · CLI commands reuse the core engine
- TUI → Runtime: drives · Interactive terminal talks directly to runtime
- Node → Runtime: serves · HTTP/SSE node fronts the engine
- Web console → Node: connects · Browser console connects to a node backend
- NPM client → Node: calls · TypeScript client speaks to node endpoints
- Runtime → Runner: delegates · Engine hands off execution flow to runner
- Runner → Context: uses · Runner reads and updates conversational context
- Runner → State: persists · Execution updates durable session state
- Runner → Config: loads · Runtime is parameterized by configuration
- Orchestrator → Runner: coordinates · Higher-level orchestration wraps execution flow
- Runtime → Local LLM: generates · Core engine can request local token generation
- Runtime → Cloud: continues · Engine can hand off turn continuation to cloud models
- Pressure → Local LLM: favors · Policy keeps traffic local when appropriate
- Pressure → Cloud: escalates · Policy escalates to cloud when needed
- Usage → Pressure: informs · Accounting informs routing and escalation decisions
- Runtime → Tools: calls · Agent actions flow through the tool boundary
- Tools → Toolkit: adapts · Tool boundary is backed by provider and infra adapters
- Tools → Integrations: bridges · Tool registry is exposed to external protocols
- Plugins → Tools: extends · Plugins can contribute tools
- Plugins → CLI: extends · Plugins can add CLI commands
- Plugins → Node: extends · Plugins can add routes or node behavior
- Recursive → State: persists · Recursive subsystem stores session and control state
- Recursive → Runtime: feeds · Sidecar MAS layer interacts with the main engine
- Mini model → Recursive: trains on · Mini model learns from recursive latents and traces
- Deploy → Toolkit: emits · Setup and endpoint helpers generate deployable artifacts
- Dashboard → Node: renders · Dashboard is served from the node surface
- Dashboard → Usage: shows · Dashboard visualizes runtime accounting and quotas
