How hishamcse/nexus-agentic-os works
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 Gradio Console · graph.py Forge Workflow · registry.py Agent Registry · evolution_agent.py Agent Evolution
Components 23
Agent Forge
- Forge Workflow
graph.py - Request State
state.py - Architect
meta_agents/architect_agent.py - Spec Writer
meta_agents/spec_writer_agent.py - Code Generator
meta_agents/code_gen_agent.py - Validator
meta_agents/validator_agent.py - Validation Sandbox
sandbox.py
Agent Operations
- Deployer
meta_agents/deployer_agent.py - Health Monitor
meta_agents/monitor_agent.py - Generated Agents
generated_agents
Evaluation & Evolution
- Benchmark Arena
arena.py - Agent Evolution
meta_agents/evolution_agent.py - Agent Pipelines
pipeline.py - Analytics
analytics.py
Operator Interface
- Gradio Console
app.py - MCP Registry Server
mcp_server.py
Persistent State
- Agent Registry
registry.py - Agent Memory
memory_store.py - Registry Data
memory/registry.json - Session Memory
memory/sessions - Arena Results
memory/arena_results.json
Other components
- Operator
- Local LLM
Connections 36
- 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