AdaClaw ⚡

30-Second Quick Start

# 1. Install (Linux / macOS)
curl -fsSL https://raw.githubusercontent.com/worldflat21-lang/AdaClaw/main/scripts/install.sh | bash

# 2. Configure interactively (sets up provider, channels, workspace)
adaclaw onboard

# 3. Start chatting
adaclaw chat

Windows:

irm https://raw.githubusercontent.com/worldflat21-lang/AdaClaw/main/scripts/install.ps1 | iex
adaclaw onboard
adaclaw chat

Or build from source:

cargo install --git https://github.com/worldflat21-lang/AdaClaw

What is AdaClaw?

AdaClaw is an open-source AI Agent Runtime — a single binary that connects your LLM of choice to channels like Telegram, Discord, Slack, DingTalk, Feishu, and WeChat Work, with a production-grade security system and hybrid memory.

Unlike cloud-hosted bot platforms, AdaClaw runs on your own machine or server. It costs nothing beyond LLM API calls, stores data locally, and never sends your conversations to a third party.

Key numbers:

• 📦 Binary size: < 10 MB (opt-level = "z", LTO = fat)
• 💾 Memory footprint: < 5 MB at idle
• 🚀 Startup time: < 50 ms
• 🔒 Security layers: 7 (pairing → allowlist → sandbox → estop → OTP → scrub → audit)

Features

🤖 Multi-Provider LLM Support

Connect to any major LLM provider — or multiple at once with automatic failover:

The ReliabilityChain provides exponential backoff + circuit breaker — if one provider fails, the next one in the chain takes over automatically.

💬 Multi-Channel Messaging

Connect to your users wherever they are:

🧠 Advanced Memory System

AdaClaw uses a hybrid RRF (Reciprocal Rank Fusion) memory system combining:

• Vector search — local FastEmbed (AllMiniLML6V2, 384-dim, zero API cost) or OpenAI embeddings
• Full-text search — SQLite FTS5 with BM25 ranking
• Automatic topic detection — cosine similarity detects when the user switches topics, pruning irrelevant context

Result: smarter context injection than either pure keyword or pure vector search.

🔒 7-Layer Security System

Layer 1  Network boundary    Gateway binds to 127.0.0.1 by default
Layer 2  Channel auth        Pairing codes + Bearer tokens + Webhook HMAC
Layer 3  User allowlist      Per-channel deny-by-default whitelist
Layer 4  Tool approval       ReadOnly / Supervised / Full autonomy levels
Layer 5  Filesystem          Workspace isolation + symlink detection + Landlock (Linux)
Layer 6  Output scrubbing    26-pattern regex strips credentials from all LLM output
Layer 7  Emergency stop      4-level estop (KillAll/NetworkKill/DomainBlock/ToolFreeze) + TOTP

Additional: rate limiting, audit logs (JSONL / SIEM-ready), ChaCha20-Poly1305 secret storage.

🤝 Multi-Agent Delegation

Define specialized agents and let them collaborate:

[agents.assistant]
provider = "openrouter"
model = "anthropic/claude-3.5-sonnet"

[agents.assistant.subagents]
allow = ["coder"]          # assistant can delegate coding tasks to coder

[agents.coder]
provider = "anthropic"
model = "claude-3-5-sonnet-20241022"
temperature = 0.2
tools = ["shell", "file_read", "file_write"]

The DelegateTool spawns sub-agents asynchronously — the main agent stays responsive while the sub-agent works.

Comparison

Installation

Pre-compiled Binary (recommended)

Linux / macOS:

curl -fsSL https://raw.githubusercontent.com/worldflat21-lang/AdaClaw/main/scripts/install.sh | bash

Windows:

irm https://raw.githubusercontent.com/worldflat21-lang/AdaClaw/main/scripts/install.ps1 | iex

macOS with Homebrew:

brew tap worldflat21-lang/adaclaw
brew install adaclaw

Build from Source

git clone https://github.com/worldflat21-lang/AdaClaw.git
cd AdaClaw
cargo build --release
# Binary: target/release/adaclaw

Configuration

Run the interactive wizard to generate config.toml:

adaclaw onboard

Or copy and edit the example:

cp config.example.toml config.toml
# Edit config.toml with your API keys and settings

See config.example.toml for a fully annotated reference covering all options.

Minimal config (CLI chat only)

[providers.openrouter]
api_key = "sk-or-..."

[agents.assistant]
provider = "openrouter"
model = "anthropic/claude-3.5-sonnet"

[[routing]]
default = true
agent = "assistant"

Then: adaclaw run or adaclaw chat

Docker Deployment (recommended for Full autonomy)

For production use with autonomy_level = "full", always run inside Docker:

# 1. Configure first
cp config.example.toml config.toml
# Edit config.toml...

# 2. Start
docker compose up -d

# 3. Check logs
docker compose logs -f

The included docker-compose.yml is hardened: read-only filesystem, dropped capabilities, tmpfs /tmp, port bound to 127.0.0.1 only.

CLI Reference

adaclaw [COMMAND]

Commands:
  run      Start the daemon (channels + gateway)
  chat     Interactive CLI chat
  daemon   Manage background daemon (start/stop/restart/status)
  onboard  Interactive first-run configuration wizard
  doctor   System health check
  config   Show active configuration
  status   Show daemon status
  stop     Stop daemon / trigger emergency stop
  help     Print help

Diagnostics

Run adaclaw doctor to check all subsystems:

AdaClaw Doctor
==============

✅  config.toml found
✅  Provider 'openrouter' configured with API key
✅  Agent 'assistant' → provider='openrouter' model='anthropic/claude-3.5-sonnet'
✅  Memory: SQLite will be created at 'memory.db' on first use
✅  Gateway: bearer token configured, listening on 127.0.0.1:8080
✅  Security: autonomy_level='supervised' — environment check passed
✅  Binary size: 8.3 MB (target: <10 MB ✓)

─────────────────────────────────────────
Doctor summary: ✅ 7 passed  ⚠️  0 warnings  ❌ 0 failed

✅  All checks passed! AdaClaw is ready to run.
   Run: adaclaw run

Architecture

See ARCHITECTURE.md for a detailed description of the system design, including the message bus, security layers, memory architecture, and module layout.

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

Quick start for contributors:

git clone https://github.com/worldflat21-lang/AdaClaw.git
cd AdaClaw
cargo test --all             # run tests
cargo clippy -- -D warnings  # lint

License

Licensed under the Apache License 2.0.