# zvnoob/agent architecture

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

## Overview

Agent is a terminal coding assistant whose main workflow is: the user submits a turn, the configured Lua registry advertises tools to a streaming chat client, and the runtime dispatches requested tools before returning their results to the model. Shell execution passes through a seccomp supervisor and Lua permission policy; tools can report through Lua-drawn TUI panels. The README also documents filesystem tools, MCP connections, conversation memory, reloadable configuration, and syntax-highlighted streaming UI. Runtime wiring is grounded in the README and sampled entry points; unsampled subsystem links are included only where documented.

Main entry points: [`src/main.rs`](https://github.com/zvnoob/agent/blob/main/src/main.rs) (Turn loop), [`lua/mcps.lua`](https://github.com/zvnoob/agent/blob/main/lua/mcps.lua) (Tool registry), [`src/lua.rs`](https://github.com/zvnoob/agent/blob/main/src/lua.rs) (Lua bridge), [`lua/bash_tool.lua`](https://github.com/zvnoob/agent/blob/main/lua/bash_tool.lua) (Shell tool)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_conversation["Conversation runtime"]
  node_main["Turn loop<br/>[main.rs]"]
  node_chat["Chat client<br/>[api.rs]"]
  node_memory[("Conversation memory<br/>[memory.rs]")]
end

subgraph group_lua["Lua configuration"]
  node_config["Starter config<br/>[init.lua]"]
  node_bridge["Lua bridge<br/>[lua.rs]"]
end

subgraph group_tools["Tools and policy"]
  node_registry["Tool registry<br/>[mcps.lua]"]
  node_filesystem["Filesystem tools<br/>[fs.lua]"]
  node_shelltool["Shell tool<br/>[bash_tool.lua]"]
  node_bashlib["Bash support<br/>[bash.lua]"]
  node_policy["Permission policy<br/>[policy.lua]"]
  node_ask["Ask protocol<br/>[ask.lua]"]
  node_mcptransport["MCP transports<br/>[mcp.rs]"]
end

subgraph group_sandbox["Sandbox runtime"]
  node_supervisor["Sandbox supervisor<br/>[mod.rs]"]
  node_asyncsandbox["Async sandbox adapter<br/>[async_sandbox.rs]"]
  node_syscalls["Syscall tables<br/>[mod.rs]"]
end

subgraph group_ui["Terminal interface"]
  node_tui["TUI shell<br/>[mod.rs]"]
  node_turnpanel["Turn panel<br/>[panel.rs]"]
  node_highlight["Markdown highlighting<br/>[highlight.rs]"]
  node_panels["Panel operations<br/>[panels.rs]"]
end

node_user(("User"))
node_endpoint["Chat endpoint"]
node_mcpservers["MCP servers"]

node_user -->|"submits turn"| node_tui
node_tui -->|"submits input"| node_main
node_main -->|"loads configuration"| node_config
node_config -->|"configures agent"| node_bridge
node_main -->|"requests stream"| node_chat
node_chat -->|"sends chat request"| node_endpoint
node_endpoint -->|"streams events"| node_chat
node_main -->|"dispatches tool call"| node_registry
node_registry -->|"registers tools"| node_filesystem
node_registry -->|"registers tools"| node_shelltool
node_shelltool -->|"uses shell support"| node_bashlib
node_shelltool -->|"runs command"| node_asyncsandbox
node_asyncsandbox -->|"drives sandbox"| node_supervisor
node_supervisor -->|"resolves syscalls"| node_syscalls
node_policy -->|"requests decision"| node_ask
node_bridge -->|"mediates policy asks"| node_supervisor
node_ask -->|"draws permission prompt"| node_panels
node_panels -->|"applies panel ops"| node_turnpanel
node_main -->|"collects panel ops"| node_panels
node_tui -->|"renders conversation"| node_turnpanel
node_turnpanel -->|"highlights messages"| node_highlight
node_main -->|"archives turns"| node_memory
node_bridge -->|"reads and writes"| node_memory
node_registry -.->|"uses transports"| node_mcptransport
node_mcptransport -.->|"connects to servers"| node_mcpservers

click node_tui "https://github.com/zvnoob/agent/blob/main/src/tui/mod.rs"
click node_turnpanel "https://github.com/zvnoob/agent/blob/main/src/tui/panel.rs"
click node_highlight "https://github.com/zvnoob/agent/blob/main/src/tui/highlight.rs"
click node_main "https://github.com/zvnoob/agent/blob/main/src/main.rs"
click node_chat "https://github.com/zvnoob/agent/blob/main/src/api.rs"
click node_memory "https://github.com/zvnoob/agent/blob/main/src/memory.rs"
click node_config "https://github.com/zvnoob/agent/blob/main/lua/init.lua"
click node_bridge "https://github.com/zvnoob/agent/blob/main/src/lua.rs"
click node_registry "https://github.com/zvnoob/agent/blob/main/lua/mcps.lua"
click node_filesystem "https://github.com/zvnoob/agent/blob/main/lua/fs.lua"
click node_shelltool "https://github.com/zvnoob/agent/blob/main/lua/bash_tool.lua"
click node_bashlib "https://github.com/zvnoob/agent/blob/main/lua/lib/bash.lua"
click node_policy "https://github.com/zvnoob/agent/blob/main/lua/policy.lua"
click node_ask "https://github.com/zvnoob/agent/blob/main/lua/lib/ask.lua"
click node_supervisor "https://github.com/zvnoob/agent/blob/main/src/seccomp/mod.rs"
click node_asyncsandbox "https://github.com/zvnoob/agent/blob/main/src/async_sandbox.rs"
click node_syscalls "https://github.com/zvnoob/agent/blob/main/src/seccomp/arch/mod.rs"
click node_mcptransport "https://github.com/zvnoob/agent/blob/main/src/mcp.rs"
click node_panels "https://github.com/zvnoob/agent/blob/main/src/panels.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_main,node_chat,node_memory,node_user toneBlue
class node_config,node_bridge toneAmber
class node_registry,node_filesystem,node_shelltool,node_bashlib,node_policy,node_ask,node_mcptransport,node_mcpservers toneMint
class node_supervisor,node_asyncsandbox,node_syscalls toneRose
class node_tui,node_turnpanel,node_highlight,node_panels,node_endpoint toneIndigo
```

## Components

### Conversation runtime

- [Turn loop](https://github.com/zvnoob/agent/blob/main/src/main.rs): `src/main.rs`
- [Chat client](https://github.com/zvnoob/agent/blob/main/src/api.rs): `src/api.rs`
- [Conversation memory](https://github.com/zvnoob/agent/blob/main/src/memory.rs): `src/memory.rs`

### Lua configuration

- [Starter config](https://github.com/zvnoob/agent/blob/main/lua/init.lua): `lua/init.lua`
- [Lua bridge](https://github.com/zvnoob/agent/blob/main/src/lua.rs): `src/lua.rs`

### Tools and policy

- [Tool registry](https://github.com/zvnoob/agent/blob/main/lua/mcps.lua): `lua/mcps.lua`
- [Filesystem tools](https://github.com/zvnoob/agent/blob/main/lua/fs.lua): `lua/fs.lua`
- [Shell tool](https://github.com/zvnoob/agent/blob/main/lua/bash_tool.lua): `lua/bash_tool.lua`
- [Bash support](https://github.com/zvnoob/agent/blob/main/lua/lib/bash.lua): `lua/lib/bash.lua`
- [Permission policy](https://github.com/zvnoob/agent/blob/main/lua/policy.lua): `lua/policy.lua`
- [Ask protocol](https://github.com/zvnoob/agent/blob/main/lua/lib/ask.lua): `lua/lib/ask.lua`
- [MCP transports](https://github.com/zvnoob/agent/blob/main/src/mcp.rs): `src/mcp.rs`

### Sandbox runtime

- [Sandbox supervisor](https://github.com/zvnoob/agent/blob/main/src/seccomp/mod.rs): `src/seccomp/mod.rs`
- [Async sandbox adapter](https://github.com/zvnoob/agent/blob/main/src/async_sandbox.rs): `src/async_sandbox.rs`
- [Syscall tables](https://github.com/zvnoob/agent/blob/main/src/seccomp/arch/mod.rs): `src/seccomp/arch/mod.rs`

### Terminal interface

- [TUI shell](https://github.com/zvnoob/agent/blob/main/src/tui/mod.rs): `src/tui/mod.rs`
- [Turn panel](https://github.com/zvnoob/agent/blob/main/src/tui/panel.rs): `src/tui/panel.rs`
- [Markdown highlighting](https://github.com/zvnoob/agent/blob/main/src/tui/highlight.rs): `src/tui/highlight.rs`
- [Panel operations](https://github.com/zvnoob/agent/blob/main/src/panels.rs): `src/panels.rs`

### Other components

- **User**
- **Chat endpoint**
- **MCP servers**

## Connections

- User → TUI shell: submits turn
- TUI shell → Turn loop: submits input
- Turn loop → Starter config: loads configuration
- Starter config → Lua bridge: configures agent
- Turn loop → Chat client: requests stream
- Chat client → Chat endpoint: sends chat request
- Chat endpoint → Chat client: streams events
- Turn loop → Tool registry: dispatches tool call
- Tool registry → Filesystem tools: registers tools
- Tool registry → Shell tool: registers tools
- Shell tool → Bash support: uses shell support
- Shell tool → Async sandbox adapter: runs command
- Async sandbox adapter → Sandbox supervisor: drives sandbox
- Sandbox supervisor → Syscall tables: resolves syscalls
- Permission policy → Ask protocol: requests decision
- Lua bridge → Sandbox supervisor: mediates policy asks
- Ask protocol → Panel operations: draws permission prompt
- Panel operations → Turn panel: applies panel ops
- Turn loop → Panel operations: collects panel ops
- TUI shell → Turn panel: renders conversation
- Turn panel → Markdown highlighting: highlights messages
- Turn loop → Conversation memory: archives turns
- Lua bridge → Conversation memory: reads and writes
- Tool registry → MCP transports: uses transports
- MCP transports → MCP servers: connects to servers