SmallClaw
Local-first AI agent framework with multi-provider LLM support, 40+ tools, multi-agent orchestration, and channel integrations.
Features &
Install &
Quick Start &
Tools &
Multi-Agent &
Channels &
Docker
**Current release:** `v3.0.9`
---
## Features
- **Multi-provider LLM** — Ollama, llama.cpp, LM Studio, OpenAI API, OpenAI Codex OAuth
- **50+ built-in tools** — Files, shell, web search, browser automation, email, PDF, PPTX, SQLite, Python eval, OCR, STT/TTS, and more
- **Multi-agent orchestration** — Spawn sub-agents, delegate tasks, parallel or sequential execution
- **Channel integrations** — Telegram, Discord, WhatsApp with file browser and inline controls
- **MCP support** — Connect external Model Context Protocol servers (stdio or HTTP/SSE)
- **Skills system** — Drop-in SKILL.md files for domain-specific capabilities; standalone Skill Apps run as independent UI panels
- **Session memory** — Persistent chat sessions with pinned context and compaction
- **Cron scheduling** — Autonomous agent runs on configurable schedules
- **Self-repair** — Detect and propose fixes for its own source code
- **Security** — Vault for secrets, log scrubbing, credential handler, error audit
- **Docker-ready** — Full containerized setup with voice support variant
- **Music App** — Guitar Pro viewer (AlphaTab + SF2), MIDI editor with piano roll, step-sequencer drum machine, beat-synced looper
- **Free forever** — No API costs when using local models
## Architecture
SmallClaw uses a reactor-based execution loop. Each turn, the model receives the system prompt (composed from workspace personality files, skill context, and session history), then either responds conversationally or calls tools. Tool results feed back into the same conversation until the model produces a final answer. Everything streams to the UI in real time via SSE.
```
Web UI / Telegram / Discord / WhatsApp
|
REST + SSE / WS
|
+-------------------------------------------------------------------+
| Express Gateway (server-v2.ts) |
| Session manager · Tool registry · Cron scheduler · MCP manager |
| Heartbeat runner · Webhook handler · Sub-agent manager |
+----------------------------+--------------------------------------+
|
Reactor loop (reactor.ts)
1) Build system prompt + history
2) LLM call with tools exposed
3) Execute tool calls → feed results back
4) Repeat until final response
5) Stream to UI / channels
|
+---------+---------+---------+---------+
| | | | |
File Web Browser Email Shell
Tools Tools Tools Tools Tools
| | | | |
Memory Scholar Desktop PPTX/PDF Python
Tools Tools Tools Tools Tools
```
### Workspace personality files
Markdown files in `workspace/` shape the agent's behavior and memory:
| File | Purpose |
|------|---------|
| `SOUL.md` | Core personality and behavioral guidelines |
| `IDENTITY.md` | Name, role, and self-concept |
| `USER.md` | User preferences and context |
| `MEMORY.md` | Persistent memory and learned facts |
| `AGENTS.md` | Available agents and their roles |
| `TOOLS.md` | Tool usage guidelines |
| `BOOT.md` | Startup instructions and boot tasks |
## Tools
SmallClaw ships with 40+ tools organized into categories. Tools are exposed via Ollama native tool-calling format — the model returns structured JSON, SmallClaw executes it sandboxed, and the result feeds back.
### File Tools
| Tool | Description |
|------|-------------|
| `read` | Read file with line numbers |
| `write` | Create a new file |
| `edit` | Replace exact text strings in a file |
| `list` | List directory contents |
| `delete` | Delete a file |
| `rename` | Rename a file |
| `copy` | Copy a file |
| `mkdir` | Create directories |
| `stat` | Get file metadata |
| `append` | Append content to a file |
| `apply_patch` | Apply a unified diff patch |
### Shell & System
| Tool | Description |
|------|-------------|
| `shell` | Run shell commands in workspace |
| `python_eval` | Evaluate Python code |
| `sqlite_query` | Execute SQLite queries |
| `time_now` | Get current date/time |
| `spawn_agent` | Spawn a sub-agent for a task |
| `task_control` | List, create, update, cancel background tasks |
### Web & Research
| Tool | Description |
|------|-------------|
| `web_search` | Multi-provider search (Tavily, Google, Brave, DuckDuckGo, SearXNG) |
| `web_fetch` | Fetch and extract text from a URL |
| `pubmed_search` | Search PubMed/NCBI literature |
| `pubmed_fetch` | Fetch PubMed abstract by PMID |
| `pubmed_fulltext` | Fetch full-text from PMC |
| `openalex_search` | Search OpenAlex academic index |
| `semantic_search` | Search Semantic Scholar |
| `weather` | Get weather data |
### Browser Automation (Playwright)
| Tool | Description |
|------|-------------|
| `browser_open` | Open URL in Playwright browser |
| `browser_snapshot` | Capture page elements and layout |
| `browser_click` | Click element by reference ID |
| `browser_fill` | Type into an input field |
| `browser_press_key` | Press Enter, Tab, Escape, etc. |
| `browser_wait` | Wait then snapshot (for dynamic pages) |
| `browser_scroll` | Scroll the page |
| `browser_close` | Close browser tab |
| `browser_get_images` | Collect images from page |
### Desktop Automation
| Tool | Description |
|------|-------------|
| `desktop_screenshot` | Capture desktop screenshot |
| `desktop_find_window` | Find a window by title |
| `desktop_focus_window` | Bring window to foreground |
| `desktop_click` | Click at screen coordinates |
| `desktop_drag` | Drag between coordinates |
| `desktop_wait` | Wait N milliseconds |
| `desktop_type` | Type text at focused position |
| `desktop_press_key` | Press keyboard key |
| `desktop_get_clipboard` | Read clipboard contents |
| `desktop_set_clipboard` | Write to clipboard |
### Email (IMAP + SMTP)
| Tool | Description |
|------|-------------|
| `email_list` | List emails in a folder |
| `email_read` | Read a specific email |
| `email_send` | Send an email |
| `email_search` | Search emails by criteria |
| `email_delete` | Delete an email |
### Documents & Media
| Tool | Description |
|------|-------------|
| `pdf_read` | Extract text from PDF files |
| `pptx_create` | Generate PowerPoint presentations |
| `pptx_edit` | Edit existing PowerPoint files |
| `image_read` | Read/OCR images (Tesseract.js) |
| `audio_transcribe` | Transcribe audio via Whisper |
### Memory & Persona
| Tool | Description |
|------|-------------|
| `memory_search` | Search stored memories (semantic/MMR) |
| `memory_write` | Store a new memory |
| `memory_read` | Read memories by ID |
| `memory_file_search` | Search files in memory store |
| `persona_read` | Read current persona configuration |
| `persona_update` | Update persona settings |
### Skills & Self-Management
| Tool | Description |
|------|-------------|
| `skill_list` | List installed skills |
| `skill_search` | Search ClawHub skill registry |
| `skill_install` | Install a skill from registry |
| `skill_remove` | Remove an installed skill |
| `skill_exec` | Execute a skill |
| `self_update` | Check and apply SmallClaw updates |
| `read_source` | Read SmallClaw own source files |
| `list_source` | List SmallClaw source files |
| `propose_repair` | Propose a self-repair for a bug |
### Tool Profiles
Agents can be assigned tool profiles to limit their capabilities:
| Profile | Description |
|---------|-------------|
| `minimal` | memory_search, memory_write, time_now |
| `coding` | shell, file tools, python, sqlite, pdf, image, audio |
| `web` | web tools, pubmed, scholar, pdf, image |
| `full` | All registered tools (default) |
## Music App
SmallClaw ships a browser-based music workstation at `/music-app.html`:
### Guitar Pro Viewer
- Loads `.gp` / `.gp3` – `.gp7` files via AlphaTab
- Renders standard notation + tablature with dark-theme support
- SF2 playback (GeneralUser GS) or forward to an external MIDI port
- Per-track mute / solo / volume, master volume up to 200%, BPM control
- Global FX chain: reverb, chorus, delay, compressor
### MIDI Editor
- Piano-roll editor with multi-track support
- SpessaSynth (AudioWorklet) SF2 playback or Web MIDI output
- Parses format 0 / 1 MIDI files: preserves notes, program changes, and all CC events (volume, expression, pan, sustain, etc.)
- Multi-channel tracks automatically split per channel on load
- Solo / mute with real-time sequencer reload (no stop/restart needed)
- Loop in/out markers, quantize, undo/redo, velocity editor
### Drum Machine
- 16-step sequencer with swing
- Real audio samples + synthesis fallback
- Sync to looper BPM
### Looper
- Mic recording synced to drum grid
- Phase-aligned beat loop recording
## Multi-Agent Orchestration
SmallClaw supports two multi-agent modes:
### Delegate to Specialist (default, `subagent_mode: false`)
Designed for 4B local models. Fixed specialist roles with structured I/O, sequential execution. The primary agent delegates to named sub-agents with restricted tool profiles (file_editor, researcher, shell_runner, reader_only). Recursion is prevented at the profile level.
### Sub-Agent Spawn (`subagent_mode: true`)
Free-form arbitrary task prompts (Claude Cowork-style). Parallel execution. Primary agent acts as orchestrator. Best for larger models.
```
Parent task calls delegate_to_specialist / subagent_spawn
|
Child task created with profile + instructions
|
Parent status -> 'waiting_subagent'
|
Child BackgroundTaskRunner executes independently
|
Child completes -> result injected into parent context
|
Parent resumes automatically
```
### Agent Definitions
Define named agents in `.smallclaw/config.json`:
```jsonc
{
"agents": [
{
"id": "main",
"name": "Rafi",
"description": "Main daily assistant",
"emoji": "🦞",
"default": true,
"tools": { "profile": "full" },
"minimalPrompt": false
},
{
"id": "researcher",
"name": "Scout",
"description": "Deep web research",
"emoji": "🔍",
"model": "ollama/qwen3:4b",
"tools": { "profile": "web", "deny": ["browser"] },
"minimalPrompt": true,
"maxSteps": 10
},
{
"id": "orchestrator",
"name": "Director",
"description": "Coordinates other agents on a cron schedule",
"emoji": "🎬",
"tools": { "profile": "full" },
"canSpawn": true,
"spawnAllowlist": ["researcher", "writer"],
"cronSchedule": "0 8 * * *"
}
]
}
```
## Channels
SmallClaw integrates with messaging platforms:
### Telegram
- Long-polling bot (no port forwarding needed)
- File browser: `/browse [path]` with inline keyboard navigation
- File download: `/download ` as Telegram attachment
- Allowed user ID allowlist
- Streaming or partial response modes
### 카카오톡
- 오픈빌더 챗봇 웹훅 — 채널 가입자 누구나 1:1 AI 대화
- 비동기 콜백 방식으로 오픈빌더 5초 제한 우회
- "나에게 보내기" OAuth — 서버 이벤트를 본인 카카오톡으로 수신
- userId → SmallClaw 계정 유저맵으로 다중 사용자 지원
- 자세한 설정: [docs/kakao-setup.md](docs/kakao-setup.md)
### Discord
- Webhook-based integration
- Bot token + guild/channel configuration
### WhatsApp
- Business API integration
- Access token + phone number ID configuration
## MCP Integrations
Connect external MCP (Model Context Protocol) servers from Settings -> Integrations:
- **stdio transport** — spawn a local process (e.g., filesystem, database MCP servers)
- **HTTP/SSE transport** — connect to remote MCP servers
- Configure auth and env values per server
- MCP tools become available to the agent after saving
## Installation
### Prerequisites
1. **Node.js** 18+
2. **At least one model provider**: Ollama, llama.cpp server, LM Studio, OpenAI API, or OpenAI Codex OAuth
3. **At least 8GB RAM** (16GB recommended for coding tasks)
### Option A: npm Global Install
```bash
npm install -g smallclaw
smallclaw onboard
smallclaw gateway start
```
Then open `http://localhost:18789`.
### Option B: From Source
```bash
git clone https://github.com/xposemarket/smallclaw.git
cd smallclaw
npm install
npm run build
npm start
```
### Auto-Start on Login
#### Linux (systemd)
```ini
# ~/.config/systemd/user/smallclaw.service
[Unit]
Description=SmallClaw AI Gateway
After=network.target
[Service]
Type=simple
ExecStart=/usr/bin/smallclaw gateway start
Restart=on-failure
RestartSec=10
StandardOutput=append:/tmp/smallclaw.log
StandardError=append:/tmp/smallclaw.err
[Install]
WantedBy=default.target
```
```bash
systemctl --user daemon-reload
systemctl --user enable smallclaw
systemctl --user start smallclaw
```
#### macOS (LaunchAgent)
Create `~/Library/LaunchAgents/com.smallclaw.plist` and load with `launchctl load`.
#### Windows (Task Scheduler)
Create a task pointing to: `smallclaw gateway start`
## Quick Start
```bash
npm install -g smallclaw
smallclaw onboard
smallclaw gateway start
```
Open `http://localhost:18789` in your browser.
### 1. Pull a model
```bash
# Lightweight — great for 8GB RAM
ollama pull qwen3:4b
# Better at code — needs 16GB+ RAM
ollama pull qwen2.5-coder:32b
```
### 2. Configure models and search
In the web UI, open Settings:
- **Models** — choose provider + model
- **Search** — add API keys for Tavily, Google, or Brave
- **Channels** — configure Telegram/Discord/WhatsApp
- **Integrations** — add MCP servers
### 3. Test webhooks
See [WEBHOOKS.md](./WEBHOOKS.md) for curl examples and webhook endpoint testing.
## Configuration
Config is stored in `.smallclaw/config.json` in the project folder (or `~/.smallclaw/config.json` as fallback):
```json
{
"models": {
"primary": "qwen3:4b",
"roles": {
"manager": "qwen3:4b",
"executor": "qwen3:4b",
"verifier": "qwen3:4b"
}
},
"ollama": {
"endpoint": "http://localhost:11434"
},
"search": {
"preferred_provider": "tavily",
"tavily_api_key": "",
"google_api_key": "",
"google_cx": "",
"brave_api_key": "",
"searxng_url": "",
"search_rigor": "verified"
},
"workspace": {
"path": "path/to/your/workspace"
},
"voice": {
"enabled": true,
"stt": { "provider": "whisper_cpp", "model": "base" },
"tts": { "provider": "piper", "model": "ko_KR-kss-medium" }
},
"orchestration": {
"enabled": true,
"secondary": { "provider": "", "model": "" },
"subagent_mode": false
}
}
```
Most settings can be changed live from the Settings panel without restarting.
## Provider Support
| Provider | Type | Auth |
|----------|------|------|
| `ollama` | Local | None |
| `llama_cpp` | Local (OpenAI-compatible) | Optional API key |
| `lm_studio` | Local (OpenAI-compatible) | Optional API key |
| `openai` | Cloud | API key |
| `openai_codex` | Cloud | ChatGPT OAuth |
Provider selection is live through the web Settings API.
## CLI Commands
```bash
# Gateway
smallclaw gateway start # Start the web UI gateway
smallclaw gateway status # Check gateway status
# Model management
smallclaw model list # List available local models
smallclaw model set qwen3:4b # Set primary model
smallclaw model pull llama-3.3:70b # Pull a new model
# System
smallclaw doctor # Health check
smallclaw update check # Check for updates
smallclaw update # Apply updates
```
## Model Recommendations
### 8GB RAM
- **qwen3:4b** — Fast, solid for everyday tasks, file editing, web lookups
### 16GB RAM
- **qwen2.5-coder:32b** — Noticeably better at multi-file code tasks and tool sequencing
- **deepseek-coder-v2:16b** — Strong alternative for code understanding
### 32GB+ RAM
- **llama-3.3:70b** — Best reasoning and planning, handles complex multi-step tasks well
## Optimizing for Small Models
SmallClaw is designed around the constraints of 4B-32B parameter models:
- **Short history window** — Only the last 5 turns are sent by default, keeping context tight
- **Line-number-first file editing** — Forces the model to read before writing, preventing content loss
- **Native tool-calling** — Uses structured tool format instead of free-form code generation
- **Tool profiles** — Restrict sub-agents to minimal tool sets to reduce decision space
- **Surgical edits over rewrites** — `edit`, `apply_patch` instead of full file rewrites
- **Session compaction** — Automatic history compression when context grows too large
## Voice Support
SmallClaw supports voice input and output when configured:
- **STT**: Whisper C++ for speech-to-text
- **TTS**: edge-tts (Microsoft Azure neural voices, e.g. `ko-KR-SunHiNeural`) — recommended for Korean; Piper also supported
- **Language**: Configurable (default: Korean)
- **Docker**: Use `docker-compose.voice.yml` + `Dockerfile.voice` for a voice-enabled container
## Self-Repair & Self-Update
SmallClaw can inspect and repair its own source code:
- `read_source` / `list_source` — Read its own source files
- `propose_repair` — Propose a fix for a detected bug
- `self_update` — Check for and apply SmallClaw updates
```bash
smallclaw update check # Check for updates
smallclaw update # Apply updates
```
## Security
- **Vault** — Encrypted storage for API keys and credentials
- **Log scrubbing** — Automatic removal of sensitive data from logs
- **Credential handler** — Safe credential management for external services
- **Error audit** — Track and audit error patterns for security anomalies
- **Error categorizer** — Classify errors by severity and type
## Docker Setup
### Quick Start (Bundled Ollama)
```bash
docker compose down
docker compose build --no-cache
docker compose --profile ollama up -d
```
Open `http://your-server-ip:18789`.
### External Ollama (Already Running)
```bash
# In .env:
SMALLCLAW_PROVIDER=ollama
OLLAMA_HOST=http://your-ollama-container:11434
# Start only the gateway:
docker compose up -d smallclaw
```
### Voice-Enabled Container
```bash
docker compose -f docker-compose.voice.yml up -d
```
### Custom Host Port
```bash
# In .env:
HOST_PORT=8080
# Docker maps: host:8080 -> container:18789
```
### Environment Variables (Docker)
| Variable | Default | Description |
|---|---|---|
| `HOST_PORT` | `18789` | Host port to expose SmallClaw on |
| `GATEWAY_PORT` | `18789` | Internal container port (do not change) |
| `GATEWAY_HOST` | `0.0.0.0` | Bind address inside container |
| `DOCKER_CONTAINER` | `true` | Auto-set in Dockerfile; enables 0.0.0.0 binding |
## Troubleshooting
### "Cannot connect to Ollama"
```bash
ollama serve
curl http://localhost:11434/api/tags
```
### "No models found" in Settings
```bash
ollama pull qwen3:4b
ollama list
```
### "Out of memory / model crashes"
- Drop to a smaller model (qwen3:4b instead of 32b)
- Close other memory-intensive apps
- Set `llm_workers: 1` in config for concurrent users
### Tool calls not working
- Confirm a model is selected and saved in Settings
- qwen3 and qwen2.5-coder series handle tool-calling best
- Try a larger model variant if tools are ignored
### Docker: Web UI unreachable
1. **Bind address** — Must be `0.0.0.0` inside Docker (handled by `DOCKER_CONTAINER=true`)
2. **Port mismatch** — Use `HOST_PORT` not `GATEWAY_PORT` for remapping
3. **Stale image** — Rebuild with `--no-cache`
## Roadmap
- [x] Reactor-based native tool-calling architecture
- [x] Session-based chat UI with compaction
- [x] 50+ tools across files, web, browser, email, documents, memory
- [x] Multi-agent orchestration (delegate + sub-agent spawn)
- [x] Channel integrations (Telegram, Discord, WhatsApp)
- [x] MCP server support
- [x] Voice input/output (Whisper + edge-tts)
- [x] Desktop automation
- [x] Self-repair and self-update
- [x] Cron scheduling for autonomous runs
- [x] Docker containerization
- [x] Music App — Guitar Pro viewer, MIDI editor, drum machine, looper
- [x] Skill Apps — standalone UI panels for domain-specific workflows
- [ ] Persistent sessions across gateway restarts
- [ ] Git operations tool
- [ ] Desktop app wrapper
## Contributing
Feel free to donate if this helped you save API costs — Cashapp $Fvnso / Venmo @Fvnso.
## License
MIT
## Credits
Inspired by [OpenClaw](https://openclaw.ai) and the Anthropic team. Built for the local-first AI community.