252 lines
7.4 KiB
Markdown
252 lines
7.4 KiB
Markdown
# 🦐 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
|