PicoClaw AI Assistant

PicoClaw is an ultra-lightweight AI assistant written in Go, designed for high efficiency and low-cost deployment.

Key Features:

• Ultra-lightweight: Core memory footprint is typically < 10MB (though recent versions may reach 10-20MB due to rapid feature updates).
• High Speed: Boots in less than 1 second even on 0.6GHz single-core hardware.
• Portability: Single binary supporting RISC-V, ARM, MIPS, x86, and LoongArch.
• MCP Support: Native integration with the Model Context Protocol to extend capabilities via MCP servers.
• Vision Pipeline: Supports multimodal LLMs by automatically base64 encoding images and files sent to the agent.
• Smart Routing: Uses rule-based routing to send simple queries to lightweight models, saving API costs.
• Low Cost: Can run on $10 hardware like the LicheeRV-Nano.

PicoClaw is an ultra-lightweight, open-source personal AI assistant written entirely in Go. It is designed to run on low-cost hardware (as low as $10) with extremely low memory requirements (typically <10MB RAM) and near-instant boot times (<1s).

Key Features

• Ultra-lightweight: Core memory footprint is <10MB.
• Portability: Single binary support for RISC-V, ARM, MIPS, and x86 architectures.
• MCP Support: Native integration with the Model Context Protocol to extend agent capabilities via MCP servers.
• Vision Pipeline: Supports sending images and files directly to the agent via automatic base64 encoding.
• Intelligent Routing: Rule-based model routing to optimize costs (e.g., sending simple queries to lightweight models).
• Fast Boot: Optimized for rapid startup even on single-core, low-frequency processors.

The web/ directory provides the standalone WebUI launcher for PicoClaw. It is a small service that bundles a React dashboard, exposes a backend API, manages launcher authentication, and controls the picoclaw gateway subprocess.

Key Components

• Backend (backend/): A Go HTTP server that serves REST APIs, handles authentication, and acts as a WebSocket reverse proxy for Pico channel traffic. It embeds the compiled frontend assets.
• Frontend (frontend/): A Vite + React 19 SPA providing the dashboard and chat UI.

Runtime Architecture

1. The launcher starts the web backend on port 18800 by default.
2. The launcher serves the dashboard and handles authentication.
3. The launcher starts or attaches to the picoclaw gateway -E process.
4. The frontend communicates with the launcher backend, which proxies chat traffic to the gateway via /pico/ws.

PicoClaw is an ultra-lightweight, high-efficiency AI assistant written entirely in Go. It is designed for extreme resource efficiency, capable of running on $10 hardware with <10MB of RAM and sub-second startup times even on low-power processors (e.g., 0.6GHz single-core).

Key features include:

• Portability: Single binary supporting x86_64, ARM64, MIPS, RISC-V, and LoongArch.
• MCP Support: Native integration with the Model Context Protocol to extend capabilities via MCP servers.
• Visual Pipeline: Supports sending images and files directly to the agent via automatic base64 encoding.
• Smart Routing: Rule-based model routing to optimize API costs (e.g., using lightweight models for simple queries).
• Low Footprint: Significantly more efficient than alternatives like OpenClaw (TypeScript) or NanoBot (Python).

The Matrix channel implementation supports the following capabilities:

• Messaging: Send and receive text messages with Markdown rendering (bold, italics, headers, code blocks, etc.).
• Message Formatting: Configurable output formats using message_format (richtext or plain).
• Media Handling:
  • Download incoming images, audio, video, and files (using MediaStore with a local path fallback).
  • Normalize incoming audio into existing transcription streams ([audio: ...]).
  • Upload and send outgoing images, audio, video, and files.
• Group Interaction: Group trigger rules, including a mention_only mode.
• User Experience:
  • Displays typing status (m.typing).
  • Uses placeholder messages that are replaced by the final response.
• Automation: Option to automatically join rooms upon receiving an invite via join_on_invite.

The Matrix channel currently supports the following capabilities:

• Messaging: Sending and receiving text messages.
• Media Handling: Inbound downloading of images, audio, video, and files (stored in MediaStore or a local fallback path). Outbound sending of media (uploaded to Matrix media repository).
• Audio Processing: Audio messages are automatically marked for the transcription workflow using the [audio: ...] tag.
• Group Interaction: Configurable trigger rules, such as responding only when the bot is @mentioned.
• User Experience: Support for m.typing status indicators and placeholder messages (e.g., Thinking... 💭) that are replaced by the final response.
• Automation: Option to automatically join invited rooms.
• Security: Support for End-to-End Encryption (E2EE) messages.

PicoClaw is an ultra-lightweight AI assistant written in Go, designed to run on low-cost hardware ($10) with minimal memory footprint (<10MB RAM).

Key Capabilities:

• Ultra-lightweight: Core memory usage <10MB.
• Fast Boot: Starts in <1s even on 0.6GHz single-core processors.
• Multi-Architecture: Single binary support for RISC-V, ARM, MIPS, and x86.
• MCP Support: Native integration with Model Context Protocol to connect any MCP server.
• Vision Pipeline: Supports sending images and files directly to the agent (automatic base64 encoding for multimodal LLMs).
• Smart Routing: Rule-based model routing to direct simple queries to lightweight, cost-effective models.

The Matrix channel currently supports the following capabilities:

• Messaging: Sending and receiving text messages with Markdown rendering (bold, italics, headers, code blocks, etc.).
• Message Formats: Configurable output via message_format (richtext or plain).
• Media Handling:
  • Downloading incoming images, audio, video, and files (prioritizing MediaStore, falling back to local paths).
  • Normalizing incoming audio into the existing transcription stream ([audio: ...]).
  • Uploading and sending outgoing images, audio, video, and files.
• Triggering: Group trigger rules, including mention_only mode.
• User Experience:
  • Typing indicators (m.typing).
  • Placeholder messages that are replaced by the final response.
• Room Management: Automatically joining invited rooms (can be disabled via join_on_invite).

PicoClaw provides an mcp CLI command group to manage Model Context Protocol (MCP) server entries in your configuration. This CLI acts as a configuration manager for the tools.mcp.servers section of your config.json.

Important Note: The CLI manages the configuration but does not keep the MCP servers running. The PicoClaw gateway/host starts the configured servers when MCP is enabled.

Configuration Location:

• Uses PICOCLAW_CONFIG environment variable if set.
• Defaults to ~/.picoclaw/config.json.

Key Behaviors:

• Adding a server via picoclaw mcp add automatically enables tools.mcp.enabled.
• Removing the last server via picoclaw mcp remove automatically disables tools.mcp.enabled.
• Writes are atomic, use 2-space JSON formatting, and are validated before saving.

PicoClaw documentation is organized by document type. Use the following directory indexes to find specific information:

• Guides: Setup, configuration, provider, and workflow guides (docs/guides/).
• Reference: Precise configuration and behavior reference (docs/reference/).
• Operations: Debugging and troubleshooting material (docs/operations/).
• Security: Security-focused guides and controls (docs/security/).
• Architecture: Implementation notes and internal design docs (docs/architecture/).
• Migration: Upgrade and migration notes (docs/migration/).
• Channels: For channel-specific setup (e.g., Chat Apps), start with guides/chat-apps.md and then look into docs/channels/<name>/README.md.