---

🧠 What is ScalyClaw?

ScalyClaw is a self-hosted AI assistant platform that connects to all your messaging channels with a single shared mind. It remembers everything, runs code, delegates to agents, and scales horizontally — all under your control.

---

🏗️ Architecture

Process	Role	Scalable
🧠 Node	Orchestrator — channels, LLM loop, guards, memory, agents, scheduling	Singleton
⚡ Worker	Execution — code, commands, skills via BullMQ	Horizontally
📊 Dashboard	Web UI — monitoring, config, chat	—

Workers are independently deployable. They share nothing with the node except Redis — no shared filesystem required.

---

📊 Dashboard

---

✨ Highlights

	Feature	Description
💬	7 Channels	Discord, Telegram, Slack, WhatsApp, Signal, Teams, Web Gateway — one memory across all
🧠	Persistent Memory	Hybrid vector + full-text search (sqlite-vec + FTS5). Auto-extracted from conversations
🤖	Autonomous Agents	Sub-workers with their own prompts, models, and skills. Delegate and let them run
🔧	Extensible Skills	JavaScript, Python, Rust, Bash. Hot-reload, auto-deps, zip deployment
🛡️	Multi-Layer Security	Echo guard, content guard, command shield, code guard. Every layer fails closed
⚡	Scalable Workers	Deploy anywhere — same machine or remote. They only need Redis
🔌	MCP Integration	Connect any Model Context Protocol server. Tools are auto-discovered
💰	Budget Control	Monthly/daily limits, per-model tracking, configurable alerts
📊	Dashboard	Real-time monitoring, personality editor, chat overlay, job inspector
🔄	Zero-Downtime Reload	Skills, agents, config, MCP servers — all reload live via Redis pub/sub
📣	Proactive Engagement	Ambient signals turn into timely broadcasts across every enabled channel — with quiet hours, per-trigger cooldowns, and an adaptive threshold that tunes to user engagement

---

🚀 Quick Start

One-Line Install

Everything — Bun, Redis, node, 3 workers, dashboard — installed and running in one command:

curl -fsSL https://scalyclaw.com/install.sh | sh

Manage your installation:

~/.scalyclaw/scalyclaw.sh --stop       # stop all
~/.scalyclaw/scalyclaw.sh --start      # start all
~/.scalyclaw/scalyclaw.sh --update     # pull latest & rebuild
~/.scalyclaw/scalyclaw.sh --status     # show status
~/.scalyclaw/scalyclaw.sh --uninstall  # remove everything

Remote access via SSH tunnel (replace user@<server_ip>):

# Dashboard (port 4173)
ssh -N -L 4173:127.0.0.1:4173 user@<server_ip>

Then open http://localhost:4173?token=<token> for the dashboard.

From Source

Prerequisites: Bun + Redis ≥ 6.2

# 📦 Clone & build
git clone https://github.com/scalyclaw/scalyclaw.git && cd scalyclaw
bun install && bun run build

# ⚙️ Setup & run
bun run scalyclaw:node setup
bun run scalyclaw:node start

# 👷 Worker (separate terminal)
bun run scalyclaw:worker setup --name worker1
bun run scalyclaw:worker start --name worker1

# 📊 Dashboard (separate terminal)
bun run scalyclaw:dashboard start

---

🔧 Skills

Skills are executable tools the AI can invoke. Each skill is a folder with a SKILL.md manifest and a script.

skills/
  weather/
    SKILL.md       # manifest (name, description, language, script)
    main.py        # entry point
  deploy/
    SKILL.md
    main.js

SKILL.md example:

---
name: Weather
description: Get current weather for a city
script: main.py
language: python
---
Optional instructions for the AI on when and how to use this skill.

Language	Runtime
🟨 JavaScript	bun run
🐍 Python	uv run
🦀 Rust	cargo run --release
🐚 Bash	bash

Dependencies auto-install on first run. Skills hot-reload via pub/sub. Deploy as zip archives.

---

🤖 Agents

Agents are autonomous sub-workers with their own prompt, model, and skill set. The AI can delegate tasks to agents when specialized behavior is needed.

Each agent has:

• Prompt — custom instructions defining its role
• Model — can use a different LLM than the main orchestrator
• Skills — restricted set of skills the agent can access
• Permissions — what the agent is allowed to do

Agents are created and managed via the dashboard. When delegated a task, they run independently on the BullMQ agents queue.

---

🧠 Memory

ScalyClaw automatically extracts and stores memories from conversations. Memories persist across all channels — what you say on Telegram is remembered on Discord.

• Hybrid search — vector similarity (sqlite-vec) + full-text search (FTS5)
• Auto-extraction — a debounced background job turns user messages into structured memories; the LLM can also call memory_store directly mid-reply
• Types — semantic, episodic, procedural, each with an importance score (1–10) used in composite retrieval scoring
• Entity graph — people, projects, technologies, places, organizations, and concepts with directed relations, queryable via the memory_graph tool
• Consolidation — scheduled background merging of near-duplicate memories into comprehensive entries
• Management — search, view, edit, delete memories from the dashboard

---

🤖 Models

ScalyClaw ships with native Anthropic support and a unified OpenAI-compatible factory that covers OpenAI, Google (Gemini via OpenAI-compat), OpenRouter, Mistral, Groq, xAI, DeepSeek, Cohere, MiniMax, Ollama, LM Studio, and any custom endpoint.

• Multiple models — configure different models for different tasks (chat, agents, guards, embeddings, memory extraction, proactive monitoring)
• Priority + weight load balancing — models are grouped by priority (lower = higher priority). Only the top group is used for selection; within it, requests are distributed by weighted-random. Transient failures retry on the same provider with exponential backoff — there is no automatic cross-provider fallback
• Reasoning — the reasoningEnabled flag plumbs through to providers that support it: OpenAI o-series / GPT-5.x, Google Gemini 2.5/3/3.1, DeepSeek-R1, Claude 4.x extended & adaptive thinking, and local models via <think> trace stripping
• Budget control — global monthly/daily spending limits with soft or hard enforcement, threshold alerts, and per-model cost tracking driven by inputPricePerMillion / outputPricePerMillion
• Embedding models — separate model config for memory vector search. Set embeddingModel to "auto" (default) to select from enabled embedding models using priority + weight

---

📣 Engagement

ScalyClaw reaches out first when something actionable happens — pending task results, upcoming deadlines, a conversation that drifted off. A scheduled cron scans six ambient signals, a single LLM call decides whether to speak, and the message is broadcast to every enabled channel in parallel.

• Six signals — idle, pending deliverables, time-sensitive memories, entity activity, user pattern, return from absence
• Four trigger types — urgent, deliverable, insight, check_in, each with its own cooldown
• Adaptive threshold — self-tunes to the user's engagement rate; midpoint during the cold-start window
• Quiet hours + mute + per-trigger cooldown + daily cap — layered timing gates with urgent-override
• All-channel broadcast — every enabled adapter gets the message in parallel; bookkeeping applied only after a successful delivery
• One LLM call per firing — the evaluate-and-generate step is merged; no wasted round-trips

Configure from the dashboard Engagement page or via POST /api/proactive/trigger for a manual smoke test.

---

🔌 MCP

Connect any Model Context Protocol server to extend ScalyClaw with external tools.

• Transports — stdio, HTTP, and SSE
• Auto-discovery — tools from connected MCP servers are automatically available to the AI
• Dashboard setup — add, remove, and configure MCP servers from the UI
• Hot-reload — connect new servers without restarting

---

🔐 Vault

Secrets are stored encrypted in Redis and injected as environment variables when skills run. They are never exposed in conversations, logs, or the dashboard.

• Manage via the dashboard Vault page
• Use in skills as $SECRET_NAME environment variables
• Scoped — secrets can be restricted to specific skills

---

🛡️ Security

Four independent guard layers — every layer fails closed:

Guard	Purpose
🔁 Echo Guard	Detects if the AI is being tricked into repeating injected text
🛑 Content Guard	Blocks prompt injection, social engineering, and harmful content
🔍 Skill & Agent Guard	Audits skill code and agent configs for malicious patterns
🛡️ Command Shield	Blocks dangerous shell commands with deterministic pattern matching — no LLM needed

All guards are configurable from the dashboard.

---

💻 CLI

scalyclaw node      <setup|start|stop|restart|status|background>
scalyclaw worker    <setup|start|stop|restart|status|background>
scalyclaw dashboard <setup|start|stop|restart|status|background>

Workers are named instances (--name worker1). Run as many as you need.

---

🛠️ Tech Stack

⚡ Runtime	Bun
📮 Queue	BullMQ + Redis
💾 Database	SQLite + sqlite-vec + FTS5
🤖 LLM	OpenAI-compatible API
💬 Channels	Telegraf, discord.js, @slack/bolt, botbuilder, WhatsApp Cloud API, Signal REST API
🔌 MCP	@modelcontextprotocol/sdk
🌐 HTTP	Fastify
📊 Dashboard	React 19, Vite 6, Tailwind CSS 4, shadcn/ui
💻 CLI	Commander + @clack/prompts

---

📁 Project Structure

Path	Description
🧠 scalyclaw/src/	Core — orchestrator, channels, guards, memory, agents, skills, tools, MCP
📦 shared/src/	Shared — queues, logger, session, skill loader, types used by node and worker
⚡ worker/src/	Worker — command/code/skill execution, skill cache, dependency management
💻 cli/src/	CLI — setup wizards, process management
📊 dashboard/src/	Dashboard — React SPA with real-time monitoring and config management
🎭 mind/	Personality — IDENTITY.md, SOUL.md, USER.md

---

🤝 Contributing

Contributions are welcome! Whether it's a bug fix, new feature, channel adapter, or skill — we'd love your help.

1. 🍴 Fork the repo
2. 🌿 Create your branch (git checkout -b feat/my-feature)
3. ✅ Commit your changes
4. 🚀 Push and open a Pull Request

Please keep PRs focused and include a clear description of what changed and why.

---

📄 License

MIT — use it, modify it, ship it.