PicoClaw

The featherweight AI agent that fits anywhere.

Small on purpose. Small is not lesser. Small is enough.

English | 中文

What is PicoClaw?

PicoClaw is an ultra-lightweight personal AI assistant written entirely in Go — not a fork of OpenClaw, NanoBot, or any other agent framework. Inspired by NanoBot, it was rebuilt from the ground up through a "self-bootstrapping" process: the agent itself drove the architecture migration and code optimization.

This repository is the actively maintained, community-driven continuation of sipeed/picoclaw, with ongoing fixes, dependency updates, and new features.

Maintenance status

	Upstream sipeed/picoclaw	This fork
Latest release
Last commit on main

The badges are rendered by shields.io from GitHub, so the table updates automatically. Upstream still receives issue and pull-request activity; the badges describe release and main-branch activity, not whether the upstream project is archived.

See maintenance status for the current comparison and migration notes if you are switching from upstream.

Runs on $10 hardware. Uses 10–20 MB of RAM. Boots in under a second.

Don't let your old hardware gather dust in the basement — give it a second life with PicoClaw!

Features

How it compares

These are reference figures, not a controlled benchmark. OpenClaw's value is a deployment recommendation, NanoBot's is a single Raspberry Pi 4 user report, and PicoClaw's is the estimate for recent builds. OpenClaw and NanoBot do not ship the complete agent as one executable; PicoClaw's size is the measured full default macOS ARM64 build — see the measurement method and other profiles.

Runtime footprint

PicoClaw's idle RSS is 37.9 MiB, with a memory footprint of ≈19 MiB (phys_footprint, what Activity Monitor reports) — the metric behind the "10–20 MB" figure above. Its core ships no full-screen TUI, so "first paint / ready" is the time for the gateway to answer GET /ready. Lighter channel profiles are listed in measured binary sizes.

python3 scripts/bench-picoclaw-runtime.py --binary ./build/picoclaw --runs 15
python3 scripts/bench-agent-tui.py --cmd opencode --runs 3 --keys '\x03'

Hardware Compatibility List — Tested boards from $5 RISC-V devices to Raspberry Pi and Android phones. Your board is missing? Submit a PR!

Install

One-line install (Linux & macOS)

curl -fsSL https://raw.githubusercontent.com/afjcjsbx/picoclaw/main/scripts/install.sh | sh

Windows PowerShell

irm https://raw.githubusercontent.com/afjcjsbx/picoclaw/main/scripts/install.ps1 | iex

The installer detects the CPU architecture, verifies the release checksum, installs both binaries, and starts the launcher. The Web UI opens at http://localhost:18800; on first run, create the dashboard password in the browser.

Precompiled binaries

Download the binary for your platform from GitHub Releases.

Build from source

Prerequisites:

• Go 1.27.3+
• Node.js 22+ and pnpm 10.33.0+ for Web UI and launcher builds

git clone https://github.com/afjcjsbx/picoclaw.git
cd picoclaw

make deps

# Install frontend dependencies
(cd web/frontend && pnpm install --frozen-lockfile)

# Build the core binary for the current platform
make build

# Build the Web UI Launcher (required for Web UI mode)
make build-launcher

# Build core binaries for all Makefile-managed platforms
make build-all

# Build a single target (used by the CI matrix)
make build-target TARGET=linux/arm64
make build-target TARGET=linux/arm GOARM=7

# Build for Raspberry Pi Zero 2 W
make build-pi-zero

# Build and install
make install

Raspberry Pi Zero 2 W: use the binary that matches your OS — 32-bit Raspberry Pi OS: make build-linux-arm; 64-bit: make build-linux-arm64. Or run make build-pi-zero to build both.

make build GO_BUILD_TAGS='goolm,stdjson,custom_channels,channel_telegram'

make build GO_BUILD_TAGS='goolm,stdjson,custom_channels,channel_telegram,no_seahorse'

Quick start

Web UI Launcher (recommended)

The Web UI Launcher provides a browser-based interface for configuration and chat. It is the easiest way to get started — no command-line knowledge required.

Option 1: double-click (desktop)

After downloading from GitHub Releases, double-click picoclaw-launcher (or picoclaw-launcher.exe on Windows). Your browser opens automatically at http://localhost:18800.

Option 2: command line

picoclaw-launcher
# Open http://localhost:18800 in your browser

[!TIP] Remote access / Docker / VM: add the -public flag to listen on all interfaces:

picoclaw-launcher -public

Getting started: open the Web UI, then 1) configure a provider (add your LLM API key) → 2) configure a channel (e.g. Telegram) → 3) start the gateway → 4) chat.

For detailed documentation, see the Web UI & Launcher Guide.

# 1. Clone this repo
git clone https://github.com/afjcjsbx/picoclaw.git
cd picoclaw

# 2. First run — auto-generates docker/data/config.json then exits
#    (only triggers when both config.json and workspace/ are missing)
docker compose -f docker/docker-compose.yml --profile launcher up
# The container prints "First-run setup complete." and stops.

# 3. Set your API keys
vim docker/data/config.json

# 4. Start
docker compose -f docker/docker-compose.yml --profile launcher up -d
# Open http://localhost:18800

# Check logs
docker compose -f docker/docker-compose.yml logs -f

# Stop
docker compose -f docker/docker-compose.yml --profile launcher down

# Update
docker compose -f docker/docker-compose.yml pull
docker compose -f docker/docker-compose.yml --profile launcher up -d

Providers

{
  "model_list": [
    {
      "model_name": "local-llama",
      "model": "ollama/llama3.1:8b",
      "api_base": "http://localhost:11434/v1"
    }
  ]
}

{
  "model_list": [
    {
      "model_name": "local-vllm",
      "model": "vllm/your-model",
      "api_base": "http://localhost:8000/v1"
    }
  ]
}

Channels

Tools

Web search

Other tools

PicoClaw includes built-in tools for file operations, code execution, scheduling, and more. See Tools for details.

Skills

Skills are modular capabilities that extend your agent. They are loaded from SKILL.md files in your workspace.

Install skills from ClawHub:

picoclaw skills search "web scraping"
picoclaw skills install <skill-name>

Configure skill registries under tools.skills.registries:

{
  "tools": {
    "skills": {
      "registries": {
        "clawhub": {
          "enabled": true,
          "base_url": "https://clawhub.ai",
          "auth_token": "your-clawhub-token"
        },
        "github": {
          "enabled": true,
          "base_url": "https://github.com",
          "auth_token": "your-github-token",
          "proxy": ""
        }
      }
    }
  }
}

The ClawHub token is optional and only raises the rate limit. The GitHub token is needed for searches and for private repositories. Pass them via PICOCLAW_SKILLS_REGISTRIES_CLAWHUB_AUTH_TOKEN and PICOCLAW_SKILLS_REGISTRIES_GITHUB_AUTH_TOKEN.

Skills and MCP servers can also be packaged together as portable Agent Plugins 1.0.0. See the plugin guide and the working demo plugin. Mem0 publishes its own Agent Plugin; read the compatibility notes before enabling it.

For more details, see Skills tools.

MCP (Model Context Protocol)

PicoClaw natively supports MCP — connect any MCP server to extend your agent's capabilities with external tools and data sources.

PicoClaw is a lightweight assistant, so remote MCP servers are the best choice. For local servers, prefer natively compiled server binaries and avoid npx, uvx, or other heavyweight dependency managers.

{
  "tools": {
    "mcp": {
      "enabled": true,
      "servers": {
        "browserbase": {
          "enabled": true,
          "deferred": false,
          "command": "",
          "type": "http",
          "url": "https://mcp.browserbase.com/mcp?browserbaseApiKey=API_KEY",
          "headers": {
            "BROWSERBASE_PROJECT_ID": "********"
          }
        }
      }
    }
  }
}

You can manage common MCP setups directly from the CLI instead of editing JSON by hand:

picoclaw mcp list
picoclaw mcp test browserbase

picoclaw mcp is a configuration manager: it updates config.json under tools.mcp.servers, but it does not keep the server process running itself.

Use picoclaw mcp edit when you need advanced fields that are not covered by picoclaw mcp add. For example, picoclaw mcp add supports --deferred and --env-file, while picoclaw mcp edit is still useful for direct JSON editing and uncommon MCP settings.

For full MCP configuration (stdio, SSE, HTTP transports, tool discovery), see MCP tools. For CLI usage and examples, see MCP Server CLI.

Join the Agent Social Network

Connect PicoClaw to the Agent Social Network by sending a single message via the CLI or any integrated chat app:

Read https://clawdchat.ai/skill.md and follow the instructions to join ClawdChat.ai.

CLI reference

Scheduled tasks and reminders

PicoClaw supports scheduled reminders and recurring tasks through the cron tool:

• One-time reminders: "Remind me in 10 minutes" → triggers once after 10 minutes.
• Recurring tasks: "Remind me every 2 hours" → triggers every 2 hours.
• Cron expressions: "Remind me at 9am daily" → uses a cron expression.

See docs/reference/cron.md for current schedule types, execution modes, command-job gates, and persistence details.

Documentation

For detailed guides beyond this README:

Contributing

PRs are welcome! The codebase is intentionally small and readable.

See CONTRIBUTING.md for guidelines.

PicoClaw is built in the open. Come build it with us.

⭐ Star PicoClaw · 💬 Join Discord · 🐛 Report an issue