Metadata-Version: 2.4
Name: localclaw
Version: 0.3.0.3
Summary: A minimal, hackable agentic framework for Ollama and BitNet - local-first AI agent toolkit
Author-email: VTSTech <veritas@vts-tech.org>
Maintainer-email: VTSTech <veritas@vts-tech.org>
License: MIT
Project-URL: Homepage, https://www.vts-tech.org
Project-URL: Documentation, https://github.com/VTSTech/LocalClaw#readme
Project-URL: Repository, https://github.com/VTSTech/LocalClaw
Project-URL: Issues, https://github.com/VTSTech/LocalClaw/issues
Project-URL: Changelog, https://github.com/VTSTech/LocalClaw/blob/main/CHANGELOG.md
Keywords: ai,agent,llm,ollama,bitnet,local-ai,agentic,tool-use,function-calling,cli
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Terminals
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"

# 🦞 LocalClaw R03

A minimal, hackable agentic framework engineered to run **entirely locally** with [Ollama](https://ollama.com) or [BitNet](https://github.com/microsoft/BitNet).

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

**Written by [VTSTech](https://www.vts-tech.org)** · [GitHub](https://github.com/VTSTech/LocalClaw)

---

## 📚 Documentation

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

---

## Installation

### From PyPI (Recommended)

```bash
pip install localclaw

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

### From Source

```bash
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:

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

---

## Quick Start

### 1. Single prompt

```bash
# 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

```bash
# 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

```bash
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](https://agentskills.io/)
- **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 |
| `tools` | List built-in tools |
| `skills` | List available Agent Skills |
| `test [example]` | Run example/test scripts (`--list` to see all) |

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

---

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

```bash
# 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](https://www.vts-tech.org)
- 📦 GitHub: [https://github.com/VTSTech/LocalClaw](https://github.com/VTSTech/LocalClaw)
- 💻 More projects: [https://github.com/VTSTech](https://github.com/VTSTech)

---

For more details, see:
- [Architecture.md](Architecture.md) — Technical architecture and design decisions
- [CHANGELOG.md](CHANGELOG.md) — Version history and release notes
- [TESTS.md](TESTS.md) — Benchmark results and model recommendations
