PicoClaw is an ultra-lightweight AI agent written in Go that runs on $10 hardware with <10MB RAM. It connects to LLM providers, executes tools, talks through messaging channels, and evolves its monitoring strategies over time through a built-in Gene Evolution Protocol.
Originally inspired by nanobot, PicoClaw was refactored from the ground up in Go through a self-bootstrapping process where the AI agent drove the entire migration.
|
|
|
PicoClaw is a single Go binary that:
- Connects to an LLM (Zhipu, OpenRouter, Anthropic, OpenAI, Gemini, Groq, or any vLLM endpoint)
- Executes tools (12 built-in: file I/O, shell exec, web search/fetch, cron, messaging, gene reporting)
- Talks through channels (Telegram, Discord, QQ, DingTalk, Feishu, WhatsApp, MaixCam)
- Learns from experience via the Gene Evolution Protocol — successful monitoring strategies are solidified into reusable "genes"
- Reports to fleet via an optional Edge API server for multi-node coordination
| OpenClaw (TS) | NanoBot (Python) | PicoClaw (Go) | |
|---|---|---|---|
| RAM | >1 GB | >100 MB | < 10 MB |
| Boot (0.8 GHz) | >500 s | >30 s | < 1 s |
| Min Hardware | Mac Mini $599 | SBC ~$50 | Any Linux $10 |
| Binary | Node runtime | Python runtime | Single static binary |
cmd/picoclaw/main.go CLI entry point (onboard|agent|gateway|status|cron|skills|gene|version)
pkg/
agent/ Agent loop, context builder, memory manager
bus/ Internal message bus
channels/ 7 messaging channels (telegram, discord, qq, dingtalk, feishu, whatsapp, maixcam)
config/ JSON + env var configuration (agents, channels, providers, gateway, edge, gene)
cron/ Cron scheduler service
edge/ Edge API server + fleet heartbeat reporter
gene/ Gene Evolution Protocol (CGEP) engine
├── types.go Gene, Capsule, EvolutionEvent, StrategyPreset structs
├── store.go JSON file persistence (genes.json, capsules.json, events.jsonl)
├── selector.go Gene scoring, selection, drift intensity computation
├── solidify.go Experience solidification into Capsules and Genes
├── signals.go Signal extraction from text/memory (8 signal types)
├── engine.go Top-level orchestrator
├── seeds.go 6 built-in seed genes
└── hash.go SHA-256 content-addressable asset IDs
heartbeat/ Periodic heartbeat service
logger/ Structured JSON logger
providers/ Unified HTTP LLM provider (OpenRouter, Anthropic, OpenAI, Gemini, Zhipu, Groq, vLLM)
session/ Conversation session manager
skills/ Skill loader + installer (from Git repos)
tools/ 12 tools: read_file, write_file, edit_file, append_file, list_dir,
exec, spawn, web_search, web_fetch, message, cron, report_gene
utils/ String utilities
voice/ Groq Whisper voice transcription
skills/ 6 built-in skills (datacenter-monitoring, github, summarize, weather, tmux, skill-creator)
1. Build
git clone https://github.com/Clawland-AI/picclaw.git
cd picclaw
make build # Single binary in build/
# or: make build-all for linux/darwin x amd64/arm64/riscv642. Initialize
picoclaw onboard3. Configure (~/.picoclaw/config.json)
{
"agents": {
"defaults": {
"model": "glm-4.7",
"max_tokens": 8192
}
},
"providers": {
"zhipu": {
"api_key": "YOUR_API_KEY"
}
}
}Minimum config: pick one provider and set its API key. Everything else has defaults.
4. Use
picoclaw agent -m "What is 2+2?" # One-shot query
picoclaw agent # Interactive chat
picoclaw gateway # Start with channels + cron + edgeAll providers use a unified HTTP interface. Pick one:
| Provider | Model prefix | Get API Key |
|---|---|---|
| Zhipu | glm-* |
bigmodel.cn |
| OpenRouter | openrouter/*, anthropic/*, openai/*, etc. |
openrouter.ai |
| Anthropic | claude-* |
console.anthropic.com |
| OpenAI | gpt-* |
platform.openai.com |
| Gemini | gemini-* |
aistudio.google.com |
| Groq | groq/* (also enables voice transcription) |
console.groq.com |
| vLLM | any (set api_base) |
Self-hosted |
Start the gateway to connect channels:
picoclaw gateway| Channel | Config keys | Notes |
|---|---|---|
| Telegram | token, allow_from |
Recommended. Supports voice messages (with Groq) |
| Discord | token, allow_from |
Enable MESSAGE CONTENT INTENT |
app_id, app_secret |
QQ Open Platform | |
| DingTalk | client_id, client_secret |
Internal app |
| Feishu | app_id, app_secret, encrypt_key, verification_token |
Lark/Feishu bot |
bridge_url |
Via WhatsApp bridge | |
| MaixCam | host, port |
Direct hardware connection |
Telegram example config
{
"channels": {
"telegram": {
"enabled": true,
"token": "123456:ABC-DEF...",
"allow_from": ["YOUR_USER_ID"]
}
}
}Get a token from @BotFather on Telegram. Get your user ID from @userinfobot.
Full config example
See config.example.json for all available options.
| Tool | Description |
|---|---|
read_file |
Read file contents |
write_file |
Create or overwrite a file |
edit_file |
Search-and-replace edit in a file |
append_file |
Append content to a file |
list_dir |
List directory contents |
exec |
Execute shell commands |
spawn |
Run background processes |
web_search |
Search the web (Brave Search API) |
web_fetch |
Fetch and extract web page content |
message |
Send messages through configured channels |
cron |
Create/manage scheduled tasks |
report_gene |
Report a learned experience to the Gene Evolution system |
PicoClaw includes a self-evolving strategy system. Agents learn from experience and reuse proven monitoring strategies.
How it works:
- Signals are extracted from sensor data, memory, and daily notes (8 types:
sensor_error,threshold_breach,cross_sensor_anomaly,new_pattern_detected,response_too_slow,strategy_proven,unknown_situation,time_pattern) - Active signals are matched against the gene pool — the best-scoring genes are injected into the LLM system prompt
- After handling, experiences are solidified into Capsules. Successful novel handling creates new Genes.
- Gene confidence adjusts over time: success increases it, failure decreases it
- High-confidence genes can be published to Fleet for cross-node sharing
6 seed genes ship by default:
| Gene | Category | Scenario | What it does |
|---|---|---|---|
gene_sensor_repair_from_errors |
repair | generic | Retry failed sensors, switch to backup |
gene_threshold_optimize_from_history |
optimize | generic | Adjust thresholds using 7-day statistics |
gene_cross_sensor_innovate |
innovate | generic | Detect cross-sensor correlations |
gene_dc_temp_spike_crosscheck |
repair | datacenter | Cross-check rack temps before alerting |
gene_pond_do_night_emergency |
repair | aquaculture | Night-time dissolved oxygen emergency |
gene_greenhouse_ventilation_schedule |
optimize | greenhouse | Optimize vent timing from rolling data |
Strategy presets control which genes are applied:
| Preset | Min Confidence | Min Verified | Use case |
|---|---|---|---|
conservative |
90% | 5 | Production critical systems |
balanced |
70% | 2 | Default |
exploratory |
30% | 0 | Testing new scenarios |
repair-only |
50% | 1 | Emergency mode |
Configure in ~/.picoclaw/config.json:
{
"gene": {
"strategy": "balanced",
"auto_publish": true,
"min_confidence": 0.7,
"min_verified_by": 3
}
}CLI:
picoclaw gene list # Show genes with confidence scores
picoclaw gene stats # Pool statistics and drift intensity
picoclaw gene export # Export genes as JSONPicoClaw can act as an L1 edge node in a distributed architecture, reporting to upstream fleet managers:
{
"edge": {
"enabled": true,
"port": 9090,
"node_id": "dc-rack-a1",
"node_name": "Datacenter Rack A1",
"cloud_endpoint": "http://nanoclaw:8080",
"cloud_token": "...",
"heartbeat_seconds": 30
}
}When enabled, PicoClaw exposes:
GET /healthz— Health checkGET /api/v1/status— Node statusPOST /api/v1/command— Receive commands from fleet
And periodically sends heartbeats (including gene stats) to the configured fleet manager.
Skills are markdown files that teach the agent domain-specific knowledge.
| Skill | Description |
|---|---|
datacenter-monitoring |
Rack temperature monitoring with mock sensors and Gene Evolution demo |
github |
GitHub workflow assistance |
summarize |
Text summarization |
weather |
Weather lookup (no API key needed) |
tmux |
Terminal multiplexer management |
skill-creator |
Create new skills |
picoclaw skills list # List installed skills
picoclaw skills install <url> # Install from Git repo
picoclaw skills install-builtin # Install all built-in skillsThe datacenter-monitoring skill includes a complete end-to-end demo:
# Test with mock sensors
python3 skills/datacenter-monitoring/scripts/mock-sensor.py --all --summary
# Simulate a temperature spike
python3 skills/datacenter-monitoring/scripts/mock-sensor.py --rack A1 --spike
# Simulate a sensor failure
python3 skills/datacenter-monitoring/scripts/mock-sensor.py --rack B2 --fail
# Random chaos mode (10% failures, 15% spikes)
python3 skills/datacenter-monitoring/scripts/mock-sensor.py --all --chaos --summarySee skills/datacenter-monitoring/DEPLOY.md for full deployment guide with real hardware.
| Command | Description |
|---|---|
picoclaw onboard |
Initialize config and workspace |
picoclaw agent -m "..." |
One-shot chat |
picoclaw agent |
Interactive chat mode |
picoclaw gateway |
Start gateway (channels + cron + edge + heartbeat) |
picoclaw status |
Show configuration status |
picoclaw cron list |
List scheduled jobs |
picoclaw cron add |
Add a scheduled job |
picoclaw skills list |
List installed skills |
picoclaw skills install <url> |
Install skill from Git |
picoclaw gene list |
Show local genes |
picoclaw gene stats |
Gene pool statistics |
picoclaw gene export |
Export genes as JSON |
picoclaw version |
Show version |
PicoClaw runs on anything with Linux and a network connection:
| Device | Price | Arch | Use case |
|---|---|---|---|
| LicheeRV Nano | $10 | RISC-V | Minimal edge agent |
| NanoKVM | $30-50 | RISC-V | Server monitoring |
| MaixCAM | $50-100 | RISC-V | Vision + AI monitoring |
| Raspberry Pi Zero 2W | $15 | ARM64 | General purpose |
| Any Linux x86/ARM server | - | x86/ARM | Cloud or on-prem |
| Full-Stack Engineering | Logging & Planning | Web Search |
|---|---|---|
 |
 |
 |
~/.picoclaw/
├── config.json # Main configuration
└── workspace/
├── genes/ # Gene Evolution data
│ ├── genes.json # Strategy definitions
│ ├── capsules.json # Solidified experiences
│ └── events.jsonl # Audit trail
├── sessions/ # Conversation history
├── memory/ # Long-term memory (MEMORY.md + daily notes)
├── cron/ # Scheduled jobs
├── skills/ # Installed skills
├── AGENTS.md # Agent behavior guide
├── IDENTITY.md # Agent identity
└── USER.md # User preferences
PicoClaw is the L1 edge agent in the Clawland-AI open-source ecosystem:
| Layer | Repo | Language | Role |
|---|---|---|---|
| L0 MCU | microclaw | C/Rust | Sensor-level agent on $2 MCUs |
| L1 Edge | picclaw (this repo) | Go | Edge AI agent on $10 hardware |
| L2 Regional | nanoclaw | Python | Regional gateway on $50 SBCs |
| L3 Cloud | moltclaw | TypeScript | Cloud AI gateway + fleet management |
Build to Earn: Contributors share 20% of net revenue through the Contributor Revenue Pool. See Clawland-AI for details.
PRs welcome. The codebase is ~7500 lines of Go across 15 packages, intentionally small and readable.
make test # Run all tests
make lint # Run golangci-lint
make build-all # Build for all platformsWeb search returns "API configuration error" — This is normal without a Brave Search API key. Get a free key at brave.com/search/api (2000 free queries/month) and add it to tools.web.search.api_key.
"Conflict: terminated by other getUpdates" — Another instance of the Telegram bot is running. Only one picoclaw gateway per bot token.
Content filtering errors — Some providers (Zhipu) have content filtering. Try rephrasing or switching models.
MIT License. See LICENSE.
Based on nanobot by HKUDS.