<img src="assets/SmallClaw.png" alt="SmallClaw logo" width="220" /> <h1 align="center">SmallClaw 🦞</h1> Local-first AI agent framework built for small models, with optional hybrid cloud support. <a href="https://github.com/XposeMarket/SmallClaw/stargazers"> <img src="https://img.shields.io/github/stars/XposeMarket/SmallClaw?style=for-the-badge" alt="Stars" /> </a> <a href="https://github.com/XposeMarket/SmallClaw/network/members"> <img src="https://img.shields.io/github/forks/XposeMarket/SmallClaw?style=for-the-badge" alt="Forks" /> </a> <a href="https://github.com/XposeMarket/SmallClaw/issues"> <img src="https://img.shields.io/github/issues/XposeMarket/SmallClaw?style=for-the-badge" alt="Issues" /> </a> <a href="https://github.com/XposeMarket/SmallClaw/blob/main/LICENSE"> <img src="https://img.shields.io/github/license/XposeMarket/SmallClaw?style=for-the-badge" alt="License" /> </a> <a href="#installation">Install</a> · <a href="#quick-start">Quick Start</a> · <a href="#provider-support">Providers</a> · <a href="#multi-agent-orchestration-optional-skill">Multi Agent</a> · <a href="#skills">Skills</a> · <a href="#troubleshooting">Troubleshooting</a> <img src="assets/SmallClawDashboard.png" alt="SmallClaw UI" width="900" />

SmallClaw v1.1

Local AI agent framework with local + cloud provider support — an open source alternative to cloud AI assistants that runs on your machine with free local models.

Current release: v1.1

Image setup: put the two images in assets/:

assets/SmallClaw.png

assets/SmallClawDashboard.png

What is SmallClaw?

SmallClaw is a chat-first AI agent that supports multiple providers for local-only or hybrid setups (Ollama, llama.cpp, LM Studio, OpenAI API, and OpenAI Codex OAuth). It gives your local model real tools — files, web search, browser automation, terminal commands — delivered through a clean web UI with no API costs, no data leaving your machine.

✅ File operations — Read, write, and surgically edit files with line-level precision
✅ Web search — Multi-provider search (Tavily, Google, Brave, DuckDuckGo) with fallback
✅ Browser automation — Full Playwright-powered browser control (click, fill, snapshot)
✅ Terminal access — Run commands in your workspace safely
✅ Session memory — Persistent chat sessions with pinned context
✅ Skills system — Drop-in SKILL.md files to give the agent new capabilities
✅ Free forever — No API costs, runs on your hardware

Architecture

SmallClaw v2 is built around a single-pass chat handler. When you send a message, one LLM call decides whether to respond conversationally or call tools — no separate planning, execution, and verification agents. This dramatically reduces latency and works much better with small models that struggle to coordinate across multiple roles.

+-----------------------------------------------+
|               Web UI (index.html)             |
|   Sessions · Chat · Process Log · Settings    |
+------------------------+----------------------+
                         |
                   SSE stream + REST
                         |
+-----------------------------------------------+
|          Express Gateway (server-v2.ts)       |
|   Session state · Tool registry · SSE stream  |
+------------------------+----------------------+
                         |
            Native tool-calling + provider API
                         |
+-----------------------------------------------+
|        handleChat() — the core loop           |
|  1) Build system prompt + short history       |
|  2) Single LLM call with tools exposed        |
|  3) Model decides: respond OR call tool(s)    |
|  4) Execute tool → stream result back         |
|  5) Repeat until final response               |
|  6) Stream final text to UI via SSE           |
+------------------------+----------------------+
        |                 |                 |
        v                 v                 v
   File Tools         Web Tools        Browser Tools
(read/write/edit)   (search/fetch)     (Playwright)

How a turn works

Every message goes through the same single path. The model sees the system prompt, a short rolling history (last 5 turns), and your message. It then either responds in plain text or emits a tool call. If it calls a tool, SmallClaw executes it and feeds the result back into the same conversation — the model keeps going until it writes a final text response. The whole thing is streamed back to the UI in real time as SSE events.

There are no separate discuss/plan/execute modes. The model decides in one shot whether a message needs tools or not.

Session state

Each browser session stores a rolling message history (last N turns) and a workspace path. History is kept short on purpose — small models perform better with compact context than with long accumulated histories. Pinned messages let you keep important context permanently in scope without bloating every turn.

How the Tools Work

SmallClaw uses Ollama's native tool-calling format. The model doesn't write code to execute — it returns a structured JSON tool call, SmallClaw runs it in a sandboxed environment, and the result goes back to the model as a tool response message.

File Tools

File editing is surgical. The model is instructed to always read a file with line numbers first, then make targeted edits rather than rewriting entire files. This prevents the common small-model failure of silently dropping content during rewrites.

| Tool | What it does | |------|-------------| | list_files | List workspace directory contents | | read_file | Read file with line numbers | | create_file | Create a new file (fails if already exists) | | replace_lines | Replace lines N–M with new content | | insert_after | Insert content after line N | | delete_lines | Delete lines N–M | | find_replace | Find exact text string and replace it | | delete_file | Delete a file |

Web Tools

| Tool | What it does | |------|-------------| | web_search | Search across providers — returns headlines and snippets | | web_fetch | Fetch and extract the full text of a URL |

Search uses a provider waterfall: Tavily → Google CSE → Brave → DuckDuckGo. You configure API keys and provider preference in Settings → Search. If no keys are set, DuckDuckGo runs without a key as a baseline fallback.

Browser Tools

SmallClaw controls a real browser via Playwright — not just opening a URL for you to click, but navigating, filling forms, and taking snapshots itself.

| Tool | What it does | |------|-------------| | browser_open | Open a URL in a Playwright-controlled browser | | browser_snapshot | Capture current page elements and layout | | browser_click | Click an element by reference ID | | browser_fill | Type into an input field | | browser_press_key | Press Enter, Tab, Escape, etc. | | browser_wait | Wait N ms then snapshot (for dynamic pages) | | browser_close | Close the browser tab |

System Tools

| Tool | What it does | |------|-------------| | run_command | Open an app or file for you to interact with (VS Code, Notepad, Chrome). SmallClaw can open it but not control it. | | start_task | Launch a multi-step background task for long-running operations |

Installation

Prerequisites

Node.js 18+ (Download)
At least one model provider:
- Ollama (Download)
- llama.cpp server
- LM Studio local server
- OpenAI API key
- OpenAI Codex OAuth (ChatGPT account)
At least 8GB RAM (16GB recommended for coding tasks)

Setup

Windows

Clone the repository: git clone https://github.com/xposemarket/smallclaw.git && cd smallclaw
Install dependencies: npm install
Build the project: npm run build
To auto-start on login: Create a Windows Task Scheduler task pointing to:
```
node dist/cli/index.js gateway start
```
(Use the Windows Task Scheduler GUI and set the action to run that command)

macOS

Clone the repository: git clone https://github.com/xposemarket/smallclaw.git && cd smallclaw
Install dependencies: npm install
Build the project: npm run build

To auto-start on login: Create a LaunchAgent at ~/Library/LaunchAgents/com.smallclaw.plist with:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.smallclaw.gateway</string>
    <key>ProgramArguments</key>
    <array>
        <string>/path/to/node</string>
        <string>/path/to/smallclaw/dist/cli/index.js</string>
        <string>gateway</string>
        <string>start</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/tmp/smallclaw.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/smallclaw.err</string>
</dict>
</plist>

Then run: launchctl load ~/Library/LaunchAgents/com.smallclaw.plist

Linux

Clone the repository: git clone https://github.com/xposemarket/smallclaw.git && cd smallclaw
Install dependencies: npm install
Build the project: npm run build

To auto-start on login: Create a systemd service at ~/.config/systemd/user/smallclaw.service with:

[Unit]
Description=SmallClaw AI Gateway
After=network.target

[Service]
Type=simple
WorkingDirectory=/path/to/smallclaw
ExecStart=/usr/bin/node dist/cli/index.js gateway start
Restart=on-failure
RestartSec=10
StandardOutput=append:/tmp/smallclaw.log
StandardError=append:/tmp/smallclaw.err

[Install]
Wante

SmallClaw

Install / Use

README