$ show sipeed/picoclaw
PicoClaw is an ultra-lightweight personal AI agent platform written in Go, engineered to run on hardware as small as $10 RISC-V boards while providing a full-featured chat agent experience. In production it is a daemon (picoclaw) that connects 30+ LLM providers (OpenAI, Anthropic, Gemini, Azure, Bedrock, Claude CLI, Codex, Ollama, etc. behind a common provider factory) to 19+ messaging channels (Telegram, Discord, WhatsApp, WeChat, WeCom, Slack, IRC, Matrix, DingTalk, Feishu, MQTT, etc.), exposing an agent loop with tool calls, MCP server integration, session management, voice I/O (ASR/TTS), cron jobs, skills marketplace, and hardware tools (I2C, SPI, serial). A companion launcher binary (picoclaw-launcher) runs a Go web backend with an embedded React/TypeScript frontend for configuration, model/channel/credential management, logs, and live chat.\n\nThe architecture is a modular monolith: pkg/agent implements the turn pipeline (context assembly, thinking levels, tool loop, streaming, stop handling), pkg/providers abstracts LLM backends with rate limiting, cooldown tracking, and fallback chains driven by an error classifier, pkg/channels provides a factory-registered channel abstraction over a shared base, and pkg/bus + pkg/events carry inbound/outbound messages and typed runtime events with backpressure. Agents are defined by AGENT.md/SOUL.md workspace files and support delegation/spawning. An experimental evolution subsystem clusters learning records and generates skill drafts via LLM, and the seahorse SQLite FTS5 store provides compacted short-term memory with BM25 retrieval and summary trees. Legacy OpenClaw configs can be migrated.\n\nThe codebase is heavily tested (500+ test files across nearly every package), uses cross-platform build tags for Windows/Linux/Unix/Android, and ships Docker images plus a self-update mechanism. Strong engineering practices include atomic file writes, zip-slip and SSRF protection utilities, typed event buses, factory registries, and a ToolResult structure separating LLM-facing vs user-facing output. The project is pre-1.0 with rapid release cadence; the evolution subsystem, some platform-specific hardware stubs, and the large channel/provider surface are the least mature areas. It is not a data-research repository - the LOCOMO memory benchmark and LLM-as-judge evaluation code in cmd/membench support engineering measurement rather than producing research artifacts.
The LLM identified 7 files worth highlighting for reuse:
HTTP client wrapper that resolves hostnames and blocks requests to private/loopback/link-local IPs, validates redirect targets, and supports proxy allowlisting. A self-contained SSRF-prevention pattern directly reusable in any Go service making outbound HTTP calls.
Generic BM25 ranking engine with configurable k1/b parameters and a pre-built index. Used for memory retrieval in the agent's seahorse store but implemented as a dependency-free package - directly extractable for keyword search over any text corpus.
Atomic file write utility implementing temp-file + fsync + rename + cleanup, used across the codebase for config, state, PID files, and skill installation. A self-contained crash-safety pattern that prevents partial writes in any Go application.
ZIP extraction with path traversal protection and total size limits - solves the classic zip-slip vulnerability class. Isolated utility applicable to any project extracting archives (plugin installers, skill packaging, asset downloads).
Typed publish/subscribe event bus with kind/scope filtering, subscription lifecycle management, and configurable backpressure strategies (DropNewest, DropOldest, Block). Self-contained concurrency design demonstrating safe channel-based pub/sub in Go with tests.
Pattern-based error classifier that maps API failures to canonical reasons (rate limit, auth, timeout, billing) to drive provider fallback chains and cooldown decisions. Demonstrates a robust degrade-gracefully design with comprehensive tests; portable to any multi-provider integration.
ToolResult structure separating ForLLM and ForUser outputs with Silent, Async, Media, and ResponseHandled flags, plus media reference handling and size limits. A clean contract for tools returning LLM-consumable vs human-consumable content, applicable to any agent tool interface.