latest updates
This commit is contained in:
Tanmay Karande
251
docs/picoclaw.md
Normal file
251
docs/picoclaw.md
Normal file
@@ -0,0 +1,251 @@
|
||||
# 🦐 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
|
||||
Reference in New Issue
Block a user