localclaw 0.3.0.10

A minimal, hackable agentic framework for Ollama and BitNet - local-first AI agent toolkit

🦞 LocalClaw R03

A minimal, hackable agentic framework engineered to run entirely locally with Ollama or BitNet.

Inspired by the architecture of OpenClaw, rebuilt from scratch for local-first operation.

Written by VTSTech · GitHub

---

📚 Documentation

Document	Description
Architecture.md	Technical documentation for developers (directory structure, core design, orchestrator modes)
CHANGELOG.md	Version history and release notes (R00–R03)
TESTS.md	Benchmark results, model recommendations, and testing guide

---

Installation

From PyPI (Recommended)

pip install localclaw

# Or install from GitHub for the latest development version:
pip install git+https://github.com/VTSTech/LocalClaw.git

From Source

git clone https://github.com/VTSTech/LocalClaw.git
cd LocalClaw
pip install -e .

No Installation Required

LocalClaw uses only Python stdlib — no dependencies! You can also just copy the localclaw directory into your project:

cp -r localclaw /path/to/your/project/

---

Quick Start

1. Single prompt

# Simple Q&A
localclaw run "What is the capital of Japan?"

# With streaming output
localclaw run "Tell me a joke." --stream

# Specify a model
localclaw run "Explain quantum computing" -m llama3.2:3b

2. Interactive chat

# Start interactive session
localclaw chat -m qwen2.5-coder:0.5b

# With tools enabled
localclaw chat -m llama3.1:8b --tools calculator,shell,read_file,write_file

# With skills loaded
localclaw chat -m llama3.2:3b --skills skill-creator --tools write_file,shell

# Fast mode (reduced context for speed)
localclaw chat -m qwen2.5-coder:0.5b --fast --verbose

3. Using BitNet backend

localclaw chat --backend bitnet --force-react
localclaw run "Calculate 17 * 23" --backend bitnet --tools calculator

---

Key Features

• Zero dependencies — uses Python stdlib only
• Ollama + BitNet backends — switch with --backend flag
• Native tool calling — auto-detected for supported models, ReAct fallback for others
• Agent Skills — follows Agent Skills specification
• Small model support — fuzzy matching, argument auto-fixing for models ≤1.5B params
• Built-in security — path validation, command blocklist, SSRF protection

---

CLI Commands

Command	Description
run "prompt"	Run single prompt and exit
chat	Interactive multi-turn conversation
models	List available Ollama models with tool support info
tools	List built-in tools
skills	List available Agent Skills
test [example]	Run example/test scripts (--list to see all)
modelfile [model]	Show model's Modelfile system prompt

Key Flags

Flag	Description
-m, --model	Model name (default: qwen2.5-coder:0.5b)
--tools	Comma-separated tool list
--skills	Comma-separated skill list
--backend	ollama or bitnet
--stream	Stream output token-by-token
--fast	Preset: reduced context for speed
-v, --verbose	Show tool calls and timing
--acp	Enable ACP (Agent Control Panel) integration
--use-mf-sys	Use Modelfile system prompt instead of LocalClaw default
--debug	Show debug info (parsed tool calls, fuzzy matching)

Models Command

# List models with family, context size, and tool support
localclaw models

# Test each model for native tool support
localclaw models --tool_support

Output shows:

• Model - Model name
• Family - Model family from Ollama API
• Context - Context window size
• Tool Support - ✓ native, ReAct, ○ none, or ReAct (?) (untested)

🦞 LocalClaw R03 Models
  Model                                      Family       Context    Tool Support
  ──────────────────────────────────────────────────────────────────────────────
  driaforall/tiny-agent-a:1.5b               qwen2        32K        ReAct
  gemma3:270m                                gemma3       32K        ○ none
  granite4:350m                              granite      32K        ✓ native
  qwen2.5-coder:0.5b-instruct-q4_k_m         qwen2        32K        ReAct

  2 model(s) untested. Use --tool_support to detect native support.

Test Command Examples

# List all available tests
localclaw test --list

# Run a quick test suite
localclaw test quick

# Run a specific test
localclaw test 01
localclaw test 07

# Run with ACP integration (activity tracking)
localclaw test 01 --acp
localclaw test 14_acp    # shorthand, auto-enables --acp

# Run with Modelfile system prompt
localclaw test 01 --use-mf-sys --model qwen2.5-coder:0.5b

# Run with debug output
localclaw test 02 --debug --verbose

---

Built-in Tools

Tool	Description
calculator	Evaluate math expressions
python_repl	Execute Python code
shell	Run shell commands
read_file	Read file contents
write_file	Write content to file
list_directory	List directory contents
http_get	HTTP GET request
save_note / get_note	Save and retrieve notes

---

Configuration

Variable	Description	Default
OLLAMA_BASE_URL	Ollama server URL	http://localhost:11434
BITNET_BASE_URL	BitNet server URL	http://localhost:8765
ACP_BASE_URL	ACP (Agent Control Panel) server URL	http://localhost:8766
LOCALCLAW_BACKEND	Backend: ollama or bitnet	ollama
LOCALCLAW_MODEL	Default model	qwen2.5-coder:0.5b-instruct-q4_k_m
LOCALCLAW_SECURITY_MODE	Security mode: strict, permissive, disabled	permissive

---

Setup Ollama

# Make sure Ollama is running:
ollama serve

# Pull a model:
ollama pull qwen2.5-coder:0.5b-instruct-q4_k_m

---

About

🦞 LocalClaw R03 is written and maintained by VTSTech.

• 🌐 Website: https://www.vts-tech.org
• 📦 GitHub: https://github.com/VTSTech/LocalClaw
• 💻 More projects: https://github.com/VTSTech

---

For more details, see:

• Architecture.md — Technical architecture and design decisions
• CHANGELOG.md — Version history and release notes
• TESTS.md — Benchmark results and model recommendations