clawhive

# clawhive

[![CI](https://github.com/longzhi/clawhive/actions/workflows/ci.yml/badge.svg)](https://github.com/longzhi/clawhive/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Rust](https://img.shields.io/badge/rust-1.92%2B-orange.svg)](https://www.rust-lang.org/)
[![GitHub release](https://img.shields.io/github/v/release/longzhi/clawhive?include_prereleases)](https://github.com/longzhi/clawhive/releases)

English | [中文](README_CN.md)

An open-source, Rust-native alternative to [OpenClaw](https://github.com/openclaw/openclaw) — deploy your own AI agents across Telegram, Discord, Slack, WhatsApp, iMessage, and more with a single binary.

**One binary, ~14 MB, zero runtime dependencies.** No Node.js, no npm, no Docker — just download, configure, and run.

## Installation

```bash
curl -fsSL https://raw.githubusercontent.com/longzhi/clawhive/main/install.sh | bash
```

Auto-detects OS/architecture, downloads latest release, installs binary and skills to `~/.clawhive/`.

After installation, run to activate in your current shell:

```bash
source ~/.clawhive/env
```

Or download manually from [GitHub Releases](https://github.com/longzhi/clawhive/releases).

## Setup

Configure providers, agents, and channels using either method:

**Option A: Web Setup Wizard** — Start the server and open the browser-based wizard:

```bash
clawhive start
# Open http://localhost:8848/setup in your browser
```

**Option B: CLI Setup Wizard** — Run the interactive terminal wizard:

```bash
clawhive setup
```

## Usage

```bash
# Setup / config
clawhive setup
clawhive validate

# Chat mode (local REPL)
clawhive chat

# Service lifecycle
clawhive start               # start in foreground
clawhive up                  # start if not already running (always daemon)
clawhive restart
clawhive stop

# Dashboard mode (observability TUI)
clawhive dashboard

# Code mode (developer TUI)
clawhive code

# Agents / sessions
clawhive agent list
clawhive agent show clawhive-main
clawhive session reset <session_key>

# Schedules / tasks
clawhive schedule list
clawhive schedule run <schedule_id>
clawhive task trigger clawhive-main "summarize today's work"

# Logs
clawhive logs

# Auth
clawhive auth status
clawhive auth login openai
```

## CLI Commands

| Command | Description |
|---------|-------------|
| `setup` | Interactive configuration wizard |
| `up` | Start as background daemon (alias for `start -d`) |
| `start [--tui] [--daemon]` | Start all configured channel bots and HTTP API server |
| `stop` | Stop a running clawhive process |
| `restart` | Restart clawhive (stop + start as daemon) |
| `chat [--agent <id>]` | Local REPL for testing |
| `validate` | Validate YAML configuration |
| `consolidate` | Run memory consolidation manually |
| `logs` | Tail the latest log file |
| `agent list\|show\|enable\|disable` | Agent management |
| `skill list\|show\|analyze\|install` | Skill management |
| `session reset <key>` | Reset a session |
| `schedule list\|run\|enable\|disable\|history` | Scheduled task management |
| `wait list` | List background wait tasks |
| `task trigger <agent> <task>` | Send a one-off task to an agent |
| `auth login\|status` | OAuth authentication management |

## Why clawhive?

- **Tiny footprint** — One binary, ~14 MB. Runs on a Raspberry Pi, a VPS, or a Mac Mini with minimal resource usage.
- **Security by design** — Two-layer security model: non-bypassable hard baseline + origin-based trust. External skills must declare permissions explicitly.
- **Bounded execution** — Enforced token budgets, timeout limits, and sub-agent recursion depth. No runaway loops, no surprise bills.
- **Web + CLI setup** — Browser-based setup wizard or interactive CLI. Get your first agent running in under 2 minutes.

## Features

- Multi-agent orchestration with per-agent personas, model routing, and memory policy controls
- Three-layer memory system: Session JSONL → Daily files → MEMORY.md (long-term)
- Hybrid search: sqlite-vec vector similarity + FTS5 BM25 over memory chunks
- Hippocampus consolidation: periodic LLM-driven synthesis into long-term memory
- Channel adapters: Telegram, Discord, Slack, WhatsApp, iMessage, Feishu, DingTalk, WeCom (multi-bot, multi-connector)
- ReAct reasoning loop with repeat guard and sub-agent spawning
- Skill system (SKILL.md with frontmatter + permission declarations)
- Token-bucket rate limiting per user
- LLM provider abstraction with retry + exponential backoff (Anthropic, OpenAI, Gemini, DeepSeek, Groq, Ollama, OpenRouter, Together, Fireworks, and any OpenAI-compatible endpoint)
- Real-time TUI dashboard and YAML-driven configuration

## Architecture

![clawhive architecture](assets/architecture.png)

<details>
<summary><strong>Project Structure</strong></summary>

```
crates/
├── clawhive-cli/        # CLI binary (clap) — start, setup, chat, validate, agent/skill/session/schedule
├── clawhive-core/       # Orchestrat

... (truncated)