sorretai/zeroclaw

1. Overall shape

- ZeroClaw is a Rust workspace centered on an agent runtime, with multiple front doors and back-end adapters. The core execution path is: inbound event or user request → runtime orchestration → model/provider call and tool execution → response back to the originating channel/client.

2. Core runtime boundary

- crates/zeroclaw-runtime is the main orchestrator. It owns agent turns, approval gates, tool execution, history management, hooks, cron, SOP execution, health, daemon/control-plane concerns, and runtime observability.

- This is the subsystem where “what happens next” is decided once a request enters the system.

3. Ingress surfaces

- Requests can enter through multiple adapters: crates/zeroclaw-channels for external messaging systems, crates/zeroclaw-gateway for HTTP/WebSocket/API clients, and ACP/JSON-RPC over stdio for editor/IDE integrations.

- The Tauri app (apps/tauri) and TUI/CLI app (apps/zerocode) are local user interfaces that talk to the runtime/gateway rather than implementing agent logic themselves.

4. Model/provider layer

- crates/zeroclaw-providers abstracts LLM backends such as Anthropic, OpenAI, Ollama, Gemini, Bedrock, and other compatible/routed providers.

- This layer includes auth, model dispatch, routing/fallback, and stream guards, so provider selection is a policy and configuration concern rather than hard-coded into the agent loop.

5. Tooling layer

- crates/zeroclaw-tools is the first-party tool catalog: browser, shell, file ops, HTTP, search, MCP, memory operations, hardware tools, integrations, and specialized workflow tools.

- Tools are invoked from the runtime during a turn, and the results are fed back into the agent history or approval/security flow.

6. Memory and retrieval

- crates/zeroclaw-memory manages durable memory, embeddings, retrieval, response caching, consolidation, and knowledge graphs.

- It supports multiple storage backends, including SQLite, Postgres, Qdrant, and “none,” making memory a pluggable subsystem rather than a single database.

7. Configuration and policy

- crates/zeroclaw-config defines the config schema, migrations, env overrides, provider aliases, presets, secrets, and validation.

- The configuration layer is tightly coupled to policy: it determines agent identities, provider bindings, channel setup, autonomy/risk profiles, and platform-specific behavior.

8. Security and trust boundaries

- Security is a first-class subsystem in the runtime, with sandboxing, prompt guarding, leak detection, IAM/policy checks, approval flows, and verifiable intent support.

- Tool execution is therefore not “direct”; it is mediated by policy, approvals, and receipts, especially for risky actions like shell or filesystem operations.

9. Gateway and dashboard

- crates/zeroclaw-gateway exposes the operational API surface: REST, WebSocket, SSE, static files, pairing/auth, logs, config, skills, plugins, quickstart, and related admin endpoints.

- The React/Vite web app in web/ is the dashboard client for that gateway, used for chat, config editing, agents, cron, memory browsing, tools, and system status.

10. Channels and event orchestration

- crates/zeroclaw-channels is a large adapter collection for messaging and voice surfaces such as Discord, Slack, Telegram, Matrix, email, WhatsApp, webhooks, and more.

- It also includes orchestration pieces like media pipelines, transcription, TTS, wake/voice handling, and protocol-specific approval or allowlist logic. These channels are the main long-lived ingress/egress integration layer.

11. Hardware and edge devices

- crates/zeroclaw-hardware plus the firmware/ tree represent the hardware subsystem: board discovery, transport, serial/UF2 flashing, peripheral registry, and board-specific tools.

- This subsystem extends the agent beyond software APIs into physical peripherals and embedded devices, with separate firmware packages for boards like ESP32, Pico, Nucleo, and UNO Q bridges.

12. Plugins, skills, and extension points

- crates/zeroclaw-plugins provides a WASM plugin runtime for extensibility.

- crates/zeroclaw-runtime/src/skills and related skill crates manage skill discovery, bundling, review, scaffolding, and execution; skills are treated as a structured extension mechanism distinct from ad hoc prompts or tools.

13. Operational subsystems

- The runtime also contains control-plane, daemon, heartbeat, cron, hooks, tunnel, observability, and SOP engines.

- These subsystems handle always-on operation, scheduled tasks, event-driven procedures, network exposure, tracing/logging/metrics, and background reliability behaviors.

14. Repo structure and delivery

- The workspace is split into focused crates for major boundaries, plus app frontends, docs, packaging, and deployment assets.

- CI/CD, Docker/Containerfile variants, Nix, k8s manifests, and release packaging live alongside the code, reflecting that ZeroClaw is intended to run locally, as a service, or in containerized deployments rather than as a single binary only.