# hishamcse/nexus-agentic-os architecture

> Architecture diagram of the GitHub repository hishamcse/nexus-agentic-os, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hishamcse/nexus-agentic-os
- Repository: https://github.com/hishamcse/nexus-agentic-os
- Video tour (about a minute): https://gitdiagram.com/hishamcse/nexus-agentic-os/video

## Overview

Nexus is a local-first agent operating system: an operator submits a request, the forge designs and generates an agent, validates it with retry routing, then deploys and monitors it. Operators can also run agents, inspect source and memory, benchmark and evolve agents, and chain them in persistent pipelines. The README documents these product branches; some runtime wiring is inferred only from that documentation because the corresponding source was not sampled.

Main entry points: [`app.py`](https://github.com/hishamcse/nexus-agentic-os/blob/main/app.py) (Gradio Console), [`graph.py`](https://github.com/hishamcse/nexus-agentic-os/blob/main/graph.py) (Forge Workflow), [`registry.py`](https://github.com/hishamcse/nexus-agentic-os/blob/main/registry.py) (Agent Registry), [`meta_agents/evolution_agent.py`](https://github.com/hishamcse/nexus-agentic-os/blob/main/meta_agents/evolution_agent.py) (Agent Evolution)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_forge["Agent Forge"]
  node_graph["Forge Workflow<br/>[graph.py]"]
  node_state_model["Request State<br/>[state.py]"]
  node_architect["Architect<br/>[architect_agent.py]"]
  node_spec_writer["Spec Writer"]
  node_codegen["Code Generator<br/>[code_gen_agent.py]"]
  node_validator["Validator<br/>[validator_agent.py]"]
  node_sandbox["Validation Sandbox<br/>[sandbox.py]"]
end

subgraph group_runtime["Agent Operations"]
  node_deployer["Deployer<br/>[deployer_agent.py]"]
  node_monitor["Health Monitor<br/>[monitor_agent.py]"]
  node_worker["Generated Agents"]
end

subgraph group_insights["Evaluation &amp; Evolution"]
  node_arena["Benchmark Arena<br/>[arena.py]"]
  node_evolution["Agent Evolution<br/>[evolution_agent.py]"]
  node_pipeline["Agent Pipelines<br/>[pipeline.py]"]
  node_analytics["Analytics<br/>[analytics.py]"]
end

subgraph group_interface["Operator Interface"]
  node_app["Gradio Console<br/>[app.py]"]
  node_mcp["MCP Registry Server<br/>[mcp_server.py]"]
end

subgraph group_state["Persistent State"]
  node_registry[("Agent Registry<br/>[registry.py]")]
  node_memory_store[("Agent Memory<br/>[memory_store.py]")]
  node_registry_data[("Registry Data<br/>[registry.json]")]
  node_memory_data[("Session Memory")]
  node_arena_data[("Arena Results<br/>[arena_results.json]")]
end

node_operator(("Operator"))
node_llm["Local LLM"]

node_operator -->|"submits requests"| node_app
node_app -->|"starts forge"| node_graph
node_graph -->|"updates state"| node_state_model
node_graph -->|"requests design"| node_architect
node_architect -->|"prompts model"| node_llm
node_graph -->|"requests spec"| node_spec_writer
node_spec_writer -->|"prompts model"| node_llm
node_graph -->|"requests code"| node_codegen
node_codegen -->|"prompts model"| node_llm
node_graph -->|"validates agent"| node_validator
node_validator -->|"runs checks"| node_sandbox
node_graph -.->|"retries generation"| node_codegen
node_graph -->|"deploys validated agent"| node_deployer
node_deployer -->|"registers agent"| node_registry
node_deployer -->|"starts subprocess"| node_worker
node_monitor -->|"checks health"| node_registry
node_monitor -->|"restarts failures"| node_worker
node_app -->|"reads agent status"| node_registry
node_app -->|"runs agent tasks"| node_worker
node_app -->|"accesses memory"| node_memory_store
node_memory_store -->|"persists sessions"| node_memory_data
node_app -->|"starts benchmarks"| node_arena
node_arena -->|"loads agents"| node_registry
node_arena -->|"records results"| node_arena_data
node_app -->|"requests evolution"| node_evolution
node_evolution -->|"reads task history"| node_memory_store
node_evolution -->|"compares versions"| node_arena
node_app -->|"runs agent chain"| node_pipeline
node_pipeline -->|"loads agents"| node_registry
node_pipeline -->|"dispatches stages"| node_worker
node_pipeline -->|"records pipeline runs"| node_memory_data
node_app -->|"views metrics"| node_analytics
node_analytics -->|"reads registry"| node_registry
node_mcp -->|"serves registry operations"| node_registry
node_registry -->|"persists records"| node_registry_data
node_evolution -->|"prompts model"| node_llm

click node_app "https://github.com/hishamcse/nexus-agentic-os/blob/main/app.py"
click node_graph "https://github.com/hishamcse/nexus-agentic-os/blob/main/graph.py"
click node_state_model "https://github.com/hishamcse/nexus-agentic-os/blob/main/state.py"
click node_architect "https://github.com/hishamcse/nexus-agentic-os/blob/main/meta_agents/architect_agent.py"
click node_spec_writer "https://github.com/hishamcse/nexus-agentic-os/blob/main/meta_agents/spec_writer_agent.py"
click node_codegen "https://github.com/hishamcse/nexus-agentic-os/blob/main/meta_agents/code_gen_agent.py"
click node_validator "https://github.com/hishamcse/nexus-agentic-os/blob/main/meta_agents/validator_agent.py"
click node_sandbox "https://github.com/hishamcse/nexus-agentic-os/blob/main/sandbox.py"
click node_deployer "https://github.com/hishamcse/nexus-agentic-os/blob/main/meta_agents/deployer_agent.py"
click node_monitor "https://github.com/hishamcse/nexus-agentic-os/blob/main/meta_agents/monitor_agent.py"
click node_registry "https://github.com/hishamcse/nexus-agentic-os/blob/main/registry.py"
click node_worker "https://github.com/hishamcse/nexus-agentic-os/tree/main/generated_agents"
click node_memory_store "https://github.com/hishamcse/nexus-agentic-os/blob/main/memory_store.py"
click node_arena "https://github.com/hishamcse/nexus-agentic-os/blob/main/arena.py"
click node_evolution "https://github.com/hishamcse/nexus-agentic-os/blob/main/meta_agents/evolution_agent.py"
click node_pipeline "https://github.com/hishamcse/nexus-agentic-os/blob/main/pipeline.py"
click node_analytics "https://github.com/hishamcse/nexus-agentic-os/blob/main/analytics.py"
click node_mcp "https://github.com/hishamcse/nexus-agentic-os/blob/main/mcp_server.py"
click node_registry_data "https://github.com/hishamcse/nexus-agentic-os/blob/main/memory/registry.json"
click node_memory_data "https://github.com/hishamcse/nexus-agentic-os/tree/main/memory/sessions"
click node_arena_data "https://github.com/hishamcse/nexus-agentic-os/blob/main/memory/arena_results.json"

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_graph,node_state_model,node_architect,node_spec_writer,node_codegen,node_validator,node_sandbox toneBlue
class node_deployer,node_monitor,node_worker toneAmber
class node_arena,node_evolution,node_pipeline,node_analytics toneMint
class node_app,node_mcp toneRose
class node_registry,node_memory_store,node_registry_data,node_memory_data,node_arena_data,node_operator,node_llm toneIndigo
```

## Components

### Agent Forge

- [Forge Workflow](https://github.com/hishamcse/nexus-agentic-os/blob/main/graph.py): `graph.py`
- [Request State](https://github.com/hishamcse/nexus-agentic-os/blob/main/state.py): `state.py`
- [Architect](https://github.com/hishamcse/nexus-agentic-os/blob/main/meta_agents/architect_agent.py): `meta_agents/architect_agent.py`
- [Spec Writer](https://github.com/hishamcse/nexus-agentic-os/blob/main/meta_agents/spec_writer_agent.py): `meta_agents/spec_writer_agent.py`
- [Code Generator](https://github.com/hishamcse/nexus-agentic-os/blob/main/meta_agents/code_gen_agent.py): `meta_agents/code_gen_agent.py`
- [Validator](https://github.com/hishamcse/nexus-agentic-os/blob/main/meta_agents/validator_agent.py): `meta_agents/validator_agent.py`
- [Validation Sandbox](https://github.com/hishamcse/nexus-agentic-os/blob/main/sandbox.py): `sandbox.py`

### Agent Operations

- [Deployer](https://github.com/hishamcse/nexus-agentic-os/blob/main/meta_agents/deployer_agent.py): `meta_agents/deployer_agent.py`
- [Health Monitor](https://github.com/hishamcse/nexus-agentic-os/blob/main/meta_agents/monitor_agent.py): `meta_agents/monitor_agent.py`
- [Generated Agents](https://github.com/hishamcse/nexus-agentic-os/tree/main/generated_agents): `generated_agents`

### Evaluation & Evolution

- [Benchmark Arena](https://github.com/hishamcse/nexus-agentic-os/blob/main/arena.py): `arena.py`
- [Agent Evolution](https://github.com/hishamcse/nexus-agentic-os/blob/main/meta_agents/evolution_agent.py): `meta_agents/evolution_agent.py`
- [Agent Pipelines](https://github.com/hishamcse/nexus-agentic-os/blob/main/pipeline.py): `pipeline.py`
- [Analytics](https://github.com/hishamcse/nexus-agentic-os/blob/main/analytics.py): `analytics.py`

### Operator Interface

- [Gradio Console](https://github.com/hishamcse/nexus-agentic-os/blob/main/app.py): `app.py`
- [MCP Registry Server](https://github.com/hishamcse/nexus-agentic-os/blob/main/mcp_server.py): `mcp_server.py`

### Persistent State

- [Agent Registry](https://github.com/hishamcse/nexus-agentic-os/blob/main/registry.py): `registry.py`
- [Agent Memory](https://github.com/hishamcse/nexus-agentic-os/blob/main/memory_store.py): `memory_store.py`
- [Registry Data](https://github.com/hishamcse/nexus-agentic-os/blob/main/memory/registry.json): `memory/registry.json`
- [Session Memory](https://github.com/hishamcse/nexus-agentic-os/tree/main/memory/sessions): `memory/sessions`
- [Arena Results](https://github.com/hishamcse/nexus-agentic-os/blob/main/memory/arena_results.json): `memory/arena_results.json`

### Other components

- **Operator**
- **Local LLM**

## Connections

- Operator → Gradio Console: submits requests
- Gradio Console → Forge Workflow: starts forge
- Forge Workflow → Request State: updates state
- Forge Workflow → Architect: requests design
- Architect → Local LLM: prompts model
- Forge Workflow → Spec Writer: requests spec
- Spec Writer → Local LLM: prompts model
- Forge Workflow → Code Generator: requests code
- Code Generator → Local LLM: prompts model
- Forge Workflow → Validator: validates agent
- Validator → Validation Sandbox: runs checks
- Forge Workflow → Code Generator: retries generation
- Forge Workflow → Deployer: deploys validated agent
- Deployer → Agent Registry: registers agent
- Deployer → Generated Agents: starts subprocess
- Health Monitor → Agent Registry: checks health
- Health Monitor → Generated Agents: restarts failures
- Gradio Console → Agent Registry: reads agent status
- Gradio Console → Generated Agents: runs agent tasks
- Gradio Console → Agent Memory: accesses memory
- Agent Memory → Session Memory: persists sessions
- Gradio Console → Benchmark Arena: starts benchmarks
- Benchmark Arena → Agent Registry: loads agents
- Benchmark Arena → Arena Results: records results
- Gradio Console → Agent Evolution: requests evolution
- Agent Evolution → Agent Memory: reads task history
- Agent Evolution → Benchmark Arena: compares versions
- Gradio Console → Agent Pipelines: runs agent chain
- Agent Pipelines → Agent Registry: loads agents
- Agent Pipelines → Generated Agents: dispatches stages
- Agent Pipelines → Session Memory: records pipeline runs
- Gradio Console → Analytics: views metrics
- Analytics → Agent Registry: reads registry
- MCP Registry Server → Agent Registry: serves registry operations
- Agent Registry → Registry Data: persists records
- Agent Evolution → Local LLM: prompts model