System Architecture

Zen is a Rust CLI productivity suite with agentic workspace architecture. It follows a binary/library split with 12 workspace crates.

High-Level Architecture

┌─────────────────────────────────────────────┐
│  zen (binary, 13 lines)                     │
│  loads .env, calls zen_cli::shell()         │
└──────────────────┬──────────────────────────┘
                   │
┌──────────────────▼──────────────────────────┐
│  zen-cli (library)                           │
│  clap Parser (29 commands), TUI (ratatui)   │
│  command dispatcher                          │
└──┬────┬────┬────┬────┬────┬────┬────┬───────┘
   │    │    │    │    │    │    │    │
   ▼    ▼    ▼    ▼    ▼    ▼    ▼    ▼
┌────┬────┬────┬────┬────┬────┬────┬──────┐
│zen │zen │zen │zen │zen │zen │zen │zen   │
│core│repo│vault│agents│mem │prov│auth│...  │
└────┴────┴────┴────┴────┴────┴────┴──────┘

Crates Overview

CrateRoleKey Modules
zenBinary entry (13-line main.rs).env loading, dispatches to zen_cli::shell()
zen-cliCLI library29 commands, TUI (ratatui), clap derive dispatch
zen-coreCore infrastructure5-layer config, error taxonomy, path scoping, constants, secrets
zen-serviceBusiness logicStarter/wps/cleanup services
zen-repoData layersqlx + rusqlite dual API, FTS5, vec0, graph schema
zen-vaultKnowledge servicesNote, Wiki, 5-tier search, consolidation, lint, ingest
zen-agentsAgent system13 agents, 4 tiers, blackboard, QualityPipeline, registry
zen-providerLLM routing13 providers, 3 protocol types, DefaultRouter, auth resolution
zen-memoryIdentity contextSOUL.md, MEMORY.md loading and management
zen-authCredential managementKeychain integration, SecretRef resolution
zen-pluginExtension systemWASM sandbox (wasmtime), MCP server
zen-gatewayHTTP daemonAxum-based HTTP server (placeholder)

Key Architectural Patterns

Binary/Library Split

The zen binary (13 lines in crates/zen/src/main.rs) loads .env, calls zen_core::config::load_config(), then delegates to zen_cli::shell().await. All logic lives in library crates.

5-Layer Configuration

Embedded defaults → ~/.zen/config.toml → .zen/config.toml → ZEN_* env vars

Each layer merges into the previous one — higher layers override only the keys they set.

4-Tier Agent Architecture

Orchestrator (L0) → Planner (L1) → Specialist (L2) → Worker (L3)
  • Orchestrator: Session coordination, routing (ZenCoordinator)
  • Planner: Task decomposition, planning (AgentOrchestrator, Prometheus)
  • Specialist: Domain expertise (search, consolidate, research)
  • Worker: Execution, tool calling (AgentExecutor)

5-Tier Search Pipeline

ripgrep → FTS5 → vector embeddings → entity graph → LLM

Each tier adds depth: keyword search first, semantic when needed.

13 Built-In Agents

AgentTierRole
SisyphusL0Lead orchestrator
PrometheusL1Task planner
MetisL1Plan correctness review
MomusL1Plan quality review
ZeusL1Escalation handler
OracleL2Architecture consultation
ExploreL2Codebase exploration
LibrarianL2External reference search
ArgusL2Monitoring & observation
HephaestusL3Tool execution
AtlasL3Knowledge pipeline
JuniorL3General task execution
HermesL3Safety & audit

Data Flow: Note Creation to Wiki

zen note create → zen-vault (NoteService) → Markdown file in inbox/
                                        → zen-repo (sqlx insert)
                                        
zen consolidate → zen-vault (ConsolidationPipeline)
                → zen-provider (entity extraction)
                → zen-repo (graph entities)
                → zen-vault (WikiPage generation)
                
zen search run → zen-vault (SearchService)
               → tier 1: ripgrep
               → tier 2: FTS5 (notes_fts)
               → tier 3: vec0 embeddings
               → tier 4: entity graph
               → tier 5: LLM semantic reranking

Learn more: AGENTS.md for the full project knowledge base.