Metadata-Version: 2.5
Name: shibaclaw
Version: 1.0.5
Summary: A lightweight personal AI assistant framework
Author: shibaclaw contributors
License: Apache-2.0
License-File: LICENSE
Keywords: agent,ai,chatbot
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.12
Requires-Dist: aiofiles<26.0.0,>=25.1.0
Requires-Dist: anthropic<1.0.0,>=0.125.0
Requires-Dist: croniter<7.0.0,>=6.2.3
Requires-Dist: cryptography>=50.0.1
Requires-Dist: ddgs<10.0.0,>=9.16.0
Requires-Dist: httpx<1.0.0,>=0.28.1
Requires-Dist: json-repair<1.0.0,>=0.63.4
Requires-Dist: keyring>=24.0.0
Requires-Dist: loguru<1.0.0,>=0.7.3
Requires-Dist: mcp<2.0.0,>=1.29.1
Requires-Dist: oauth-cli-kit<1.0.0,>=0.1.6
Requires-Dist: openai<3.0.0,>=2.54.0
Requires-Dist: prompt-toolkit<4.0.0,>=3.0.53
Requires-Dist: pydantic-settings<3.0.0,>=2.15.0
Requires-Dist: pydantic<3.0.0,>=2.13.5
Requires-Dist: pyjwt<3.0.0,>=2.14.0
Requires-Dist: python-multipart>=0.0.32
Requires-Dist: python-telegram-bot[socks]<23.0,>=22.8
Requires-Dist: pyyaml<7.0,>=6.0.3
Requires-Dist: readability-lxml<1.0.0,>=0.9
Requires-Dist: rich<16.0.0,>=14.3.4
Requires-Dist: starlette<2.0.0,>=1.6.0
Requires-Dist: tiktoken<1.0.0,>=0.14.0
Requires-Dist: typer<1.0.0,>=0.27.2
Requires-Dist: uvicorn<1.0.0,>=0.52.4
Requires-Dist: websockets<17.0,>=16.1.1
Provides-Extra: all-channels
Requires-Dist: aiohttp<4.0.0,>=3.9.0; extra == 'all-channels'
Requires-Dist: cryptography>=46.0.7; extra == 'all-channels'
Requires-Dist: dingtalk-stream<1.0.0,>=0.24.0; extra == 'all-channels'
Requires-Dist: lark-oapi<2.0.0,>=1.5.0; extra == 'all-channels'
Requires-Dist: matrix-nio>=0.25.2; extra == 'all-channels'
Requires-Dist: mistune<4.0.0,>=3.0.0; extra == 'all-channels'
Requires-Dist: nh3<1.0.0,>=0.2.17; extra == 'all-channels'
Requires-Dist: qq-botpy<2.0.0,>=1.2.0; extra == 'all-channels'
Requires-Dist: slack-sdk<4.0.0,>=3.39.0; extra == 'all-channels'
Requires-Dist: slackify-markdown<1.0.0,>=0.2.0; extra == 'all-channels'
Requires-Dist: wecom-aibot-sdk-python>=0.1.5; extra == 'all-channels'
Provides-Extra: audit
Requires-Dist: pip-audit<3.0.0,>=2.10.1; extra == 'audit'
Provides-Extra: desktop
Requires-Dist: pillow<13.0.0,>=12.3.0; extra == 'desktop'
Requires-Dist: pystray<1.0.0,>=0.19.5; extra == 'desktop'
Requires-Dist: pywebview<7.0,>=6.2.1; extra == 'desktop'
Provides-Extra: dev
Requires-Dist: httpx<1.0.0,>=0.28.1; extra == 'dev'
Requires-Dist: pyinstaller<7.0.0,>=6.22.2; extra == 'dev'
Requires-Dist: pytest-asyncio<2.0.0,>=1.4.0; extra == 'dev'
Requires-Dist: pytest<10.0.0,>=9.1.1; extra == 'dev'
Requires-Dist: ruff>=0.16.5; extra == 'dev'
Provides-Extra: dingtalk
Requires-Dist: dingtalk-stream<1.0.0,>=0.24.0; extra == 'dingtalk'
Provides-Extra: feishu
Requires-Dist: lark-oapi<2.0.0,>=1.5.0; extra == 'feishu'
Provides-Extra: full
Requires-Dist: aiohttp<4.0.0,>=3.9.0; extra == 'full'
Requires-Dist: beautifulsoup4>=4.15.0; extra == 'full'
Requires-Dist: cryptography>=46.0.7; extra == 'full'
Requires-Dist: dingtalk-stream<1.0.0,>=0.24.0; extra == 'full'
Requires-Dist: faiss-cpu>=1.14.3; extra == 'full'
Requires-Dist: filelock<4.0.0,>=3.32.5; extra == 'full'
Requires-Dist: langchain-community<1.0.0,>=0.4.0; extra == 'full'
Requires-Dist: langchain-core<2.0.0,>=1.2.22; extra == 'full'
Requires-Dist: langchain-google-genai>=2.0.0; extra == 'full'
Requires-Dist: langchain-openai<2.0.0,>=1.1.14; extra == 'full'
Requires-Dist: langchain-text-splitters<2.0.0,>=1.1.2; extra == 'full'
Requires-Dist: langchain<2.0.0,>=1.3.9; extra == 'full'
Requires-Dist: lark-oapi<2.0.0,>=1.5.0; extra == 'full'
Requires-Dist: matrix-nio>=0.25.2; extra == 'full'
Requires-Dist: mistune<4.0.0,>=3.0.0; extra == 'full'
Requires-Dist: nh3<1.0.0,>=0.2.17; extra == 'full'
Requires-Dist: pillow<13.0.0,>=12.3.0; extra == 'full'
Requires-Dist: pip-audit<3.0.0,>=2.10.1; extra == 'full'
Requires-Dist: pypdf>=6.19.0; extra == 'full'
Requires-Dist: pystray<1.0.0,>=0.19.5; extra == 'full'
Requires-Dist: pywebview<7.0,>=6.2.1; extra == 'full'
Requires-Dist: qq-botpy<2.0.0,>=1.2.0; extra == 'full'
Requires-Dist: slack-sdk<4.0.0,>=3.39.0; extra == 'full'
Requires-Dist: slackify-markdown<1.0.0,>=0.2.0; extra == 'full'
Requires-Dist: wecom-aibot-sdk-python>=0.1.5; extra == 'full'
Provides-Extra: matrix
Requires-Dist: cryptography>=46.0.7; extra == 'matrix'
Requires-Dist: matrix-nio>=0.25.2; extra == 'matrix'
Requires-Dist: mistune<4.0.0,>=3.0.0; extra == 'matrix'
Requires-Dist: nh3<1.0.0,>=0.2.17; extra == 'matrix'
Provides-Extra: mochat
Requires-Dist: msgpack<2.0.0,>=1.2.2; extra == 'mochat'
Requires-Dist: python-socketio<6.0.0,>=5.16.4; extra == 'mochat'
Provides-Extra: qq
Requires-Dist: qq-botpy<2.0.0,>=1.2.0; extra == 'qq'
Provides-Extra: rag
Requires-Dist: beautifulsoup4>=4.15.0; extra == 'rag'
Requires-Dist: faiss-cpu>=1.14.3; extra == 'rag'
Requires-Dist: filelock<4.0.0,>=3.32.5; extra == 'rag'
Requires-Dist: langchain-community<1.0.0,>=0.4.0; extra == 'rag'
Requires-Dist: langchain-core<2.0.0,>=1.2.22; extra == 'rag'
Requires-Dist: langchain-google-genai>=2.0.0; extra == 'rag'
Requires-Dist: langchain-openai<2.0.0,>=1.1.14; extra == 'rag'
Requires-Dist: langchain-text-splitters<2.0.0,>=1.1.2; extra == 'rag'
Requires-Dist: langchain<2.0.0,>=1.3.9; extra == 'rag'
Requires-Dist: pypdf>=6.19.0; extra == 'rag'
Provides-Extra: rag-local
Requires-Dist: beautifulsoup4>=4.15.0; extra == 'rag-local'
Requires-Dist: faiss-cpu>=1.14.3; extra == 'rag-local'
Requires-Dist: filelock<4.0.0,>=3.32.5; extra == 'rag-local'
Requires-Dist: langchain-community<1.0.0,>=0.4.0; extra == 'rag-local'
Requires-Dist: langchain-core<2.0.0,>=1.2.22; extra == 'rag-local'
Requires-Dist: langchain-google-genai>=2.0.0; extra == 'rag-local'
Requires-Dist: langchain-huggingface<2.0.0,>=0.1.0; extra == 'rag-local'
Requires-Dist: langchain-openai<2.0.0,>=1.1.14; extra == 'rag-local'
Requires-Dist: langchain-text-splitters<2.0.0,>=1.1.2; extra == 'rag-local'
Requires-Dist: langchain<2.0.0,>=1.3.9; extra == 'rag-local'
Requires-Dist: pypdf>=6.19.0; extra == 'rag-local'
Requires-Dist: sentence-transformers>=5.6.0; extra == 'rag-local'
Provides-Extra: server
Requires-Dist: pip-audit<3.0.0,>=2.10.1; extra == 'server'
Provides-Extra: slack
Requires-Dist: slack-sdk<4.0.0,>=3.39.0; extra == 'slack'
Requires-Dist: slackify-markdown<1.0.0,>=0.2.0; extra == 'slack'
Provides-Extra: wecom
Requires-Dist: aiohttp<4.0.0,>=3.9.0; extra == 'wecom'
Requires-Dist: wecom-aibot-sdk-python>=0.1.5; extra == 'wecom'
Provides-Extra: windows-native
Requires-Dist: pythonnet<4.0,>=3.0; extra == 'windows-native'
Description-Content-Type: text/markdown

<p align="center">
  <img src="assets/shibaclaw_logo_readme.webp" width="640" alt="ShibaClaw">
</p>

<h1 align="center">ShibaClaw</h1>

<p align="center"><i>Self-hosted, security-first AI agent with a built-in web UI</i></p>

<p align="center">
  <a href="https://pypi.org/project/shibaclaw/"><img src="https://img.shields.io/pypi/v/shibaclaw.svg?style=flat-square&color=orange" alt="version"></a>
  <a href="https://pepy.tech/projects/shibaclaw"><img src="https://static.pepy.tech/personalized-badge/shibaclaw?period=total&units=ABBREVIATION&left_color=YELLOWGREEN&right_color=ORANGE&left_text=downloads" alt="PyPI Downloads"></a>
  <img src="https://img.shields.io/badge/python-%3E%3D3.12-blue?style=flat-square&logo=python&logoColor=white" alt="python">
  <a href="https://github.com/RikyZ90/ShibaClaw/blob/main/LICENSE"><img src="https://img.shields.io/github/license/RikyZ90/ShibaClaw?style=flat-square&label=license&color=blue" alt="license"></a>
  <a href="https://deepwiki.com/RikyZ90/ShibaClaw"><img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki"></a>
</p>

<p align="center">
  <a href="#features">Features</a> ·
  <a href="#quick-start">Quick Start</a> ·
  <a href="#security">Security</a> ·
  <a href="#memory-system">Memory</a> ·
  <a href="#supported-providers">Providers</a> ·
  <a href="#architecture">Architecture</a> ·
  <a href="#channels">Channels</a> ·
  <a href="#troubleshooting">Troubleshooting</a>
</p>

<p align="center">
  🌐 <a href="./README.zh-CN.md">简体中文</a> ·
  <a href="./README.es.md">Español</a> ·
  <a href="./README.pt-BR.md">Português (BR)</a> ·
  <a href="./README.ja.md">日本語</a> ·
  <a href="./README.de.md">Deutsch</a> ·
  <a href="./README.fr.md">Français</a> ·
  <a href="./README.it.md">Italiano</a>
</p>

---

<details open>
<summary>🚀 <b>What's new — v1.0.5</b> (click to expand)</summary>

**Version v1.0.5 (2026-10-16):**

- **Specialist profiles and library** — Adds owner-only `agent_send`, a profile graph, and editable soul and people documents. Agent sessions cannot chain messages; private sessions cannot use `agent_send`.
- **Safer agent runs** — Adds tool-call preflight checks, observation masking, artifact-preserving compaction, circuit breakers, subagent context modes, resource guards, and a CI gate for evolution merges.
- **Subscription login and model selection** — Adds subscription OAuth flows and model pickers to the WebUI.
- **Reliability fixes** — Corrects privacy and concurrent context handling, tool-call protocol, Windows frontmatter, approval fingerprints, profile model allowlists, OAuth handling, and packaged frontend assets.
- **Gemini endpoint validation** — Requires an exact hostname match, blocking lookalike domains from being treated as Google's model catalog.

See [CHANGELOG.md](./CHANGELOG.md) for the full release history.

</details>

---

ShibaClaw is a self-hosted AI agent you run on your own machine or server: a Python engine with a built-in web UI, native SDK support for 28 model providers, and 11 chat-platform integrations (Discord, Telegram, Slack, WhatsApp, Matrix, and more). It's built around three priorities — simplicity, security, and privacy — with defenses like install-time CVE auditing, prompt-injection wrapping, and SSRF protection shipped in the core engine instead of bolted on as external glue.

<p align="center">
  <img src="assets/shibdemo.webp" width="480" alt="ShibaClaw Desktop Demo" style="margin-right: 12px; vertical-align: middle;">
  <img src="assets/shibmobiledemo.webp" width="188" alt="ShibaClaw Mobile Demo" style="vertical-align: middle;">
</p>

> [!NOTE]
> Release notes live in [CHANGELOG.md](./CHANGELOG.md).

## Features

- **Advanced Safety & Resilience (SRE)** — StuckDetector, Cost Circuit Breakers, Context Overflow Guard, Agentic SRE, CheckpointManager, IdempotentSaga, SelfRepair, HardStepCap, SREMonitor, and LayeredDefense
- **Security-first core** — encrypted credentials vault, install-time CVE audit, prompt-injection wrapping, SSRF/DNS-rebinding guard
- **Three-tier memory & WebUI Manager** — working, semantic (FAISS), and procedural memory with interactive WebUI management, live editing, dream diary, and safe quarantine
- **Human-in-the-loop interactive UX** — structured in-turn prompts (`ask_user`), masked vault credentials, progress cards, and dynamic permission sandboxing
- **28 providers, native SDKs** — OpenAI, Anthropic, Gemini, DeepSeek, and more, no LiteLLM proxy layer
- **Web and mobile** — expose the WebUI on your LAN and use the same agent from your phone
- **Windows desktop app** — native launcher with system tray integration
- **MCP-ready** — connect any MCP server, tools are auto-registered

## Quick Start

**Requirements:** Docker, or Python 3.12+ for the pip route. The Windows auto-installer needs neither — it ships a pre-built desktop app.

### Auto-installer (recommended)

One command downloads the latest release, sets up shortcuts, and launches the UI.

> [!TIP]
> Bring your own model: connect to local endpoints (Ollama, LM Studio) or use free API tiers via OpenRouter to start chatting at zero cost.

**🪟 Windows (PowerShell):**
```powershell
irm https://github.com/RikyZ90/ShibaClaw/releases/latest/download/install.ps1 | iex
```

**🐧 Linux / 🍎 macOS:**
```bash
curl -fsSL https://github.com/RikyZ90/ShibaClaw/releases/latest/download/install.sh | bash
```

> [!NOTE]
> On Windows this downloads the pre-built desktop app from the latest GitHub release — no Python required, with Desktop/Start Menu shortcuts and clean uninstall via Apps & Features. On Linux/macOS the script installs via pip in an isolated virtual environment.

### Docker

```bash
curl -fsSL https://raw.githubusercontent.com/RikyZ90/ShibaClaw/main/docker-compose.yml -o docker-compose.yml
docker compose up -d     # pulls from Docker Hub
docker exec -it shibaclaw-gateway shibaclaw print-token
```

Open `http://localhost:3000`, paste the token, and follow the onboarding wizard. Expose `shibaclaw-web` on your LAN (e.g. via reverse proxy) to reach it from your phone.

### pip

```bash
pip install shibaclaw
shibaclaw web --with-gateway   # starts WebUI + agent engine on :3000
```

Open `http://localhost:3000` and follow the onboarding wizard, or run `shibaclaw onboard` for the CLI version of the same setup.

---

## Security

Defenses that are normally scattered across app glue or external proxies ship in the ShibaClaw core, on by default.

| Layer | What it does |
|---|---|
| Install-time audit | Audits `pip` and `npm` before execution — blocks critical/high CVEs |
| Prompt-injection wrap & pre-scan | Wraps every tool result in a randomized `<tool_output_...>` boundary; regex pre-scanning for jailbreaks |
| Shell hardening | 20+ deny patterns, escape normalization, internal URL detection |
| Local-first engine | Native command emulator (`ls`, `cat`) bypasses subprocess overhead; offline `tiktoken` fallback |
| Network guard | SSRF filtering, redirect revalidation, DNS-rebinding-safe resolution |
| Workspace sandbox | File tools and file browser locked to the configured workspace |
| Access control | Bearer token auth, constant-time checks, channel allowlists, optional rate limiting |
| Distributed engine | UI (~128 MB) decoupled from agent brain (~256 MB+) |

Every tool result is wrapped in a dynamically generated boundary with a randomized nonce (e.g. `<tool_output_a1b2c3d4>`), so an attacker can't prematurely close the tag or inject fake system instructions through tool output — the boundary is unpredictable per session.

> [!TIP]
> This wrapping mechanism is also available standalone as [Muzzle](https://github.com/RikyZ90/Muzzle), a zero-dependency Python library you can drop into any agent framework (LangChain, LlamaIndex, CrewAI, AutoGen, or a custom loop).

## Memory System

ShibaClaw uses a three-tier memory architecture:

1. **Working memory** (per session) — rolling context with automatic summarization and token-aware truncation
2. **Semantic memory** (cross-session) — FAISS + sentence-transformers vector store with automatic fact extraction and semantic search
3. **Procedural memory** (skills & automations) — learned workflows saved as reusable skills, plus cron-like schedules

Proactive learning extracts and stores useful facts automatically, auto-compaction keeps context from overflowing, and sessions are stored as append-only JSONL for fast, cache-friendly logging.

## MCP & Integrations

ShibaClaw speaks the Model Context Protocol, so it can connect to any MCP-compliant server — Google Drive, Slack, GitHub, PostgreSQL, and more — without changing core code. Configure servers from the Settings panel.

For popular SaaS tools (Gmail, Google Drive, Slack, GitHub, Outlook...), ShibaClaw integrates with [Klavis](https://klavis.ai): one API key gets you one-click OAuth connections instead of manually registering an OAuth app with each provider. Connected apps are auto-registered as MCP servers in the active session.

## Supported Providers

ShibaClaw uses native SDKs — no LiteLLM proxy — and resolves the provider from the selected model or a provider-prefixed model ID. All configured provider catalogs are merged into one searchable list in the WebUI.

**API key**

| Provider | Env variable |
|---|---|
| OpenAI | `OPENAI_API_KEY` |
| Anthropic | `ANTHROPIC_API_KEY` |
| DeepSeek | `DEEPSEEK_API_KEY` |
| Google Gemini | `GEMINI_API_KEY`¹ |
| Groq | `GROQ_API_KEY` |
| Moonshot | `MOONSHOT_API_KEY` |
| MiniMax | `MINIMAX_API_KEY` |
| Zhipu AI | `ZAI_API_KEY` |
| DashScope | `DASHSCOPE_API_KEY` |

¹ Setting `GEMINI_API_KEY` is sufficient — the OpenAI-compatible endpoint is pre-configured.

**Gateway / proxy** — OpenRouter, AiHubMix, SiliconFlow, VolcEngine, BytePlus, auto-detected by key prefix or `api_base`.

**Local** — Ollama, LM Studio, llama.cpp, vLLM, or any OpenAI-compatible endpoint.

> [!NOTE]
> In Docker, `localhost` points inside the container. To reach a local server on the host (LM Studio, Ollama), use `http://host.docker.internal:PORT` on Windows/macOS or `http://172.17.0.1:PORT` on native Linux.

**OAuth**

| Provider | Flow | Setup |
|----------|------|-------|
| OpenRouter | PKCE browser flow, stores returned API key in provider config | WebUI Settings |
| GitHub Copilot | Device flow, auto token refresh | `shibaclaw provider login github-copilot` or WebUI Settings |
| OpenAI Codex | PKCE browser flow | `shibaclaw provider login openai-codex` or WebUI Settings |
| Google Gemini CLI | PKCE browser flow, requires `SHIBACLAW_GEMINI_OAUTH_CLIENT_ID` and `SHIBACLAW_GEMINI_OAUTH_CLIENT_SECRET` env vars. **Note:** Unofficial third-party integration, Google may apply account restrictions. Use a separate account if this is a concern. | WebUI Settings |

For OpenRouter, the callback reuses the current WebUI URL and port by default, so `http://localhost:3000` is not a dedicated OAuth-only port. If you expose the WebUI behind a reverse proxy or need a different public callback origin, set `SHIBACLAW_OPENROUTER_CALLBACK_BASE_URL=https://your-public-webui-host` before starting the server.

### 💡 Pro Tip: Cost-Effective & Premium Models

ShibaClaw performs exceptionally well even without expensive API usage:
- **Free/Open Models:** We highly recommend using **OpenRouter** to access powerful free models like `nvidia/nemotron-3-super-120b-a12b:free` or `gemma-4-31b-it:free`.
- **Unlimited Premium:** If you use the **GitHub Copilot** OAuth integration, you gain access to premium models like `raptor` (`oswe-vscode-prime`) at zero additional cost, effectively giving you unlimited requests.

***

## 📊 How ShibaClaw Compares (Security-First)

> [!NOTE]
> OpenRouter's OAuth callback reuses the current WebUI URL and port. Behind a reverse proxy, set `SHIBACLAW_OPENROUTER_CALLBACK_BASE_URL` before starting the server.

For zero-cost usage, OpenRouter's free tier (e.g. `nvidia/nemotron-3-super-120b-a12b:free`) and the GitHub Copilot OAuth integration (unlimited access to models like `raptor`) both work well without a paid API key.

## Architecture

<p align="center">
  <img src="assets/arch.png" width="640" alt="ShibaClaw architecture">
</p>

**Docker Compose**

| Service | Role | Default port |
|---|---|---|
| `shibaclaw-gateway` | Core agent loop, message bus, channel integrations | 19999 (HTTP) · 19998 (WS) |
| `shibaclaw-web` | WebUI (Starlette + WebSocket), automations service | 3000 |

Both share the `~/.shibaclaw/` volume (config, workspace, memory, automation jobs, media cache). `shibaclaw web` alone runs agent + WebUI + automations in a single process, no gateway container needed.

**Stack** — Uvicorn/Starlette (ASGI), native WebSocket, vanilla JS + Marked.js + Highlight.js frontend, JSONL append-only sessions.

**Resource usage** — ~120 MB idle / ~350 MB peak per component (gateway, WebUI). Docker Compose caps each container at 512 MB / 256 MB reservation; tool output streams with bounded buffers so long-running commands can't blow up memory.

## CLI Reference

```bash
shibaclaw web               # Start WebUI (agent + automations in-process)
shibaclaw gateway           # Start gateway only (for Docker split)
shibaclaw onboard           # CLI-based first-time setup wizard
shibaclaw agent -m "Hello"  # One-shot message via terminal
shibaclaw agent             # Interactive REPL with history
shibaclaw status            # Provider, workspace, OAuth health check
shibaclaw print-token       # Show WebUI auth token
shibaclaw channels status   # List enabled channels
shibaclaw provider login <p># OAuth login (github-copilot, openai-codex)
shibaclaw desktop           # Launch Windows desktop app
```

## Channels

| Channel | Type | Notes |
|---|---|---|
| WebUI | Built-in | Primary interface, full feature access |
| Discord | Bot | Rich embeds, slash commands, attachments |
| Telegram | Bot | Inline keyboards, media, reply markup |
| WhatsApp | Plugin | Via WhatsApp Web |
| Slack | Bot | Block kit, threads, app mentions |
| DingTalk | Bot | Enterprise messaging |
| Feishu/Lark | Bot | Rich cards, interactive elements |
| QQ | Bot | Group & private messages |
| WeCom | Bot | Workplace communication |
| Matrix | Bot | Decentralized, E2E encryption |
| MoChat | Bot | WeChat ecosystem |

Each channel is configured independently in WebUI Settings and supports hot-reload on config changes.

## Plugin System

ShibaClaw discovers plugins via Python entry points:

- **Channel plugins** — implement `BaseChannel`, discoverable via `shibaclaw.integrations`
- **TTS plugins** — implement `BaseTTS`, discoverable via `shibaclaw.tts`

Built-in: `shibaclaw-channel-whatsapp` (WhatsApp Web) and `shibaclaw-tts-supertonic` (free, offline ONNX speech synthesis, 31 languages). Install or remove plugins from WebUI Settings > Plugins, with hot-reload and version pinning. See [`docs/PLUGINS_DEVELOPMENT_GUIDE.md`](./docs/PLUGINS_DEVELOPMENT_GUIDE.md) to build your own.

## Text-to-Speech

The built-in Supertonic engine runs offline on ONNX (no PyTorch dependency, CPU-only), supports 31 languages with `F1`/`M1` voice profiles and adjustable speed, and plays back through an in-browser widget. Enable it in WebUI Settings > TTS.

## Automation & Scheduling

Background tasks run on cron-like schedules or event triggers (messages, webhooks, system events), in isolated sessions that don't pollute chat history. Manage, monitor, and view logs from the Automations panel; jobs persist across restarts via JSONL storage.

## Knowledge Base (RAG)

Local, privacy-first retrieval-augmented generation: organize documents into named collections (PDF, CSV, HTML, TXT, Markdown), upload via drag-and-drop, and search with a FAISS index over `all-MiniLM-L6-v2` embeddings. The agent can call `knowledge_search` during conversation, or you can target a specific collection with `@kb:name`. It's an optional dependency — install with `pip install shibaclaw[rag]`.

## Safety & Resilience (SRE)

ShibaClaw includes a suite of advanced, production-grade safety and resilience features to ensure reliable and cost-effective execution:

- **StuckDetector**: Monitors agent progress to detect repetitive actions, tool-call loops, or lack of progress, automatically triggering goal reassessment and recovery prompts.
- **Cost Circuit Breakers**: Prevents runaway API costs by enforcing strict budget limits per session and automatically halting execution when thresholds are exceeded.
- **Context Overflow Guard**: A three-threshold guardrail (Warning, Critical, Hard Limit) that manages context window limits with automatic summarization, token compression, and emergency checkpointing.
- **Agentic SRE**: Specialized Monitor, Recovery, and Audit agents that continuously track liveness, progress, and quality, ensuring autonomous self-healing, system stability, and continuous improvement of the core agent loop.
- **CheckpointManager**: Saves and restores agent state to allow seamless resumption of long-running tasks, preventing progress loss, ensuring state consistency, and enabling robust recovery of the execution context, state, memory, and progress tracking capabilities of the core agent loop system architecture design pattern implementation framework library module package bundle component element unit system architecture design pattern architecture design pattern architecture design pattern framework library module package bundle component pattern implementation.
- **IdempotentSaga**: Ensures safe, transactional execution of multi-step tasks with side effects, automatic rollback capabilities, and strict idempotency guarantees.
- **Self-Repair**: Automatically diagnoses and repairs internal control mechanisms upon failure to maintain operational continuity, system integrity, and self-healing capabilities.
- **Hard Step Caps**: Enforces strict limits on the number of execution steps to prevent infinite loops, runaway token consumption, and execution stalls.
- **LayeredDefense**: Integrates all safety and resilience mechanisms into a unified, multi-layered defense system to guarantee robust, fault-tolerant execution and system reliability.

## Troubleshooting

| Problem | Try |
|---|---|
| General status check | `shibaclaw status` |
| Container logs | `docker logs shibaclaw-gateway` / `docker logs shibaclaw-web` |
| WebUI won't connect | Check token with `shibaclaw print-token`, verify port binding |
| Provider errors | `shibaclaw status` shows API key and OAuth state |
| Login fails after upgrading from v0.9.5 | Run `shibaclaw reset-admin` |
| Security policy | [`SECURITY.md`](./SECURITY.md) |

---

<p align="center">
See <a href="./CONTRIBUTING.md">CONTRIBUTING.md</a> to contribute and <a href="./CHANGELOG.md">CHANGELOG.md</a> for release history.
</p>
