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 (23 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 library23 commands, TUI (ratatui), clap derive dispatch
zen-coreCore infrastructure4-layer global-only 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, plan-DAG executor, QualityPipeline, registry, scheduler workers
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 client/server, agent tools
zen-gatewaySole-owner daemonUDS JSON-RPC 2.0, hosted agent sessions, loopback HTTP carrier, MCP stdio, QQ bot channel

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.

4-Layer Configuration (global-only)

Rust built-in defaults → embedded config.toml → ~/.zen/config.toml → ZEN_* env vars

Each layer merges into the previous one — higher layers override only the keys they set. Configuration is global-only: the .zen/ directory marks project context but is not a config layer.

4-Tier Agent Architecture

Orchestrator (L0) → Planner (L1) → Specialist (L2) → Worker (L3)
  • Orchestrator: Session coordination, intent routing (AgentOrchestrator, Sisyphus)
  • Planner: Task decomposition, plan-DAG execution (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

note dropped into vault/inbox/ → ZenScheduler (zen_loop worker, every 5 min)
    → zen-vault (DistillationPipeline: extract → normalize → compile → merge → archive)
    → zen-vault ingest (pdf/office/sidecar formats convert to Markdown at intake)
    → zen-provider (entity extraction)
    → zen-repo (graph entities + FTS5 + embeddings)
    → zen-vault (WikiPage generation, AtomicWikiWriter)

search (TUI chat / agent tools) → zen-vault (SearchService)
    → tier 1: ripgrep
    → tier 2: FTS5 (notes_fts)
    → tier 3: vec0 embeddings
    → tier 4: entity graph (+ PPR seeded ranking)
    → tier 5: LLM semantic reranking

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