![\"SenClaw](\"docs/images/senclaw-logo.png\"){kind=logo}
\n\n \n
\n A general-purpose framework for personal AI agents.\n
\n\n\n ![\"Latest](\"https://img.shields.io/github/v/tag/NortonBen/SenClaw?label=version\")
![\"Build](\"https://github.com/NortonBen/SenClaw/actions/workflows/desktop.yml/badge.svg\"){kind=icon}
\n ![\"License:](\"https://img.shields.io/badge/License-MIT-yellow.svg\"){kind=icon}
\n
\n English · Tiếng Việt\n
\n\nSenClaw provides the runtime machinery around large language models: permissions, memory, scheduling, multi-agent orchestration, channel adapters, Space Apps, local model support, and a desktop app. It turns a raw model provider or local model into a practical personal AI system.\n\n---\n\n## About\n\nSenClaw is a **local-first personal AI workstation**: a single Rust daemon that hosts your agents, and a native Flutter desktop app that supervises it. Your data — chats, notes, calendar, memories, wiki — lives in SQLite under `~/.senclaw/` on your machine; the model can be a cloud provider **or run fully offline** on Apple Silicon via MLX.\n\nWhat that adds up to:\n\n- **One assistant, everywhere** — talk to the same agents from the desktop app, Telegram / Feishu / QQ, the mobile app (relay), or the browser extension.\n- **Agents that do real work** — tool permissions with human-in-the-loop approval, Plan mode, and DAG multi-agent teams (Cowork) for larger tasks.\n- **Memory that compounds** — a cognitive knowledge graph plus curated `memory/*.md` files that are consolidated automatically when context is compacted, and recalled into future turns.\n- **A personal Space** — notes, calendar with reminders that fire as native notifications, and recurring schedules that run agents on cron.\n- **Space Apps** — installable full-stack mini-apps (SSH Manager, DeepWiki, Email, …) that ship their own UI, MCP tools, and skills.\n- **Local models** — native MLX inference for LLMs (Gemma, Qwen, DeepSeek, …), Whisper speech-to-text, TTS, OCR, and embeddings — no GPU cloud required.\n\n### Screenshots\n\n| Dashboard | Chat |\n| --- | --- |\n|  |  |\n\n| Kanban Board | Cowork (Multi-Agent Teams) |\n| --- | --- |\n|  |  |\n\n| Space Apps | Knowledge (Wiki) |\n| --- | --- |\n|  |  |\n\n| Plugins (Skills / MCP / Subagents) | Kanban Boards |\n| --- | --- |\n|  |  |\n\n---\n\n## Highlights\n\n- **Personal agent runtime**: agent lifecycle, tool permissions, clarification flow, workspace state, and per-agent personas.\n- **Memory and knowledge**: hybrid FTS/vector memory, curated auto-memory, daily logs, and a Git-backed personal wiki.\n- **Multi-agent orchestration**: DAG team execution, virtual workers, dispatch bridge, and subagent support.\n- **Scheduled work**: notification, script, agent, and script-plus-agent task modes.\n- **Multi-channel gateway**: Telegram, Feishu/Lark, QQ, WeChat, WebSocket, HTTP API, and Web UI.\n- **Space Apps**: isolated micro-apps such as SSH Manager, DeepWiki, Email, Google Workspace, and Test Manager that expose tools through MCP.\n- **Local AI options**: MLX/Candle local inference, local embeddings, OCR, Whisper speech-to-text, and local TTS.\n- **Desktop app**: native Flutter app (macOS/Windows/Linux/web) that supervises the daemon as a child process.\n- **Mobile app**: Flutter app over the relay — chat, sessions, workflows, Space Apps, push notifications, and background sync.\n- **Deterministic safety guards**: fail-closed SSRF blocking for URL-fetch tools (loopback / link-local / cloud-metadata / private ranges) and read-only shell-command classification, applied before the model ever sees a risky call — on top of the prompt/tool trust boundaries.\n\n---\n\n## Supported Local LLMs\n\nSenClaw ships its own **native MLX runtime** (Rust `mlx-rs`, Apple Silicon — no Python, no llama.cpp) plus a cross-platform **Candle** fallback. Any HuggingFace checkpoint whose `model_type` matches a supported architecture can be downloaded and run from *Settings → Local Models*:\n\n| Architecture (`model_type`) | Family | Notes |\n|---|---|---|\n| `qwen3`, `qwen2` | Qwen 2.5 / Qwen 3 | Full tool-calling + thinking markers; recommended default for agents. |\n| `qwen3_5` | Qwen 3.5 hybrid | GatedDeltaNet linear-attention + attention hybrid (OptiQ quant); recurrent prefix cache skips ~90% of prefill on multi-turn agent loops. |\n| `gemma2`, `gemma3`, `gemma4` | Google Gemma | Gemma 4 runs the text backbone (Per-Layer Embeddings, cross-layer KV sharing); vision tower in progress. |\n| `llama` | Llama 3.x | Standard transformer path. |\n| `deepseek_v2` | DeepSeek-Coder-V2-Lite | Multi-head Latent Attention + Mixture-of-Experts. |\n| `ouro` | Ouro LoopLM | Looped-depth universal transformer with a `recurrence_steps` depth knob. |\n| `mamba2`, `falcon_mamba` | State-space models | Attention-free SSM decoding. |\n| `bonsai_q1` | Bonsai Q1 | Compact experimental architecture. |\n\nCurated one-click downloads (verified end-to-end): **Qwen3 4B Instruct 4-bit** (tools/agents), **Qwen2.5 0.5B** (fast chat), **Qwen3.5 0.8B OptiQ** (chat + agentic), **Gemma 4 E2B-it 4-bit / OptiQ** (long-form text). Custom repos can be added by HF id.\n\nRuntime extras: **TurboQuant KV-cache quantization** (TQ3/TQ4 — long contexts in a fraction of the RAM), prefix caching, and streaming tool-call/thinking parsers per model dialect. Beyond LLMs, the same local stack covers **Whisper** speech-to-text (incl. Vietnamese), **TTS** (macOS native voice; ZipVoice in progress), **PaddleOCR** (Metal/CoreML), and **local embeddings**. Build with `make run-release` / `make app-build` to get the full feature set.\n\n---\n\n## Install\n\n### One-line install (macOS / Linux)\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/NortonBen/SenClaw/main/scripts/install.sh | bash\n```\n\n### Windows (PowerShell)\n\n```powershell\npowershell -ExecutionPolicy Bypass -c \"irm https://raw.githubusercontent.com/NortonBen/SenClaw/main/scripts/install.ps1 | iex\"\n```\n\nBoth installers download the latest release binary into `~/.senclaw/bin` (`%USERPROFILE%\\.senclaw\\bin` on Windows) and add it to your PATH. To pin a release, set `SENCLAW_VERSION=v0.3.0` before running the installer.\n\nThe `senclaw` binary ships **without** the Web UI or the desktop app — they are downloaded on demand:\n\n```bash\nsenclaw web # download the Web UI bundle (first run only), then start the daemon serving it\nsenclaw install desktop # download & install the native desktop app for this platform\nsenclaw uninstall desktop # remove the desktop app again\n```\n\n- `senclaw web` stores the UI bundle in `~/.senclaw/web/dist` and serves it at `http://127.0.0.1:18788`. Use `--force` to re-download, `--version v0.3.0` to pin a release.\n- `senclaw install desktop` installs into `/Applications` (macOS), `%LOCALAPPDATA%\\SenClaw\\Desktop` (Windows), or `~/.senclaw/desktop` plus a launcher entry (Linux). It supports macOS (Apple Silicon + Intel), Windows x64, and Linux x64.\n\n---\n\n## Quick Start (from source)\n\n### 1. Clone\n\n```bash\ngit clone https://github.com/NortonBen/SenClaw.git\ncd SenClaw\n```\n\n### 2. Build the Web UI\n\n```bash\ncd web\nnpm install\nnpm run build\ncd ..\n```\n\n### 3. Build and run the daemon\n\n```bash\ncargo run\n```\n\nFor an optimized build:\n\n```bash\ncargo build --release\n./target/release/senclaw\n```\n\nThen open the Web UI:\n\n```bash\nopen http://127.0.0.1:18788\n```\n\nOn Linux, open the same URL in your browser manually if `open` is unavailable.\n\n---\n\n## Configuration\n\nSenClaw can start in Web UI-only mode, but agent runs need at least one LLM profile. On first launch, open:\n\n```text\nSettings -> LLM\n```\n\nAdd a provider profile such as OpenAI, Anthropic, DeepSeek, Qwen, OpenRouter, Ollama, or a compatible API endpoint. The profile is stored in:\n\n```text\n~/.senclaw/config.json\n```\n\nChannel and runtime settings can be configured through `.env`:\n\n```bash\ncp .env.example .env\n```\n\nCommon values:\n\n```env\nTELEGRAM_BOT_TOKEN=\nADMIN_TELEGRAM_USER_ID=\nFEISHU_APP_ID=\nFEISHU_APP_SECRET=\nQQ_APP_ID=\nQQ_APP_SECRET=\nGATEWAY_UI_PORT=18788\nGATEWAY_PORT=18789\nMAX_CONCURRENT_AGENTS=5\nMAX_MESSAGES_PER_GROUP=100\nSCHEDULER_INTERVAL_SEC=60\n```\n\nIf channel tokens are left empty, SenClaw can still be used from the Web UI.\n\n---\n\n## Common Commands\n\n```bash\n# Check Rust code\ncargo check\n\n# Run Rust tests\ncargo test\n\n# Run the daemon\ncargo run\n\n# Run with local model features used by the Makefile\nmake run\n\n# Run an optimized local-model build\nmake run-release\n\n# Start the Web UI dev server\nmake run-web\n\n# Build the browser extension\nmake build-extension\n```\n\n---\n\n## Desktop App\n\nSenClaw ships a native **Flutter** desktop app in `desktop_app/` (macOS / Windows / Linux / web). It replaces the former Tauri shell: instead of embedding a WebView, it talks to the daemon directly over HTTP/WebSocket and **supervises the `senclaw` daemon as a child process** (spawns the bundled binary, streams its logs, restarts it on demand).\n\nOn launch the app shows a **startup gate**: if a daemon is already running it opens straight into the UI; otherwise it spawns the bundled daemon, waits until the HTTP API answers, then switches to the main screen (with a retryable error screen if the daemon can't start).\n\n```bash\n# Development (runs the Flutter app; it adopts a running daemon or spawns one)\nmake app-dev\n\n# Production bundle (builds the daemon with the full Apple-Silicon feature set\n# — MLX LLM, Whisper ASR, TTS, OCR Metal, embeddings — and bundles the binary\n# into Contents/Resources so the supervisor can launch it)\nmake app-build # macOS\nmake app-build-windows # Windows\nmake app-build-linux # Linux\nmake app-build-web # web\n\n# Install the freshly-built .app into /Applications and launch it (macOS)\nmake app-install\n```\n\n---\n\n## Runtime Layout\n\nBy default, SenClaw stores runtime data under the user's home directory, split into a hidden config/state root and a user-visible workspace:\n\n```text\n~/.senclaw/ # config, databases, model caches\n├── config.json # global config (LLM profiles, toggles)\n├── senclaw.db # main SQLite DB (groups, messages, tasks, events)\n├── senclaw_cognitive.db # cognitive memory graph\n├── dispatch-state.json # DAG team state\n├── hooks.json # user hooks\n├── llm_logs/ # per-request LLM logs\n├── models/ local-models/ # downloaded local LLMs (MLX/Candle)\n├── whisper-models/ tts-models/ ocr-models/\n├── managed/skills/ # skills installed by Space Apps\n├── space-apps-data/{app-id}/ # per-app data (settings, databases)\n├── plans/ # saved Plan-mode plans\n└── workspace-state-{folder}.json # per-agent workspace state\n\n~/senclaw/ # user-visible workspace\n├── agents/{folder}/ # one folder per agent profile\n│ ├── SOUL.md # persona\n│ ├── memory/ # curated memory (*.md + MEMORY.md index)\n│ └── .sema/sessions/ # conversation sessions\n├── workspace/{folder}/ # working directories for chats\n├── workspace/space-apps/{app-id}/ # installed Space Apps (binary + web_dist)\n├── wiki/ # Git-backed knowledge base\n├── quicknotes/ # Space notes\n├── workflows/ workflow-data/ # saved workflows and their runs\n└── virtual-agents/ # DAG virtual worker folders\n```\n\nMost paths can be overridden through `.env` or `~/.senclaw/config.json`.\n\n---\n\n## Project Structure\n\n```text\nSenClaw/\n├── src/ # Rust daemon and core runtime\n│ ├── agent/ # Agent pool, permissions, personas, DAG dispatch\n│ ├── zen_core/ # Agent engine (sessions, tools, LLM querying)\n│ ├── channels/ # Telegram, Feishu/Lark, QQ, WeChat, app-relay adapters\n│ ├── gateway/ # HTTP + WebSocket gateway, routing, UI server\n│ ├── mcp/ # MCP servers exposed to agents (space, memory, browser, …)\n│ ├── memory/ # FTS/vector memory, curated auto-memory, daily logs\n│ ├── scheduler/ # Cron/interval/once tasks + event reminders\n│ ├── local_model/ # Native MLX/Candle local inference (LLM/ASR/TTS)\n│ ├── browser/ # Browser-automation backend for senclaw-browser\n│ ├── clawhub/ # ClawHub skill marketplace + relay client\n│ ├── marketplace/ # Plugin marketplace manager\n│ ├── skills/ subagents/ # Bundled skills and subagent definitions\n│ ├── workflow/ # Deterministic multi-agent workflow runner\n│ ├── cli/ # senclaw CLI subcommands\n│ ├── db/ # rusqlite storage layer\n│ └── wiki/ # Git-backed knowledge base\n├── desktop_app/ # Flutter desktop app (macOS/Windows/Linux/web)\n├── channel_app/ # Flutter mobile app (connects over the relay)\n├── web/ # React + Vite Web UI (legacy; served by the daemon)\n├── apps/ # Space Apps (ssh-manager, deepwiki, email, …)\n├── app-space-sdk/ # SDK for building Space Apps\n├── hub-backend/ # Relay hub backend (mobile app channel)\n├── senclaw-extension-chrome/ # Chrome extension (browser remote control)\n├── skills/ # Bundled skill definitions\n├── scripts/ # install.sh / install.ps1 one-line installers\n├── examples/ # Example apps and SDK usage\n├── docs/ # Architecture and feature docs\n└── tests/ # Integration tests\n```\n\n---\n\n## Documentation\n\n| Document | Description |\n|---|---|\n| [Quick Start](docs/QUICK_START.md) | Setup, runtime layout, and usage notes. |\n| [Architecture](docs/ARCHITECTURE.md) | System layers, startup flow, and data flow. |\n| [Memory](docs/memory.md) | Memory design and retrieval flow. |\n| [Curated Memory](docs/curated-memory-design.md) | Claude-Code-style auto-memory: consolidation on compaction + recall. |\n| [DAG Team](docs/DAG_Team.md) | Multi-agent task decomposition and execution. |\n| [Cowork](docs/COWORK_DESIGN.md) | Persistent agent teams built on DAG dispatch. |\n| [Workflows](docs/workflow.md) | Saved, parameterized DAGs of agent + script steps. |\n| [Space Apps](docs/workspace-feature-design.md) | How Space Apps are designed and registered. |\n| [Flutter Desktop](docs/flutter-desktop-migration.md) | Desktop app architecture (supervisor, startup gate). |\n| [Mobile Channel App](docs/CHANNEL_APP_DESIGN.md) | Flutter mobile app over the relay. |\n| [Local MLX Runtime](docs/mlx-rs-turboquant-native-runtime.md) | Native MLX inference + TurboQuant KV cache. |\n| [Chrome Extension](docs/senclaw-extension-design.md) | Browser remote-control extension design. |\n| [ClawHub Plugins & Skills](docs/clawhub-plugins-skills.md) | Skill marketplace and plugin system. |\n| [Prompt Injection Security](docs/prompt-injection-security.md) | Security notes for tool and prompt boundaries. |\n\n---\n\n## Development Notes\n\nSenClaw is primarily a Rust workspace. The Web UI is a React/Vite application under `web/`, and several Space Apps have their own package manifests under `apps/`.\n\nUseful feature builds:\n\n```bash\n# Local embeddings\ncargo build --features local-embed\n\n# Local embeddings with Apple Silicon Metal\ncargo build --features local-embed-metal\n\n# Local Candle runtime\ncargo build --features local-candle\n\n# Local MLX runtime\ncargo build --features local-mlx\n```\n\nSome local model, OCR, audio, and TTS features require platform-specific dependencies. Start with `cargo check` or the default `cargo run` path before enabling optional heavy features.\n\n---\n\n## Contributing\n\nIssues, pull requests, experiments, and design discussions are welcome. Please keep changes focused, document behavior that affects users, and include tests for risky runtime changes.\n\n---\n\n## License\n\n[MIT](LICENSE)\n\n---\n\n## Acknowledgments\n\nSenClaw is a Rust rewrite that grew out of — and is deeply inspired by — [**SemaClaw**](https://github.com/midea-ai/SemaClaw) (midea-ai), the original TypeScript multi-channel AI agent gateway. It runs on the [sema-code-core](https://github.com/midea-ai/sema-code-core) agent runtime.\n\nSenClaw also integrates with the [ClaWHub](https://github.com/openclaw/clawhub) plugin marketplace and takes inspiration from [OpenClaw](https://github.com/openclaw/openclaw), the [Model Context Protocol](https://modelcontextprotocol.io), and the broader open-source agent tooling ecosystem.\n"}