# 🦐 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

```mermaid
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

```mermaid
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

```mermaid
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

```mermaid
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