SmallClaw: a local-first AI agent framework with single-pass chat handling

SmallClaw tackles a common pain point in AI agent development: coordinating multiple roles like planning, execution, and verification often overwhelms small local models. Instead of a multi-agent pipeline, it opts for a single-pass chat handler that decides in one go whether to respond conversationally or invoke external tools. This architectural choice simplifies interaction with local models that don’t handle multi-role workflows well.

What SmallClaw does and how it is built

SmallClaw is a local-first AI agent framework written in TypeScript and running on Node.js. It enables running AI agents on your machine, leveraging free local language models accessible via Ollama, llama.cpp, or LM Studio, with optional fallback to cloud providers like OpenAI.

The core architectural decision is the single-pass chat handler. Unlike frameworks that separate planning, executing, and verifying steps into distinct agent roles or calls, SmallClaw uses one LLM call per message. This call either produces a conversational response or triggers a tool invocation. This approach is tailored for smaller models that struggle with multi-agent coordination.

The framework exposes a set of structured tools that agents can call. These include surgical line-level file editing, web search with a provider waterfall fallback, Playwright-based browser automation, and terminal command execution. The interface to these tools is delivered through a clean web UI that streams output with Server-Sent Events (SSE) for a responsive experience.

Sessions keep a compact rolling history with pinned context, ensuring that small models operate efficiently without losing essential context. This design targets performance and usability on machines with limited RAM (at least 8GB, with 16GB recommended for coding tasks).

Architectural tradeoffs and code quality

The single-pass chat handler is SmallClaw’s defining feature. Instead of juggling multiple calls for planning, tool execution, and verification — a pattern that often breaks down for smaller models — it condenses the decision-making into one prompt-response cycle. This reduces latency and complexity but places a higher burden on prompt engineering and the LLM’s native tool-calling capabilities.

SmallClaw relies on Ollama’s native tool-calling format, which streamlines how the LLM decides when and how to invoke tools. This dependency means the framework’s effectiveness is closely tied to the quality of the underlying local models and their tool-calling support.

The codebase is TypeScript-based, which helps with type safety and maintainability. The tooling system is modular, allowing new tools or skills to be added via a defined SKILL.md specification. The code is surprisingly clean for a project juggling asynchronous SSE streams, multi-tool coordination, and local/cloud provider fallbacks.

However, the tradeoff is that the single-pass approach may limit complex workflows requiring multi-step reasoning or multi-agent orchestration. The framework’s focus on small local models also means it’s not aimed at heavyweight models or large-scale distributed AI systems.

Installation and quick start

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

verdict

SmallClaw is a pragmatic framework for developers wanting to run AI agents locally with smaller models. Its single-pass chat handler is a solid architectural choice that avoids the complexity and fragility of multi-agent orchestration, a common stumbling block for local AI projects.

The framework is best suited for use cases where local-first operation and tooling integration matter more than heavyweight reasoning or large-scale orchestration. The modular tool system and SSE streaming UI help with practical developer experience.

Limitations include the reliance on specific local model providers and the inherent constraints of small models, especially in handling complex multi-step workflows. The RAM requirements (minimum 8GB) are modest for modern developer machines but worth noting.

If you want a lightweight, local-first AI agent framework with clean code and sensible tradeoffs around tool usage and model capabilities, SmallClaw is worth your time.

LLM-driven browser automation with Browser-Use: a hands-on look — Browser-Use is a Python library enabling LLM-powered AI agents to automate browsers efficiently. It features a custom Ch
LlamaFactory: modular, extensible fine-tuning framework for large language models — LlamaFactory offers a modular Python framework for fine-tuning 100+ LLMs with diverse algorithms and optimizations, incl
Ollama: a unified CLI and API platform for local large language models — Ollama simplifies running and managing open-source large language models locally with a unified CLI and REST API, suppor
OpenAI Codex CLI: local-first AI coding assistant with ChatGPT integration — OpenAI Codex CLI brings AI coding assistance local to your terminal, integrating with ChatGPT plans for powerful hybrid
Jan: a local-first desktop app for large language models with Tauri and Rust — Jan is an open-source desktop app that runs large language models locally using Tauri, Node.js, and Rust. It offers priv

→ GitHub Repo: XposeMarket/SmallClaw ⭐ 245 · TypeScript

Noureddine RAMDI / SmallClaw: a local-first AI agent framework with single-pass chat handling