# hcy2315/zeroclaw architecture

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

- Interactive diagram: https://gitdiagram.com/hcy2315/zeroclaw
- Repository: https://github.com/hcy2315/zeroclaw
- Video tour (about a minute): https://gitdiagram.com/hcy2315/zeroclaw/video

## Overview

ZeroClaw is a self-hosted personal AI assistant runtime, exposed through messaging channels, a gateway, ACP, and a terminal UI. The principal workflow is an inbound request reaching the agent loop, which consults a model provider and may invoke tools before returning a response through the initiating interface. The graph also preserves documented capabilities such as memory, hardware, scheduled automation, and SOPs. Source excerpts are partial, so some documented subsystem links use the README as evidence; unsampled implementation details are not asserted.

Main entry points: [`crates/zeroclaw-runtime/src/agent/loop_.rs`](https://github.com/hcy2315/zeroclaw/blob/master/crates/zeroclaw-runtime/src/agent/loop_.rs) (Agent loop), [`apps/zerocode/src/client.rs`](https://github.com/hcy2315/zeroclaw/blob/master/apps/zerocode/src/client.rs) (RPC client), [`apps/zerocode/src/app.rs`](https://github.com/hcy2315/zeroclaw/blob/master/apps/zerocode/src/app.rs) (Terminal UI), [`apps/zerocode/src/chat.rs`](https://github.com/hcy2315/zeroclaw/blob/master/apps/zerocode/src/chat.rs) (Chat pane)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_tui["Terminal UI<br/>[app.rs]"]
  node_chat["Chat pane<br/>[chat.rs]"]
  node_dashboard["Dashboard pane<br/>[dashboard.rs]"]
  node_configui["Config pane<br/>[config_manager.rs]"]
  node_quickstart["Quickstart pane<br/>[quickstart_pane.rs]"]
  node_sopui["SOP pane<br/>[sop_pane.rs]"]
  node_logsui["Logs pane<br/>[logs.rs]"]
  node_client["RPC client<br/>[client.rs]"]
  node_wire["RPC wire types<br/>[wire.rs]"]
  node_channels["Channel adapters<br/>[lib.rs]"]
  node_gateway["HTTP/WS gateway<br/>[api.rs]"]
  node_acp["ACP integration<br/>[acp_server.rs]"]
end

subgraph group_runtime["Agent runtime"]
  node_agent["Agent loop<br/>[loop_.rs]"]
  node_providers["Model providers<br/>[router.rs]"]
  node_tools["Tool execution<br/>[pipeline.rs]"]
  node_approval["Approval gates<br/>[mod.rs]"]
end

subgraph group_capabilities["Agent capabilities"]
  node_memory[("Memory and retrieval<br/>[retrieval.rs]")]
  node_hardware["Hardware peripherals<br/>[registry.rs]"]
  node_sop["SOP engine<br/>[mod.rs]"]
  node_routines["Event routines<br/>[engine.rs]"]
  node_cron["Scheduled tasks<br/>[mod.rs]"]
end

subgraph group_platform["Runtime platform"]
  node_config["Configuration<br/>[lib.rs]"]
  node_sessions[("Session storage<br/>[session_store.rs]")]
  node_plugins["Plugin runtime<br/>[runtime.rs]"]
end

node_user(("User"))

node_user -->|"sends message"| node_channels
node_channels -->|"delivers inbound"| node_agent
node_user -->|"uses gateway"| node_gateway
node_gateway -->|"routes requests"| node_agent
node_user -->|"uses editor"| node_acp
node_acp -->|"integrates with"| node_agent
node_user -->|"interacts"| node_tui
node_tui -->|"dispatches to"| node_chat
node_tui -->|"dispatches to"| node_dashboard
node_tui -->|"dispatches to"| node_configui
node_tui -->|"uses RPC"| node_client
node_client -->|"encodes messages"| node_wire
node_chat -->|"sends requests"| node_client
node_dashboard -->|"sends requests"| node_client
node_quickstart -.->|"configures runtime"| node_client
node_sopui -.->|"manages runs"| node_client
node_logsui -.->|"reads logs"| node_client
node_agent -->|"requests completions"| node_providers
node_agent -->|"invokes tools"| node_tools
node_agent -->|"checks risky actions"| node_approval
node_agent -.->|"uses memory"| node_memory
node_agent -->|"uses peripherals"| node_hardware
node_agent -->|"runs procedures"| node_sop
node_agent -.->|"triggers automation"| node_routines
node_agent -->|"schedules tasks"| node_cron
node_agent -.->|"persists sessions"| node_sessions
node_agent -.->|"loads extensions"| node_plugins
node_config -.->|"configures runtime"| node_agent

click node_tui "https://github.com/hcy2315/zeroclaw/blob/master/apps/zerocode/src/app.rs"
click node_chat "https://github.com/hcy2315/zeroclaw/blob/master/apps/zerocode/src/chat.rs"
click node_dashboard "https://github.com/hcy2315/zeroclaw/blob/master/apps/zerocode/src/dashboard.rs"
click node_configui "https://github.com/hcy2315/zeroclaw/blob/master/apps/zerocode/src/config_manager.rs"
click node_quickstart "https://github.com/hcy2315/zeroclaw/blob/master/apps/zerocode/src/quickstart_pane.rs"
click node_sopui "https://github.com/hcy2315/zeroclaw/blob/master/apps/zerocode/src/sop_pane.rs"
click node_logsui "https://github.com/hcy2315/zeroclaw/blob/master/apps/zerocode/src/logs.rs"
click node_client "https://github.com/hcy2315/zeroclaw/blob/master/apps/zerocode/src/client.rs"
click node_wire "https://github.com/hcy2315/zeroclaw/blob/master/apps/zerocode/src/wire.rs"
click node_channels "https://github.com/hcy2315/zeroclaw/blob/master/crates/zeroclaw-channels/src/lib.rs"
click node_gateway "https://github.com/hcy2315/zeroclaw/blob/master/crates/zeroclaw-gateway/src/api.rs"
click node_acp "https://github.com/hcy2315/zeroclaw/blob/master/crates/zeroclaw-channels/src/orchestrator/acp_server.rs"
click node_agent "https://github.com/hcy2315/zeroclaw/blob/master/crates/zeroclaw-runtime/src/agent/loop_.rs"
click node_providers "https://github.com/hcy2315/zeroclaw/blob/master/crates/zeroclaw-providers/src/router.rs"
click node_tools "https://github.com/hcy2315/zeroclaw/blob/master/crates/zeroclaw-tools/src/pipeline.rs"
click node_approval "https://github.com/hcy2315/zeroclaw/blob/master/src/approval/mod.rs"
click node_memory "https://github.com/hcy2315/zeroclaw/blob/master/crates/zeroclaw-memory/src/retrieval.rs"
click node_hardware "https://github.com/hcy2315/zeroclaw/blob/master/crates/zeroclaw-hardware/src/registry.rs"
click node_sop "https://github.com/hcy2315/zeroclaw/blob/master/src/sop/mod.rs"
click node_routines "https://github.com/hcy2315/zeroclaw/blob/master/crates/zeroclaw-runtime/src/routines/engine.rs"
click node_cron "https://github.com/hcy2315/zeroclaw/blob/master/src/cron/mod.rs"
click node_config "https://github.com/hcy2315/zeroclaw/blob/master/crates/zeroclaw-config/src/lib.rs"
click node_sessions "https://github.com/hcy2315/zeroclaw/blob/master/crates/zeroclaw-infra/src/session_store.rs"
click node_plugins "https://github.com/hcy2315/zeroclaw/blob/master/crates/zeroclaw-plugins/src/runtime.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_tui,node_chat,node_dashboard,node_configui,node_quickstart,node_sopui,node_logsui,node_client,node_wire,node_channels,node_gateway,node_acp,node_user toneBlue
class node_agent,node_providers,node_tools,node_approval toneAmber
class node_memory,node_hardware,node_sop,node_routines,node_cron toneMint
class node_config,node_sessions,node_plugins toneRose
```

## Components

### User interfaces

- [Terminal UI](https://github.com/hcy2315/zeroclaw/blob/master/apps/zerocode/src/app.rs): `apps/zerocode/src/app.rs`
- [Chat pane](https://github.com/hcy2315/zeroclaw/blob/master/apps/zerocode/src/chat.rs): `apps/zerocode/src/chat.rs`
- [Dashboard pane](https://github.com/hcy2315/zeroclaw/blob/master/apps/zerocode/src/dashboard.rs): `apps/zerocode/src/dashboard.rs`
- [Config pane](https://github.com/hcy2315/zeroclaw/blob/master/apps/zerocode/src/config_manager.rs): `apps/zerocode/src/config_manager.rs`
- [Quickstart pane](https://github.com/hcy2315/zeroclaw/blob/master/apps/zerocode/src/quickstart_pane.rs): `apps/zerocode/src/quickstart_pane.rs`
- [SOP pane](https://github.com/hcy2315/zeroclaw/blob/master/apps/zerocode/src/sop_pane.rs): `apps/zerocode/src/sop_pane.rs`
- [Logs pane](https://github.com/hcy2315/zeroclaw/blob/master/apps/zerocode/src/logs.rs): `apps/zerocode/src/logs.rs`
- [RPC client](https://github.com/hcy2315/zeroclaw/blob/master/apps/zerocode/src/client.rs): `apps/zerocode/src/client.rs`
- [RPC wire types](https://github.com/hcy2315/zeroclaw/blob/master/apps/zerocode/src/wire.rs): `apps/zerocode/src/wire.rs`
- [Channel adapters](https://github.com/hcy2315/zeroclaw/blob/master/crates/zeroclaw-channels/src/lib.rs): `crates/zeroclaw-channels/src/lib.rs`
- [HTTP/WS gateway](https://github.com/hcy2315/zeroclaw/blob/master/crates/zeroclaw-gateway/src/api.rs): `crates/zeroclaw-gateway/src/api.rs`
- [ACP integration](https://github.com/hcy2315/zeroclaw/blob/master/crates/zeroclaw-channels/src/orchestrator/acp_server.rs): `crates/zeroclaw-channels/src/orchestrator/acp_server.rs`

### Agent runtime

- [Agent loop](https://github.com/hcy2315/zeroclaw/blob/master/crates/zeroclaw-runtime/src/agent/loop_.rs): `crates/zeroclaw-runtime/src/agent/loop_.rs`
- [Model providers](https://github.com/hcy2315/zeroclaw/blob/master/crates/zeroclaw-providers/src/router.rs): `crates/zeroclaw-providers/src/router.rs`
- [Tool execution](https://github.com/hcy2315/zeroclaw/blob/master/crates/zeroclaw-tools/src/pipeline.rs): `crates/zeroclaw-tools/src/pipeline.rs`
- [Approval gates](https://github.com/hcy2315/zeroclaw/blob/master/src/approval/mod.rs): `src/approval/mod.rs`

### Agent capabilities

- [Memory and retrieval](https://github.com/hcy2315/zeroclaw/blob/master/crates/zeroclaw-memory/src/retrieval.rs): `crates/zeroclaw-memory/src/retrieval.rs`
- [Hardware peripherals](https://github.com/hcy2315/zeroclaw/blob/master/crates/zeroclaw-hardware/src/registry.rs): `crates/zeroclaw-hardware/src/registry.rs`
- [SOP engine](https://github.com/hcy2315/zeroclaw/blob/master/src/sop/mod.rs): `src/sop/mod.rs`
- [Event routines](https://github.com/hcy2315/zeroclaw/blob/master/crates/zeroclaw-runtime/src/routines/engine.rs): `crates/zeroclaw-runtime/src/routines/engine.rs`
- [Scheduled tasks](https://github.com/hcy2315/zeroclaw/blob/master/src/cron/mod.rs): `src/cron/mod.rs`

### Runtime platform

- [Configuration](https://github.com/hcy2315/zeroclaw/blob/master/crates/zeroclaw-config/src/lib.rs): `crates/zeroclaw-config/src/lib.rs`
- [Session storage](https://github.com/hcy2315/zeroclaw/blob/master/crates/zeroclaw-infra/src/session_store.rs): `crates/zeroclaw-infra/src/session_store.rs`
- [Plugin runtime](https://github.com/hcy2315/zeroclaw/blob/master/crates/zeroclaw-plugins/src/runtime.rs): `crates/zeroclaw-plugins/src/runtime.rs`

### Other components

- **User**

## Connections

- User → Channel adapters: sends message (evidence: `README.md`)
- Channel adapters → Agent loop: delivers inbound (evidence: `README.md`)
- User → HTTP/WS gateway: uses gateway (evidence: `README.md`)
- HTTP/WS gateway → Agent loop: routes requests (evidence: `README.md`)
- User → ACP integration: uses editor (evidence: `README.md`)
- ACP integration → Agent loop: integrates with (evidence: `README.md`)
- User → Terminal UI: interacts (evidence: `README.md`)
- Terminal UI → Chat pane: dispatches to (evidence: `apps/zerocode/src/app.rs`)
- Terminal UI → Dashboard pane: dispatches to (evidence: `apps/zerocode/src/app.rs`)
- Terminal UI → Config pane: dispatches to (evidence: `apps/zerocode/src/app.rs`)
- Terminal UI → RPC client: uses RPC (evidence: `apps/zerocode/src/app.rs`)
- RPC client → RPC wire types: encodes messages (evidence: `apps/zerocode/src/client.rs`)
- Chat pane → RPC client: sends requests
- Dashboard pane → RPC client: sends requests (evidence: `apps/zerocode/src/dashboard.rs`)
- Quickstart pane → RPC client: configures runtime
- SOP pane → RPC client: manages runs
- Logs pane → RPC client: reads logs
- Agent loop → Model providers: requests completions (evidence: `README.md`)
- Agent loop → Tool execution: invokes tools (evidence: `README.md`)
- Agent loop → Approval gates: checks risky actions (evidence: `README.md`)
- Agent loop → Memory and retrieval: uses memory
- Agent loop → Hardware peripherals: uses peripherals (evidence: `README.md`)
- Agent loop → SOP engine: runs procedures (evidence: `README.md`)
- Agent loop → Event routines: triggers automation
- Agent loop → Scheduled tasks: schedules tasks (evidence: `README.md`)
- Agent loop → Session storage: persists sessions
- Agent loop → Plugin runtime: loads extensions
- Configuration → Agent loop: configures runtime