clawhive AGENTS.md

AGENTS.md

This file provides guidance to AI coding agents when working with code in this repository.

Project Overview

Clawhive is a Rust-native single-binary (~14MB) multi-agent AI platform for deploying agents across messaging channels (Telegram, Discord, Slack, WhatsApp, iMessage). 13-crate workspace, edition 2021, Rust 1.92.0+, version 0.1.0-alpha.*.

Build / Test / Lint

# One-time setup (git hooks: fmt+clippy on commit, full check on push)
just install-hooks

# Full CI-equivalent quality gate (run before every PR)
just check
# Equivalent to:
#   1. cargo fmt --all -- --check
#   2. cargo clippy --workspace --all-targets -- -D warnings
#   3. cargo test --workspace

# Individual commands
just fmt                # cargo fmt --all (auto-format)
just fmt-check          # cargo fmt --all -- --check
just clippy             # cargo clippy --workspace --all-targets -- -D warnings
just test               # cargo test --workspace
cargo build --release   # release binary

# Run a single test (by name substring)
cargo test -p clawhive-core -- policy::tests::check_exec -v

# Run all tests in one crate
cargo test -p clawhive-core

# Run tests matching a pattern
cargo test -p clawhive-scheduler -- integration

# Frontend (in web/ directory, use bun not npm)
cd web && bun install && bun run build
cd web && bun run dev   # dev server with proxy to localhost:3001

# Deploy to Mac Studio (pushes dev, builds remotely, restarts daemon)
./deploy.sh

# Version release (tags on main, not dev)
just release patch  # or minor/major

CI runs 4 parallel jobs on ubuntu-latest: check, test, clippy, fmt. RUSTFLAGS=-Dwarnings is set globally in CI — all warnings are errors.

Workspace Structure

crates/
├── clawhive-cli/        # CLI binary (clap) — the only bin crate
├── clawhive-core/       # Orchestrator, tools, policy, skills, config — most logic lives here
├── clawhive-memory/     # Memory system (file store, JSONL sessions, SQLite index, embedding)
├── clawhive-gateway/    # Gateway, agent routing, rate limiting, scheduled task listener
├── clawhive-bus/        # In-process event bus (pub/sub)
├── clawhive-provider/   # LLM provider trait + multi-provider adapters
├── clawhive-channels/   # Channel adapters (Telegram, Discord, Slack, WhatsApp, iMessage)
├── clawhive-auth/       # OAuth and API key auth
├── clawhive-scheduler/  # Cron-based task scheduling
├── clawhive-server/     # HTTP API server (axum) + embedded SPA
├── clawhive-schema/     # Shared DTOs (InboundMessage, OutboundMessage, BusMessage)
├── clawhive-runtime/    # Task executor abstraction
└── clawhive-tui/        # Terminal dashboard (ratatui)