CloseClaw is an open-source Python framework for running a local AI agent on your own hardware with Ollama-backed models, local tools, optional voice, and hardware plus simulation primitives for robotics and edge AI workflows.
If you are looking for a robot operating system, a local LLM stack for robots, or an offline-first AI runtime for Raspberry Pi, Jetson, workshop PCs, and secure edge devices, CloseClaw is the hackable local-first path. It is designed for people who want an agent they can inspect, modify, and run without shipping chat history or tool output to a hosted SaaS.
Important
CloseClaw is currently alpha software. The core runtime and test suite are strong, but the project is still evolving and the public API may change.
Today, the repository includes:
- A local CLI chat agent backed by Ollama
- Hardware detection with model recommendations for constrained devices
- Built-in local tools for shell, file reads/writes, and file search
- A TOML-based skill system for lightweight local automation
- Conversation history stored locally in SQLite
- A small REST API server for embedding CloseClaw in other systems
- Optional offline voice plumbing with graceful fallbacks when dependencies are missing
- Simulation, body, and brain modules aimed at robotics and embodied-agent experimentation
Most agent frameworks are optimized for cloud APIs first and local hardware second.
CloseClaw starts from a different assumption: if you are running on a Raspberry Pi, Jetson, Mac mini, workshop PC, or a robot on a private network, local control matters. That means:
- local model serving
- local memory
- local tools
- inspectable Python code
- graceful degradation when hardware is missing
Once your dependencies and local models are installed, CloseClaw can run entirely on your own machine.
git clone https://github.com/BitmapAsset/CloseClaw.git
cd CloseClaw
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -e .
closeclaw init
closeclaw chatcurl -fsSL https://raw.githubusercontent.com/BitmapAsset/CloseClaw/main/install.sh | shThe installer:
- detects your OS and hardware
- installs the Python package into
~/.closeclaw/venv - places
closeclawandclawdwrappers in~/.local/bin - runs the first boot sequence
Voice support is intentionally optional.
python3 -m pip install -e ".[voice]"CloseClaw will still run without voice packages. Missing voice components fall back cleanly instead of hard-failing startup.
These commands are implemented in the current codebase:
closeclaw init # detect hardware, create config, help with model setup
closeclaw chat # start an interactive local chat session
closeclaw info # system info + voice support + available models
closeclaw detect # hardware detection summary
closeclaw model list # list local Ollama models
closeclaw model pull gemma4:e4b # pull a model through Ollama
closeclaw skills list # list bundled and user skills
closeclaw skills run hello name=Pi
closeclaw history list # browse local conversation history
closeclaw serve --host 127.0.0.1 --port 8765
closeclaw simulate --hours 2 --environment warehouse
closeclaw body # hardware/body report
closeclaw brain # memory/brain report
closeclaw genesis # first-boot sequence
closeclaw daemon statusCloseClaw is especially useful when you want a local agent adjacent to hardware.
closeclaw detect
closeclaw info
closeclaw bodycloseclaw simulate --hours 4 --environment homeThe simulation environment is text-based and stdlib-only, which makes it useful for CI, dry runs, and robotics experiments on laptops that do not have GPIO or sensors attached.
closeclaw serve --host 127.0.0.1 --port 8765This is handy for local dashboards, kiosk apps, workshop tools, or robot control panels that need a simple HTTP interface.
CloseClaw ships with a lightweight skill format built around skill.toml plus a local entrypoint script.
Bundled example skills in this repo include:
hellocalculatornotessysinfo
List them:
closeclaw skills listRun one directly:
closeclaw skills run calculator expression="(3 * 7) + 2"User-installed skills live in ~/.closeclaw/skills.
Start the server:
closeclaw serve --host 127.0.0.1 --port 8765Available endpoints:
GET /healthGET /modelsGET /skillsGET /hardwarePOST /chat
Example:
curl http://127.0.0.1:8765/health
curl -X POST http://127.0.0.1:8765/chat \
-H 'Content-Type: application/json' \
-d '{"message":"Summarize the files in this folder","stream":false}'python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -e ".[dev]"
python3 -m pytest -q
ruff check closeclaw testsThe current tree passes 1,186 tests.
PRs are welcome, especially around:
- hardware detection on more devices
- robotics and embodied-agent integrations
- local skill examples
- install and packaging polish
- docs and reproducible test coverage
See CONTRIBUTING.md.
MIT, see LICENSE.