<!-- source: https://deepwiki.com/qhkm/zeptoclaw/13-development-guide -->

# Development Guide

- .github/ISSUE_TEMPLATE/bug_report.md
- .github/ISSUE_TEMPLATE/config.yml
- .github/ISSUE_TEMPLATE/feature_request.md
- .github/PULL_REQUEST_TEMPLATE.md
- CONTRIBUTING.md

This page provides guidance for developers contributing to or extending ZeptoClaw. It covers the codebase structure, build system, development workflows, core abstractions, and testing strategies.

## Project Structure

ZeptoClaw is organized as a single Rust binary crate with a library component. The codebase follows a modular architecture where each major feature area is isolated into its own module with well-defined public interfaces.

### Module Organization

```

```

**Module Dependency Graph**

The codebase consists of over 40 modules organized into specialized subsystems. Core traits such as `LLMProvider`, `Tool`, `Channel`, and `ContainerRuntime` are defined at module roots, with specific implementations in submodules. The `lib.rs` file exports public symbols to facilitate library usage and integration testing.

Sources: [CONTRIBUTING.md100-115](https://github.com/qhkm/zeptoclaw/blob/2c743d31/CONTRIBUTING.md?plain=1#L100-L115) [CLAUDE.md53-83](https://github.com/qhkm/zeptoclaw/blob/2c743d31/CLAUDE.md?plain=1#L53-L83) [CLAUDE.md89-91](https://github.com/qhkm/zeptoclaw/blob/2c743d31/CLAUDE.md?plain=1#L89-L91) [AGENTS.md40-41](https://github.com/qhkm/zeptoclaw/blob/2c743d31/AGENTS.md?plain=1#L40-L41)

For a detailed breakdown of the directory layout and module organization, see [Project Structure](/qhkm/zeptoclaw/13.1-project-structure).

## Build System and Dependencies

### Development Workflow

ZeptoClaw uses `cargo` for its build pipeline. Developers are expected to follow a strict pre-push checklist to maintain code quality. Contributors must branch from `upstream/main` and use conventional commits.

Sources: [CONTRIBUTING.md12-21](https://github.com/qhkm/zeptoclaw/blob/2c743d31/CONTRIBUTING.md?plain=1#L12-L21) [CONTRIBUTING.md25-37](https://github.com/qhkm/zeptoclaw/blob/2c743d31/CONTRIBUTING.md?plain=1#L25-L37) [CONTRIBUTING.md86-94](https://github.com/qhkm/zeptoclaw/blob/2c743d31/CONTRIBUTING.md?plain=1#L86-L94)

### Dependency Philosophy

ZeptoClaw minimizes dependencies to maintain a lightweight footprint, targeting a binary size of approximately 6 MB. New dependencies are only added if strictly necessary.

Sources: [.github/PULL_REQUEST_TEMPLATE.md21](https://github.com/qhkm/zeptoclaw/blob/2c743d31/.github/PULL_REQUEST_TEMPLATE.md?plain=1#L21-L21)

For analysis of `Cargo.toml`, feature flags, and build configuration, see [Dependencies and Build](/qhkm/zeptoclaw/13.2-dependencies-and-build).

## Testing Strategy

ZeptoClaw maintains a rigorous testing standard including unit tests and integration tests. Every pull request must pass the full test suite.

### Test Architecture

```

```

**Bridge: Natural Language to Code Entities**

Tests are organized to verify both individual component logic (Unit) and the interaction between subsystems. The `CONTRIBUTING.md` and `PULL_REQUEST_TEMPLATE.md` specify that new features or bug fixes must include updated tests.

Sources: [CONTRIBUTING.md15-16](https://github.com/qhkm/zeptoclaw/blob/2c743d31/CONTRIBUTING.md?plain=1#L15-L16) [CONTRIBUTING.md79](https://github.com/qhkm/zeptoclaw/blob/2c743d31/CONTRIBUTING.md?plain=1#L79-L79) [.github/PULL_REQUEST_TEMPLATE.md18-19](https://github.com/qhkm/zeptoclaw/blob/2c743d31/.github/PULL_REQUEST_TEMPLATE.md?plain=1#L18-L19)

For details on test fixtures and patterns, see [Testing Strategy](/qhkm/zeptoclaw/13.3-testing-strategy).

## Extending ZeptoClaw

ZeptoClaw is designed for extensibility through trait implementations.

1. Tools : Create a new file in src/tools/ , implement the Tool trait with async fn execute() , and register it in src/tools/mod.rs , src/lib.rs , and src/cli/common.rs .
2. Channels : Create a new file in src/channels/ , implement the Channel trait, and register it in the channel factory and configuration types.
3. Providers : Implement the LLMProvider trait for new model backends.

Sources: [CONTRIBUTING.md100-115](https://github.com/qhkm/zeptoclaw/blob/2c743d31/CONTRIBUTING.md?plain=1#L100-L115)

For a guide to adding new components with examples, see [Extending ZeptoClaw](/qhkm/zeptoclaw/13.4-extending-zeptoclaw).

## Diagnostics and Debugging

The project includes built-in utilities for troubleshooting and environment validation.

Sources: [CONTRIBUTING.md61-64](https://github.com/qhkm/zeptoclaw/blob/2c743d31/CONTRIBUTING.md?plain=1#L61-L64) [.github/ISSUE_TEMPLATE/bug_report.md14-28](https://github.com/qhkm/zeptoclaw/blob/2c743d31/.github/ISSUE_TEMPLATE/bug_report.md?plain=1#L14-L28) [.github/ISSUE_TEMPLATE/feature_request.md9-21](https://github.com/qhkm/zeptoclaw/blob/2c743d31/.github/ISSUE_TEMPLATE/feature_request.md?plain=1#L9-L21)

For details on logging, health checks, and troubleshooting, see [Diagnostics and Debugging](/qhkm/zeptoclaw/13.5-diagnostics-and-debugging).
