# encyc/zen-agent architecture

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

- Interactive diagram: https://gitdiagram.com/encyc/zen-agent
- Repository: https://github.com/encyc/zen-agent

## Overview

ZenAgent is a Python coding-agent kernel driven through terminal, headless, RPC/SDK, and Tauri desktop surfaces. A typical request enters through a surface, reaches the shared runtime and agent loop, then uses a provider and tools; events and transcript views carry results back, while sessions preserve history. The README also documents extensions, MCP, subagents, and Taiji. Several of these capabilities are represented by their existing implementation paths, but their internal wiring was not sampled, so uncertain links are omitted. Our source evidence is limited to the README and indexed excerpts/references.

Main entry points: [`zenagent/agent/loop.py`](https://github.com/encyc/zen-agent/blob/main/zenagent/agent/loop.py) (Agent Loop), [`zenagent/app/runtime.py`](https://github.com/encyc/zen-agent/blob/main/zenagent/app/runtime.py) (Runtime Setup), [`zenagent/cli/rpc/server.py`](https://github.com/encyc/zen-agent/blob/main/zenagent/cli/rpc/server.py) (RPC Server), [`zenagent/agent/session.py`](https://github.com/encyc/zen-agent/blob/main/zenagent/agent/session.py) (Session Files)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_surfaces["User Surfaces"]
  node_cli["CLI &amp; TUI<br/>[main.py]"]
  node_rpc["RPC Server<br/>[server.py]"]
end

subgraph group_runtime["Agent Runtime"]
  node_runtime_core["Runtime Setup<br/>[runtime.py]"]
  node_agent["Agent Loop<br/>[loop.py]"]
  node_events["Event Protocol<br/>[events.py]"]
  node_provider["Provider Adapters"]
  node_provider_catalog["Provider Catalog<br/>[catalog.py]"]
  node_types["Shared Data Types<br/>[types.py]"]
end

subgraph group_capabilities["Tools &amp; Extensions"]
  node_tools["Built-in Tools"]
  node_subagents["Subagents"]
  node_mcp["MCP Servers<br/>[manager.py]"]
  node_extensions["Extensions<br/>[extensions.py]"]
  node_taiji["Taiji Workflows"]
end

subgraph group_state["Sessions &amp; Views"]
  node_session_ops["Session Lifecycle<br/>[sessions.py]"]
  node_session_store[("Session Files<br/>[session.py]")]
  node_views["Transcript Views<br/>[views.py]"]
end

subgraph group_desktop["Desktop Client"]
  node_desktop_app["Desktop App<br/>[App.tsx]"]
  node_rpc_client["RPC Client<br/>[client.ts]"]
end

node_user(("User"))
node_external_models{{"Model APIs"}}

node_user -->|"drives"| node_cli
node_user -->|"uses"| node_desktop_app
node_user -->|"drives"| node_rpc
node_cli -->|"prepares runtime"| node_runtime_core
node_rpc -.->|"serves requests"| node_runtime_core
node_desktop_app -->|"issues requests"| node_rpc_client
node_rpc_client -->|"uses protocol"| node_rpc
node_runtime_core -->|"creates session"| node_agent
node_agent -->|"requests completions"| node_provider
node_agent -->|"resolves provider"| node_provider_catalog
node_provider -.->|"sends requests"| node_external_models
node_agent -->|"emits events"| node_events
node_agent -->|"executes calls"| node_tools
node_agent -.->|"delegates tasks"| node_subagents
node_agent -->|"registers tools"| node_mcp
node_runtime_core -.->|"loads extensions"| node_extensions
node_runtime_core -.->|"sets up workflows"| node_taiji
node_runtime_core -->|"uses session"| node_session_store
node_session_ops -->|"browses and changes"| node_session_store
node_session_store -->|"serializes messages"| node_types
node_views -->|"updates from events"| node_events
node_rpc -->|"serves view data"| node_views

click node_cli "https://github.com/encyc/zen-agent/blob/main/zenagent/cli/main.py"
click node_rpc "https://github.com/encyc/zen-agent/blob/main/zenagent/cli/rpc/server.py"
click node_desktop_app "https://github.com/encyc/zen-agent/blob/main/desktop/src/App.tsx"
click node_rpc_client "https://github.com/encyc/zen-agent/blob/main/desktop/src/rpc/client.ts"
click node_runtime_core "https://github.com/encyc/zen-agent/blob/main/zenagent/app/runtime.py"
click node_agent "https://github.com/encyc/zen-agent/blob/main/zenagent/agent/loop.py"
click node_events "https://github.com/encyc/zen-agent/blob/main/zenagent/events.py"
click node_provider "https://github.com/encyc/zen-agent/blob/main/zenagent/providers/openai_completions.py"
click node_provider_catalog "https://github.com/encyc/zen-agent/blob/main/zenagent/providers/catalog.py"
click node_tools "https://github.com/encyc/zen-agent/tree/main/zenagent/tools"
click node_subagents "https://github.com/encyc/zen-agent/blob/main/zenagent/agent/subagents_runtime.py"
click node_mcp "https://github.com/encyc/zen-agent/blob/main/zenagent/mcp/manager.py"
click node_extensions "https://github.com/encyc/zen-agent/blob/main/zenagent/extensions.py"
click node_taiji "https://github.com/encyc/zen-agent/tree/main/zenagent/app/taiji"
click node_session_ops "https://github.com/encyc/zen-agent/blob/main/zenagent/app/sessions.py"
click node_session_store "https://github.com/encyc/zen-agent/blob/main/zenagent/agent/session.py"
click node_views "https://github.com/encyc/zen-agent/blob/main/zenagent/app/views.py"
click node_types "https://github.com/encyc/zen-agent/blob/main/zenagent/types.py"

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_cli,node_rpc,node_user toneBlue
class node_runtime_core,node_agent,node_events,node_provider,node_provider_catalog,node_types toneAmber
class node_tools,node_subagents,node_mcp,node_extensions,node_taiji,node_external_models toneMint
class node_session_ops,node_session_store,node_views toneRose
class node_desktop_app,node_rpc_client toneIndigo
```

## Components

### User Surfaces

- [CLI & TUI](https://github.com/encyc/zen-agent/blob/main/zenagent/cli/main.py): `zenagent/cli/main.py`
- [RPC Server](https://github.com/encyc/zen-agent/blob/main/zenagent/cli/rpc/server.py): `zenagent/cli/rpc/server.py`

### Agent Runtime

- [Runtime Setup](https://github.com/encyc/zen-agent/blob/main/zenagent/app/runtime.py): `zenagent/app/runtime.py`
- [Agent Loop](https://github.com/encyc/zen-agent/blob/main/zenagent/agent/loop.py): `zenagent/agent/loop.py`
- [Event Protocol](https://github.com/encyc/zen-agent/blob/main/zenagent/events.py): `zenagent/events.py`
- [Provider Adapters](https://github.com/encyc/zen-agent/blob/main/zenagent/providers/openai_completions.py): `zenagent/providers/openai_completions.py`
- [Provider Catalog](https://github.com/encyc/zen-agent/blob/main/zenagent/providers/catalog.py): `zenagent/providers/catalog.py`
- [Shared Data Types](https://github.com/encyc/zen-agent/blob/main/zenagent/types.py): `zenagent/types.py`

### Tools & Extensions

- [Built-in Tools](https://github.com/encyc/zen-agent/tree/main/zenagent/tools): `zenagent/tools`
- [Subagents](https://github.com/encyc/zen-agent/blob/main/zenagent/agent/subagents_runtime.py): `zenagent/agent/subagents_runtime.py`
- [MCP Servers](https://github.com/encyc/zen-agent/blob/main/zenagent/mcp/manager.py): `zenagent/mcp/manager.py`
- [Extensions](https://github.com/encyc/zen-agent/blob/main/zenagent/extensions.py): `zenagent/extensions.py`
- [Taiji Workflows](https://github.com/encyc/zen-agent/tree/main/zenagent/app/taiji): `zenagent/app/taiji`

### Sessions & Views

- [Session Lifecycle](https://github.com/encyc/zen-agent/blob/main/zenagent/app/sessions.py): `zenagent/app/sessions.py`
- [Session Files](https://github.com/encyc/zen-agent/blob/main/zenagent/agent/session.py): `zenagent/agent/session.py`
- [Transcript Views](https://github.com/encyc/zen-agent/blob/main/zenagent/app/views.py): `zenagent/app/views.py`

### Desktop Client

- [Desktop App](https://github.com/encyc/zen-agent/blob/main/desktop/src/App.tsx): `desktop/src/App.tsx`
- [RPC Client](https://github.com/encyc/zen-agent/blob/main/desktop/src/rpc/client.ts): `desktop/src/rpc/client.ts`

### Other components

- **User**
- **Model APIs**

## Connections

- User → CLI & TUI: drives (evidence: `README.md`)
- User → Desktop App: uses (evidence: `README.md`)
- User → RPC Server: drives (evidence: `README.md`)
- CLI & TUI → Runtime Setup: prepares runtime (evidence: `zenagent/cli/main.py`)
- RPC Server → Runtime Setup: serves requests
- Desktop App → RPC Client: issues requests (evidence: `desktop/src/App.tsx`)
- RPC Client → RPC Server: uses protocol (evidence: `README.md`)
- Runtime Setup → Agent Loop: creates session (evidence: `zenagent/app/runtime.py`)
- Agent Loop → Provider Adapters: requests completions (evidence: `zenagent/agent/loop.py`)
- Agent Loop → Provider Catalog: resolves provider (evidence: `zenagent/agent/loop.py`)
- Provider Adapters → Model APIs: sends requests
- Agent Loop → Event Protocol: emits events (evidence: `zenagent/agent/loop.py`)
- Agent Loop → Built-in Tools: executes calls (evidence: `zenagent/agent/loop.py`)
- Agent Loop → Subagents: delegates tasks
- Agent Loop → MCP Servers: registers tools (evidence: `zenagent/mcp/manager.py`)
- Runtime Setup → Extensions: loads extensions (evidence: `zenagent/app/runtime.py`)
- Runtime Setup → Taiji Workflows: sets up workflows (evidence: `zenagent/app/runtime.py`)
- Runtime Setup → Session Files: uses session (evidence: `zenagent/app/runtime.py`)
- Session Lifecycle → Session Files: browses and changes (evidence: `zenagent/app/sessions.py`)
- Session Files → Shared Data Types: serializes messages (evidence: `zenagent/agent/session.py`)
- Transcript Views → Event Protocol: updates from events (evidence: `zenagent/app/views.py`)
- RPC Server → Transcript Views: serves view data (evidence: `zenagent/cli/rpc/server.py`)