<!-- source: https://deepwiki.com/qhkm/zeptoclaw/13.1-project-structure -->

# Project Structure

- AGENTS.md
- CLAUDE.md
- src/cli/common.rs
- src/lib.rs
- src/tools/mod.rs

This document describes the directory layout, module organization, and architectural patterns used throughout the ZeptoClaw codebase. It provides a map of where to find specific functionality and explains how the codebase is structured for maintainability and security.

## Repository Layout

The repository follows a standard Rust workspace structure with additional directories for frontend, benchmarks, and documentation.

```
zeptoclaw/
├── src/                    # Core Rust source code (library + binary)
├── benches/                # Criterion.rs benchmarks
├── tests/                  # Integration and E2E tests
├── panel/                  # React + Vite dashboard (optional feature)
├── landing/                # Static landing page HTML/assets
├── Cargo.toml              # Root manifest with dependencies and features
├── CLAUDE.md               # Architecture reference and quick commands
├── AGENTS.md               # Guidance for coding agents
└── README.md               # User-facing documentation
```

**Sources:** [CLAUDE.md55-82](https://github.com/qhkm/zeptoclaw/blob/2c743d31/CLAUDE.md?plain=1#L55-L82) [AGENTS.md5-14](https://github.com/qhkm/zeptoclaw/blob/2c743d31/AGENTS.md?plain=1#L5-L14)

## Source Code Organization

The `src/` directory contains all Rust code organized into modules by domain responsibility. The codebase uses a **domain-driven module structure** where each top-level module represents a major subsystem.

### Module Map

```

```

**Sources:** [CLAUDE.md55-78](https://github.com/qhkm/zeptoclaw/blob/2c743d31/CLAUDE.md?plain=1#L55-L78) [src/lib.rs3-44](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/lib.rs#L3-L44)

## Core Module Responsibilities

### Agent Loop and Context ( src/agent/ )

The agent module contains the core message processing loop and context management. It manages the lifecycle of a conversation, including tool execution and token management.

**Sources:** [src/lib.rs33-46](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/lib.rs#L33-L46) [AGENTS.md50-51](https://github.com/qhkm/zeptoclaw/blob/2c743d31/AGENTS.md?plain=1#L50-L51)

### Communication Channels ( src/channels/ )

ZeptoClaw supports 10+ communication channels. Each implementation lives in its own file and implements the `Channel` trait.

```

```

The `ChannelManager` handles registration and lifecycle [src/lib.rs51](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/lib.rs#L51-L51) Channel tasks are isolated using `catch_unwind` to prevent panics in one channel from crashing the entire gateway [AGENTS.md28](https://github.com/qhkm/zeptoclaw/blob/2c743d31/AGENTS.md?plain=1#L28-L28)

**Sources:** [src/lib.rs48-53](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/lib.rs#L48-L53) [AGENTS.md15-28](https://github.com/qhkm/zeptoclaw/blob/2c743d31/AGENTS.md?plain=1#L15-L28)

### Tool System ( src/tools/ )

Tools are organized into individual files implementing the `Tool` async trait [src/tools/mod.rs171](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/mod.rs#L171-L171) The system supports 33+ built-in tools, MCP (Model Context Protocol) servers, and binary plugins.

**Key Components:**

- ToolRegistry : Central registry for managing and executing tools src/tools/mod.rs 128
- ToolContext : Execution context providing access to the channel, chat_id, and workspace src/tools/mod.rs 138
- ToolOutput : Dual-audience result structure (for LLM vs user) src/tools/mod.rs 138

**Tool Categories:**

- Filesystem: ReadFileTool , WriteFileTool , ListDirTool , EditFileTool src/tools/mod.rs 18-21
- Execution: ShellTool , GitTool , SpawnTool src/tools/mod.rs 22-96
- Web: WebSearchTool , WebFetchTool , WebScreenshotTool src/tools/mod.rs 23-131
- System: CronTool , ReminderTool , MessageTool src/tools/mod.rs 66-124

**Sources:** [src/tools/mod.rs1-143](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/mod.rs#L1-L143) [src/lib.rs94-100](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/lib.rs#L94-L100)

### Provider System ( src/providers/ )

LLM providers implement the `LLMProvider` trait [src/lib.rs59](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/lib.rs#L59-L59) The system supports Anthropic, OpenAI, Gemini, Groq, Ollama, and more.

**Architectural Patterns:**

- Decorator Chain: Providers can be wrapped in RetryProvider , FallbackProvider , or QuotaProvider to add resiliency and cost tracking CLAUDE.md 70
- Runtime Resolution: The system builds the provider chain in registry order, honoring fallback and retry configurations AGENTS.md 21-22

**Sources:** [src/lib.rs58-61](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/lib.rs#L58-L61) [AGENTS.md21-23](https://github.com/qhkm/zeptoclaw/blob/2c743d31/AGENTS.md?plain=1#L21-L23)

### Security and Isolation ( src/safety/ and src/runtime/ )

Security is a core design pillar, implemented across multiple layers:

1. SafetyLayer ( src/safety/ ) : Performs injection detection (21 patterns), leak scanning (22 patterns), and policy enforcement src/lib.rs 36
2. Taint Engine ( src/safety/taint.rs ) : Tracks sensitive data flow through the system src/lib.rs 35
3. Runtime Isolation ( src/runtime/ ) : Executes dangerous commands (like shell) inside isolated environments. Supported runtimes include Docker, Apple Container, Landlock, Firejail, and Bubblewrap src/lib.rs 62-65
4. Audit Chain : An in-memory SHA-256 hash chain records tool executions for integrity verification via record_audit_chain_event and verify_audit_chain_integrity CLAUDE.md 95

**Sources:** [src/lib.rs35-38](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/lib.rs#L35-L38) [src/lib.rs62-65](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/lib.rs#L62-L65) [AGENTS.md16-17](https://github.com/qhkm/zeptoclaw/blob/2c743d31/AGENTS.md?plain=1#L16-L17) [CLAUDE.md95](https://github.com/qhkm/zeptoclaw/blob/2c743d31/CLAUDE.md?plain=1#L95-L95)

### Library Facade ( src/lib.rs )

The `lib.rs` file serves as the public API for the ZeptoClaw crate, exporting core types and builders for embedding.

**Core Exports:**

- ZeptoAgent and ZeptoAgentBuilder : Primary entry point for embedding src/lib.rs 46
- MessageBus : The central async communication hub src/lib.rs 47
- Config : The unified configuration object src/lib.rs 54
- SessionManager : Persistence and history management src/lib.rs 87

**Sources:** [src/lib.rs1-101](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/lib.rs#L1-L101)

### CLI Implementation ( src/cli/ )

The CLI is a multi-command interface built with `clap`.

- common.rs : Contains shared logic for creating agents, resolving templates, and building skills prompts src/cli/common.rs 191-200
- Agent Creation : create_agent_with_template is the primary function used to initialize an AgentLoop with the correct tools, providers, and context src/cli/common.rs 196-200

**Sources:** [src/cli/common.rs1-200](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/common.rs#L1-L200) [CLAUDE.md62](https://github.com/qhkm/zeptoclaw/blob/2c743d31/CLAUDE.md?plain=1#L62-L62)

## Architectural Patterns

### Unified Tool Execution

Both the internal `AgentLoop` and the external `MCP server` route through `kernel::execute_tool()`. This ensures a single point for safety scans, taint checks, and metrics recording [AGENTS.md40](https://github.com/qhkm/zeptoclaw/blob/2c743d31/AGENTS.md?plain=1#L40-L40)

### Context Compaction

The system implements a three-tier compaction strategy (Normal/Emergency/Critical) triggered at 70%, 90%, and 95% of the token budget respectively to prevent context overflow [AGENTS.md50](https://github.com/qhkm/zeptoclaw/blob/2c743d31/AGENTS.md?plain=1#L50-L50)

### Channel Panic Isolation

To ensure high availability, channel tasks are spawned with `catch_unwind`. This isolates failures so that a crash in the Discord gateway does not affect the Telegram or Slack integrations [AGENTS.md28](https://github.com/qhkm/zeptoclaw/blob/2c743d31/AGENTS.md?plain=1#L28-L28)

### Hot Reloading

The gateway service polls the configuration file every 30 seconds. If changes are detected, it applies updates to providers, channels, and safety settings without a full restart [AGENTS.md53](https://github.com/qhkm/zeptoclaw/blob/2c743d31/AGENTS.md?plain=1#L53-L53)

### Data Flow: Message to Tool Execution

```

```

**Sources:** [src/lib.rs46-47](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/lib.rs#L46-L47) [src/cli/common.rs191-200](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/common.rs#L191-L200) [AGENTS.md40-49](https://github.com/qhkm/zeptoclaw/blob/2c743d31/AGENTS.md?plain=1#L40-L49)
