angel-claw 0.10.0

Angel Claw personal AI agent framework

🪽 Angel Claw

The Multi-Tenant AI Agent Framework with memory, skills, and multi-channel superpowers.

---

What Is Angel Claw?

Angel Claw is a powerful, extensible AI agent framework designed for both personal and multi-user environments. It provides a robust engine for building autonomous agents that learn, remember, and act across multiple platforms.

• 🧠 Multi-Tenant Memory: Isolated, long-term memory for every user.
• 🛠 Extensible Skills: Self-generating tools and community skills from ClawHub.
• 🔌 MCP Host: Standardized standardized external tool interoperability (Model Context Protocol).
• 📅 Proactive Automation: Built-in scheduling (cron, at, every) for autonomous actions.
• 📱 Omni-Channel: Consistent experience across Web, CLI, Telegram, and WhatsApp.
• 🔐 Enterprise Ready: Secure API keys, pairing tokens, and Shopyo-based user management.
• 💬 Peer-to-Peer Messaging: Users can send internal notes and messages to each other via the AI agent.

$ pip install angel-claw
$ angel-claw serve    # DEV: Starts Web + Bridges in one process (simplest)
$ angel-claw bridges  # PROD: Starts ONLY Bridges (run exactly ONE instance)
$ angel-claw chat     # CLI: Interactive chat mode

---

🚀 Key Features

Feature	Description
👥 Multi-User Support	Full identity management with Shopyo integration.
🧠 Isolated Memory	User data stored securely in ~/.angelclaw/users/{user_id}.
⚡ Multi-Model	OpenAI, Anthropic, Ollama & more via litellm.
🔁 Proactive Tasks	Autonomous execution of scheduled jobs.
✅ Todo Management	Native task tracking with priorities and due dates.
📅 Calendar Sync	Manage events and sync with Google Calendar.
🌐 Web Dashboard	Modern UI with 🪽 branding and connection indicators.
✉️ Internal Notes	Send peer-to-peer messages: "Send a note to [e-mail] telling check fridge".
📱 Secure Pairing	Link Telegram/WhatsApp using time-limited secure tokens.
🔑 Developer APIs	Create and manage scoped API keys for external integration.

---

🏁 Quick Start

📦 Installation

pip install angel-claw

⚙️ Setup

Run the setup wizard to configure your LLM and basic settings:

angel-claw chat

🌐 Run the Web Dashboard

Start the full multi-tenant environment:

angel-claw serve

Access at http://localhost:5000. Default admin: [e-mail] / admin.

---

🏗️ Production Architecture

Angel Claw is designed for robust production deployment by separating the Web UI from background tasks.

1. Web UI (Gunicorn)

In production, run the web interface using a WSGI server like Gunicorn. This process does not handle bridges.

gunicorn -w 4 "angel_claw.app.app:create_app('production')"

2. Bridge Worker (Single Instance)

You must start exactly one instance of the bridge worker to handle Telegram, WhatsApp, and Cron tasks for all users:

angel-claw bridges

Note: angel-claw serve is only for development as it bundles both together.

📦 Package-First Persistence

All data is stored outside the package directory for safe updates:

• DB: ~/.angelclaw/angelclaw.db
• Bridges: ~/.angelclaw/bridges/
• Vaults: ~/.angelclaw/vaults/

See DEPLOY.md for full Nginx, Gunicorn, and Systemd templates.

---

💬 Internal Messaging

Angel Claw supports secure, internal communication between users. The agent handles delivery and notification.

Commands:

• "Send an internal note to [e-mail] telling him the meeting is at 5"
• "Do I have any unread messages?"
• "Tell [e-mail] that I finished the report"

---

🛠️ Built-in Skills

Angel Claw comes with high-quality native skills that integrate deeply with its memory.

✅ Todo Management

Keep track of your life without leaving the chat.

• "Add a high priority todo: Buy milk by Friday"
• "Show my pending todos"
• "Mark todo 1 as complete"

📅 Calendar Integration

Manage your schedule and sync with external providers.

• "Schedule a meeting with Sarah tomorrow at 2pm"
• "What's on my calendar for next week?"
• "Sync my events with Google Calendar"

---

📱 Multi-Channel Bridges

...

Control your AI from anywhere.

Telegram

1. Add TELEGRAM_TOKEN to .env.
2. Generate a pairing token on the Web Dashboard.
3. Message your bot: /pair <your-token>.

WhatsApp

1. Run angel-claw login-whatsapp.
2. Scan QR code.
3. Message the bot: /pair <your-token>.

---

💬 Developer API

Generate an API key in the Dashboard and use it to build your own integrations:

curl -X POST http://localhost:5000/agent/chat \
     -H "Authorization: Bearer ac_v1_..." \
     -H "Content-Type: application/json" \
     -d '{"message": "Remind me to call John tomorrow"}'

---

🧪 Testing

# Run engine and isolation tests
.venv/bin/pytest tests/test_basic.py tests/test_engine_todos.py

# Run Shopyo endpoint tests
PYTHONPATH=src/angel_claw/app .venv/bin/pytest tests/test_shopyo_endpoints.py

---

📜 License

Apache 2.0 License.

---

🪽 Angel Claw

The multi-tenant, evolving AI agent framework.