Aetheel/docs/picoclaw.md

🦐 PicoClaw — Architecture & How It Works

Ultra-Efficient AI Assistant in Go — $10 hardware, 10MB RAM, 1s boot time.

Overview

PicoClaw is an extreme-lightweight rewrite of Nanobot in Go, designed to run on the cheapest possible hardware — including $10 RISC-V SBCs with <10MB RAM. The entire project was AI-bootstrapped (95% agent-generated) through a self-bootstrapping migration from Python to Go.

Attribute	Value
Language	Go 1.21+
RAM Usage	<10MB
Startup Time	<1s (even at 0.6GHz)
Hardware Cost	As low as $10
Architectures	x86_64, ARM64, RISC-V
Binary	Single self-contained binary
Config	~/.picoclaw/config.json

---

Architecture Flowchart

graph TB
    subgraph Channels["📱 Chat Channels"]
        TG["Telegram"]
        DC["Discord"]
        QQ["QQ"]
        DT["DingTalk"]
        LINE["LINE"]
    end

    subgraph Core["🧠 Core Agent (Single Binary)"]
        MAIN["Main Entry\n(cmd/)"]
        AGENT["Agent Loop\n(pkg/agent/)"]
        CONF["Config\n(pkg/config/)"]
        AUTH["Auth\n(pkg/auth/)"]
        PROV["Providers\n(pkg/providers/)"]
        TOOLS["Tools\n(pkg/tools/)"]
    end

    subgraph ToolSet["🔧 Built-in Tools"]
        SHELL["Shell Exec"]
        FILE["File R/W"]
        WEB["Web Search\n(Brave / DuckDuckGo)"]
        CRON_T["Cron / Reminders"]
        SPAWN["Spawn Subagent"]
        MSG["Message Tool"]
    end

    subgraph Workspace["💾 Workspace"]
        AGENTS_MD["AGENTS.md"]
        SOUL_MD["SOUL.md"]
        TOOLS_MD["TOOLS.md"]
        USER_MD["USER.md"]
        IDENTITY["IDENTITY.md"]
        HB["HEARTBEAT.md"]
        MEM["MEMORY.md"]
        SESSIONS["sessions/"]
        SKILLS["skills/"]
    end

    subgraph Providers["☁️ LLM Providers"]
        GEMINI["Gemini"]
        ZHIPU["Zhipu"]
        OR["OpenRouter"]
        OA["OpenAI"]
        AN["Anthropic"]
        DS["DeepSeek"]
        GROQ["Groq\n(+ voice)"]
    end

    Channels --> Core
    AGENT --> ToolSet
    AGENT --> Workspace
    AGENT --> Providers

---

Message Flow

sequenceDiagram
    participant User
    participant Channel as Chat Channel
    participant GW as Gateway
    participant Agent as Agent Loop
    participant LLM as LLM Provider
    participant Tools as Tools

    User->>Channel: Send message
    Channel->>GW: Forward message
    GW->>Agent: Route to agent
    Agent->>Agent: Load context (AGENTS.md, SOUL.md, USER.md)
    Agent->>LLM: Send prompt + tool defs
    LLM-->>Agent: Response

    alt Tool Call
        Agent->>Tools: Execute tool
        Tools-->>Agent: Result
        Agent->>LLM: Continue
        LLM-->>Agent: Next response
    end

    Agent->>Agent: Update memory/session
    Agent-->>GW: Return response
    GW-->>Channel: Send reply
    Channel-->>User: Display

---

Heartbeat System Flow

sequenceDiagram
    participant Timer as Heartbeat Timer
    participant Agent as Agent
    participant HB as HEARTBEAT.md
    participant Subagent as Spawn Subagent
    participant User

    Timer->>Agent: Trigger (every 30 min)
    Agent->>HB: Read periodic tasks
    
    alt Quick Task
        Agent->>Agent: Execute directly
        Agent-->>Timer: HEARTBEAT_OK
    end
    
    alt Long Task
        Agent->>Subagent: Spawn async subagent
        Agent-->>Timer: Continue to next task
        Subagent->>Subagent: Work independently
        Subagent->>User: Send result via message tool
    end

---

Key Components

1. Agent Loop (pkg/agent/)

Go-native implementation of the LLM ↔ tool execution loop:

• Builds context from workspace identity files
• Sends to LLM provider with tool definitions
• Iterates on tool calls up to max_tool_iterations (default: 20)
• Session history managed in workspace/sessions/

2. Provider System (pkg/providers/)

• Gemini and Zhipu are fully tested
• OpenRouter, Anthropic, OpenAI, DeepSeek marked "to be tested"
• Groq for voice transcription (Whisper)
• Each provider implements a common interface

3. Tool System (pkg/tools/)

Built-in tools:

• read_file / write_file / list_dir / edit_file / append_file — File operations
• exec — Shell command execution (with safety guards)
• web_search — Brave Search or DuckDuckGo fallback
• cron — Scheduled reminders and recurring tasks
• spawn — Create async subagents
• message — Subagent-to-user communication

4. Security Sandbox

graph TD
    RW["restrict_to_workspace = true"]
    
    RW --> RF["read_file: workspace only"]
    RW --> WF["write_file: workspace only"]
    RW --> LD["list_dir: workspace only"]
    RW --> EF["edit_file: workspace only"]
    RW --> AF["append_file: workspace only"]
    RW --> EX["exec: workspace paths only"]
    
    EX --> BL["ALWAYS Blocked:"]
    BL --> RM["rm -rf"]
    BL --> FMT["format, mkfs"]
    BL --> DD["dd if="]
    BL --> SHUT["shutdown, reboot"]
    BL --> FORK["fork bomb"]

• Workspace sandbox enabled by default
• All tools restricted to workspace directory
• Dangerous commands always blocked (even with sandbox off)
• Consistent across main agent, subagents, and heartbeat tasks

5. Heartbeat System

• Reads HEARTBEAT.md every 30 minutes
• Quick tasks executed directly
• Long tasks spawned as async subagents
• Subagents communicate independently via message tool

6. Channel System

• Telegram — Easy setup (token only)
• Discord — Bot token + intents
• QQ — AppID + AppSecret
• DingTalk — Client credentials
• LINE — Credentials + webhook URL (HTTPS required)

7. Workspace Layout

~/.picoclaw/workspace/
├── sessions/          # Conversation history
├── memory/            # Long-term memory (MEMORY.md)
├── state/             # Persistent state
├── cron/              # Scheduled jobs database
├── skills/            # Custom skills
├── AGENTS.md          # Agent behavior guide
├── HEARTBEAT.md       # Periodic task prompts
├── IDENTITY.md        # Agent identity
├── SOUL.md            # Agent soul
├── TOOLS.md           # Tool descriptions
└── USER.md            # User preferences

---

Comparison Table (from README)

	OpenClaw	NanoBot	PicoClaw
Language	TypeScript	Python	Go
RAM	>1GB	>100MB	<10MB
Startup (0.8GHz)	>500s	>30s	<1s
Cost	Mac $599	SBC ~$50	Any Linux, ~$10

---

Deployment Targets

PicoClaw can run on almost any Linux device:

• $9.9 LicheeRV-Nano — Minimal home assistant
• $30-50 NanoKVM — Automated server maintenance
• $50-100 MaixCAM — Smart monitoring

---

Key Design Decisions

1. Go for minimal footprint — Single binary, no runtime deps, tiny memory
2. AI-bootstrapped migration — 95% of Go code generated by the AI agent itself
3. Web search with fallback — Brave Search primary, DuckDuckGo fallback (free)
4. Heartbeat for proactive tasks — Agent checks HEARTBEAT.md periodically
5. Subagent pattern — Long tasks run async, don't block heartbeat
6. Default sandbox — restrict_to_workspace: true by default
7. Cross-architecture — Single binary compiles for x86, ARM64, RISC-V