# zeroxzhang/zerox-agent architecture

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

- Interactive diagram: https://gitdiagram.com/zeroxzhang/zerox-agent
- Repository: https://github.com/zeroxzhang/zerox-agent

## Overview

Zerox Agent is a local-first macOS desktop control plane for permissioned, observable, recoverable agent work. Users start in the desktop interface, send a chat request or pursue a multi-step Goal, and review execution status and evidence. Chat and Goal execution use model providers and controlled tools; Goal work adds contract-based planning, execution, and final acceptance. Local persistence supports sessions, runs, memory, and checkpoints. The README also documents scheduled tasks, multi-agent sessions, and user-reviewed learning and evaluation. Wiring for those unsampled capabilities is shown only at the subsystem level.

Main entry points: [`src/main/main.ts`](https://github.com/zeroxzhang/zerox-agent/blob/main/src/main/main.ts) (Main process), [`src/main/agentRuntimeEngine.ts`](https://github.com/zeroxzhang/zerox-agent/blob/main/src/main/agentRuntimeEngine.ts) (Agent runtime), [`src/main/goalRuntimeEngine.ts`](https://github.com/zeroxzhang/zerox-agent/blob/main/src/main/goalRuntimeEngine.ts) (Goal execution), [`src/main/chatService.ts`](https://github.com/zeroxzhang/zerox-agent/blob/main/src/main/chatService.ts) (Chat service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Desktop interface"]
  node_ui["Desktop UI<br/>[App.tsx]"]
  node_main["Main process<br/>[main.ts]"]
end

subgraph group_execution["Agent execution"]
  node_chat["Chat service<br/>[chatService.ts]"]
  node_runtime["Agent runtime"]
  node_providers["Model providers"]
  node_tools["Tools and permissions"]
  node_kernel["Runtime kernel"]
end

subgraph group_goals["Goal lifecycle"]
  node_goal["Goal execution"]
  node_planning["Goal planning<br/>[plannerKernel.ts]"]
  node_deterministic["Deterministic tasks"]
end

subgraph group_state["Local state"]
  node_storage[("SQLite store<br/>[storageDb.ts]")]
  node_chatrepo["Chat event repository"]
  node_sessions["Session and actor repository"]
end

subgraph group_capabilities["Product capabilities"]
  node_memory["Memory"]
  node_scheduled["Scheduled tasks"]
  node_multiagent["Multi-agent sessions"]
  node_learning["Learning and evals"]
end

node_user(("User"))

node_user -->|"requests work"| node_ui
node_ui -->|"sends requests"| node_main
node_main -->|"dispatches chat"| node_chat
node_chat -->|"runs agent"| node_runtime
node_runtime -->|"requests completion"| node_providers
node_runtime -->|"executes tools"| node_tools
node_main -->|"dispatches Goal"| node_goal
node_goal -->|"plans work"| node_planning
node_goal -->|"runs pipeline"| node_deterministic
node_goal -->|"settles execution"| node_kernel
node_runtime -->|"compacts context"| node_kernel
node_chat -->|"persists events"| node_chatrepo
node_chatrepo -->|"reads and writes"| node_storage
node_sessions -->|"reads and writes"| node_storage
node_main -->|"manages sessions"| node_sessions
node_user -.->|"configures tasks"| node_scheduled
node_user -.->|"starts sessions"| node_multiagent
node_user -.->|"reviews candidates"| node_learning
node_user -.->|"reviews memory"| node_memory

click node_ui "https://github.com/zeroxzhang/zerox-agent/blob/main/src/renderer/App.tsx"
click node_main "https://github.com/zeroxzhang/zerox-agent/blob/main/src/main/main.ts"
click node_chat "https://github.com/zeroxzhang/zerox-agent/blob/main/src/main/chatService.ts"
click node_runtime "https://github.com/zeroxzhang/zerox-agent/blob/main/src/main/agentRuntimeEngine.ts"
click node_providers "https://github.com/zeroxzhang/zerox-agent/tree/main/src/main/providers"
click node_tools "https://github.com/zeroxzhang/zerox-agent/blob/main/src/main/kernel/permissionEngine.ts"
click node_goal "https://github.com/zeroxzhang/zerox-agent/blob/main/src/main/goalRuntimeEngine.ts"
click node_planning "https://github.com/zeroxzhang/zerox-agent/blob/main/src/main/plannerKernel.ts"
click node_deterministic "https://github.com/zeroxzhang/zerox-agent/blob/main/src/main/agentDeterministicGoalPipeline.ts"
click node_kernel "https://github.com/zeroxzhang/zerox-agent/tree/main/src/main/kernel"
click node_storage "https://github.com/zeroxzhang/zerox-agent/blob/main/src/main/storage/storageDb.ts"
click node_chatrepo "https://github.com/zeroxzhang/zerox-agent/blob/main/src/main/storage/repositories/chatSessionEventRepository.ts"
click node_sessions "https://github.com/zeroxzhang/zerox-agent/blob/main/src/main/storage/repositories/sessionRepository.ts"
click node_memory "https://github.com/zeroxzhang/zerox-agent/blob/main/src/main/memoryIngestionService.ts"
click node_scheduled "https://github.com/zeroxzhang/zerox-agent/tree/main/src/main"
click node_multiagent "https://github.com/zeroxzhang/zerox-agent/tree/main/src/main"
click node_learning "https://github.com/zeroxzhang/zerox-agent/tree/main/src/main"

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_ui,node_main,node_user toneBlue
class node_chat,node_runtime,node_providers,node_tools,node_kernel toneAmber
class node_goal,node_planning,node_deterministic toneMint
class node_storage,node_chatrepo,node_sessions toneRose
class node_memory,node_scheduled,node_multiagent,node_learning toneIndigo
```

## Components

### Desktop interface

- [Desktop UI](https://github.com/zeroxzhang/zerox-agent/blob/main/src/renderer/App.tsx): `src/renderer/App.tsx`
- [Main process](https://github.com/zeroxzhang/zerox-agent/blob/main/src/main/main.ts): `src/main/main.ts`

### Agent execution

- [Chat service](https://github.com/zeroxzhang/zerox-agent/blob/main/src/main/chatService.ts): `src/main/chatService.ts`
- [Agent runtime](https://github.com/zeroxzhang/zerox-agent/blob/main/src/main/agentRuntimeEngine.ts): `src/main/agentRuntimeEngine.ts`
- [Model providers](https://github.com/zeroxzhang/zerox-agent/tree/main/src/main/providers): `src/main/providers`
- [Tools and permissions](https://github.com/zeroxzhang/zerox-agent/blob/main/src/main/kernel/permissionEngine.ts): `src/main/kernel/permissionEngine.ts`
- [Runtime kernel](https://github.com/zeroxzhang/zerox-agent/tree/main/src/main/kernel): `src/main/kernel`

### Goal lifecycle

- [Goal execution](https://github.com/zeroxzhang/zerox-agent/blob/main/src/main/goalRuntimeEngine.ts): `src/main/goalRuntimeEngine.ts`
- [Goal planning](https://github.com/zeroxzhang/zerox-agent/blob/main/src/main/plannerKernel.ts): `src/main/plannerKernel.ts`
- [Deterministic tasks](https://github.com/zeroxzhang/zerox-agent/blob/main/src/main/agentDeterministicGoalPipeline.ts): `src/main/agentDeterministicGoalPipeline.ts`

### Local state

- [SQLite store](https://github.com/zeroxzhang/zerox-agent/blob/main/src/main/storage/storageDb.ts): `src/main/storage/storageDb.ts`
- [Chat event repository](https://github.com/zeroxzhang/zerox-agent/blob/main/src/main/storage/repositories/chatSessionEventRepository.ts): `src/main/storage/repositories/chatSessionEventRepository.ts`
- [Session and actor repository](https://github.com/zeroxzhang/zerox-agent/blob/main/src/main/storage/repositories/sessionRepository.ts): `src/main/storage/repositories/sessionRepository.ts`

### Product capabilities

- [Memory](https://github.com/zeroxzhang/zerox-agent/blob/main/src/main/memoryIngestionService.ts): `src/main/memoryIngestionService.ts`
- [Scheduled tasks](https://github.com/zeroxzhang/zerox-agent/tree/main/src/main): `src/main`
- [Multi-agent sessions](https://github.com/zeroxzhang/zerox-agent/tree/main/src/main): `src/main`
- [Learning and evals](https://github.com/zeroxzhang/zerox-agent/tree/main/src/main): `src/main`

### Other components

- **User**

## Connections

- User → Desktop UI: requests work
- Desktop UI → Main process: sends requests
- Main process → Chat service: dispatches chat
- Chat service → Agent runtime: runs agent
- Agent runtime → Model providers: requests completion
- Agent runtime → Tools and permissions: executes tools
- Main process → Goal execution: dispatches Goal
- Goal execution → Goal planning: plans work
- Goal execution → Deterministic tasks: runs pipeline
- Goal execution → Runtime kernel: settles execution
- Agent runtime → Runtime kernel: compacts context
- Chat service → Chat event repository: persists events
- Chat event repository → SQLite store: reads and writes
- Session and actor repository → SQLite store: reads and writes
- Main process → Session and actor repository: manages sessions
- User → Scheduled tasks: configures tasks
- User → Multi-agent sessions: starts sessions
- User → Learning and evals: reviews candidates
- User → Memory: reviews memory