How zeroxzhang/zerox-agent works
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: main.ts Main process · agentRuntimeEngine.ts Agent runtime · goalRuntimeEngine.ts Goal execution · chatService.ts Chat service
Components 18
Desktop interface
- Desktop UI
src/renderer/App.tsx - Main process
src/main/main.ts
Agent execution
- Chat service
src/main/chatService.ts - Agent runtime
src/main/agentRuntimeEngine.ts - Model providers
src/main/providers - Tools and permissions
src/main/kernel/permissionEngine.ts - Runtime kernel
src/main/kernel
Goal lifecycle
- Goal execution
src/main/goalRuntimeEngine.ts - Goal planning
src/main/plannerKernel.ts - Deterministic tasks
src/main/agentDeterministicGoalPipeline.ts
Local state
- SQLite store
src/main/storage/storageDb.ts - Chat event repository
src/main/storage/repositories/chatSessionEventRepository.ts - Session and actor repository
src/main/storage/repositories/sessionRepository.ts
Product capabilities
- Memory
src/main/memoryIngestionService.ts - Scheduled tasks
src/main - Multi-agent sessions
src/main - Learning and evals
src/main
Other components
- User
Connections 19
- 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