# twowb/znaide architecture

> Architecture diagram of the GitHub repository twowb/znaide, 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/twowb/znaide
- Repository: https://github.com/twowb/znaide

## Overview

znaide is a terminal-based general-purpose AI agent. Users enter a natural-language task interactively or with `-p`; the session sends context and tools to an OpenAI-compatible model, dispatches permitted tool calls, and returns the result. The major runtime branches include file and command safety with undo, search/web/memory tools, MCP, skills, personas, and persistent/resumable sessions. The graph follows documented capabilities and sampled call sites; some UI and integration wiring is not visible in the excerpts, so uncertain links are omitted.

Main entry points: [`crates/core/src/session.rs`](https://github.com/twowb/znaide/blob/main/crates/core/src/session.rs) (Agent Session), [`crates/core/src/tools/mod.rs`](https://github.com/twowb/znaide/blob/main/crates/core/src/tools/mod.rs) (Tool Registry), [`crates/cli/src/main.rs`](https://github.com/twowb/znaide/blob/main/crates/cli/src/main.rs) (CLI Entry), [`crates/tui/src/app.rs`](https://github.com/twowb/znaide/blob/main/crates/tui/src/app.rs) (Terminal UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User Experience"]
  node_cli["CLI Entry<br/>[main.rs]"]
  node_tui["Terminal UI<br/>[app.rs]"]
  node_config_ui["Config Wizard<br/>[config_ui.rs]"]
end

subgraph group_agent["Agent Runtime"]
  node_session["Agent Session<br/>[session.rs]"]
  node_llm["Model Client<br/>[openai.rs]"]
  node_config["Configuration<br/>[config.rs]"]
  node_refs["File References<br/>[refs.rs]"]
end

subgraph group_tools["Tools and Safety"]
  node_permissions["Permission Checks<br/>[permissions.rs]"]
  node_tool_registry["Tool Registry<br/>[mod.rs]"]
  node_file_tools["File Tools<br/>[file.rs]"]
  node_search_tools["Search Tools<br/>[search.rs]"]
  node_shell_tool["Shell Runner<br/>[shell.rs]"]
  node_web_tool["Web Fetch<br/>[web.rs]"]
end

subgraph group_state["Persistent State"]
  node_undo[("Undo Snapshots<br/>[undo.rs]")]
  node_session_store[("Session History<br/>[session.rs]")]
  node_memory_tool["Memory Tools<br/>[memory.rs]"]
  node_memory_store[("Long-term Memory<br/>[memory.rs]")]
end

subgraph group_extensions["Extensions"]
  node_skills["Skills<br/>[skills.rs]"]
  node_personas["Personas<br/>[persona.rs]"]
  node_mcp["MCP Tools<br/>[mcp.rs]"]
  node_updater["Updater<br/>[update.rs]"]
end

node_user(("User"))
node_model_service{{"Model Endpoint"}}
node_mcp_server{{"MCP Server"}}
node_release_sources{{"Update Sources"}}

node_user -->|"starts task"| node_cli
node_cli -->|"loads settings"| node_config
node_cli -->|"starts session"| node_session
node_cli -->|"runs interactive"| node_tui
node_user -->|"enters commands"| node_tui
node_tui -->|"sends commands"| node_session
node_tui -->|"opens setup"| node_config_ui
node_config_ui -->|"queries models"| node_llm
node_config_ui -->|"saves settings"| node_config
node_session -->|"requests completion"| node_llm
node_llm -->|"sends requests"| node_model_service
node_model_service -->|"returns reply"| node_llm
node_session -->|"dispatches tools"| node_tool_registry
node_tool_registry -->|"routes file calls"| node_file_tools
node_tool_registry -->|"routes searches"| node_search_tools
node_tool_registry -->|"routes commands"| node_shell_tool
node_tool_registry -->|"routes web calls"| node_web_tool
node_session -->|"checks actions"| node_permissions
node_session -->|"snapshots before writes"| node_undo
node_session -->|"records and resumes"| node_session_store
node_session -->|"expands references"| node_refs
node_session -->|"loads persona"| node_personas
node_session -->|"loads and runs skills"| node_skills
node_session -->|"dispatches MCP calls"| node_mcp
node_mcp -.->|"invokes tools"| node_mcp_server
node_tool_registry -->|"routes memory calls"| node_memory_tool
node_memory_tool -->|"reads and writes"| node_memory_store
node_cli -->|"checks or updates"| node_updater
node_updater -.->|"fetches releases"| node_release_sources

click node_cli "https://github.com/twowb/znaide/blob/main/crates/cli/src/main.rs"
click node_tui "https://github.com/twowb/znaide/blob/main/crates/tui/src/app.rs"
click node_config_ui "https://github.com/twowb/znaide/blob/main/crates/tui/src/config_ui.rs"
click node_session "https://github.com/twowb/znaide/blob/main/crates/core/src/session.rs"
click node_llm "https://github.com/twowb/znaide/blob/main/crates/core/src/llm/openai.rs"
click node_config "https://github.com/twowb/znaide/blob/main/crates/core/src/config.rs"
click node_permissions "https://github.com/twowb/znaide/blob/main/crates/core/src/permissions.rs"
click node_tool_registry "https://github.com/twowb/znaide/blob/main/crates/core/src/tools/mod.rs"
click node_file_tools "https://github.com/twowb/znaide/blob/main/crates/core/src/tools/file.rs"
click node_search_tools "https://github.com/twowb/znaide/blob/main/crates/core/src/tools/search.rs"
click node_shell_tool "https://github.com/twowb/znaide/blob/main/crates/core/src/tools/shell.rs"
click node_web_tool "https://github.com/twowb/znaide/blob/main/crates/core/src/tools/web.rs"
click node_undo "https://github.com/twowb/znaide/blob/main/crates/core/src/undo.rs"
click node_session_store "https://github.com/twowb/znaide/blob/main/crates/core/src/session.rs"
click node_memory_tool "https://github.com/twowb/znaide/blob/main/crates/core/src/tools/memory.rs"
click node_memory_store "https://github.com/twowb/znaide/blob/main/crates/core/src/tools/memory.rs"
click node_refs "https://github.com/twowb/znaide/blob/main/crates/core/src/refs.rs"
click node_skills "https://github.com/twowb/znaide/blob/main/crates/core/src/skills.rs"
click node_personas "https://github.com/twowb/znaide/blob/main/crates/core/src/persona.rs"
click node_mcp "https://github.com/twowb/znaide/blob/main/crates/core/src/mcp.rs"
click node_updater "https://github.com/twowb/znaide/blob/main/crates/core/src/update.rs"

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_tui,node_config_ui,node_user toneBlue
class node_session,node_llm,node_config,node_refs toneAmber
class node_permissions,node_tool_registry,node_file_tools,node_search_tools,node_shell_tool,node_web_tool,node_mcp_server toneMint
class node_undo,node_session_store,node_memory_tool,node_memory_store toneRose
class node_skills,node_personas,node_mcp,node_updater,node_model_service,node_release_sources toneIndigo
```

## Components

### User Experience

- [CLI Entry](https://github.com/twowb/znaide/blob/main/crates/cli/src/main.rs): `crates/cli/src/main.rs`
- [Terminal UI](https://github.com/twowb/znaide/blob/main/crates/tui/src/app.rs): `crates/tui/src/app.rs`
- [Config Wizard](https://github.com/twowb/znaide/blob/main/crates/tui/src/config_ui.rs): `crates/tui/src/config_ui.rs`

### Agent Runtime

- [Agent Session](https://github.com/twowb/znaide/blob/main/crates/core/src/session.rs): `crates/core/src/session.rs`
- [Model Client](https://github.com/twowb/znaide/blob/main/crates/core/src/llm/openai.rs): `crates/core/src/llm/openai.rs`
- [Configuration](https://github.com/twowb/znaide/blob/main/crates/core/src/config.rs): `crates/core/src/config.rs`
- [File References](https://github.com/twowb/znaide/blob/main/crates/core/src/refs.rs): `crates/core/src/refs.rs`

### Tools and Safety

- [Permission Checks](https://github.com/twowb/znaide/blob/main/crates/core/src/permissions.rs): `crates/core/src/permissions.rs`
- [Tool Registry](https://github.com/twowb/znaide/blob/main/crates/core/src/tools/mod.rs): `crates/core/src/tools/mod.rs`
- [File Tools](https://github.com/twowb/znaide/blob/main/crates/core/src/tools/file.rs): `crates/core/src/tools/file.rs`
- [Search Tools](https://github.com/twowb/znaide/blob/main/crates/core/src/tools/search.rs): `crates/core/src/tools/search.rs`
- [Shell Runner](https://github.com/twowb/znaide/blob/main/crates/core/src/tools/shell.rs): `crates/core/src/tools/shell.rs`
- [Web Fetch](https://github.com/twowb/znaide/blob/main/crates/core/src/tools/web.rs): `crates/core/src/tools/web.rs`

### Persistent State

- [Undo Snapshots](https://github.com/twowb/znaide/blob/main/crates/core/src/undo.rs): `crates/core/src/undo.rs`
- [Session History](https://github.com/twowb/znaide/blob/main/crates/core/src/session.rs): `crates/core/src/session.rs`
- [Memory Tools](https://github.com/twowb/znaide/blob/main/crates/core/src/tools/memory.rs): `crates/core/src/tools/memory.rs`
- [Long-term Memory](https://github.com/twowb/znaide/blob/main/crates/core/src/tools/memory.rs): `crates/core/src/tools/memory.rs`

### Extensions

- [Skills](https://github.com/twowb/znaide/blob/main/crates/core/src/skills.rs): `crates/core/src/skills.rs`
- [Personas](https://github.com/twowb/znaide/blob/main/crates/core/src/persona.rs): `crates/core/src/persona.rs`
- [MCP Tools](https://github.com/twowb/znaide/blob/main/crates/core/src/mcp.rs): `crates/core/src/mcp.rs`
- [Updater](https://github.com/twowb/znaide/blob/main/crates/core/src/update.rs): `crates/core/src/update.rs`

### Other components

- **User**
- **Model Endpoint**
- **MCP Server**
- **Update Sources**

## Connections

- User → CLI Entry: starts task
- CLI Entry → Configuration: loads settings
- CLI Entry → Agent Session: starts session
- CLI Entry → Terminal UI: runs interactive
- User → Terminal UI: enters commands
- Terminal UI → Agent Session: sends commands
- Terminal UI → Config Wizard: opens setup
- Config Wizard → Model Client: queries models
- Config Wizard → Configuration: saves settings
- Agent Session → Model Client: requests completion
- Model Client → Model Endpoint: sends requests
- Model Endpoint → Model Client: returns reply
- Agent Session → Tool Registry: dispatches tools
- Tool Registry → File Tools: routes file calls
- Tool Registry → Search Tools: routes searches
- Tool Registry → Shell Runner: routes commands
- Tool Registry → Web Fetch: routes web calls
- Agent Session → Permission Checks: checks actions
- Agent Session → Undo Snapshots: snapshots before writes
- Agent Session → Session History: records and resumes
- Agent Session → File References: expands references
- Agent Session → Personas: loads persona
- Agent Session → Skills: loads and runs skills
- Agent Session → MCP Tools: dispatches MCP calls
- MCP Tools → MCP Server: invokes tools
- Tool Registry → Memory Tools: routes memory calls
- Memory Tools → Long-term Memory: reads and writes
- CLI Entry → Updater: checks or updates
- Updater → Update Sources: fetches releases