# hunainadhi/zeneraneo architecture

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

- Interactive diagram: https://gitdiagram.com/hunainadhi/zeneraneo
- Repository: https://github.com/hunainadhi/zeneraneo
- Video tour (about a minute): https://gitdiagram.com/hunainadhi/zeneraneo/video

## Overview

ZeneraNeo is a toolkit for specifying, generating, running, and improving specialized agent systems. The main user workflow is to configure a project specification, use the meta-agent to generate it, run the agents through the CLI, and inspect trajectories for improvement. The graph also preserves the documented retrieval, memory, sandbox, server, and evaluation capabilities. Some subsystem connections are documented only at the product level; omitted source excerpts limit finer-grained call relationships.

Main entry points: [`packages/engine/src/engine.ts`](https://github.com/hunainadhi/zeneraneo/blob/main/packages/engine/src/engine.ts) (Run orchestration), [`packages/cli/src/main.ts`](https://github.com/hunainadhi/zeneraneo/blob/main/packages/cli/src/main.ts) (Zen CLI), [`packages/neo/src/runner.ts`](https://github.com/hunainadhi/zeneraneo/blob/main/packages/neo/src/runner.ts) (Agent execution), [`packages/meta/src/command.ts`](https://github.com/hunainadhi/zeneraneo/blob/main/packages/meta/src/command.ts) (Meta-agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Project authoring"]
  node_meta["Meta-agent<br/>[command.ts]"]
  node_meta_chat["Meta chat<br/>[session.ts]"]
  node_project["Project configuration<br/>[projects.ts]"]
end

subgraph group_runtime["Agent runtime"]
  node_engine["Run orchestration<br/>[engine.ts]"]
  node_session[("Run sessions<br/>[session.ts]")]
  node_neo["Agent execution<br/>[runner.ts]"]
  node_services["Runtime services<br/>[services.ts]"]
  node_memory[("Agent memory<br/>[index.ts]")]
  node_skills["Skills catalog<br/>[skills.ts]"]
  node_models["Model adapters"]
  node_sandbox["Command sandbox<br/>[bwrap.ts]"]
end

subgraph group_knowledge["Knowledge and evaluation"]
  node_rag["Schema retrieval<br/>[search.ts]"]
  node_gym["Agent evaluation<br/>[server.ts]"]
  node_dataset[("Evaluation datasets<br/>[command.ts]")]
end

subgraph group_operations["CLI and operations"]
  node_cli["Zen CLI<br/>[main.ts]"]
  node_terminal["Interactive terminal<br/>[app.tsx]"]
end

subgraph group_hosting["Serving and viewing"]
  node_server["Agent server<br/>[server.ts]"]
  node_server_state[("Private user state<br/>[userState.ts]")]
  node_viewer["Project viewer<br/>[server.ts]"]
end

node_user(("Project author"))

node_user -->|"runs commands"| node_cli
node_cli -->|"invokes meta"| node_meta
node_user -->|"writes specification"| node_project
node_meta -->|"generates system"| node_project
node_meta -->|"offers chat"| node_meta_chat
node_cli -->|"runs project"| node_engine
node_engine -->|"loads project"| node_project
node_engine -->|"builds run report"| node_neo
node_engine -->|"updates session"| node_session
node_engine -->|"tears down sandbox"| node_sandbox
node_neo -->|"uses services"| node_services
node_services -->|"provides memory"| node_memory
node_services -->|"indexes skills"| node_skills
node_neo -.->|"uses model adapters"| node_models
node_cli -->|"preflights sandbox"| node_sandbox
node_user -->|"queries knowledge"| node_rag
node_rag -->|"uses embeddings"| node_neo
node_user -.->|"evaluates agents"| node_gym
node_dataset -.->|"supplies cases"| node_gym
node_user -->|"starts hosted service"| node_server
node_server -->|"routes user state"| node_server_state
node_user -.->|"opens project view"| node_viewer
node_cli -->|"opens interactive run"| node_terminal

click node_cli "https://github.com/hunainadhi/zeneraneo/blob/main/packages/cli/src/main.ts"
click node_terminal "https://github.com/hunainadhi/zeneraneo/blob/main/packages/cli/src/tui/app.tsx"
click node_meta "https://github.com/hunainadhi/zeneraneo/blob/main/packages/meta/src/command.ts"
click node_meta_chat "https://github.com/hunainadhi/zeneraneo/blob/main/packages/meta/src/chat/session.ts"
click node_project "https://github.com/hunainadhi/zeneraneo/blob/main/packages/engine/src/projects.ts"
click node_engine "https://github.com/hunainadhi/zeneraneo/blob/main/packages/engine/src/engine.ts"
click node_session "https://github.com/hunainadhi/zeneraneo/blob/main/packages/engine/src/session.ts"
click node_neo "https://github.com/hunainadhi/zeneraneo/blob/main/packages/neo/src/runner.ts"
click node_services "https://github.com/hunainadhi/zeneraneo/blob/main/packages/neo/src/services.ts"
click node_memory "https://github.com/hunainadhi/zeneraneo/blob/main/packages/neo/src/memory/index.ts"
click node_skills "https://github.com/hunainadhi/zeneraneo/blob/main/packages/neo/src/skills.ts"
click node_models "https://github.com/hunainadhi/zeneraneo/tree/main/packages/neo/src/models"
click node_sandbox "https://github.com/hunainadhi/zeneraneo/blob/main/packages/sandbox/src/bwrap.ts"
click node_rag "https://github.com/hunainadhi/zeneraneo/blob/main/packages/rag/src/schema/search.ts"
click node_gym "https://github.com/hunainadhi/zeneraneo/blob/main/packages/gym/src/server.ts"
click node_dataset "https://github.com/hunainadhi/zeneraneo/blob/main/packages/meta/src/dataset/command.ts"
click node_server "https://github.com/hunainadhi/zeneraneo/blob/main/packages/server/src/server.ts"
click node_server_state "https://github.com/hunainadhi/zeneraneo/blob/main/packages/server/src/userState.ts"
click node_viewer "https://github.com/hunainadhi/zeneraneo/blob/main/packages/view/src/server.ts"

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_meta,node_meta_chat,node_project toneBlue
class node_engine,node_session,node_neo,node_services,node_memory,node_skills,node_models,node_sandbox toneAmber
class node_rag,node_gym,node_dataset toneMint
class node_cli,node_terminal toneRose
class node_server,node_server_state,node_viewer,node_user toneIndigo
```

## Components

### Project authoring

- [Meta-agent](https://github.com/hunainadhi/zeneraneo/blob/main/packages/meta/src/command.ts): `packages/meta/src/command.ts`
- [Meta chat](https://github.com/hunainadhi/zeneraneo/blob/main/packages/meta/src/chat/session.ts): `packages/meta/src/chat/session.ts`
- [Project configuration](https://github.com/hunainadhi/zeneraneo/blob/main/packages/engine/src/projects.ts): `packages/engine/src/projects.ts`

### Agent runtime

- [Run orchestration](https://github.com/hunainadhi/zeneraneo/blob/main/packages/engine/src/engine.ts): `packages/engine/src/engine.ts`
- [Run sessions](https://github.com/hunainadhi/zeneraneo/blob/main/packages/engine/src/session.ts): `packages/engine/src/session.ts`
- [Agent execution](https://github.com/hunainadhi/zeneraneo/blob/main/packages/neo/src/runner.ts): `packages/neo/src/runner.ts`
- [Runtime services](https://github.com/hunainadhi/zeneraneo/blob/main/packages/neo/src/services.ts): `packages/neo/src/services.ts`
- [Agent memory](https://github.com/hunainadhi/zeneraneo/blob/main/packages/neo/src/memory/index.ts): `packages/neo/src/memory/index.ts`
- [Skills catalog](https://github.com/hunainadhi/zeneraneo/blob/main/packages/neo/src/skills.ts): `packages/neo/src/skills.ts`
- [Model adapters](https://github.com/hunainadhi/zeneraneo/tree/main/packages/neo/src/models): `packages/neo/src/models`
- [Command sandbox](https://github.com/hunainadhi/zeneraneo/blob/main/packages/sandbox/src/bwrap.ts): `packages/sandbox/src/bwrap.ts`

### Knowledge and evaluation

- [Schema retrieval](https://github.com/hunainadhi/zeneraneo/blob/main/packages/rag/src/schema/search.ts): `packages/rag/src/schema/search.ts`
- [Agent evaluation](https://github.com/hunainadhi/zeneraneo/blob/main/packages/gym/src/server.ts): `packages/gym/src/server.ts`
- [Evaluation datasets](https://github.com/hunainadhi/zeneraneo/blob/main/packages/meta/src/dataset/command.ts): `packages/meta/src/dataset/command.ts`

### CLI and operations

- [Zen CLI](https://github.com/hunainadhi/zeneraneo/blob/main/packages/cli/src/main.ts): `packages/cli/src/main.ts`
- [Interactive terminal](https://github.com/hunainadhi/zeneraneo/blob/main/packages/cli/src/tui/app.tsx): `packages/cli/src/tui/app.tsx`

### Serving and viewing

- [Agent server](https://github.com/hunainadhi/zeneraneo/blob/main/packages/server/src/server.ts): `packages/server/src/server.ts`
- [Private user state](https://github.com/hunainadhi/zeneraneo/blob/main/packages/server/src/userState.ts): `packages/server/src/userState.ts`
- [Project viewer](https://github.com/hunainadhi/zeneraneo/blob/main/packages/view/src/server.ts): `packages/view/src/server.ts`

### Other components

- **Project author**

## Connections

- Project author → Zen CLI: runs commands
- Zen CLI → Meta-agent: invokes meta
- Project author → Project configuration: writes specification
- Meta-agent → Project configuration: generates system
- Meta-agent → Meta chat: offers chat (evidence: `packages/meta/src/command.ts`)
- Zen CLI → Run orchestration: runs project
- Run orchestration → Project configuration: loads project (evidence: `packages/engine/src/engine.ts`)
- Run orchestration → Agent execution: builds run report (evidence: `packages/engine/src/engine.ts`)
- Run orchestration → Run sessions: updates session (evidence: `packages/engine/src/engine.ts`)
- Run orchestration → Command sandbox: tears down sandbox (evidence: `packages/engine/src/engine.ts`)
- Agent execution → Runtime services: uses services (evidence: `packages/neo/src/services.ts`)
- Runtime services → Agent memory: provides memory (evidence: `packages/neo/src/services.ts`)
- Runtime services → Skills catalog: indexes skills (evidence: `packages/neo/src/services.ts`)
- Agent execution → Model adapters: uses model adapters
- Zen CLI → Command sandbox: preflights sandbox
- Project author → Schema retrieval: queries knowledge
- Schema retrieval → Agent execution: uses embeddings (evidence: `packages/rag/src/schema/search.ts`)
- Project author → Agent evaluation: evaluates agents
- Evaluation datasets → Agent evaluation: supplies cases
- Project author → Agent server: starts hosted service
- Agent server → Private user state: routes user state (evidence: `packages/server/src/server.ts`)
- Project author → Project viewer: opens project view
- Zen CLI → Interactive terminal: opens interactive run
