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:

{
  "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 <path> as Telegram attachment
• Allowed user ID allowlist
• Streaming or partial response modes

카카오톡

• 오픈빌더 챗봇 웹훅 — 채널 가입자 누구나 1:1 AI 대화
• 비동기 콜백 방식으로 오픈빌더 5초 제한 우회
• "나에게 보내기" OAuth — 서버 이벤트를 본인 카카오톡으로 수신
• userId → SmallClaw 계정 유저맵으로 다중 사용자 지원
• 자세한 설정: 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

npm install -g smallclaw
smallclaw onboard
smallclaw gateway start

Then open http://localhost:18789.

Option B: From Source

git clone https://github.com/xposemarket/smallclaw.git
cd smallclaw
npm install
npm run build
npm start

Auto-Start on Login

Linux (systemd)

# ~/.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

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

npm install -g smallclaw
smallclaw onboard
smallclaw gateway start

Open http://localhost:18789 in your browser.

1. Pull a model

# 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 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):

{
  "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

# 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

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)

docker compose down
docker compose build --no-cache
docker compose --profile ollama up -d

Open http://your-server-ip:18789.

External Ollama (Already Running)

# In .env:
SMALLCLAW_PROVIDER=ollama
OLLAMA_HOST=http://your-ollama-container:11434

# Start only the gateway:
docker compose up -d smallclaw

Voice-Enabled Container

docker compose -f docker-compose.voice.yml up -d

Custom Host Port

# 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"

ollama serve
curl http://localhost:11434/api/tags

"No models found" in Settings

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

• Reactor-based native tool-calling architecture
• Session-based chat UI with compaction
• 50+ tools across files, web, browser, email, documents, memory
• Multi-agent orchestration (delegate + sub-agent spawn)
• Channel integrations (Telegram, Discord, WhatsApp)
• MCP server support
• Voice input/output (Whisper + edge-tts)
• Desktop automation
• Self-repair and self-update
• Cron scheduling for autonomous runs
• Docker containerization
• Music App — Guitar Pro viewer, MIDI editor, drum machine, looper
• 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 and the Anthropic team. Built for the local-first AI community.