* First commit

.gitignore

@@ -0,0 +1,15 @@
+bin/
+*.exe
+*.dll
+*.so
+*.dylib
+*.test
+*.out
+.picoclaw/
+config.json
+sessions/
+coverage.txt
+coverage.html
+.DS_Store
+build
+

LICENSE

@@ -0,0 +1,25 @@
+MIT License
+
+Copyright (c) 2026 PicoClaw contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+PicoClaw is heavily inspired by and based on [nanobot](https://github.com/HKUDS/nanobot) by HKUDS.

Makefile

@@ -0,0 +1,179 @@
+.PHONY: all build install uninstall clean help test
+
+# Build variables
+BINARY_NAME=picoclaw
+BUILD_DIR=build
+CMD_DIR=cmd/$(BINARY_NAME)
+MAIN_GO=$(CMD_DIR)/main.go
+
+# Version
+VERSION?=$(shell git describe --tags --always --dirty 2>/dev/null || echo "dev")
+BUILD_TIME=$(shell date +%FT%T%z)
+LDFLAGS=-ldflags "-X main.version=$(VERSION) -X main.buildTime=$(BUILD_TIME)"
+
+# Go variables
+GO?=go
+GOFLAGS?=-v
+
+# Installation
+INSTALL_PREFIX?=$(HOME)/.local
+INSTALL_BIN_DIR=$(INSTALL_PREFIX)/bin
+INSTALL_MAN_DIR=$(INSTALL_PREFIX)/share/man/man1
+
+# Workspace and Skills
+PICOCLAW_HOME?=$(HOME)/.picoclaw
+WORKSPACE_DIR?=$(PICOCLAW_HOME)/workspace
+WORKSPACE_SKILLS_DIR=$(WORKSPACE_DIR)/skills
+BUILTIN_SKILLS_DIR=$(CURDIR)/skills
+
+# OS detection
+UNAME_S:=$(shell uname -s)
+UNAME_M:=$(shell uname -m)
+
+# Platform-specific settings
+ifeq ($(UNAME_S),Linux)
+	PLATFORM=linux
+	ifeq ($(UNAME_M),x86_64)
+		ARCH=amd64
+	else ifeq ($(UNAME_M),aarch64)
+		ARCH=arm64
+	else ifeq ($(UNAME_M),riscv64)
+		ARCH=riscv64
+	else
+		ARCH=$(UNAME_M)
+	endif
+else ifeq ($(UNAME_S),Darwin)
+	PLATFORM=darwin
+	ifeq ($(UNAME_M),x86_64)
+		ARCH=amd64
+	else ifeq ($(UNAME_M),arm64)
+		ARCH=arm64
+	else
+		ARCH=$(UNAME_M)
+	endif
+else
+	PLATFORM=$(UNAME_S)
+	ARCH=$(UNAME_M)
+endif
+
+BINARY_PATH=$(BUILD_DIR)/$(BINARY_NAME)-$(PLATFORM)-$(ARCH)
+
+# Default target
+all: build
+
+## build: Build the picoclaw binary for current platform
+build:
+	@echo "Building $(BINARY_NAME) for $(PLATFORM)/$(ARCH)..."
+	@mkdir -p $(BUILD_DIR)
+	$(GO) build $(GOFLAGS) $(LDFLAGS) -o $(BINARY_PATH) ./$(CMD_DIR)
+	@echo "Build complete: $(BINARY_PATH)"
+	@ln -sf $(BINARY_NAME)-$(PLATFORM)-$(ARCH) $(BUILD_DIR)/$(BINARY_NAME)
+
+## build-all: Build picoclaw for all platforms
+build-all:
+	@echo "Building for multiple platforms..."
+	@mkdir -p $(BUILD_DIR)
+	GOOS=linux GOARCH=amd64 $(GO) build $(LDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-linux-amd64 ./$(CMD_DIR)
+	GOOS=linux GOARCH=arm64 $(GO) build $(LDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-linux-arm64 ./$(CMD_DIR)
+	GOOS=linux GOARCH=riscv64 $(GO) build $(LDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-linux-riscv64 ./$(CMD_DIR)
+# 	GOOS=darwin GOARCH=amd64 $(GO) build $(LDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-darwin-amd64 ./$(CMD_DIR)
+	GOOS=windows GOARCH=amd64 $(GO) build $(LDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-windows-amd64.exe ./$(CMD_DIR)
+	@echo "All builds complete"
+
+## install: Install picoclaw to system and copy builtin skills
+install: build
+	@echo "Installing $(BINARY_NAME)..."
+	@mkdir -p $(INSTALL_BIN_DIR)
+	@cp $(BUILD_DIR)/$(BINARY_NAME) $(INSTALL_BIN_DIR)/$(BINARY_NAME)
+	@chmod +x $(INSTALL_BIN_DIR)/$(BINARY_NAME)
+	@echo "Installed binary to $(INSTALL_BIN_DIR)/$(BINARY_NAME)"
+	@echo "Installing builtin skills to $(WORKSPACE_SKILLS_DIR)..."
+	@mkdir -p $(WORKSPACE_SKILLS_DIR)
+	@for skill in $(BUILTIN_SKILLS_DIR)/*/; do \
+		if [ -d "$$skill" ]; then \
+			skill_name=$$(basename "$$skill"); \
+			if [ -f "$$skill/SKILL.md" ]; then \
+				cp -r "$$skill" $(WORKSPACE_SKILLS_DIR); \
+				echo "  ✓ Installed skill: $$skill_name"; \
+			fi; \
+		fi; \
+	done
+	@echo "Installation complete!"
+
+## install-skills: Install builtin skills to workspace
+install-skills:
+	@echo "Installing builtin skills to $(WORKSPACE_SKILLS_DIR)..."
+	@mkdir -p $(WORKSPACE_SKILLS_DIR)
+	@for skill in $(BUILTIN_SKILLS_DIR)/*/; do \
+		if [ -d "$$skill" ]; then \
+			skill_name=$$(basename "$$skill"); \
+			if [ -f "$$skill/SKILL.md" ]; then \
+				mkdir -p $(WORKSPACE_SKILLS_DIR)/$$skill_name; \
+				cp -r "$$skill" $(WORKSPACE_SKILLS_DIR); \
+				echo "  ✓ Installed skill: $$skill_name"; \
+			fi; \
+		fi; \
+	done
+	@echo "Skills installation complete!"
+
+## uninstall: Remove picoclaw from system
+uninstall:
+	@echo "Uninstalling $(BINARY_NAME)..."
+	@rm -f $(INSTALL_BIN_DIR)/$(BINARY_NAME)
+	@echo "Removed binary from $(INSTALL_BIN_DIR)/$(BINARY_NAME)"
+	@echo "Note: Only the executable file has been deleted."
+	@echo "If you need to delete all configurations (config.json, workspace, etc.), run 'make uninstall-all'"
+
+## uninstall-all: Remove picoclaw and all data
+uninstall-all:
+	@echo "Removing workspace and skills..."
+	@rm -rf $(PICOCLAW_HOME)
+	@echo "Removed workspace: $(PICOCLAW_HOME)"
+	@echo "Complete uninstallation done!"
+
+## clean: Remove build artifacts
+clean:
+	@echo "Cleaning build artifacts..."
+	@rm -rf $(BUILD_DIR)
+	@echo "Clean complete"
+
+## fmt: Format Go code
+fmt:
+	@$(GO) fmt ./...
+
+## deps: Update dependencies
+deps:
+	@$(GO) get -u ./...
+	@$(GO) mod tidy
+
+## run: Build and run picoclaw
+run: build
+	@$(BUILD_DIR)/$(BINARY_NAME) $(ARGS)
+
+## help: Show this help message
+help:
+	@echo "picoclaw Makefile"
+	@echo ""
+	@echo "Usage:"
+	@echo "  make [target]"
+	@echo ""
+	@echo "Targets:"
+	@grep -E '^## ' $(MAKEFILE_LIST) | sed 's/## /  /'
+	@echo ""
+	@echo "Examples:"
+	@echo "  make build              # Build for current platform"
+	@echo "  make install            # Install to /usr/local/bin"
+	@echo "  make install-user       # Install to ~/.local/bin"
+	@echo "  make uninstall          # Remove from /usr/local/bin"
+	@echo "  make install-skills     # Install skills to workspace"
+	@echo ""
+	@echo "Environment Variables:"
+	@echo "  INSTALL_PREFIX          # Installation prefix (default: /usr/local)"
+	@echo "  WORKSPACE_DIR           # Workspace directory (default: ~/.picoclaw/workspace)"
+	@echo "  VERSION                 # Version string (default: git describe)"
+	@echo ""
+	@echo "Current Configuration:"
+	@echo "  Platform: $(PLATFORM)/$(ARCH)"
+	@echo "  Binary: $(BINARY_PATH)"
+	@echo "  Install Prefix: $(INSTALL_PREFIX)"
+	@echo "  Workspace: $(WORKSPACE_DIR)"

README.md

@@ -0,0 +1,449 @@
+<div align="center">
+<img src="assets/logo.jpg" alt="PicoClaw" width="512">
+
+<h1>PicoClaw: Ultra-Efficient AI Assistant in Go</h1>
+
+<h3>$10 Hardware · 10MB RAM · 1s Boot · 皮皮虾，我们走！</h3>
+<h3></h3>
+
+<p>
+<img src="https://img.shields.io/badge/Go-1.21+-00ADD8?style=flat&logo=go&logoColor=white" alt="Go">
+<img src="https://img.shields.io/badge/Arch-x86__64%2C%20ARM64%2C%20RISC--V-blue" alt="Hardware">
+<img src="https://img.shields.io/badge/license-MIT-green" alt="License">
+</p>
+
+</div>
+
+
+---
+
+🦐 PicoClaw is an ultra-lightweight personal AI Assistant inspired by [nanobot](https://github.com/HKUDS/nanobot), refactored from the ground up in Go through a self-bootstrapping process, where the AI agent itself drove the entire architectural migration and code optimization.
+
+⚡️ Runs on $10 hardware with <10MB RAM: That's 99% less memory than OpenClaw and 98% cheaper than a Mac mini!
+
+<table align="center">
+  <tr align="center">
+    <td align="center" valign="top">
+      <p align="center">
+        <img src="assets/picoclaw_mem.gif" width="360" height="240">
+      </p>
+    </td>
+    <td align="center" valign="top">
+      <p align="center">
+        <img src="assets/licheervnano.png" width="400" height="240">
+      </p>
+    </td>
+  </tr>
+</table>
+
+## 📢 News
+2026-02-09 🎉 PicoClaw Launched! Built in 1 day to bring AI Agents to $10 hardware with <10MB RAM. 🦐 皮皮虾，我们走！
+
+## ✨ Features
+
+🪶 **Ultra-Lightweight**: <10MB Memory footprint — 99% smaller than Clawdbot - core functionality.
+
+💰 **Minimal Cost**: Efficient enough to run on $10 Hardware — 98% cheaper than a Mac mini.
+
+⚡️ **Lightning Fast**: 400X Faster startup time, boot in 1 second even in 0.6GHz single core.
+
+🌍 **True Portability**: Single self-contained binary across RISC-V, ARM, and x86, One-click to Go!
+
+🤖 **AI-Bootstrapped**: Autonomous Go-native implementation — 95% Agent-generated core with human-in-the-loop refinement.
+
+|  | OpenClaw  | NanoBot | **PicoClaw** |
+| --- | --- | --- |--- |
+| **Language** | TypeScript | Python | **Go** |
+| **RAM** | >1GB |>100MB| **< 10MB** |
+| **Startup**</br>(0.8GHz core) | >500s | >30s |  **<1s** |
+| **Cost** | Mac Mini 599$ | Most Linux SBC </br>~50$ |**Any Linux Board**</br>**As low as 10$** |
+<img src="assets/compare.jpg" alt="PicoClaw" width="512">
+
+
+## 🦾 Demonstration
+### 🛠️ Standard Assistant Workflows
+<table align="center">
+  <tr align="center">
+    <th><p align="center">🧩 Full-Stack Engineer</p></th>
+    <th><p align="center">🗂️ Logging & Planning Management</p></th>
+    <th><p align="center">🔎 Web Search & Learning</p></th>
+  </tr>
+  <tr>
+    <td align="center"><p align="center"><img src="assets/picoclaw_code.gif" width="240" height="180"></p></td>
+    <td align="center"><p align="center"><img src="assets/picoclaw_memory.gif" width="240" height="180"></p></td>
+    <td align="center"><p align="center"><img src="assets/picoclaw_search.gif" width="240" height="180"></p></td>
+  </tr>
+  <tr>
+    <td align="center">Develop • Deploy • Scale</td>
+    <td align="center">Schedule • Automate • Memory</td>
+    <td align="center">Discovery • Insights • Trends</td>
+  </tr>
+</table>
+
+### 🐜 Innovative Low-Footprint Deploy
+1. Minimal 10$ Home Assitant
+2. NanoKVM Automated Maintenance
+3. MaixCAM2 Smart Monitoring
+
+https://private-user-images.githubusercontent.com/83055338/547056448-e7b031ff-d6f5-4468-bcca-5726b6fecb5c.mp4
+
+🌟 More Deployment Cases Await！
+
+## 📦 Install
+
+### Install with precompiled binary
+
+Download the firmware for your platform from the [release](https://github.com/sipeed/picoclaw/releases) page.
+
+### Install from source (latest features, recommended for development)
+
+```bash
+git clone https://github.com/sipeed/picoclaw.git
+
+cd picoclaw
+make deps
+
+# Build, no need to install
+make build
+
+# Build for multiple platforms
+make build-all
+
+# Build And Install
+make install
+```
+
+### 🚀 Quick Start
+
+> [!TIP]
+> Set your API key in `~/.picoclaw/config.json`.
+> Get API keys: [OpenRouter](https://openrouter.ai/keys) (LLM) · [Zhipu](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) (LLM)
+> Web search is **optional** - get free [Brave Search API](https://brave.com/search/api) (2000 free queries/month)
+
+**1. Initialize**
+
+```bash
+picoclaw onboard
+```
+
+**2. Configure** (`~/.picoclaw/config.json`)
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "workspace": "~/.picoclaw/workspace",
+      "model": "glm-4.7",
+      "max_tokens": 8192,
+      "temperature": 0.7,
+      "max_tool_iterations": 20
+    }
+  },
+  "providers": {
+    "openrouter": {
+      "api_key": "xxx",
+      "api_base": "https://open.bigmodel.cn/api/paas/v4"
+    }
+  },
+  "tools": {
+    "web": {
+      "search": {
+        "api_key": "YOUR_BRAVE_API_KEY",
+        "max_results": 5
+      }
+    }
+  }
+}
+```
+
+**3. Get API Keys**
+
+- **LLM Provider**: [OpenRouter](https://openrouter.ai/keys) · [Zhipu](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) · [Anthropic](https://console.anthropic.com) · [OpenAI](https://platform.openai.com)
+- **Web Search** (optional): [Brave Search](https://brave.com/search/api) - Free tier available (2000 requests/month)
+
+> **Note**: See `config.example.json` for a complete configuration template.
+
+- **LLM Provider**: [OpenRouter](https://openrouter.ai/keys) · [Zhipu](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) · [Anthropic](https://console.anthropic.com) · [OpenAI](https://platform.openai.com) · [Gemini](https://aistudio.google.com/api-keys)
+- **Web Search** (optional): [Brave Search](https://brave.com/search/api) - Free tier available (2000 requests/month)
+
+
+**3. Chat**
+
+```bash
+picoclaw agent -m "What is 2+2?"
+```
+
+That's it! You have a working AI assistant in 2 minutes.
+
+---
+
+## 💬 Chat Apps
+
+Talk to your picoclaw through Telegram
+
+| Channel | Setup |
+|---------|-------|
+| **Telegram** | Easy (just a token) |
+| **Discord** | Easy (bot token + intents) |
+
+<details>
+<summary><b>Telegram</b> (Recommended)</summary>
+
+**1. Create a bot**
+
+- Open Telegram, search `@BotFather`
+- Send `/newbot`, follow prompts
+- Copy the token
+
+**2. Configure**
+
+```json
+{
+  "channels": {
+    "telegram": {
+      "enabled": true,
+      "token": "YOUR_BOT_TOKEN",
+      "allowFrom": ["YOUR_USER_ID"]
+    }
+  }
+}
+```
+
+> Get your user ID from `@userinfobot` on Telegram.
+
+**3. Run**
+
+```bash
+picoclaw gateway
+```
+</details>
+
+
+<details>
+<summary><b>Discord</b></summary>
+
+**1. Create a bot**
+- Go to https://discord.com/developers/applications
+- Create an application → Bot → Add Bot
+- Copy the bot token
+
+**2. Enable intents**
+- In the Bot settings, enable **MESSAGE CONTENT INTENT**
+- (Optional) Enable **SERVER MEMBERS INTENT** if you plan to use allow lists based on member data
+
+**3. Get your User ID**
+- Discord Settings → Advanced → enable **Developer Mode**
+- Right-click your avatar → **Copy User ID**
+
+**4. Configure**
+
+```json
+{
+  "channels": {
+    "discord": {
+      "enabled": true,
+      "token": "YOUR_BOT_TOKEN",
+      "allowFrom": ["YOUR_USER_ID"]
+    }
+  }
+}
+```
+
+**5. Invite the bot**
+- OAuth2 → URL Generator
+- Scopes: `bot`
+- Bot Permissions: `Send Messages`, `Read Message History`
+- Open the generated invite URL and add the bot to your server
+
+**6. Run**
+
+```bash
+nanobot gateway
+```
+
+</details>
+
+## ⚙️ Configuration
+
+Config file: `~/.picoclaw/config.json`
+
+### Providers
+
+> [!NOTE]
+> Groq provides free voice transcription via Whisper. If configured, Telegram voice messages will be automatically transcribed.
+
+| Provider | Purpose | Get API Key |
+|----------|---------|-------------|
+| `gemini` | LLM (Gemini direct) | [aistudio.google.com](https://aistudio.google.com) |
+| `zhipu` | LLM (Zhipu direct) | [bigmodel.cn](bigmodel.cn) |
+| `openrouter(To be tested)` | LLM (recommended, access to all models) | [openrouter.ai](https://openrouter.ai) |
+| `anthropic(To be tested)` | LLM (Claude direct) | [console.anthropic.com](https://console.anthropic.com) |
+| `openai(To be tested)` | LLM (GPT direct) | [platform.openai.com](https://platform.openai.com) |
+| `deepseek(To be tested)` | LLM (DeepSeek direct) | [platform.deepseek.com](https://platform.deepseek.com) |
+| `groq(To be tested)` | LLM + **Voice transcription** (Whisper) | [console.groq.com](https://console.groq.com) |
+
+
+<details>
+<summary><b>Zhipu</b></summary>
+
+**1. Get API key and base URL**
+- Get [API key](https://bigmodel.cn/usercenter/proj-mgmt/apikeys)
+
+**2. Configure**
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "workspace": "~/.picoclaw/workspace",
+      "model": "glm-4.7",
+      "max_tokens": 8192,
+      "temperature": 0.7,
+      "max_tool_iterations": 20
+    }
+  },
+  "providers": {
+    "zhipu": {
+      "api_key": "Your API Key",
+      "api_base": "https://open.bigmodel.cn/api/paas/v4"
+    },
+  },
+}
+```
+
+**3. Run**
+
+```bash
+picoclaw agent -m "Hello"
+```
+</details>
+
+<details>
+<summary><b>Full config example</b></summary>
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "model": "anthropic/claude-opus-4-5"
+    }
+  },
+  "providers": {
+    "openrouter": {
+      "apiKey": "sk-or-v1-xxx"
+    },
+    "groq": {
+      "apiKey": "gsk_xxx"
+    }
+  },
+  "channels": {
+    "telegram": {
+      "enabled": true,
+      "token": "123456:ABC...",
+      "allowFrom": ["123456789"]
+    },
+    "discord": {
+      "enabled": true,
+      "token": "",
+      "allow_from": [""]
+    },
+    "whatsapp": {
+      "enabled": false
+    },
+    "feishu": {
+      "enabled": false,
+      "appId": "cli_xxx",
+      "appSecret": "xxx",
+      "encryptKey": "",
+      "verificationToken": "",
+      "allowFrom": []
+    }
+  },
+  "tools": {
+    "web": {
+      "search": {
+        "apiKey": "BSA..."
+      }
+    }
+  }
+}
+```
+
+</details>
+
+## CLI Reference
+
+| Command | Description |
+|---------|-------------|
+| `picoclaw onboard` | Initialize config & workspace |
+| `picoclaw agent -m "..."` | Chat with the agent |
+| `picoclaw agent` | Interactive chat mode |
+| `picoclaw gateway` | Start the gateway |
+| `picoclaw status` | Show status |
+| `picoclaw channels login` | Link WhatsApp (scan QR) |
+| `picoclaw channels status` | Show channel status |
+
+<details>
+<summary><b>Scheduled Tasks (Cron)</b></summary>
+
+```bash
+# Add a job
+picoclaw cron add --name "daily" --message "Good morning!" --cron "0 9 * * *"
+picoclaw cron add --name "hourly" --message "Check status" --every 3600
+
+# List jobs
+picoclaw cron list
+
+# Remove a job
+picoclaw cron remove <job_id>
+```
+
+</details>
+
+## 🤝 Contribute & Roadmap
+
+PRs welcome! The codebase is intentionally small and readable. 🤗
+
+**Roadmap** — Pick an item and [open a PR](https://github.com/HKUDS/picoclaw/pulls)!
+
+
+## 🐛 Troubleshooting
+
+### Web search says "API 配置问题"
+
+This is normal if you haven't configured a search API key yet. PicoClaw will provide helpful links for manual searching.
+
+To enable web search:
+1. Get a free API key at [https://brave.com/search/api](https://brave.com/search/api) (2000 free queries/month)
+2. Add to `~/.picoclaw/config.json`:
+   ```json
+   {
+     "tools": {
+       "web": {
+         "search": {
+           "api_key": "YOUR_BRAVE_API_KEY",
+           "max_results": 5
+         }
+       }
+     }
+   }
+   ```
+
+### Getting content filtering errors
+
+Some providers (like Zhipu) have content filtering. Try rephrasing your query or use a different model.
+
+### Telegram bot says "Conflict: terminated by other getUpdates"
+
+This happens when another instance of the bot is running. Make sure only one `picoclaw gateway` is running at a time.
+
+---
+
+## 📝 API Key Comparison
+
+| Service | Free Tier | Use Case |
+|---------|-----------|-----------|
+| **OpenRouter** | 200K tokens/month | Multiple models (Claude, GPT-4, etc.) |
+| **Zhipu** | 200K tokens/month | Best for Chinese users |
+| **Brave Search** | 2000 queries/month | Web search functionality |
+| **Groq** | Free tier available | Fast inference (Llama, Mixtral) |

config.example.json

@@ -0,0 +1,84 @@
+{
+  "agents": {
+    "defaults": {
+      "workspace": "~/.picoclaw/workspace",
+      "model": "glm-4.7",
+      "max_tokens": 8192,
+      "temperature": 0.7,
+      "max_tool_iterations": 20
+    }
+  },
+  "channels": {
+    "telegram": {
+      "enabled": false,
+      "token": "YOUR_TELEGRAM_BOT_TOKEN",
+      "allow_from": ["YOUR_USER_ID"]
+    },
+    "discord": {
+      "enabled": false,
+      "token": "YOUR_DISCORD_BOT_TOKEN",
+      "allow_from": []
+    },
+    "maixcam": {
+      "enabled": false,
+      "host": "0.0.0.0",
+      "port": 18790,
+      "allow_from": []
+    },
+    "whatsapp": {
+      "enabled": false,
+      "bridge_url": "ws://localhost:3001",
+      "allow_from": []
+    },
+    "feishu": {
+      "enabled": false,
+      "app_id": "",
+      "app_secret": "",
+      "encrypt_key": "",
+      "verification_token": "",
+      "allow_from": []
+    }
+  },
+  "providers": {
+    "anthropic": {
+      "api_key": "",
+      "api_base": ""
+    },
+    "openai": {
+      "api_key": "",
+      "api_base": ""
+    },
+    "openrouter": {
+      "api_key": "sk-or-v1-xxx",
+      "api_base": ""
+    },
+    "groq": {
+      "api_key": "gsk_xxx",
+      "api_base": ""
+    },
+    "zhipu": {
+      "api_key": "YOUR_ZHIPU_API_KEY",
+      "api_base": ""
+    },
+    "gemini": {
+      "api_key": "",
+      "api_base": ""
+    },
+    "vllm": {
+      "api_key": "",
+      "api_base": ""
+    }
+  },
+  "tools": {
+    "web": {
+      "search": {
+        "api_key": "YOUR_BRAVE_API_KEY",
+        "max_results": 5
+      }
+    }
+  },
+  "gateway": {
+    "host": "0.0.0.0",
+    "port": 18790
+  }
+}

go.mod

@@ -0,0 +1,16 @@
+module github.com/sipeed/picoclaw
+
+go 1.18
+
+require (
+	github.com/bwmarrin/discordgo v0.28.1
+	github.com/caarlos0/env/v11 v11.3.1
+	github.com/chzyer/readline v1.5.1
+	github.com/go-telegram-bot-api/telegram-bot-api/v5 v5.5.1
+	github.com/gorilla/websocket v1.5.3
+)
+
+require (
+	golang.org/x/crypto v0.28.0 // indirect
+	golang.org/x/sys v0.40.0 // indirect
+)

go.sum

@@ -0,0 +1,26 @@
+github.com/bwmarrin/discordgo v0.28.1 h1:gXsuo2GBO7NbR6uqmrrBDplPUx2T3nzu775q/Rd1aG4=
+github.com/bwmarrin/discordgo v0.28.1/go.mod h1:NJZpH+1AfhIcyQsPeuBKsUtYrRnjkyu0kIVMCHkZtRY=
+github.com/caarlos0/env/v11 v11.3.1 h1:cArPWC15hWmEt+gWk7YBi7lEXTXCvpaSdCiZE2X5mCA=
+github.com/caarlos0/env/v11 v11.3.1/go.mod h1:qupehSf/Y0TUTsxKywqRt/vJjN5nz6vauiYEUUr8P4U=
+github.com/chzyer/logex v1.2.1 h1:XHDu3E6q+gdHgsdTPH6ImJMIp436vR6MPtH8gP05QzM=
+github.com/chzyer/logex v1.2.1/go.mod h1:JLbx6lG2kDbNRFnfkgvh4eRJRPX1QCoOIWomwysCBrQ=
+github.com/chzyer/readline v1.5.1 h1:upd/6fQk4src78LMRzh5vItIt361/o4uq553V8B5sGI=
+github.com/chzyer/readline v1.5.1/go.mod h1:Eh+b79XXUwfKfcPLepksvw2tcLE/Ct21YObkaSkeBlk=
+github.com/chzyer/test v1.0.0 h1:p3BQDXSxOhOG0P9z6/hGnII4LGiEPOYBhs8asl/fC04=
+github.com/chzyer/test v1.0.0/go.mod h1:2JlltgoNkt4TW/z9V/IzDdFaMTM2JPIi26O1pF38GC8=
+github.com/go-telegram-bot-api/telegram-bot-api/v5 v5.5.1 h1:wG8n/XJQ07TmjbITcGiUaOtXxdrINDz1b0J1w0SzqDc=
+github.com/go-telegram-bot-api/telegram-bot-api/v5 v5.5.1/go.mod h1:A2S0CWkNylc2phvKXWBBdD3K0iGnDBGbzRpISP2zBl8=
+github.com/gorilla/websocket v1.4.2/go.mod h1:YR8l580nyteQvAITg2hZ9XVh4b55+EU/adAjf1fMHhE=
+github.com/gorilla/websocket v1.5.3 h1:saDtZ6Pbx/0u+bgYQ3q96pZgCzfhKXGPqt7kZ72aNNg=
+github.com/gorilla/websocket v1.5.3/go.mod h1:YR8l580nyteQvAITg2hZ9XVh4b55+EU/adAjf1fMHhE=
+golang.org/x/crypto v0.0.0-20210421170649-83a5a9bb288b/go.mod h1:T9bdIzuCu7OtxOm1hfPfRQxPLYneinmdGuTeoZ9dtd4=
+golang.org/x/crypto v0.28.0 h1:GBDwsMXVQi34v5CCYUm2jkJvu4cbtru2U4TN2PSyQnw=
+golang.org/x/crypto v0.28.0/go.mod h1:rmgy+3RHxRZMyY0jjAJShp2zgEdOqj2AO7U0pYmeQ7U=
+golang.org/x/net v0.0.0-20210226172049-e18ecbb05110/go.mod h1:m0MpNAwzfU5UDzcl9v0D8zg8gWTRqZa9RBIspLL5mdg=
+golang.org/x/sys v0.0.0-20201119102817-f84b799fce68/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20220310020820-b874c991c1a5/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.40.0 h1:DBZZqJ2Rkml6QMQsZywtnjnnGvHza6BTfYFWY9kjEWQ=
+golang.org/x/sys v0.40.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
+golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo=
+golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
+golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=

pkg/agent/context.go

@@ -0,0 +1,158 @@
+package agent
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/providers"
+	"github.com/sipeed/picoclaw/pkg/skills"
+)
+
+type ContextBuilder struct {
+	workspace    string
+	skillsLoader *skills.SkillsLoader
+}
+
+func NewContextBuilder(workspace string) *ContextBuilder {
+	builtinSkillsDir := filepath.Join(filepath.Dir(workspace), "picoclaw", "skills")
+	return &ContextBuilder{
+		workspace:    workspace,
+		skillsLoader: skills.NewSkillsLoader(workspace, builtinSkillsDir),
+	}
+}
+
+func (cb *ContextBuilder) BuildSystemPrompt() string {
+	now := time.Now().Format("2006-01-02 15:04 (Monday)")
+	workspacePath, _ := filepath.Abs(filepath.Join(cb.workspace))
+
+	return fmt.Sprintf(`# picoclaw 🦞
+
+You are picoclaw, a helpful AI assistant. You have access to tools that allow you to:
+- Read, write, and edit files
+- Execute shell commands
+- Search the web and fetch web pages
+- Send messages to users on chat channels
+- Spawn subagents for complex background tasks
+
+## Current Time
+%s
+
+## Workspace
+Your workspace is at: %s
+- Memory files: %s/memory/MEMORY.md
+- Daily notes: %s/memory/2006-01-02.md
+- Custom skills: %s/skills/{skill-name}/SKILL.md
+
+## Weather Information
+When users ask about weather, use the web_fetch tool with wttr.in URLs:
+- Current weather: https://wttr.in/{city}?format=j1
+- Beijing: https://wttr.in/Beijing?format=j1
+- Shanghai: https://wttr.in/Shanghai?format=j1
+- New York: https://wttr.in/New_York?format=j1
+- London: https://wttr.in/London?format=j1
+- Tokyo: https://wttr.in/Tokyo?format=j1
+
+IMPORTANT: When responding to direct questions or conversations, reply directly with your text response.
+Only use the 'message' tool when you need to send a message to a specific chat channel (like WhatsApp).
+For normal conversation, just respond with text - do not call the message tool.
+
+Always be helpful, accurate, and concise. When using tools, explain what you're doing.
+When remembering something, write to %s/memory/MEMORY.md`,
+		now, workspacePath, workspacePath, workspacePath, workspacePath, workspacePath)
+}
+
+func (cb *ContextBuilder) LoadBootstrapFiles() string {
+	bootstrapFiles := []string{
+		"AGENTS.md",
+		"SOUL.md",
+		"USER.md",
+		"TOOLS.md",
+		"IDENTITY.md",
+		"MEMORY.md",
+	}
+
+	var result string
+	for _, filename := range bootstrapFiles {
+		filePath := filepath.Join(cb.workspace, filename)
+		if data, err := os.ReadFile(filePath); err == nil {
+			result += fmt.Sprintf("## %s\n\n%s\n\n", filename, string(data))
+		}
+	}
+
+	return result
+}
+
+func (cb *ContextBuilder) BuildMessages(history []providers.Message, currentMessage string, media []string) []providers.Message {
+	messages := []providers.Message{}
+
+	systemPrompt := cb.BuildSystemPrompt()
+	bootstrapContent := cb.LoadBootstrapFiles()
+	if bootstrapContent != "" {
+		systemPrompt += "\n\n" + bootstrapContent
+	}
+
+	skillsSummary := cb.skillsLoader.BuildSkillsSummary()
+	if skillsSummary != "" {
+		systemPrompt += "\n\n## Available Skills\n\n" + skillsSummary
+	}
+
+	skillsContent := cb.loadSkills()
+	if skillsContent != "" {
+		systemPrompt += "\n\n" + skillsContent
+	}
+
+	messages = append(messages, providers.Message{
+		Role:    "system",
+		Content: systemPrompt,
+	})
+
+	messages = append(messages, history...)
+
+	messages = append(messages, providers.Message{
+		Role:    "user",
+		Content: currentMessage,
+	})
+
+	return messages
+}
+
+func (cb *ContextBuilder) AddToolResult(messages []providers.Message, toolCallID, toolName, result string) []providers.Message {
+	messages = append(messages, providers.Message{
+		Role:       "tool",
+		Content:    result,
+		ToolCallID: toolCallID,
+	})
+	return messages
+}
+
+func (cb *ContextBuilder) AddAssistantMessage(messages []providers.Message, content string, toolCalls []map[string]interface{}) []providers.Message {
+	msg := providers.Message{
+		Role:    "assistant",
+		Content: content,
+	}
+	if len(toolCalls) > 0 {
+		messages = append(messages, msg)
+	}
+	return messages
+}
+
+func (cb *ContextBuilder) loadSkills() string {
+	allSkills := cb.skillsLoader.ListSkills(true)
+	if len(allSkills) == 0 {
+		return ""
+	}
+
+	var skillNames []string
+	for _, s := range allSkills {
+		skillNames = append(skillNames, s.Name)
+	}
+
+	content := cb.skillsLoader.LoadSkillsForContext(skillNames)
+	if content == "" {
+		return ""
+	}
+
+	return "# Skill Definitions\n\n" + content
+}

pkg/agent/loop.go

@@ -0,0 +1,193 @@
+// PicoClaw - Ultra-lightweight personal AI agent
+// Inspired by and based on nanobot: https://github.com/HKUDS/nanobot
+// License: MIT
+//
+// Copyright (c) 2026 PicoClaw contributors
+
+package agent
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/providers"
+	"github.com/sipeed/picoclaw/pkg/session"
+	"github.com/sipeed/picoclaw/pkg/tools"
+)
+
+type AgentLoop struct {
+	bus            *bus.MessageBus
+	provider       providers.LLMProvider
+	workspace      string
+	model          string
+	maxIterations  int
+	sessions       *session.SessionManager
+	contextBuilder *ContextBuilder
+	tools          *tools.ToolRegistry
+	running        bool
+}
+
+func NewAgentLoop(cfg *config.Config, bus *bus.MessageBus, provider providers.LLMProvider) *AgentLoop {
+	workspace := cfg.WorkspacePath()
+	os.MkdirAll(workspace, 0755)
+
+	toolsRegistry := tools.NewToolRegistry()
+	toolsRegistry.Register(&tools.ReadFileTool{})
+	toolsRegistry.Register(&tools.WriteFileTool{})
+	toolsRegistry.Register(&tools.ListDirTool{})
+	toolsRegistry.Register(tools.NewExecTool(workspace))
+
+	braveAPIKey := cfg.Tools.Web.Search.APIKey
+	toolsRegistry.Register(tools.NewWebSearchTool(braveAPIKey, cfg.Tools.Web.Search.MaxResults))
+	toolsRegistry.Register(tools.NewWebFetchTool(50000))
+
+	sessionsManager := session.NewSessionManager(filepath.Join(filepath.Dir(cfg.WorkspacePath()), "sessions"))
+
+	return &AgentLoop{
+		bus:            bus,
+		provider:       provider,
+		workspace:      workspace,
+		model:          cfg.Agents.Defaults.Model,
+		maxIterations:  cfg.Agents.Defaults.MaxToolIterations,
+		sessions:       sessionsManager,
+		contextBuilder: NewContextBuilder(workspace),
+		tools:          toolsRegistry,
+		running:        false,
+	}
+}
+
+func (al *AgentLoop) Run(ctx context.Context) error {
+	al.running = true
+
+	for al.running {
+		select {
+		case <-ctx.Done():
+			return nil
+		default:
+			msg, ok := al.bus.ConsumeInbound(ctx)
+			if !ok {
+				continue
+			}
+
+			response, err := al.processMessage(ctx, msg)
+			if err != nil {
+				response = fmt.Sprintf("Error processing message: %v", err)
+			}
+
+			if response != "" {
+				al.bus.PublishOutbound(bus.OutboundMessage{
+					Channel: msg.Channel,
+					ChatID:  msg.ChatID,
+					Content: response,
+				})
+			}
+		}
+	}
+
+	return nil
+}
+
+func (al *AgentLoop) Stop() {
+	al.running = false
+}
+
+func (al *AgentLoop) ProcessDirect(ctx context.Context, content, sessionKey string) (string, error) {
+	msg := bus.InboundMessage{
+		Channel:    "cli",
+		SenderID:   "user",
+		ChatID:     "direct",
+		Content:    content,
+		SessionKey: sessionKey,
+	}
+
+	return al.processMessage(ctx, msg)
+}
+
+func (al *AgentLoop) processMessage(ctx context.Context, msg bus.InboundMessage) (string, error) {
+	messages := al.contextBuilder.BuildMessages(
+		al.sessions.GetHistory(msg.SessionKey),
+		msg.Content,
+		nil,
+	)
+
+	iteration := 0
+	var finalContent string
+
+	for iteration < al.maxIterations {
+		iteration++
+
+		toolDefs := al.tools.GetDefinitions()
+		providerToolDefs := make([]providers.ToolDefinition, 0, len(toolDefs))
+		for _, td := range toolDefs {
+			providerToolDefs = append(providerToolDefs, providers.ToolDefinition{
+				Type: td["type"].(string),
+				Function: providers.ToolFunctionDefinition{
+					Name:        td["function"].(map[string]interface{})["name"].(string),
+					Description: td["function"].(map[string]interface{})["description"].(string),
+					Parameters:  td["function"].(map[string]interface{})["parameters"].(map[string]interface{}),
+				},
+			})
+		}
+
+		response, err := al.provider.Chat(ctx, messages, providerToolDefs, al.model, map[string]interface{}{
+			"max_tokens":  8192,
+			"temperature": 0.7,
+		})
+
+		if err != nil {
+			return "", fmt.Errorf("LLM call failed: %w", err)
+		}
+
+		if len(response.ToolCalls) == 0 {
+			finalContent = response.Content
+			break
+		}
+
+		assistantMsg := providers.Message{
+			Role:    "assistant",
+			Content: response.Content,
+		}
+
+		for _, tc := range response.ToolCalls {
+			argumentsJSON, _ := json.Marshal(tc.Arguments)
+			assistantMsg.ToolCalls = append(assistantMsg.ToolCalls, providers.ToolCall{
+				ID:   tc.ID,
+				Type: "function",
+				Function: &providers.FunctionCall{
+					Name:      tc.Name,
+					Arguments: string(argumentsJSON),
+				},
+			})
+		}
+		messages = append(messages, assistantMsg)
+
+		for _, tc := range response.ToolCalls {
+			result, err := al.tools.Execute(ctx, tc.Name, tc.Arguments)
+			if err != nil {
+				result = fmt.Sprintf("Error: %v", err)
+			}
+
+			toolResultMsg := providers.Message{
+				Role:       "tool",
+				Content:    result,
+				ToolCallID: tc.ID,
+			}
+			messages = append(messages, toolResultMsg)
+		}
+	}
+
+	if finalContent == "" {
+		finalContent = "I've completed processing but have no response to give."
+	}
+
+	al.sessions.AddMessage(msg.SessionKey, "user", msg.Content)
+	al.sessions.AddMessage(msg.SessionKey, "assistant", finalContent)
+	al.sessions.Save(al.sessions.GetOrCreate(msg.SessionKey))
+
+	return finalContent, nil
+}

pkg/bus/bus.go

@@ -0,0 +1,65 @@
+package bus
+
+import (
+	"context"
+	"sync"
+)
+
+type MessageBus struct {
+	inbound  chan InboundMessage
+	outbound chan OutboundMessage
+	handlers map[string]MessageHandler
+	mu       sync.RWMutex
+}
+
+func NewMessageBus() *MessageBus {
+	return &MessageBus{
+		inbound:  make(chan InboundMessage, 100),
+		outbound: make(chan OutboundMessage, 100),
+		handlers: make(map[string]MessageHandler),
+	}
+}
+
+func (mb *MessageBus) PublishInbound(msg InboundMessage) {
+	mb.inbound <- msg
+}
+
+func (mb *MessageBus) ConsumeInbound(ctx context.Context) (InboundMessage, bool) {
+	select {
+	case msg := <-mb.inbound:
+		return msg, true
+	case <-ctx.Done():
+		return InboundMessage{}, false
+	}
+}
+
+func (mb *MessageBus) PublishOutbound(msg OutboundMessage) {
+	mb.outbound <- msg
+}
+
+func (mb *MessageBus) SubscribeOutbound(ctx context.Context) (OutboundMessage, bool) {
+	select {
+	case msg := <-mb.outbound:
+		return msg, true
+	case <-ctx.Done():
+		return OutboundMessage{}, false
+	}
+}
+
+func (mb *MessageBus) RegisterHandler(channel string, handler MessageHandler) {
+	mb.mu.Lock()
+	defer mb.mu.Unlock()
+	mb.handlers[channel] = handler
+}
+
+func (mb *MessageBus) GetHandler(channel string) (MessageHandler, bool) {
+	mb.mu.RLock()
+	defer mb.mu.RUnlock()
+	handler, ok := mb.handlers[channel]
+	return handler, ok
+}
+
+func (mb *MessageBus) Close() {
+	close(mb.inbound)
+	close(mb.outbound)
+}

pkg/bus/types.go

@@ -0,0 +1,19 @@
+package bus
+
+type InboundMessage struct {
+	Channel    string            `json:"channel"`
+	SenderID   string            `json:"sender_id"`
+	ChatID     string            `json:"chat_id"`
+	Content    string            `json:"content"`
+	Media      []string          `json:"media,omitempty"`
+	SessionKey string            `json:"session_key"`
+	Metadata   map[string]string `json:"metadata,omitempty"`
+}
+
+type OutboundMessage struct {
+	Channel string `json:"channel"`
+	ChatID  string `json:"chat_id"`
+	Content string `json:"content"`
+}
+
+type MessageHandler func(InboundMessage) error

pkg/channels/base.go

@@ -0,0 +1,77 @@
+package channels
+
+import (
+	"context"
+
+	"github.com/sipeed/picoclaw/pkg/bus"
+)
+
+type Channel interface {
+	Name() string
+	Start(ctx context.Context) error
+	Stop(ctx context.Context) error
+	Send(ctx context.Context, msg bus.OutboundMessage) error
+	IsRunning() bool
+	IsAllowed(senderID string) bool
+}
+
+type BaseChannel struct {
+	config    interface{}
+	bus       *bus.MessageBus
+	running   bool
+	name      string
+	allowList []string
+}
+
+func NewBaseChannel(name string, config interface{}, bus *bus.MessageBus, allowList []string) *BaseChannel {
+	return &BaseChannel{
+		config:    config,
+		bus:       bus,
+		name:      name,
+		allowList: allowList,
+		running:   false,
+	}
+}
+
+func (c *BaseChannel) Name() string {
+	return c.name
+}
+
+func (c *BaseChannel) IsRunning() bool {
+	return c.running
+}
+
+func (c *BaseChannel) IsAllowed(senderID string) bool {
+	if len(c.allowList) == 0 {
+		return true
+	}
+
+	for _, allowed := range c.allowList {
+		if senderID == allowed {
+			return true
+		}
+	}
+
+	return false
+}
+
+func (c *BaseChannel) HandleMessage(senderID, chatID, content string, media []string, metadata map[string]string) {
+	if !c.IsAllowed(senderID) {
+		return
+	}
+
+	msg := bus.InboundMessage{
+		Channel:  c.name,
+		SenderID: senderID,
+		ChatID:   chatID,
+		Content:  content,
+		Media:    media,
+		Metadata: metadata,
+	}
+
+	c.bus.PublishInbound(msg)
+}
+
+func (c *BaseChannel) setRunning(running bool) {
+	c.running = running
+}

pkg/channels/discord.go

@@ -0,0 +1,138 @@
+package channels
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/bwmarrin/discordgo"
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/logger"
+)
+
+type DiscordChannel struct {
+	*BaseChannel
+	session *discordgo.Session
+	config  config.DiscordConfig
+}
+
+func NewDiscordChannel(cfg config.DiscordConfig, bus *bus.MessageBus) (*DiscordChannel, error) {
+	session, err := discordgo.New("Bot " + cfg.Token)
+	if err != nil {
+		return nil, fmt.Errorf("failed to create discord session: %w", err)
+	}
+
+	base := NewBaseChannel("discord", cfg, bus, cfg.AllowFrom)
+
+	return &DiscordChannel{
+		BaseChannel: base,
+		session:     session,
+		config:      cfg,
+	}, nil
+}
+
+func (c *DiscordChannel) Start(ctx context.Context) error {
+	logger.InfoC("discord", "Starting Discord bot")
+
+	c.session.AddHandler(c.handleMessage)
+
+	if err := c.session.Open(); err != nil {
+		return fmt.Errorf("failed to open discord session: %w", err)
+	}
+
+	c.setRunning(true)
+
+	botUser, err := c.session.User("@me")
+	if err != nil {
+		return fmt.Errorf("failed to get bot user: %w", err)
+	}
+	logger.InfoCF("discord", "Discord bot connected", map[string]interface{}{
+		"username": botUser.Username,
+		"user_id":  botUser.ID,
+	})
+
+	return nil
+}
+
+func (c *DiscordChannel) Stop(ctx context.Context) error {
+	logger.InfoC("discord", "Stopping Discord bot")
+	c.setRunning(false)
+
+	if err := c.session.Close(); err != nil {
+		return fmt.Errorf("failed to close discord session: %w", err)
+	}
+
+	return nil
+}
+
+func (c *DiscordChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
+	if !c.IsRunning() {
+		return fmt.Errorf("discord bot not running")
+	}
+
+	channelID := msg.ChatID
+	if channelID == "" {
+		return fmt.Errorf("channel ID is empty")
+	}
+
+	message := msg.Content
+
+	if _, err := c.session.ChannelMessageSend(channelID, message); err != nil {
+		return fmt.Errorf("failed to send discord message: %w", err)
+	}
+
+	return nil
+}
+
+func (c *DiscordChannel) handleMessage(s *discordgo.Session, m *discordgo.MessageCreate) {
+	if m == nil || m.Author == nil {
+		return
+	}
+
+	if m.Author.ID == s.State.User.ID {
+		return
+	}
+
+	senderID := m.Author.ID
+	senderName := m.Author.Username
+	if m.Author.Discriminator != "" && m.Author.Discriminator != "0" {
+		senderName += "#" + m.Author.Discriminator
+	}
+
+	content := m.Content
+	mediaPaths := []string{}
+
+	for _, attachment := range m.Attachments {
+		mediaPaths = append(mediaPaths, attachment.URL)
+		if content != "" {
+			content += "\n"
+		}
+		content += fmt.Sprintf("[attachment: %s]", attachment.URL)
+	}
+
+	if content == "" && len(mediaPaths) == 0 {
+		return
+	}
+
+	if content == "" {
+		content = "[media only]"
+	}
+
+	logger.DebugCF("discord", "Received message", map[string]interface{}{
+		"sender_name": senderName,
+		"sender_id":   senderID,
+		"preview":     truncateString(content, 50),
+	})
+
+	metadata := map[string]string{
+		"message_id":   m.ID,
+		"user_id":      senderID,
+		"username":     m.Author.Username,
+		"display_name": senderName,
+		"guild_id":     m.GuildID,
+		"channel_id":   m.ChannelID,
+		"is_dm":        fmt.Sprintf("%t", m.GuildID == ""),
+	}
+
+	c.HandleMessage(senderID, m.ChannelID, content, mediaPaths, metadata)
+}

pkg/channels/feishu.go

@@ -0,0 +1,70 @@
+package channels
+
+import (
+	"context"
+	"fmt"
+	"log"
+
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+type FeishuChannel struct {
+	*BaseChannel
+	config config.FeishuConfig
+}
+
+func NewFeishuChannel(cfg config.FeishuConfig, bus *bus.MessageBus) (*FeishuChannel, error) {
+	base := NewBaseChannel("feishu", cfg, bus, cfg.AllowFrom)
+
+	return &FeishuChannel{
+		BaseChannel: base,
+		config:      cfg,
+	}, nil
+}
+
+func (c *FeishuChannel) Start(ctx context.Context) error {
+	log.Println("Feishu channel started")
+	c.setRunning(true)
+	return nil
+}
+
+func (c *FeishuChannel) Stop(ctx context.Context) error {
+	log.Println("Feishu channel stopped")
+	c.setRunning(false)
+	return nil
+}
+
+func (c *FeishuChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
+	if !c.IsRunning() {
+		return fmt.Errorf("feishu channel not running")
+	}
+
+	htmlContent := markdownToFeishuCard(msg.Content)
+
+	log.Printf("Feishu send to %s: %s", msg.ChatID, truncateString(htmlContent, 100))
+
+	return nil
+}
+
+func (c *FeishuChannel) handleIncomingMessage(data map[string]interface{}) {
+	senderID, _ := data["sender_id"].(string)
+	chatID, _ := data["chat_id"].(string)
+	content, _ := data["content"].(string)
+
+	log.Printf("Feishu message from %s: %s...", senderID, truncateString(content, 50))
+
+	metadata := make(map[string]string)
+	if messageID, ok := data["message_id"].(string); ok {
+		metadata["message_id"] = messageID
+	}
+	if userName, ok := data["sender_name"].(string); ok {
+		metadata["sender_name"] = userName
+	}
+
+	c.HandleMessage(senderID, chatID, content, nil, metadata)
+}
+
+func markdownToFeishuCard(markdown string) string {
+	return markdown
+}

pkg/channels/maixcam.go

@@ -0,0 +1,243 @@
+package channels
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"net"
+	"sync"
+
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/logger"
+)
+
+type MaixCamChannel struct {
+	*BaseChannel
+	config     config.MaixCamConfig
+	listener   net.Listener
+	clients    map[net.Conn]bool
+	clientsMux sync.RWMutex
+	running    bool
+}
+
+type MaixCamMessage struct {
+	Type      string                 `json:"type"`
+	Tips      string                 `json:"tips"`
+	Timestamp float64                `json:"timestamp"`
+	Data      map[string]interface{} `json:"data"`
+}
+
+func NewMaixCamChannel(cfg config.MaixCamConfig, bus *bus.MessageBus) (*MaixCamChannel, error) {
+	base := NewBaseChannel("maixcam", cfg, bus, cfg.AllowFrom)
+
+	return &MaixCamChannel{
+		BaseChannel: base,
+		config:      cfg,
+		clients:     make(map[net.Conn]bool),
+		running:     false,
+	}, nil
+}
+
+func (c *MaixCamChannel) Start(ctx context.Context) error {
+	logger.InfoC("maixcam", "Starting MaixCam channel server")
+
+	addr := fmt.Sprintf("%s:%d", c.config.Host, c.config.Port)
+	listener, err := net.Listen("tcp", addr)
+	if err != nil {
+		return fmt.Errorf("failed to listen on %s: %w", addr, err)
+	}
+
+	c.listener = listener
+	c.setRunning(true)
+
+	logger.InfoCF("maixcam", "MaixCam server listening", map[string]interface{}{
+		"host": c.config.Host,
+		"port": c.config.Port,
+	})
+
+	go c.acceptConnections(ctx)
+
+	return nil
+}
+
+func (c *MaixCamChannel) acceptConnections(ctx context.Context) {
+	logger.DebugC("maixcam", "Starting connection acceptor")
+
+	for {
+		select {
+		case <-ctx.Done():
+			logger.InfoC("maixcam", "Stopping connection acceptor")
+			return
+		default:
+			conn, err := c.listener.Accept()
+			if err != nil {
+				if c.running {
+					logger.ErrorCF("maixcam", "Failed to accept connection", map[string]interface{}{
+						"error": err.Error(),
+					})
+				}
+				return
+			}
+
+			logger.InfoCF("maixcam", "New connection from MaixCam device", map[string]interface{}{
+				"remote_addr": conn.RemoteAddr().String(),
+			})
+
+			c.clientsMux.Lock()
+			c.clients[conn] = true
+			c.clientsMux.Unlock()
+
+			go c.handleConnection(conn, ctx)
+		}
+	}
+}
+
+func (c *MaixCamChannel) handleConnection(conn net.Conn, ctx context.Context) {
+	logger.DebugC("maixcam", "Handling MaixCam connection")
+
+	defer func() {
+		conn.Close()
+		c.clientsMux.Lock()
+		delete(c.clients, conn)
+		c.clientsMux.Unlock()
+		logger.DebugC("maixcam", "Connection closed")
+	}()
+
+	decoder := json.NewDecoder(conn)
+
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		default:
+			var msg MaixCamMessage
+			if err := decoder.Decode(&msg); err != nil {
+				if err.Error() != "EOF" {
+					logger.ErrorCF("maixcam", "Failed to decode message", map[string]interface{}{
+						"error": err.Error(),
+					})
+				}
+				return
+			}
+
+			c.processMessage(msg, conn)
+		}
+	}
+}
+
+func (c *MaixCamChannel) processMessage(msg MaixCamMessage, conn net.Conn) {
+	switch msg.Type {
+	case "person_detected":
+		c.handlePersonDetection(msg)
+	case "heartbeat":
+		logger.DebugC("maixcam", "Received heartbeat")
+	case "status":
+		c.handleStatusUpdate(msg)
+	default:
+		logger.WarnCF("maixcam", "Unknown message type", map[string]interface{}{
+			"type": msg.Type,
+		})
+	}
+}
+
+func (c *MaixCamChannel) handlePersonDetection(msg MaixCamMessage) {
+	logger.InfoCF("maixcam", "", map[string]interface{}{
+		"timestamp": msg.Timestamp,
+		"data":      msg.Data,
+	})
+
+	senderID := "maixcam"
+	chatID := "default"
+
+	classInfo, ok := msg.Data["class_name"].(string)
+	if !ok {
+		classInfo = "person"
+	}
+
+	score, _ := msg.Data["score"].(float64)
+	x, _ := msg.Data["x"].(float64)
+	y, _ := msg.Data["y"].(float64)
+	w, _ := msg.Data["w"].(float64)
+	h, _ := msg.Data["h"].(float64)
+
+	content := fmt.Sprintf("📷 Person detected!\nClass: %s\nConfidence: %.2f%%\nPosition: (%.0f, %.0f)\nSize: %.0fx%.0f",
+		classInfo, score*100, x, y, w, h)
+
+	metadata := map[string]string{
+		"timestamp": fmt.Sprintf("%.0f", msg.Timestamp),
+		"class_id":  fmt.Sprintf("%.0f", msg.Data["class_id"]),
+		"score":     fmt.Sprintf("%.2f", score),
+		"x":         fmt.Sprintf("%.0f", x),
+		"y":         fmt.Sprintf("%.0f", y),
+		"w":         fmt.Sprintf("%.0f", w),
+		"h":         fmt.Sprintf("%.0f", h),
+	}
+
+	c.HandleMessage(senderID, chatID, content, []string{}, metadata)
+}
+
+func (c *MaixCamChannel) handleStatusUpdate(msg MaixCamMessage) {
+	logger.InfoCF("maixcam", "Status update from MaixCam", map[string]interface{}{
+		"status": msg.Data,
+	})
+}
+
+func (c *MaixCamChannel) Stop(ctx context.Context) error {
+	logger.InfoC("maixcam", "Stopping MaixCam channel")
+	c.setRunning(false)
+
+	if c.listener != nil {
+		c.listener.Close()
+	}
+
+	c.clientsMux.Lock()
+	defer c.clientsMux.Unlock()
+
+	for conn := range c.clients {
+		conn.Close()
+	}
+	c.clients = make(map[net.Conn]bool)
+
+	logger.InfoC("maixcam", "MaixCam channel stopped")
+	return nil
+}
+
+func (c *MaixCamChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
+	if !c.IsRunning() {
+		return fmt.Errorf("maixcam channel not running")
+	}
+
+	c.clientsMux.RLock()
+	defer c.clientsMux.RUnlock()
+
+	if len(c.clients) == 0 {
+		logger.WarnC("maixcam", "No MaixCam devices connected")
+		return fmt.Errorf("no connected MaixCam devices")
+	}
+
+	response := map[string]interface{}{
+		"type":      "command",
+		"timestamp": float64(0),
+		"message":   msg.Content,
+		"chat_id":   msg.ChatID,
+	}
+
+	data, err := json.Marshal(response)
+	if err != nil {
+		return fmt.Errorf("failed to marshal response: %w", err)
+	}
+
+	var sendErr error
+	for conn := range c.clients {
+		if _, err := conn.Write(data); err != nil {
+			logger.ErrorCF("maixcam", "Failed to send to client", map[string]interface{}{
+				"client": conn.RemoteAddr().String(),
+				"error":  err.Error(),
+			})
+			sendErr = err
+		}
+	}
+
+	return sendErr
+}

pkg/channels/manager.go

@@ -0,0 +1,261 @@
+// PicoClaw - Ultra-lightweight personal AI agent
+// Inspired by and based on nanobot: https://github.com/HKUDS/nanobot
+// License: MIT
+//
+// Copyright (c) 2026 PicoClaw contributors
+
+package channels
+
+import (
+	"context"
+	"fmt"
+	"sync"
+
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/logger"
+)
+
+type Manager struct {
+	channels     map[string]Channel
+	bus          *bus.MessageBus
+	config       *config.Config
+	dispatchTask *asyncTask
+	mu           sync.RWMutex
+}
+
+type asyncTask struct {
+	cancel context.CancelFunc
+}
+
+func NewManager(cfg *config.Config, messageBus *bus.MessageBus) (*Manager, error) {
+	m := &Manager{
+		channels: make(map[string]Channel),
+		bus:      messageBus,
+		config:   cfg,
+	}
+
+	if err := m.initChannels(); err != nil {
+		return nil, err
+	}
+
+	return m, nil
+}
+
+func (m *Manager) initChannels() error {
+	logger.InfoC("channels", "Initializing channel manager")
+
+	if m.config.Channels.Telegram.Enabled && m.config.Channels.Telegram.Token != "" {
+		logger.DebugC("channels", "Attempting to initialize Telegram channel")
+		telegram, err := NewTelegramChannel(m.config.Channels.Telegram, m.bus)
+		if err != nil {
+			logger.ErrorCF("channels", "Failed to initialize Telegram channel", map[string]interface{}{
+				"error": err.Error(),
+			})
+		} else {
+			m.channels["telegram"] = telegram
+			logger.InfoC("channels", "Telegram channel enabled successfully")
+		}
+	}
+
+	if m.config.Channels.WhatsApp.Enabled && m.config.Channels.WhatsApp.BridgeURL != "" {
+		logger.DebugC("channels", "Attempting to initialize WhatsApp channel")
+		whatsapp, err := NewWhatsAppChannel(m.config.Channels.WhatsApp, m.bus)
+		if err != nil {
+			logger.ErrorCF("channels", "Failed to initialize WhatsApp channel", map[string]interface{}{
+				"error": err.Error(),
+			})
+		} else {
+			m.channels["whatsapp"] = whatsapp
+			logger.InfoC("channels", "WhatsApp channel enabled successfully")
+		}
+	}
+
+	if m.config.Channels.Discord.Enabled && m.config.Channels.Discord.Token != "" {
+		logger.DebugC("channels", "Attempting to initialize Discord channel")
+		discord, err := NewDiscordChannel(m.config.Channels.Discord, m.bus)
+		if err != nil {
+			logger.ErrorCF("channels", "Failed to initialize Discord channel", map[string]interface{}{
+				"error": err.Error(),
+			})
+		} else {
+			m.channels["discord"] = discord
+			logger.InfoC("channels", "Discord channel enabled successfully")
+		}
+	}
+
+	if m.config.Channels.MaixCam.Enabled {
+		logger.DebugC("channels", "Attempting to initialize MaixCam channel")
+		maixcam, err := NewMaixCamChannel(m.config.Channels.MaixCam, m.bus)
+		if err != nil {
+			logger.ErrorCF("channels", "Failed to initialize MaixCam channel", map[string]interface{}{
+				"error": err.Error(),
+			})
+		} else {
+			m.channels["maixcam"] = maixcam
+			logger.InfoC("channels", "MaixCam channel enabled successfully")
+		}
+	}
+
+	logger.InfoCF("channels", "Channel initialization completed", map[string]interface{}{
+		"enabled_channels": len(m.channels),
+	})
+
+	return nil
+}
+
+func (m *Manager) StartAll(ctx context.Context) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+
+	if len(m.channels) == 0 {
+		logger.WarnC("channels", "No channels enabled")
+		return nil
+	}
+
+	logger.InfoC("channels", "Starting all channels")
+
+	dispatchCtx, cancel := context.WithCancel(ctx)
+	m.dispatchTask = &asyncTask{cancel: cancel}
+
+	go m.dispatchOutbound(dispatchCtx)
+
+	for name, channel := range m.channels {
+		logger.InfoCF("channels", "Starting channel", map[string]interface{}{
+			"channel": name,
+		})
+		if err := channel.Start(ctx); err != nil {
+			logger.ErrorCF("channels", "Failed to start channel", map[string]interface{}{
+				"channel": name,
+				"error":   err.Error(),
+			})
+		}
+	}
+
+	logger.InfoC("channels", "All channels started")
+	return nil
+}
+
+func (m *Manager) StopAll(ctx context.Context) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+
+	logger.InfoC("channels", "Stopping all channels")
+
+	if m.dispatchTask != nil {
+		m.dispatchTask.cancel()
+		m.dispatchTask = nil
+	}
+
+	for name, channel := range m.channels {
+		logger.InfoCF("channels", "Stopping channel", map[string]interface{}{
+			"channel": name,
+		})
+		if err := channel.Stop(ctx); err != nil {
+			logger.ErrorCF("channels", "Error stopping channel", map[string]interface{}{
+				"channel": name,
+				"error":   err.Error(),
+			})
+		}
+	}
+
+	logger.InfoC("channels", "All channels stopped")
+	return nil
+}
+
+func (m *Manager) dispatchOutbound(ctx context.Context) {
+	logger.InfoC("channels", "Outbound dispatcher started")
+
+	for {
+		select {
+		case <-ctx.Done():
+			logger.InfoC("channels", "Outbound dispatcher stopped")
+			return
+		default:
+			msg, ok := m.bus.SubscribeOutbound(ctx)
+			if !ok {
+				continue
+			}
+
+			m.mu.RLock()
+			channel, exists := m.channels[msg.Channel]
+			m.mu.RUnlock()
+
+			if !exists {
+				logger.WarnCF("channels", "Unknown channel for outbound message", map[string]interface{}{
+					"channel": msg.Channel,
+				})
+				continue
+			}
+
+			if err := channel.Send(ctx, msg); err != nil {
+				logger.ErrorCF("channels", "Error sending message to channel", map[string]interface{}{
+					"channel": msg.Channel,
+					"error":   err.Error(),
+				})
+			}
+		}
+	}
+}
+
+func (m *Manager) GetChannel(name string) (Channel, bool) {
+	m.mu.RLock()
+	defer m.mu.RUnlock()
+	channel, ok := m.channels[name]
+	return channel, ok
+}
+
+func (m *Manager) GetStatus() map[string]interface{} {
+	m.mu.RLock()
+	defer m.mu.RUnlock()
+
+	status := make(map[string]interface{})
+	for name, channel := range m.channels {
+		status[name] = map[string]interface{}{
+			"enabled": true,
+			"running": channel.IsRunning(),
+		}
+	}
+	return status
+}
+
+func (m *Manager) GetEnabledChannels() []string {
+	m.mu.RLock()
+	defer m.mu.RUnlock()
+
+	names := make([]string, 0, len(m.channels))
+	for name := range m.channels {
+		names = append(names, name)
+	}
+	return names
+}
+
+func (m *Manager) RegisterChannel(name string, channel Channel) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	m.channels[name] = channel
+}
+
+func (m *Manager) UnregisterChannel(name string) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	delete(m.channels, name)
+}
+
+func (m *Manager) SendToChannel(ctx context.Context, channelName, chatID, content string) error {
+	m.mu.RLock()
+	channel, exists := m.channels[channelName]
+	m.mu.RUnlock()
+
+	if !exists {
+		return fmt.Errorf("channel %s not found", channelName)
+	}
+
+	msg := bus.OutboundMessage{
+		Channel: channelName,
+		ChatID:  chatID,
+		Content: content,
+	}
+
+	return channel.Send(ctx, msg)
+}

pkg/channels/telegram.go

@@ -0,0 +1,394 @@
+package channels
+
+import (
+	"context"
+	"fmt"
+	"log"
+	"regexp"
+	"strings"
+	"time"
+
+	tgbotapi "github.com/go-telegram-bot-api/telegram-bot-api/v5"
+
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/voice"
+)
+
+type TelegramChannel struct {
+	*BaseChannel
+	bot         *tgbotapi.BotAPI
+	config      config.TelegramConfig
+	chatIDs     map[string]int64
+	updates     tgbotapi.UpdatesChannel
+	transcriber *voice.GroqTranscriber
+}
+
+func NewTelegramChannel(cfg config.TelegramConfig, bus *bus.MessageBus) (*TelegramChannel, error) {
+	bot, err := tgbotapi.NewBotAPI(cfg.Token)
+	if err != nil {
+		return nil, fmt.Errorf("failed to create telegram bot: %w", err)
+	}
+
+	base := NewBaseChannel("telegram", cfg, bus, cfg.AllowFrom)
+
+	return &TelegramChannel{
+		BaseChannel: base,
+		bot:         bot,
+		config:      cfg,
+		chatIDs:     make(map[string]int64),
+		transcriber: nil,
+	}, nil
+}
+
+func (c *TelegramChannel) SetTranscriber(transcriber *voice.GroqTranscriber) {
+	c.transcriber = transcriber
+}
+
+func (c *TelegramChannel) Start(ctx context.Context) error {
+	log.Printf("Starting Telegram bot (polling mode)...")
+
+	u := tgbotapi.NewUpdate(0)
+	u.Timeout = 30
+
+	updates := c.bot.GetUpdatesChan(u)
+	c.updates = updates
+
+	c.setRunning(true)
+
+	botInfo, err := c.bot.GetMe()
+	if err != nil {
+		return fmt.Errorf("failed to get bot info: %w", err)
+	}
+	log.Printf("Telegram bot @%s connected", botInfo.UserName)
+
+	go func() {
+		for {
+			select {
+			case <-ctx.Done():
+				return
+			case update, ok := <-updates:
+				if !ok {
+					log.Printf("Updates channel closed, reconnecting...")
+					return
+				}
+				if update.Message != nil {
+					c.handleMessage(update)
+				}
+			}
+		}
+	}()
+
+	return nil
+}
+
+func (c *TelegramChannel) Stop(ctx context.Context) error {
+	log.Println("Stopping Telegram bot...")
+	c.setRunning(false)
+
+	if c.updates != nil {
+		c.bot.StopReceivingUpdates()
+		c.updates = nil
+	}
+
+	return nil
+}
+
+func (c *TelegramChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
+	if !c.IsRunning() {
+		return fmt.Errorf("telegram bot not running")
+	}
+
+	chatID, err := parseChatID(msg.ChatID)
+	if err != nil {
+		return fmt.Errorf("invalid chat ID: %w", err)
+	}
+
+	htmlContent := markdownToTelegramHTML(msg.Content)
+
+	tgMsg := tgbotapi.NewMessage(chatID, htmlContent)
+	tgMsg.ParseMode = tgbotapi.ModeHTML
+
+	if _, err := c.bot.Send(tgMsg); err != nil {
+		log.Printf("HTML parse failed, falling back to plain text: %v", err)
+		tgMsg = tgbotapi.NewMessage(chatID, msg.Content)
+		tgMsg.ParseMode = ""
+		_, err = c.bot.Send(tgMsg)
+		return err
+	}
+
+	return nil
+}
+
+func (c *TelegramChannel) handleMessage(update tgbotapi.Update) {
+	message := update.Message
+	if message == nil {
+		return
+	}
+
+	user := message.From
+	if user == nil {
+		return
+	}
+
+	senderID := fmt.Sprintf("%d", user.ID)
+	if user.UserName != "" {
+		senderID = fmt.Sprintf("%d|%s", user.ID, user.UserName)
+	}
+
+	chatID := message.Chat.ID
+	c.chatIDs[senderID] = chatID
+
+	content := ""
+	mediaPaths := []string{}
+
+	if message.Text != "" {
+		content += message.Text
+	}
+
+	if message.Caption != "" {
+		if content != "" {
+			content += "\n"
+		}
+		content += message.Caption
+	}
+
+	if message.Photo != nil && len(message.Photo) > 0 {
+		photo := message.Photo[len(message.Photo)-1]
+		photoPath := c.downloadPhoto(photo.FileID)
+		if photoPath != "" {
+			mediaPaths = append(mediaPaths, photoPath)
+			if content != "" {
+				content += "\n"
+			}
+			content += fmt.Sprintf("[image: %s]", photoPath)
+		}
+	}
+
+	if message.Voice != nil {
+		voicePath := c.downloadFile(message.Voice.FileID, ".ogg")
+		if voicePath != "" {
+			mediaPaths = append(mediaPaths, voicePath)
+
+			transcribedText := ""
+			if c.transcriber != nil && c.transcriber.IsAvailable() {
+				ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+				defer cancel()
+
+				result, err := c.transcriber.Transcribe(ctx, voicePath)
+				if err != nil {
+					log.Printf("Voice transcription failed: %v", err)
+					transcribedText = fmt.Sprintf("[voice: %s (transcription failed)]", voicePath)
+				} else {
+					transcribedText = fmt.Sprintf("[voice transcription: %s]", result.Text)
+					log.Printf("Voice transcribed successfully: %s", result.Text)
+				}
+			} else {
+				transcribedText = fmt.Sprintf("[voice: %s]", voicePath)
+			}
+
+			if content != "" {
+				content += "\n"
+			}
+			content += transcribedText
+		}
+	}
+
+	if message.Audio != nil {
+		audioPath := c.downloadFile(message.Audio.FileID, ".mp3")
+		if audioPath != "" {
+			mediaPaths = append(mediaPaths, audioPath)
+			if content != "" {
+				content += "\n"
+			}
+			content += fmt.Sprintf("[audio: %s]", audioPath)
+		}
+	}
+
+	if message.Document != nil {
+		docPath := c.downloadFile(message.Document.FileID, "")
+		if docPath != "" {
+			mediaPaths = append(mediaPaths, docPath)
+			if content != "" {
+				content += "\n"
+			}
+			content += fmt.Sprintf("[file: %s]", docPath)
+		}
+	}
+
+	if content == "" {
+		content = "[empty message]"
+	}
+
+	log.Printf("Telegram message from %s: %s...", senderID, truncateString(content, 50))
+
+	metadata := map[string]string{
+		"message_id": fmt.Sprintf("%d", message.MessageID),
+		"user_id":    fmt.Sprintf("%d", user.ID),
+		"username":   user.UserName,
+		"first_name": user.FirstName,
+		"is_group":   fmt.Sprintf("%t", message.Chat.Type != "private"),
+	}
+
+	c.HandleMessage(senderID, fmt.Sprintf("%d", chatID), content, mediaPaths, metadata)
+}
+
+func (c *TelegramChannel) downloadPhoto(fileID string) string {
+	file, err := c.bot.GetFile(tgbotapi.FileConfig{FileID: fileID})
+	if err != nil {
+		log.Printf("Failed to get photo file: %v", err)
+		return ""
+	}
+
+	return c.downloadFileWithInfo(&file, ".jpg")
+}
+
+func (c *TelegramChannel) downloadFileWithInfo(file *tgbotapi.File, ext string) string {
+	if file.FilePath == "" {
+		return ""
+	}
+
+	url := file.Link(c.bot.Token)
+	log.Printf("File URL: %s", url)
+
+	mediaDir := "/tmp/picoclaw_media"
+
+	return fmt.Sprintf("%s/%s%s", mediaDir, file.FilePath[:min(16, len(file.FilePath))], ext)
+}
+
+func min(a, b int) int {
+	if a < b {
+		return a
+	}
+	return b
+}
+
+func (c *TelegramChannel) downloadFile(fileID, ext string) string {
+	file, err := c.bot.GetFile(tgbotapi.FileConfig{FileID: fileID})
+	if err != nil {
+		log.Printf("Failed to get file: %v", err)
+		return ""
+	}
+
+	if file.FilePath == "" {
+		return ""
+	}
+
+	url := file.Link(c.bot.Token)
+	log.Printf("File URL: %s", url)
+
+	mediaDir := "/tmp/picoclaw_media"
+
+	return fmt.Sprintf("%s/%s%s", mediaDir, fileID[:16], ext)
+}
+
+func parseChatID(chatIDStr string) (int64, error) {
+	var id int64
+	_, err := fmt.Sscanf(chatIDStr, "%d", &id)
+	return id, err
+}
+
+func truncateString(s string, maxLen int) string {
+	if len(s) <= maxLen {
+		return s
+	}
+	return s[:maxLen]
+}
+
+func markdownToTelegramHTML(text string) string {
+	if text == "" {
+		return ""
+	}
+
+	codeBlocks := extractCodeBlocks(text)
+	text = codeBlocks.text
+
+	inlineCodes := extractInlineCodes(text)
+	text = inlineCodes.text
+
+	text = regexp.MustCompile(`^#{1,6}\s+(.+)$`).ReplaceAllString(text, "$1")
+
+	text = regexp.MustCompile(`^>\s*(.*)$`).ReplaceAllString(text, "$1")
+
+	text = escapeHTML(text)
+
+	text = regexp.MustCompile(`\[([^\]]+)\]\(([^)]+)\)`).ReplaceAllString(text, `<a href="$2">$1</a>`)
+
+	text = regexp.MustCompile(`\*\*(.+?)\*\*`).ReplaceAllString(text, "<b>$1</b>")
+
+	text = regexp.MustCompile(`__(.+?)__`).ReplaceAllString(text, "<b>$1</b>")
+
+	reItalic := regexp.MustCompile(`_([^_]+)_`)
+	text = reItalic.ReplaceAllStringFunc(text, func(s string) string {
+		match := reItalic.FindStringSubmatch(s)
+		if len(match) < 2 {
+			return s
+		}
+		return "<i>" + match[1] + "</i>"
+	})
+
+	text = regexp.MustCompile(`~~(.+?)~~`).ReplaceAllString(text, "<s>$1</s>")
+
+	text = regexp.MustCompile(`^[-*]\s+`).ReplaceAllString(text, "• ")
+
+	for i, code := range inlineCodes.codes {
+		escaped := escapeHTML(code)
+		text = strings.ReplaceAll(text, fmt.Sprintf("\x00IC%d\x00", i), fmt.Sprintf("<code>%s</code>", escaped))
+	}
+
+	for i, code := range codeBlocks.codes {
+		escaped := escapeHTML(code)
+		text = strings.ReplaceAll(text, fmt.Sprintf("\x00CB%d\x00", i), fmt.Sprintf("<pre><code>%s</code></pre>", escaped))
+	}
+
+	return text
+}
+
+type codeBlockMatch struct {
+	text  string
+	codes []string
+}
+
+func extractCodeBlocks(text string) codeBlockMatch {
+	re := regexp.MustCompile("```[\\w]*\\n?([\\s\\S]*?)```")
+	matches := re.FindAllStringSubmatch(text, -1)
+
+	codes := make([]string, 0, len(matches))
+	for _, match := range matches {
+		codes = append(codes, match[1])
+	}
+
+	text = re.ReplaceAllStringFunc(text, func(m string) string {
+		return fmt.Sprintf("\x00CB%d\x00", len(codes)-1)
+	})
+
+	return codeBlockMatch{text: text, codes: codes}
+}
+
+type inlineCodeMatch struct {
+	text  string
+	codes []string
+}
+
+func extractInlineCodes(text string) inlineCodeMatch {
+	re := regexp.MustCompile("`([^`]+)`")
+	matches := re.FindAllStringSubmatch(text, -1)
+
+	codes := make([]string, 0, len(matches))
+	for _, match := range matches {
+		codes = append(codes, match[1])
+	}
+
+	text = re.ReplaceAllStringFunc(text, func(m string) string {
+		return fmt.Sprintf("\x00IC%d\x00", len(codes)-1)
+	})
+
+	return inlineCodeMatch{text: text, codes: codes}
+}
+
+func escapeHTML(text string) string {
+	text = strings.ReplaceAll(text, "&", "&amp;")
+	text = strings.ReplaceAll(text, "<", "&lt;")
+	text = strings.ReplaceAll(text, ">", "&gt;")
+	return text
+}

pkg/channels/whatsapp.go

@@ -0,0 +1,183 @@
+package channels
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"log"
+	"sync"
+	"time"
+
+	"github.com/gorilla/websocket"
+
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+type WhatsAppChannel struct {
+	*BaseChannel
+	conn      *websocket.Conn
+	config    config.WhatsAppConfig
+	url       string
+	mu        sync.Mutex
+	connected bool
+}
+
+func NewWhatsAppChannel(cfg config.WhatsAppConfig, bus *bus.MessageBus) (*WhatsAppChannel, error) {
+	base := NewBaseChannel("whatsapp", cfg, bus, cfg.AllowFrom)
+
+	return &WhatsAppChannel{
+		BaseChannel: base,
+		config:      cfg,
+		url:         cfg.BridgeURL,
+		connected:   false,
+	}, nil
+}
+
+func (c *WhatsAppChannel) Start(ctx context.Context) error {
+	log.Printf("Starting WhatsApp channel connecting to %s...", c.url)
+
+	dialer := websocket.DefaultDialer
+	dialer.HandshakeTimeout = 10 * time.Second
+
+	conn, _, err := dialer.Dial(c.url, nil)
+	if err != nil {
+		return fmt.Errorf("failed to connect to WhatsApp bridge: %w", err)
+	}
+
+	c.mu.Lock()
+	c.conn = conn
+	c.connected = true
+	c.mu.Unlock()
+
+	c.setRunning(true)
+	log.Println("WhatsApp channel connected")
+
+	go c.listen(ctx)
+
+	return nil
+}
+
+func (c *WhatsAppChannel) Stop(ctx context.Context) error {
+	log.Println("Stopping WhatsApp channel...")
+
+	c.mu.Lock()
+	defer c.mu.Unlock()
+
+	if c.conn != nil {
+		if err := c.conn.Close(); err != nil {
+			log.Printf("Error closing WhatsApp connection: %v", err)
+		}
+		c.conn = nil
+	}
+
+	c.connected = false
+	c.setRunning(false)
+
+	return nil
+}
+
+func (c *WhatsAppChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+
+	if c.conn == nil {
+		return fmt.Errorf("whatsapp connection not established")
+	}
+
+	payload := map[string]interface{}{
+		"type":    "message",
+		"to":      msg.ChatID,
+		"content": msg.Content,
+	}
+
+	data, err := json.Marshal(payload)
+	if err != nil {
+		return fmt.Errorf("failed to marshal message: %w", err)
+	}
+
+	if err := c.conn.WriteMessage(websocket.TextMessage, data); err != nil {
+		return fmt.Errorf("failed to send message: %w", err)
+	}
+
+	return nil
+}
+
+func (c *WhatsAppChannel) listen(ctx context.Context) {
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		default:
+			c.mu.Lock()
+			conn := c.conn
+			c.mu.Unlock()
+
+			if conn == nil {
+				time.Sleep(1 * time.Second)
+				continue
+			}
+
+			_, message, err := conn.ReadMessage()
+			if err != nil {
+				log.Printf("WhatsApp read error: %v", err)
+				time.Sleep(2 * time.Second)
+				continue
+			}
+
+			var msg map[string]interface{}
+			if err := json.Unmarshal(message, &msg); err != nil {
+				log.Printf("Failed to unmarshal WhatsApp message: %v", err)
+				continue
+			}
+
+			msgType, ok := msg["type"].(string)
+			if !ok {
+				continue
+			}
+
+			if msgType == "message" {
+				c.handleIncomingMessage(msg)
+			}
+		}
+	}
+}
+
+func (c *WhatsAppChannel) handleIncomingMessage(msg map[string]interface{}) {
+	senderID, ok := msg["from"].(string)
+	if !ok {
+		return
+	}
+
+	chatID, ok := msg["chat"].(string)
+	if !ok {
+		chatID = senderID
+	}
+
+	content, ok := msg["content"].(string)
+	if !ok {
+		content = ""
+	}
+
+	var mediaPaths []string
+	if mediaData, ok := msg["media"].([]interface{}); ok {
+		mediaPaths = make([]string, 0, len(mediaData))
+		for _, m := range mediaData {
+			if path, ok := m.(string); ok {
+				mediaPaths = append(mediaPaths, path)
+			}
+		}
+	}
+
+	metadata := make(map[string]string)
+	if messageID, ok := msg["id"].(string); ok {
+		metadata["message_id"] = messageID
+	}
+	if userName, ok := msg["from_name"].(string); ok {
+		metadata["user_name"] = userName
+	}
+
+	log.Printf("WhatsApp message from %s: %s...", senderID, truncateString(content, 50))
+
+	c.HandleMessage(senderID, chatID, content, mediaPaths, metadata)
+}

pkg/config/config.go

@@ -0,0 +1,276 @@
+package config
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"sync"
+
+	"github.com/caarlos0/env/v11"
+)
+
+type Config struct {
+	Agents    AgentsConfig    `json:"agents"`
+	Channels  ChannelsConfig  `json:"channels"`
+	Providers ProvidersConfig `json:"providers"`
+	Gateway   GatewayConfig   `json:"gateway"`
+	Tools     ToolsConfig     `json:"tools"`
+	mu        sync.RWMutex
+}
+
+type AgentsConfig struct {
+	Defaults AgentDefaults `json:"defaults"`
+}
+
+type AgentDefaults struct {
+	Workspace         string  `json:"workspace" env:"PICOCLAW_AGENTS_DEFAULTS_WORKSPACE"`
+	Model             string  `json:"model" env:"PICOCLAW_AGENTS_DEFAULTS_MODEL"`
+	MaxTokens         int     `json:"max_tokens" env:"PICOCLAW_AGENTS_DEFAULTS_MAX_TOKENS"`
+	Temperature       float64 `json:"temperature" env:"PICOCLAW_AGENTS_DEFAULTS_TEMPERATURE"`
+	MaxToolIterations int     `json:"max_tool_iterations" env:"PICOCLAW_AGENTS_DEFAULTS_MAX_TOOL_ITERATIONS"`
+}
+
+type ChannelsConfig struct {
+	WhatsApp WhatsAppConfig `json:"whatsapp"`
+	Telegram TelegramConfig `json:"telegram"`
+	Feishu   FeishuConfig   `json:"feishu"`
+	Discord  DiscordConfig  `json:"discord"`
+	MaixCam  MaixCamConfig  `json:"maixcam"`
+}
+
+type WhatsAppConfig struct {
+	Enabled   bool     `json:"enabled" env:"PICOCLAW_CHANNELS_WHATSAPP_ENABLED"`
+	BridgeURL string   `json:"bridge_url" env:"PICOCLAW_CHANNELS_WHATSAPP_BRIDGE_URL"`
+	AllowFrom []string `json:"allow_from" env:"PICOCLAW_CHANNELS_WHATSAPP_ALLOW_FROM"`
+}
+
+type TelegramConfig struct {
+	Enabled   bool     `json:"enabled" env:"PICOCLAW_CHANNELS_TELEGRAM_ENABLED"`
+	Token     string   `json:"token" env:"PICOCLAW_CHANNELS_TELEGRAM_TOKEN"`
+	AllowFrom []string `json:"allow_from" env:"PICOCLAW_CHANNELS_TELEGRAM_ALLOW_FROM"`
+}
+
+type FeishuConfig struct {
+	Enabled           bool     `json:"enabled" env:"PICOCLAW_CHANNELS_FEISHU_ENABLED"`
+	AppID             string   `json:"app_id" env:"PICOCLAW_CHANNELS_FEISHU_APP_ID"`
+	AppSecret         string   `json:"app_secret" env:"PICOCLAW_CHANNELS_FEISHU_APP_SECRET"`
+	EncryptKey        string   `json:"encrypt_key" env:"PICOCLAW_CHANNELS_FEISHU_ENCRYPT_KEY"`
+	VerificationToken string   `json:"verification_token" env:"PICOCLAW_CHANNELS_FEISHU_VERIFICATION_TOKEN"`
+	AllowFrom         []string `json:"allow_from" env:"PICOCLAW_CHANNELS_FEISHU_ALLOW_FROM"`
+}
+
+type DiscordConfig struct {
+	Enabled   bool     `json:"enabled" env:"PICOCLAW_CHANNELS_DISCORD_ENABLED"`
+	Token     string   `json:"token" env:"PICOCLAW_CHANNELS_DISCORD_TOKEN"`
+	AllowFrom []string `json:"allow_from" env:"PICOCLAW_CHANNELS_DISCORD_ALLOW_FROM"`
+}
+
+type MaixCamConfig struct {
+	Enabled   bool     `json:"enabled" env:"PICOCLAW_CHANNELS_MAIXCAM_ENABLED"`
+	Host      string   `json:"host" env:"PICOCLAW_CHANNELS_MAIXCAM_HOST"`
+	Port      int      `json:"port" env:"PICOCLAW_CHANNELS_MAIXCAM_PORT"`
+	AllowFrom []string `json:"allow_from" env:"PICOCLAW_CHANNELS_MAIXCAM_ALLOW_FROM"`
+}
+
+type ProvidersConfig struct {
+	Anthropic  ProviderConfig `json:"anthropic"`
+	OpenAI     ProviderConfig `json:"openai"`
+	OpenRouter ProviderConfig `json:"openrouter"`
+	Groq       ProviderConfig `json:"groq"`
+	Zhipu      ProviderConfig `json:"zhipu"`
+	VLLM       ProviderConfig `json:"vllm"`
+	Gemini     ProviderConfig `json:"gemini"`
+}
+
+type ProviderConfig struct {
+	APIKey  string `json:"api_key" env:"PICOCLAW_PROVIDERS_{{.Name}}_API_KEY"`
+	APIBase string `json:"api_base" env:"PICOCLAW_PROVIDERS_{{.Name}}_API_BASE"`
+}
+
+type GatewayConfig struct {
+	Host string `json:"host" env:"PICOCLAW_GATEWAY_HOST"`
+	Port int    `json:"port" env:"PICOCLAW_GATEWAY_PORT"`
+}
+
+type WebSearchConfig struct {
+	APIKey     string `json:"api_key" env:"PICOCLAW_TOOLS_WEB_SEARCH_API_KEY"`
+	MaxResults int    `json:"max_results" env:"PICOCLAW_TOOLS_WEB_SEARCH_MAX_RESULTS"`
+}
+
+type WebToolsConfig struct {
+	Search WebSearchConfig `json:"search"`
+}
+
+type ToolsConfig struct {
+	Web WebToolsConfig `json:"web"`
+}
+
+func DefaultConfig() *Config {
+	return &Config{
+		Agents: AgentsConfig{
+			Defaults: AgentDefaults{
+				Workspace:         "~/.picoclaw/workspace",
+				Model:             "glm-4.7",
+				MaxTokens:         8192,
+				Temperature:       0.7,
+				MaxToolIterations: 20,
+			},
+		},
+		Channels: ChannelsConfig{
+			WhatsApp: WhatsAppConfig{
+				Enabled:   false,
+				BridgeURL: "ws://localhost:3001",
+				AllowFrom: []string{},
+			},
+			Telegram: TelegramConfig{
+				Enabled:   false,
+				Token:     "",
+				AllowFrom: []string{},
+			},
+			Feishu: FeishuConfig{
+				Enabled:           false,
+				AppID:             "",
+				AppSecret:         "",
+				EncryptKey:        "",
+				VerificationToken: "",
+				AllowFrom:         []string{},
+			},
+			Discord: DiscordConfig{
+				Enabled:   false,
+				Token:     "",
+				AllowFrom: []string{},
+			},
+			MaixCam: MaixCamConfig{
+				Enabled:   false,
+				Host:      "0.0.0.0",
+				Port:      18790,
+				AllowFrom: []string{},
+			},
+		},
+		Providers: ProvidersConfig{
+			Anthropic:  ProviderConfig{},
+			OpenAI:     ProviderConfig{},
+			OpenRouter: ProviderConfig{},
+			Groq:       ProviderConfig{},
+			Zhipu:      ProviderConfig{},
+			VLLM:       ProviderConfig{},
+			Gemini:     ProviderConfig{},
+		},
+		Gateway: GatewayConfig{
+			Host: "0.0.0.0",
+			Port: 18790,
+		},
+		Tools: ToolsConfig{
+			Web: WebToolsConfig{
+				Search: WebSearchConfig{
+					APIKey:     "",
+					MaxResults: 5,
+				},
+			},
+		},
+	}
+}
+
+func LoadConfig(path string) (*Config, error) {
+	cfg := DefaultConfig()
+
+	data, err := os.ReadFile(path)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return cfg, nil
+		}
+		return nil, err
+	}
+
+	if err := json.Unmarshal(data, cfg); err != nil {
+		return nil, err
+	}
+
+	if err := env.Parse(cfg); err != nil {
+		return nil, err
+	}
+
+	return cfg, nil
+}
+
+func SaveConfig(path string, cfg *Config) error {
+	cfg.mu.RLock()
+	defer cfg.mu.RUnlock()
+
+	data, err := json.MarshalIndent(cfg, "", "  ")
+	if err != nil {
+		return err
+	}
+
+	dir := filepath.Dir(path)
+	if err := os.MkdirAll(dir, 0755); err != nil {
+		return err
+	}
+
+	return os.WriteFile(path, data, 0644)
+}
+
+func (c *Config) WorkspacePath() string {
+	c.mu.RLock()
+	defer c.mu.RUnlock()
+	return expandHome(c.Agents.Defaults.Workspace)
+}
+
+func (c *Config) GetAPIKey() string {
+	c.mu.RLock()
+	defer c.mu.RUnlock()
+	if c.Providers.OpenRouter.APIKey != "" {
+		return c.Providers.OpenRouter.APIKey
+	}
+	if c.Providers.Anthropic.APIKey != "" {
+		return c.Providers.Anthropic.APIKey
+	}
+	if c.Providers.OpenAI.APIKey != "" {
+		return c.Providers.OpenAI.APIKey
+	}
+	if c.Providers.Gemini.APIKey != "" {
+		return c.Providers.Gemini.APIKey
+	}
+	if c.Providers.Zhipu.APIKey != "" {
+		return c.Providers.Zhipu.APIKey
+	}
+	if c.Providers.Groq.APIKey != "" {
+		return c.Providers.Groq.APIKey
+	}
+	if c.Providers.VLLM.APIKey != "" {
+		return c.Providers.VLLM.APIKey
+	}
+	return ""
+}
+
+func (c *Config) GetAPIBase() string {
+	c.mu.RLock()
+	defer c.mu.RUnlock()
+	if c.Providers.OpenRouter.APIKey != "" {
+		if c.Providers.OpenRouter.APIBase != "" {
+			return c.Providers.OpenRouter.APIBase
+		}
+		return "https://openrouter.ai/api/v1"
+	}
+	if c.Providers.Zhipu.APIKey != "" {
+		return c.Providers.Zhipu.APIBase
+	}
+	if c.Providers.VLLM.APIKey != "" && c.Providers.VLLM.APIBase != "" {
+		return c.Providers.VLLM.APIBase
+	}
+	return ""
+}
+
+func expandHome(path string) string {
+	if path == "" {
+		return path
+	}
+	if path[0] == '~' {
+		home, _ := os.UserHomeDir()
+		if len(path) > 1 && path[1] == '/' {
+			return home + path[1:]
+		}
+		return home
+	}
+	return path
+}

pkg/cron/service.go

@@ -0,0 +1,381 @@
+package cron
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"sync"
+	"time"
+)
+
+type CronSchedule struct {
+	Kind    string `json:"kind"`
+	AtMS    *int64 `json:"atMs,omitempty"`
+	EveryMS *int64 `json:"everyMs,omitempty"`
+	Expr    string `json:"expr,omitempty"`
+	TZ      string `json:"tz,omitempty"`
+}
+
+type CronPayload struct {
+	Kind    string `json:"kind"`
+	Message string `json:"message"`
+	Deliver bool   `json:"deliver"`
+	Channel string `json:"channel,omitempty"`
+	To      string `json:"to,omitempty"`
+}
+
+type CronJobState struct {
+	NextRunAtMS *int64 `json:"nextRunAtMs,omitempty"`
+	LastRunAtMS *int64 `json:"lastRunAtMs,omitempty"`
+	LastStatus  string `json:"lastStatus,omitempty"`
+	LastError   string `json:"lastError,omitempty"`
+}
+
+type CronJob struct {
+	ID             string       `json:"id"`
+	Name           string       `json:"name"`
+	Enabled        bool         `json:"enabled"`
+	Schedule       CronSchedule `json:"schedule"`
+	Payload        CronPayload  `json:"payload"`
+	State          CronJobState `json:"state"`
+	CreatedAtMS    int64        `json:"createdAtMs"`
+	UpdatedAtMS    int64        `json:"updatedAtMs"`
+	DeleteAfterRun bool         `json:"deleteAfterRun"`
+}
+
+type CronStore struct {
+	Version int       `json:"version"`
+	Jobs    []CronJob `json:"jobs"`
+}
+
+type JobHandler func(job *CronJob) (string, error)
+
+type CronService struct {
+	storePath string
+	store     *CronStore
+	onJob     JobHandler
+	mu        sync.RWMutex
+	running   bool
+	stopChan  chan struct{}
+}
+
+func NewCronService(storePath string, onJob JobHandler) *CronService {
+	cs := &CronService{
+		storePath: storePath,
+		onJob:     onJob,
+		stopChan:  make(chan struct{}),
+	}
+	cs.loadStore()
+	return cs
+}
+
+func (cs *CronService) Start() error {
+	cs.mu.Lock()
+	defer cs.mu.Unlock()
+
+	if cs.running {
+		return nil
+	}
+
+	if err := cs.loadStore(); err != nil {
+		return fmt.Errorf("failed to load store: %w", err)
+	}
+
+	cs.recomputeNextRuns()
+	if err := cs.saveStore(); err != nil {
+		return fmt.Errorf("failed to save store: %w", err)
+	}
+
+	cs.running = true
+	go cs.runLoop()
+
+	return nil
+}
+
+func (cs *CronService) Stop() {
+	cs.mu.Lock()
+	defer cs.mu.Unlock()
+
+	if !cs.running {
+		return
+	}
+
+	cs.running = false
+	close(cs.stopChan)
+}
+
+func (cs *CronService) runLoop() {
+	ticker := time.NewTicker(1 * time.Second)
+	defer ticker.Stop()
+
+	for {
+		select {
+		case <-cs.stopChan:
+			return
+		case <-ticker.C:
+			cs.checkJobs()
+		}
+	}
+}
+
+func (cs *CronService) checkJobs() {
+	cs.mu.RLock()
+	if !cs.running {
+		cs.mu.RUnlock()
+		return
+	}
+
+	now := time.Now().UnixMilli()
+	var dueJobs []*CronJob
+
+	for i := range cs.store.Jobs {
+		job := &cs.store.Jobs[i]
+		if job.Enabled && job.State.NextRunAtMS != nil && *job.State.NextRunAtMS <= now {
+			dueJobs = append(dueJobs, job)
+		}
+	}
+	cs.mu.RUnlock()
+
+	for _, job := range dueJobs {
+		cs.executeJob(job)
+	}
+
+	cs.mu.Lock()
+	defer cs.mu.Unlock()
+	cs.saveStore()
+}
+
+func (cs *CronService) executeJob(job *CronJob) {
+	startTime := time.Now().UnixMilli()
+
+	var err error
+	if cs.onJob != nil {
+		_, err = cs.onJob(job)
+	}
+
+	cs.mu.Lock()
+	defer cs.mu.Unlock()
+
+	job.State.LastRunAtMS = &startTime
+	job.UpdatedAtMS = time.Now().UnixMilli()
+
+	if err != nil {
+		job.State.LastStatus = "error"
+		job.State.LastError = err.Error()
+	} else {
+		job.State.LastStatus = "ok"
+		job.State.LastError = ""
+	}
+
+	if job.Schedule.Kind == "at" {
+		if job.DeleteAfterRun {
+			cs.removeJobUnsafe(job.ID)
+		} else {
+			job.Enabled = false
+			job.State.NextRunAtMS = nil
+		}
+	} else {
+		nextRun := cs.computeNextRun(&job.Schedule, time.Now().UnixMilli())
+		job.State.NextRunAtMS = nextRun
+	}
+}
+
+func (cs *CronService) computeNextRun(schedule *CronSchedule, nowMS int64) *int64 {
+	if schedule.Kind == "at" {
+		if schedule.AtMS != nil && *schedule.AtMS > nowMS {
+			return schedule.AtMS
+		}
+		return nil
+	}
+
+	if schedule.Kind == "every" {
+		if schedule.EveryMS == nil || *schedule.EveryMS <= 0 {
+			return nil
+		}
+		next := nowMS + *schedule.EveryMS
+		return &next
+	}
+
+	return nil
+}
+
+func (cs *CronService) recomputeNextRuns() {
+	now := time.Now().UnixMilli()
+	for i := range cs.store.Jobs {
+		job := &cs.store.Jobs[i]
+		if job.Enabled {
+			job.State.NextRunAtMS = cs.computeNextRun(&job.Schedule, now)
+		}
+	}
+}
+
+func (cs *CronService) getNextWakeMS() *int64 {
+	var nextWake *int64
+	for _, job := range cs.store.Jobs {
+		if job.Enabled && job.State.NextRunAtMS != nil {
+			if nextWake == nil || *job.State.NextRunAtMS < *nextWake {
+				nextWake = job.State.NextRunAtMS
+			}
+		}
+	}
+	return nextWake
+}
+
+func (cs *CronService) Load() error {
+	return cs.loadStore()
+}
+
+func (cs *CronService) loadStore() error {
+	cs.store = &CronStore{
+		Version: 1,
+		Jobs:    []CronJob{},
+	}
+
+	data, err := os.ReadFile(cs.storePath)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return nil
+		}
+		return err
+	}
+
+	return json.Unmarshal(data, cs.store)
+}
+
+func (cs *CronService) saveStore() error {
+	dir := filepath.Dir(cs.storePath)
+	if err := os.MkdirAll(dir, 0755); err != nil {
+		return err
+	}
+
+	data, err := json.MarshalIndent(cs.store, "", "  ")
+	if err != nil {
+		return err
+	}
+
+	return os.WriteFile(cs.storePath, data, 0644)
+}
+
+func (cs *CronService) AddJob(name string, schedule CronSchedule, message string, deliver bool, channel, to string) (*CronJob, error) {
+	cs.mu.Lock()
+	defer cs.mu.Unlock()
+
+	now := time.Now().UnixMilli()
+
+	job := CronJob{
+		ID:       generateID(),
+		Name:     name,
+		Enabled:  true,
+		Schedule: schedule,
+		Payload: CronPayload{
+			Kind:    "agent_turn",
+			Message: message,
+			Deliver: deliver,
+			Channel: channel,
+			To:      to,
+		},
+		State: CronJobState{
+			NextRunAtMS: cs.computeNextRun(&schedule, now),
+		},
+		CreatedAtMS:    now,
+		UpdatedAtMS:    now,
+		DeleteAfterRun: false,
+	}
+
+	cs.store.Jobs = append(cs.store.Jobs, job)
+	if err := cs.saveStore(); err != nil {
+		return nil, err
+	}
+
+	return &job, nil
+}
+
+func (cs *CronService) RemoveJob(jobID string) bool {
+	cs.mu.Lock()
+	defer cs.mu.Unlock()
+
+	return cs.removeJobUnsafe(jobID)
+}
+
+func (cs *CronService) removeJobUnsafe(jobID string) bool {
+	before := len(cs.store.Jobs)
+	var jobs []CronJob
+	for _, job := range cs.store.Jobs {
+		if job.ID != jobID {
+			jobs = append(jobs, job)
+		}
+	}
+	cs.store.Jobs = jobs
+	removed := len(cs.store.Jobs) < before
+
+	if removed {
+		cs.saveStore()
+	}
+
+	return removed
+}
+
+func (cs *CronService) EnableJob(jobID string, enabled bool) *CronJob {
+	cs.mu.Lock()
+	defer cs.mu.Unlock()
+
+	for i := range cs.store.Jobs {
+		job := &cs.store.Jobs[i]
+		if job.ID == jobID {
+			job.Enabled = enabled
+			job.UpdatedAtMS = time.Now().UnixMilli()
+
+			if enabled {
+				job.State.NextRunAtMS = cs.computeNextRun(&job.Schedule, time.Now().UnixMilli())
+			} else {
+				job.State.NextRunAtMS = nil
+			}
+
+			cs.saveStore()
+			return job
+		}
+	}
+
+	return nil
+}
+
+func (cs *CronService) ListJobs(includeDisabled bool) []CronJob {
+	cs.mu.RLock()
+	defer cs.mu.RUnlock()
+
+	if includeDisabled {
+		return cs.store.Jobs
+	}
+
+	var enabled []CronJob
+	for _, job := range cs.store.Jobs {
+		if job.Enabled {
+			enabled = append(enabled, job)
+		}
+	}
+
+	return enabled
+}
+
+func (cs *CronService) Status() map[string]interface{} {
+	cs.mu.RLock()
+	defer cs.mu.RUnlock()
+
+	var enabledCount int
+	for _, job := range cs.store.Jobs {
+		if job.Enabled {
+			enabledCount++
+		}
+	}
+
+	return map[string]interface{}{
+		"enabled":      cs.running,
+		"jobs":         len(cs.store.Jobs),
+		"nextWakeAtMS": cs.getNextWakeMS(),
+	}
+}
+
+func generateID() string {
+	return fmt.Sprintf("%d", time.Now().UnixNano())
+}

pkg/heartbeat/service.go

@@ -0,0 +1,134 @@
+package heartbeat
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"sync"
+	"time"
+)
+
+type HeartbeatService struct {
+	workspace   string
+	onHeartbeat func(string) (string, error)
+	interval    time.Duration
+	enabled     bool
+	mu          sync.RWMutex
+	stopChan    chan struct{}
+}
+
+func NewHeartbeatService(workspace string, onHeartbeat func(string) (string, error), intervalS int, enabled bool) *HeartbeatService {
+	return &HeartbeatService{
+		workspace:   workspace,
+		onHeartbeat: onHeartbeat,
+		interval:    time.Duration(intervalS) * time.Second,
+		enabled:     enabled,
+		stopChan:    make(chan struct{}),
+	}
+}
+
+func (hs *HeartbeatService) Start() error {
+	hs.mu.Lock()
+	defer hs.mu.Unlock()
+
+	if hs.running() {
+		return nil
+	}
+
+	if !hs.enabled {
+		return fmt.Errorf("heartbeat service is disabled")
+	}
+
+	go hs.runLoop()
+
+	return nil
+}
+
+func (hs *HeartbeatService) Stop() {
+	hs.mu.Lock()
+	defer hs.mu.Unlock()
+
+	if !hs.running() {
+		return
+	}
+
+	close(hs.stopChan)
+}
+
+func (hs *HeartbeatService) running() bool {
+	select {
+	case <-hs.stopChan:
+		return false
+	default:
+		return true
+	}
+}
+
+func (hs *HeartbeatService) runLoop() {
+	ticker := time.NewTicker(hs.interval)
+	defer ticker.Stop()
+
+	for {
+		select {
+		case <-hs.stopChan:
+			return
+		case <-ticker.C:
+			hs.checkHeartbeat()
+		}
+	}
+}
+
+func (hs *HeartbeatService) checkHeartbeat() {
+	hs.mu.RLock()
+	if !hs.enabled || !hs.running() {
+		hs.mu.RUnlock()
+		return
+	}
+	hs.mu.RUnlock()
+
+	prompt := hs.buildPrompt()
+
+	if hs.onHeartbeat != nil {
+		_, err := hs.onHeartbeat(prompt)
+		if err != nil {
+			hs.log(fmt.Sprintf("Heartbeat error: %v", err))
+		}
+	}
+}
+
+func (hs *HeartbeatService) buildPrompt() string {
+	notesDir := filepath.Join(hs.workspace, "memory")
+	notesFile := filepath.Join(notesDir, "HEARTBEAT.md")
+
+	var notes string
+	if data, err := os.ReadFile(notesFile); err == nil {
+		notes = string(data)
+	}
+
+	now := time.Now().Format("2006-01-02 15:04")
+
+	prompt := fmt.Sprintf(`# Heartbeat Check
+
+Current time: %s
+
+Check if there are any tasks I should be aware of or actions I should take.
+Review the memory file for any important updates or changes.
+Be proactive in identifying potential issues or improvements.
+
+%s
+`, now, notes)
+
+	return prompt
+}
+
+func (hs *HeartbeatService) log(message string) {
+	logFile := filepath.Join(hs.workspace, "memory", "heartbeat.log")
+	f, err := os.OpenFile(logFile, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0644)
+	if err != nil {
+		return
+	}
+	defer f.Close()
+
+	timestamp := time.Now().Format("2006-01-02 15:04:05")
+	f.WriteString(fmt.Sprintf("[%s] %s\n", timestamp, message))
+}

pkg/logger/logger.go

@@ -0,0 +1,239 @@
+package logger
+
+import (
+	"encoding/json"
+	"fmt"
+	"log"
+	"os"
+	"runtime"
+	"strings"
+	"sync"
+	"time"
+)
+
+type LogLevel int
+
+const (
+	DEBUG LogLevel = iota
+	INFO
+	WARN
+	ERROR
+	FATAL
+)
+
+var (
+	logLevelNames = map[LogLevel]string{
+		DEBUG: "DEBUG",
+		INFO:  "INFO",
+		WARN:  "WARN",
+		ERROR: "ERROR",
+		FATAL: "FATAL",
+	}
+
+	currentLevel = INFO
+	logger       *Logger
+	once         sync.Once
+	mu           sync.RWMutex
+)
+
+type Logger struct {
+	file *os.File
+}
+
+type LogEntry struct {
+	Level     string                 `json:"level"`
+	Timestamp string                 `json:"timestamp"`
+	Component string                 `json:"component,omitempty"`
+	Message   string                 `json:"message"`
+	Fields    map[string]interface{} `json:"fields,omitempty"`
+	Caller    string                 `json:"caller,omitempty"`
+}
+
+func init() {
+	once.Do(func() {
+		logger = &Logger{}
+	})
+}
+
+func SetLevel(level LogLevel) {
+	mu.Lock()
+	defer mu.Unlock()
+	currentLevel = level
+}
+
+func GetLevel() LogLevel {
+	mu.RLock()
+	defer mu.RUnlock()
+	return currentLevel
+}
+
+func EnableFileLogging(filePath string) error {
+	mu.Lock()
+	defer mu.Unlock()
+
+	file, err := os.OpenFile(filePath, os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0644)
+	if err != nil {
+		return fmt.Errorf("failed to open log file: %w", err)
+	}
+
+	if logger.file != nil {
+		logger.file.Close()
+	}
+
+	logger.file = file
+	log.Println("File logging enabled:", filePath)
+	return nil
+}
+
+func DisableFileLogging() {
+	mu.Lock()
+	defer mu.Unlock()
+
+	if logger.file != nil {
+		logger.file.Close()
+		logger.file = nil
+		log.Println("File logging disabled")
+	}
+}
+
+func logMessage(level LogLevel, component string, message string, fields map[string]interface{}) {
+	if level < currentLevel {
+		return
+	}
+
+	entry := LogEntry{
+		Level:     logLevelNames[level],
+		Timestamp: time.Now().UTC().Format(time.RFC3339),
+		Component: component,
+		Message:   message,
+		Fields:    fields,
+	}
+
+	if pc, file, line, ok := runtime.Caller(2); ok {
+		fn := runtime.FuncForPC(pc)
+		if fn != nil {
+			entry.Caller = fmt.Sprintf("%s:%d (%s)", file, line, fn.Name())
+		}
+	}
+
+	if logger.file != nil {
+		jsonData, err := json.Marshal(entry)
+		if err == nil {
+			logger.file.WriteString(string(jsonData) + "\n")
+		}
+	}
+
+	var fieldStr string
+	if len(fields) > 0 {
+		fieldStr = " " + formatFields(fields)
+	}
+
+	logLine := fmt.Sprintf("[%s] [%s]%s %s%s",
+		entry.Timestamp,
+		logLevelNames[level],
+		formatComponent(component),
+		message,
+		fieldStr,
+	)
+
+	log.Println(logLine)
+
+	if level == FATAL {
+		os.Exit(1)
+	}
+}
+
+func formatComponent(component string) string {
+	if component == "" {
+		return ""
+	}
+	return fmt.Sprintf(" %s:", component)
+}
+
+func formatFields(fields map[string]interface{}) string {
+	var parts []string
+	for k, v := range fields {
+		parts = append(parts, fmt.Sprintf("%s=%v", k, v))
+	}
+	return fmt.Sprintf("{%s}", strings.Join(parts, ", "))
+}
+
+func Debug(message string) {
+	logMessage(DEBUG, "", message, nil)
+}
+
+func DebugC(component string, message string) {
+	logMessage(DEBUG, component, message, nil)
+}
+
+func DebugF(message string, fields map[string]interface{}) {
+	logMessage(DEBUG, "", message, fields)
+}
+
+func DebugCF(component string, message string, fields map[string]interface{}) {
+	logMessage(DEBUG, component, message, fields)
+}
+
+func Info(message string) {
+	logMessage(INFO, "", message, nil)
+}
+
+func InfoC(component string, message string) {
+	logMessage(INFO, component, message, nil)
+}
+
+func InfoF(message string, fields map[string]interface{}) {
+	logMessage(INFO, "", message, fields)
+}
+
+func InfoCF(component string, message string, fields map[string]interface{}) {
+	logMessage(INFO, component, message, fields)
+}
+
+func Warn(message string) {
+	logMessage(WARN, "", message, nil)
+}
+
+func WarnC(component string, message string) {
+	logMessage(WARN, component, message, nil)
+}
+
+func WarnF(message string, fields map[string]interface{}) {
+	logMessage(WARN, "", message, fields)
+}
+
+func WarnCF(component string, message string, fields map[string]interface{}) {
+	logMessage(WARN, component, message, fields)
+}
+
+func Error(message string) {
+	logMessage(ERROR, "", message, nil)
+}
+
+func ErrorC(component string, message string) {
+	logMessage(ERROR, component, message, nil)
+}
+
+func ErrorF(message string, fields map[string]interface{}) {
+	logMessage(ERROR, "", message, fields)
+}
+
+func ErrorCF(component string, message string, fields map[string]interface{}) {
+	logMessage(ERROR, component, message, fields)
+}
+
+func Fatal(message string) {
+	logMessage(FATAL, "", message, nil)
+}
+
+func FatalC(component string, message string) {
+	logMessage(FATAL, component, message, nil)
+}
+
+func FatalF(message string, fields map[string]interface{}) {
+	logMessage(FATAL, "", message, fields)
+}
+
+func FatalCF(component string, message string, fields map[string]interface{}) {
+	logMessage(FATAL, component, message, fields)
+}

pkg/logger/logger_test.go

@@ -0,0 +1,139 @@
+package logger
+
+import (
+	"testing"
+)
+
+func TestLogLevelFiltering(t *testing.T) {
+	initialLevel := GetLevel()
+	defer SetLevel(initialLevel)
+
+	SetLevel(WARN)
+
+	tests := []struct {
+		name      string
+		level     LogLevel
+		shouldLog bool
+	}{
+		{"DEBUG message", DEBUG, false},
+		{"INFO message", INFO, false},
+		{"WARN message", WARN, true},
+		{"ERROR message", ERROR, true},
+		{"FATAL message", FATAL, true},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			switch tt.level {
+			case DEBUG:
+				Debug(tt.name)
+			case INFO:
+				Info(tt.name)
+			case WARN:
+				Warn(tt.name)
+			case ERROR:
+				Error(tt.name)
+			case FATAL:
+				if tt.shouldLog {
+					t.Logf("FATAL test skipped to prevent program exit")
+				}
+			}
+		})
+	}
+
+	SetLevel(INFO)
+}
+
+func TestLoggerWithComponent(t *testing.T) {
+	initialLevel := GetLevel()
+	defer SetLevel(initialLevel)
+
+	SetLevel(DEBUG)
+
+	tests := []struct {
+		name      string
+		component string
+		message   string
+		fields    map[string]interface{}
+	}{
+		{"Simple message", "test", "Hello, world!", nil},
+		{"Message with component", "discord", "Discord message", nil},
+		{"Message with fields", "telegram", "Telegram message", map[string]interface{}{
+			"user_id": "12345",
+			"count":   42,
+		}},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			switch {
+			case tt.fields == nil && tt.component != "":
+				InfoC(tt.component, tt.message)
+			case tt.fields != nil:
+				InfoF(tt.message, tt.fields)
+			default:
+				Info(tt.message)
+			}
+		})
+	}
+
+	SetLevel(INFO)
+}
+
+func TestLogLevels(t *testing.T) {
+	tests := []struct {
+		name  string
+		level LogLevel
+		want  string
+	}{
+		{"DEBUG level", DEBUG, "DEBUG"},
+		{"INFO level", INFO, "INFO"},
+		{"WARN level", WARN, "WARN"},
+		{"ERROR level", ERROR, "ERROR"},
+		{"FATAL level", FATAL, "FATAL"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if logLevelNames[tt.level] != tt.want {
+				t.Errorf("logLevelNames[%d] = %s, want %s", tt.level, logLevelNames[tt.level], tt.want)
+			}
+		})
+	}
+}
+
+func TestSetGetLevel(t *testing.T) {
+	initialLevel := GetLevel()
+	defer SetLevel(initialLevel)
+
+	tests := []LogLevel{DEBUG, INFO, WARN, ERROR, FATAL}
+
+	for _, level := range tests {
+		SetLevel(level)
+		if GetLevel() != level {
+			t.Errorf("SetLevel(%v) -> GetLevel() = %v, want %v", level, GetLevel(), level)
+		}
+	}
+}
+
+func TestLoggerHelperFunctions(t *testing.T) {
+	initialLevel := GetLevel()
+	defer SetLevel(initialLevel)
+
+	SetLevel(INFO)
+
+	Debug("This should not log")
+	Info("This should log")
+	Warn("This should log")
+	Error("This should log")
+
+	InfoC("test", "Component message")
+	InfoF("Fields message", map[string]interface{}{"key": "value"})
+
+	WarnC("test", "Warning with component")
+	ErrorF("Error with fields", map[string]interface{}{"error": "test"})
+
+	SetLevel(DEBUG)
+	DebugC("test", "Debug with component")
+	WarnF("Warning with fields", map[string]interface{}{"key": "value"})
+}

pkg/providers/http_provider.go

@@ -0,0 +1,245 @@
+// PicoClaw - Ultra-lightweight personal AI agent
+// Inspired by and based on nanobot: https://github.com/HKUDS/nanobot
+// License: MIT
+//
+// Copyright (c) 2026 PicoClaw contributors
+
+package providers
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"strings"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+type HTTPProvider struct {
+	apiKey     string
+	apiBase    string
+	httpClient *http.Client
+}
+
+func NewHTTPProvider(apiKey, apiBase string) *HTTPProvider {
+	return &HTTPProvider{
+		apiKey:  apiKey,
+		apiBase: apiBase,
+		httpClient: &http.Client{
+			Timeout: 0,
+		},
+	}
+}
+
+func (p *HTTPProvider) Chat(ctx context.Context, messages []Message, tools []ToolDefinition, model string, options map[string]interface{}) (*LLMResponse, error) {
+	if p.apiBase == "" {
+		return nil, fmt.Errorf("API base not configured")
+	}
+
+	requestBody := map[string]interface{}{
+		"model":    model,
+		"messages": messages,
+	}
+
+	if len(tools) > 0 {
+		requestBody["tools"] = tools
+		requestBody["tool_choice"] = "auto"
+	}
+
+	if maxTokens, ok := options["max_tokens"].(int); ok {
+		requestBody["max_tokens"] = maxTokens
+	}
+
+	if temperature, ok := options["temperature"].(float64); ok {
+		requestBody["temperature"] = temperature
+	}
+
+	jsonData, err := json.Marshal(requestBody)
+	if err != nil {
+		return nil, fmt.Errorf("failed to marshal request: %w", err)
+	}
+
+	req, err := http.NewRequestWithContext(ctx, "POST", p.apiBase+"/chat/completions", bytes.NewReader(jsonData))
+	if err != nil {
+		return nil, fmt.Errorf("failed to create request: %w", err)
+	}
+
+	req.Header.Set("Content-Type", "application/json")
+	if p.apiKey != "" {
+		authHeader := "Bearer " + p.apiKey
+		req.Header.Set("Authorization", authHeader)
+	}
+
+	resp, err := p.httpClient.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("failed to send request: %w", err)
+	}
+	defer resp.Body.Close()
+
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, fmt.Errorf("failed to read response: %w", err)
+	}
+
+	if resp.StatusCode != http.StatusOK {
+		return nil, fmt.Errorf("API error: %s", string(body))
+	}
+
+	return p.parseResponse(body)
+}
+
+func (p *HTTPProvider) parseResponse(body []byte) (*LLMResponse, error) {
+	var apiResponse struct {
+		Choices []struct {
+			Message struct {
+				Content   string `json:"content"`
+				ToolCalls []struct {
+					ID       string `json:"id"`
+					Type     string `json:"type"`
+					Function *struct {
+						Name      string `json:"name"`
+						Arguments string `json:"arguments"`
+					} `json:"function"`
+				} `json:"tool_calls"`
+			} `json:"message"`
+			FinishReason string `json:"finish_reason"`
+		} `json:"choices"`
+		Usage *UsageInfo `json:"usage"`
+	}
+
+	if err := json.Unmarshal(body, &apiResponse); err != nil {
+		return nil, fmt.Errorf("failed to unmarshal response: %w", err)
+	}
+
+	if len(apiResponse.Choices) == 0 {
+		return &LLMResponse{
+			Content:      "",
+			FinishReason: "stop",
+		}, nil
+	}
+
+	choice := apiResponse.Choices[0]
+
+	toolCalls := make([]ToolCall, 0, len(choice.Message.ToolCalls))
+	for _, tc := range choice.Message.ToolCalls {
+		arguments := make(map[string]interface{})
+		name := ""
+
+		// Handle OpenAI format with nested function object
+		if tc.Type == "function" && tc.Function != nil {
+			name = tc.Function.Name
+			if tc.Function.Arguments != "" {
+				if err := json.Unmarshal([]byte(tc.Function.Arguments), &arguments); err != nil {
+					arguments["raw"] = tc.Function.Arguments
+				}
+			}
+		} else if tc.Function != nil {
+			// Legacy format without type field
+			name = tc.Function.Name
+			if tc.Function.Arguments != "" {
+				if err := json.Unmarshal([]byte(tc.Function.Arguments), &arguments); err != nil {
+					arguments["raw"] = tc.Function.Arguments
+				}
+			}
+		}
+
+		toolCalls = append(toolCalls, ToolCall{
+			ID:        tc.ID,
+			Name:      name,
+			Arguments: arguments,
+		})
+	}
+
+	return &LLMResponse{
+		Content:      choice.Message.Content,
+		ToolCalls:    toolCalls,
+		FinishReason: choice.FinishReason,
+		Usage:        apiResponse.Usage,
+	}, nil
+}
+
+func (p *HTTPProvider) GetDefaultModel() string {
+	return ""
+}
+
+func CreateProvider(cfg *config.Config) (LLMProvider, error) {
+	model := cfg.Agents.Defaults.Model
+
+	var apiKey, apiBase string
+
+	lowerModel := strings.ToLower(model)
+
+	switch {
+	case strings.HasPrefix(model, "openrouter/") || strings.HasPrefix(model, "anthropic/") || strings.HasPrefix(model, "openai/") || strings.HasPrefix(model, "meta-llama/") || strings.HasPrefix(model, "deepseek/") || strings.HasPrefix(model, "google/"):
+		apiKey = cfg.Providers.OpenRouter.APIKey
+		if cfg.Providers.OpenRouter.APIBase != "" {
+			apiBase = cfg.Providers.OpenRouter.APIBase
+		} else {
+			apiBase = "https://openrouter.ai/api/v1"
+		}
+
+	case strings.Contains(lowerModel, "claude") || strings.HasPrefix(model, "anthropic/"):
+		apiKey = cfg.Providers.Anthropic.APIKey
+		apiBase = cfg.Providers.Anthropic.APIBase
+		if apiBase == "" {
+			apiBase = "https://api.anthropic.com/v1"
+		}
+
+	case strings.Contains(lowerModel, "gpt") || strings.HasPrefix(model, "openai/"):
+		apiKey = cfg.Providers.OpenAI.APIKey
+		apiBase = cfg.Providers.OpenAI.APIBase
+		if apiBase == "" {
+			apiBase = "https://api.openai.com/v1"
+		}
+
+	case strings.Contains(lowerModel, "gemini") || strings.HasPrefix(model, "google/"):
+		apiKey = cfg.Providers.Gemini.APIKey
+		apiBase = cfg.Providers.Gemini.APIBase
+		if apiBase == "" {
+			apiBase = "https://generativelanguage.googleapis.com/v1beta"
+		}
+
+	case strings.Contains(lowerModel, "glm") || strings.Contains(lowerModel, "zhipu") || strings.Contains(lowerModel, "zai"):
+		apiKey = cfg.Providers.Zhipu.APIKey
+		apiBase = cfg.Providers.Zhipu.APIBase
+		if apiBase == "" {
+			apiBase = "https://open.bigmodel.cn/api/paas/v4"
+		}
+
+	case strings.Contains(lowerModel, "groq") || strings.HasPrefix(model, "groq/"):
+		apiKey = cfg.Providers.Groq.APIKey
+		apiBase = cfg.Providers.Groq.APIBase
+		if apiBase == "" {
+			apiBase = "https://api.groq.com/openai/v1"
+		}
+
+	case cfg.Providers.VLLM.APIBase != "":
+		apiKey = cfg.Providers.VLLM.APIKey
+		apiBase = cfg.Providers.VLLM.APIBase
+
+	default:
+		if cfg.Providers.OpenRouter.APIKey != "" {
+			apiKey = cfg.Providers.OpenRouter.APIKey
+			if cfg.Providers.OpenRouter.APIBase != "" {
+				apiBase = cfg.Providers.OpenRouter.APIBase
+			} else {
+				apiBase = "https://openrouter.ai/api/v1"
+			}
+		} else {
+			return nil, fmt.Errorf("no API key configured for model: %s", model)
+		}
+	}
+
+	if apiKey == "" && !strings.HasPrefix(model, "bedrock/") {
+		return nil, fmt.Errorf("no API key configured for provider (model: %s)", model)
+	}
+
+	if apiBase == "" {
+		return nil, fmt.Errorf("no API base configured for provider (model: %s)", model)
+	}
+
+	return NewHTTPProvider(apiKey, apiBase), nil
+}

pkg/providers/types.go

@@ -0,0 +1,52 @@
+package providers
+
+import "context"
+
+type ToolCall struct {
+	ID        string                 `json:"id"`
+	Type      string                 `json:"type,omitempty"`
+	Function  *FunctionCall          `json:"function,omitempty"`
+	Name      string                 `json:"name,omitempty"`
+	Arguments map[string]interface{} `json:"arguments,omitempty"`
+}
+
+type FunctionCall struct {
+	Name      string `json:"name"`
+	Arguments string `json:"arguments"`
+}
+
+type LLMResponse struct {
+	Content      string     `json:"content"`
+	ToolCalls    []ToolCall `json:"tool_calls,omitempty"`
+	FinishReason string     `json:"finish_reason"`
+	Usage        *UsageInfo `json:"usage,omitempty"`
+}
+
+type UsageInfo struct {
+	PromptTokens     int `json:"prompt_tokens"`
+	CompletionTokens int `json:"completion_tokens"`
+	TotalTokens      int `json:"total_tokens"`
+}
+
+type Message struct {
+	Role       string     `json:"role"`
+	Content    string     `json:"content"`
+	ToolCalls  []ToolCall `json:"tool_calls,omitempty"`
+	ToolCallID string     `json:"tool_call_id,omitempty"`
+}
+
+type LLMProvider interface {
+	Chat(ctx context.Context, messages []Message, tools []ToolDefinition, model string, options map[string]interface{}) (*LLMResponse, error)
+	GetDefaultModel() string
+}
+
+type ToolDefinition struct {
+	Type     string                 `json:"type"`
+	Function ToolFunctionDefinition `json:"function"`
+}
+
+type ToolFunctionDefinition struct {
+	Name        string                 `json:"name"`
+	Description string                 `json:"description"`
+	Parameters  map[string]interface{} `json:"parameters"`
+}

pkg/session/manager.go

@@ -0,0 +1,143 @@
+package session
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"sync"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/providers"
+)
+
+type Session struct {
+	Key      string              `json:"key"`
+	Messages []providers.Message `json:"messages"`
+	Created  time.Time           `json:"created"`
+	Updated  time.Time           `json:"updated"`
+}
+
+type SessionManager struct {
+	sessions map[string]*Session
+	mu       sync.RWMutex
+	storage  string
+}
+
+func NewSessionManager(storage string) *SessionManager {
+	sm := &SessionManager{
+		sessions: make(map[string]*Session),
+		storage:  storage,
+	}
+
+	if storage != "" {
+		os.MkdirAll(storage, 0755)
+		sm.loadSessions()
+	}
+
+	return sm
+}
+
+func (sm *SessionManager) GetOrCreate(key string) *Session {
+	sm.mu.RLock()
+	session, ok := sm.sessions[key]
+	sm.mu.RUnlock()
+
+	if !ok {
+		sm.mu.Lock()
+		session = &Session{
+			Key:      key,
+			Messages: []providers.Message{},
+			Created:  time.Now(),
+			Updated:  time.Now(),
+		}
+		sm.sessions[key] = session
+		sm.mu.Unlock()
+	}
+
+	return session
+}
+
+func (sm *SessionManager) AddMessage(sessionKey, role, content string) {
+	sm.mu.Lock()
+	defer sm.mu.Unlock()
+
+	session, ok := sm.sessions[sessionKey]
+	if !ok {
+		session = &Session{
+			Key:      sessionKey,
+			Messages: []providers.Message{},
+			Created:  time.Now(),
+		}
+		sm.sessions[sessionKey] = session
+	}
+
+	session.Messages = append(session.Messages, providers.Message{
+		Role:    role,
+		Content: content,
+	})
+	session.Updated = time.Now()
+}
+
+func (sm *SessionManager) GetHistory(key string) []providers.Message {
+	sm.mu.RLock()
+	defer sm.mu.RUnlock()
+
+	session, ok := sm.sessions[key]
+	if !ok {
+		return []providers.Message{}
+	}
+
+	history := make([]providers.Message, len(session.Messages))
+	copy(history, session.Messages)
+	return history
+}
+
+func (sm *SessionManager) Save(session *Session) error {
+	if sm.storage == "" {
+		return nil
+	}
+
+	sm.mu.Lock()
+	defer sm.mu.Unlock()
+
+	sessionPath := filepath.Join(sm.storage, session.Key+".json")
+
+	data, err := json.MarshalIndent(session, "", "  ")
+	if err != nil {
+		return err
+	}
+
+	return os.WriteFile(sessionPath, data, 0644)
+}
+
+func (sm *SessionManager) loadSessions() error {
+	files, err := os.ReadDir(sm.storage)
+	if err != nil {
+		return err
+	}
+
+	for _, file := range files {
+		if file.IsDir() {
+			continue
+		}
+
+		if filepath.Ext(file.Name()) != ".json" {
+			continue
+		}
+
+		sessionPath := filepath.Join(sm.storage, file.Name())
+		data, err := os.ReadFile(sessionPath)
+		if err != nil {
+			continue
+		}
+
+		var session Session
+		if err := json.Unmarshal(data, &session); err != nil {
+			continue
+		}
+
+		sm.sessions[session.Key] = &session
+	}
+
+	return nil
+}

pkg/skills/installer.go

@@ -0,0 +1,171 @@
+package skills
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"os"
+	"path/filepath"
+	"strings"
+	"time"
+)
+
+type SkillInstaller struct {
+	workspace string
+}
+
+type AvailableSkill struct {
+	Name        string   `json:"name"`
+	Repository  string   `json:"repository"`
+	Description string   `json:"description"`
+	Author      string   `json:"author"`
+	Tags        []string `json:"tags"`
+}
+
+type BuiltinSkill struct {
+	Name    string `json:"name"`
+	Path    string `json:"path"`
+	Enabled bool   `json:"enabled"`
+}
+
+func NewSkillInstaller(workspace string) *SkillInstaller {
+	return &SkillInstaller{
+		workspace: workspace,
+	}
+}
+
+func (si *SkillInstaller) InstallFromGitHub(ctx context.Context, repo string) error {
+	skillDir := filepath.Join(si.workspace, "skills", filepath.Base(repo))
+
+	if _, err := os.Stat(skillDir); err == nil {
+		return fmt.Errorf("skill '%s' already exists", filepath.Base(repo))
+	}
+
+	url := fmt.Sprintf("https://raw.githubusercontent.com/%s/main/SKILL.md", repo)
+
+	client := &http.Client{Timeout: 15 * time.Second}
+	req, err := http.NewRequestWithContext(ctx, "GET", url, nil)
+	if err != nil {
+		return fmt.Errorf("failed to create request: %w", err)
+	}
+
+	resp, err := client.Do(req)
+	if err != nil {
+		return fmt.Errorf("failed to fetch skill: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != 200 {
+		return fmt.Errorf("failed to fetch skill: HTTP %d", resp.StatusCode)
+	}
+
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return fmt.Errorf("failed to read response: %w", err)
+	}
+
+	if err := os.MkdirAll(skillDir, 0755); err != nil {
+		return fmt.Errorf("failed to create skill directory: %w", err)
+	}
+
+	skillPath := filepath.Join(skillDir, "SKILL.md")
+	if err := os.WriteFile(skillPath, body, 0644); err != nil {
+		return fmt.Errorf("failed to write skill file: %w", err)
+	}
+
+	return nil
+}
+
+func (si *SkillInstaller) Uninstall(skillName string) error {
+	skillDir := filepath.Join(si.workspace, "skills", skillName)
+
+	if _, err := os.Stat(skillDir); os.IsNotExist(err) {
+		return fmt.Errorf("skill '%s' not found", skillName)
+	}
+
+	if err := os.RemoveAll(skillDir); err != nil {
+		return fmt.Errorf("failed to remove skill: %w", err)
+	}
+
+	return nil
+}
+
+func (si *SkillInstaller) ListAvailableSkills(ctx context.Context) ([]AvailableSkill, error) {
+	url := "https://raw.githubusercontent.com/sipeed/picoclaw-skills/main/skills.json"
+
+	client := &http.Client{Timeout: 15 * time.Second}
+	req, err := http.NewRequestWithContext(ctx, "GET", url, nil)
+	if err != nil {
+		return nil, fmt.Errorf("failed to create request: %w", err)
+	}
+
+	resp, err := client.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("failed to fetch skills list: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != 200 {
+		return nil, fmt.Errorf("failed to fetch skills list: HTTP %d", resp.StatusCode)
+	}
+
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, fmt.Errorf("failed to read response: %w", err)
+	}
+
+	var skills []AvailableSkill
+	if err := json.Unmarshal(body, &skills); err != nil {
+		return nil, fmt.Errorf("failed to parse skills list: %w", err)
+	}
+
+	return skills, nil
+}
+
+func (si *SkillInstaller) ListBuiltinSkills() []BuiltinSkill {
+	builtinSkillsDir := filepath.Join(filepath.Dir(si.workspace), "picoclaw", "skills")
+
+	entries, err := os.ReadDir(builtinSkillsDir)
+	if err != nil {
+		return nil
+	}
+
+	var skills []BuiltinSkill
+	for _, entry := range entries {
+		if entry.IsDir() {
+			_ = entry
+			skillName := entry.Name()
+			skillFile := filepath.Join(builtinSkillsDir, skillName, "SKILL.md")
+
+			data, err := os.ReadFile(skillFile)
+			description := ""
+			if err == nil {
+				content := string(data)
+				if idx := strings.Index(content, "\n"); idx > 0 {
+					firstLine := content[:idx]
+					if strings.Contains(firstLine, "description:") {
+						descLine := strings.Index(content[idx:], "\n")
+						if descLine > 0 {
+							description = strings.TrimSpace(content[idx+descLine : idx+descLine])
+						}
+					}
+				}
+			}
+
+			// skill := BuiltinSkill{
+			// 	Name:    skillName,
+			// 	Path:    description,
+			// 	Enabled: true,
+			// }
+
+			status := "✓"
+			fmt.Printf("  %s  %s\n", status, entry.Name())
+			if description != "" {
+				fmt.Printf("    %s\n", description)
+			}
+		}
+	}
+	return skills
+}

pkg/skills/loader.go

@@ -0,0 +1,306 @@
+package skills
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"regexp"
+	"strings"
+)
+
+type SkillMetadata struct {
+	Name        string             `json:"name"`
+	Description string             `json:"description"`
+	Always      bool               `json:"always"`
+	Requires    *SkillRequirements `json:"requires,omitempty"`
+}
+
+type SkillRequirements struct {
+	Bins []string `json:"bins"`
+	Env  []string `json:"env"`
+}
+
+type SkillInfo struct {
+	Name        string `json:"name"`
+	Path        string `json:"path"`
+	Source      string `json:"source"`
+	Description string `json:"description"`
+	Available   bool   `json:"available"`
+	Missing     string `json:"missing,omitempty"`
+}
+
+type SkillsLoader struct {
+	workspace       string
+	workspaceSkills string
+	builtinSkills   string
+}
+
+func NewSkillsLoader(workspace string, builtinSkills string) *SkillsLoader {
+	return &SkillsLoader{
+		workspace:       workspace,
+		workspaceSkills: filepath.Join(workspace, "skills"),
+		builtinSkills:   builtinSkills,
+	}
+}
+
+func (sl *SkillsLoader) ListSkills(filterUnavailable bool) []SkillInfo {
+	skills := make([]SkillInfo, 0)
+
+	if sl.workspaceSkills != "" {
+		if dirs, err := os.ReadDir(sl.workspaceSkills); err == nil {
+			for _, dir := range dirs {
+				if dir.IsDir() {
+					skillFile := filepath.Join(sl.workspaceSkills, dir.Name(), "SKILL.md")
+					if _, err := os.Stat(skillFile); err == nil {
+						info := SkillInfo{
+							Name:   dir.Name(),
+							Path:   skillFile,
+							Source: "workspace",
+						}
+						metadata := sl.getSkillMetadata(skillFile)
+						if metadata != nil {
+							info.Description = metadata.Description
+							info.Available = sl.checkRequirements(metadata.Requires)
+							if !info.Available {
+								info.Missing = sl.getMissingRequirements(metadata.Requires)
+							}
+						} else {
+							info.Available = true
+						}
+						skills = append(skills, info)
+					}
+				}
+			}
+		}
+	}
+
+	if sl.builtinSkills != "" {
+		if dirs, err := os.ReadDir(sl.builtinSkills); err == nil {
+			for _, dir := range dirs {
+				if dir.IsDir() {
+					skillFile := filepath.Join(sl.builtinSkills, dir.Name(), "SKILL.md")
+					if _, err := os.Stat(skillFile); err == nil {
+						exists := false
+						for _, s := range skills {
+							if s.Name == dir.Name() && s.Source == "workspace" {
+								exists = true
+								break
+							}
+						}
+						if exists {
+							continue
+						}
+
+						info := SkillInfo{
+							Name:   dir.Name(),
+							Path:   skillFile,
+							Source: "builtin",
+						}
+						metadata := sl.getSkillMetadata(skillFile)
+						if metadata != nil {
+							info.Description = metadata.Description
+							info.Available = sl.checkRequirements(metadata.Requires)
+							if !info.Available {
+								info.Missing = sl.getMissingRequirements(metadata.Requires)
+							}
+						} else {
+							info.Available = true
+						}
+						skills = append(skills, info)
+					}
+				}
+			}
+		}
+	}
+
+	if filterUnavailable {
+		filtered := make([]SkillInfo, 0)
+		for _, s := range skills {
+			if s.Available {
+				filtered = append(filtered, s)
+			}
+		}
+		return filtered
+	}
+
+	return skills
+}
+
+func (sl *SkillsLoader) LoadSkill(name string) (string, bool) {
+	if sl.workspaceSkills != "" {
+		skillFile := filepath.Join(sl.workspaceSkills, name, "SKILL.md")
+		if content, err := os.ReadFile(skillFile); err == nil {
+			return sl.stripFrontmatter(string(content)), true
+		}
+	}
+
+	if sl.builtinSkills != "" {
+		skillFile := filepath.Join(sl.builtinSkills, name, "SKILL.md")
+		if content, err := os.ReadFile(skillFile); err == nil {
+			return sl.stripFrontmatter(string(content)), true
+		}
+	}
+
+	return "", false
+}
+
+func (sl *SkillsLoader) LoadSkillsForContext(skillNames []string) string {
+	if len(skillNames) == 0 {
+		return ""
+	}
+
+	var parts []string
+	for _, name := range skillNames {
+		content, ok := sl.LoadSkill(name)
+		if ok {
+			parts = append(parts, fmt.Sprintf("### Skill: %s\n\n%s", name, content))
+		}
+	}
+
+	return strings.Join(parts, "\n\n---\n\n")
+}
+
+func (sl *SkillsLoader) BuildSkillsSummary() string {
+	allSkills := sl.ListSkills(false)
+	if len(allSkills) == 0 {
+		return ""
+	}
+
+	var lines []string
+	lines = append(lines, "<skills>")
+	for _, s := range allSkills {
+		escapedName := escapeXML(s.Name)
+		escapedDesc := escapeXML(s.Description)
+		escapedPath := escapeXML(s.Path)
+
+		available := "true"
+		if !s.Available {
+			available = "false"
+		}
+
+		lines = append(lines, fmt.Sprintf("  <skill available=\"%s\">", available))
+		lines = append(lines, fmt.Sprintf("    <name>%s</name>", escapedName))
+		lines = append(lines, fmt.Sprintf("    <description>%s</description>", escapedDesc))
+		lines = append(lines, fmt.Sprintf("    <location>%s</location>", escapedPath))
+
+		if !s.Available && s.Missing != "" {
+			escapedMissing := escapeXML(s.Missing)
+			lines = append(lines, fmt.Sprintf("    <requires>%s</requires>", escapedMissing))
+		}
+
+		lines = append(lines, "  </skill>")
+	}
+	lines = append(lines, "</skills>")
+
+	return strings.Join(lines, "\n")
+}
+
+func (sl *SkillsLoader) GetAlwaysSkills() []string {
+	skills := sl.ListSkills(true)
+	var always []string
+	for _, s := range skills {
+		metadata := sl.getSkillMetadata(s.Path)
+		if metadata != nil && metadata.Always {
+			always = append(always, s.Name)
+		}
+	}
+	return always
+}
+
+func (sl *SkillsLoader) getSkillMetadata(skillPath string) *SkillMetadata {
+	content, err := os.ReadFile(skillPath)
+	if err != nil {
+		return nil
+	}
+
+	frontmatter := sl.extractFrontmatter(string(content))
+	if frontmatter == "" {
+		return &SkillMetadata{
+			Name: filepath.Base(filepath.Dir(skillPath)),
+		}
+	}
+
+	var metadata struct {
+		Name        string             `json:"name"`
+		Description string             `json:"description"`
+		Always      bool               `json:"always"`
+		Requires    *SkillRequirements `json:"requires"`
+	}
+
+	if err := json.Unmarshal([]byte(frontmatter), &metadata); err != nil {
+		return nil
+	}
+
+	return &SkillMetadata{
+		Name:        metadata.Name,
+		Description: metadata.Description,
+		Always:      metadata.Always,
+		Requires:    metadata.Requires,
+	}
+}
+
+func (sl *SkillsLoader) extractFrontmatter(content string) string {
+	re := regexp.MustCompile(`^---\n(.*?)\n---`)
+	match := re.FindStringSubmatch(content)
+	if len(match) > 1 {
+		return match[1]
+	}
+	return ""
+}
+
+func (sl *SkillsLoader) stripFrontmatter(content string) string {
+	re := regexp.MustCompile(`^---\n.*?\n---\n`)
+	return re.ReplaceAllString(content, "")
+}
+
+func (sl *SkillsLoader) checkRequirements(requires *SkillRequirements) bool {
+	if requires == nil {
+		return true
+	}
+
+	for _, bin := range requires.Bins {
+		if _, err := exec.LookPath(bin); err != nil {
+			continue
+		} else {
+			return true
+		}
+	}
+
+	for _, env := range requires.Env {
+		if os.Getenv(env) == "" {
+			return false
+		}
+	}
+
+	return true
+}
+
+func (sl *SkillsLoader) getMissingRequirements(requires *SkillRequirements) string {
+	if requires == nil {
+		return ""
+	}
+
+	var missing []string
+	for _, bin := range requires.Bins {
+		if _, err := exec.LookPath(bin); err != nil {
+			missing = append(missing, fmt.Sprintf("CLI: %s", bin))
+		}
+	}
+
+	for _, env := range requires.Env {
+		if os.Getenv(env) == "" {
+			missing = append(missing, fmt.Sprintf("ENV: %s", env))
+		}
+	}
+
+	return strings.Join(missing, ", ")
+}
+
+func escapeXML(s string) string {
+	s = strings.ReplaceAll(s, "&", "&amp;")
+	s = strings.ReplaceAll(s, "<", "&lt;")
+	s = strings.ReplaceAll(s, ">", "&gt;")
+	return s
+}

pkg/tools/base.go

@@ -0,0 +1,21 @@
+package tools
+
+import "context"
+
+type Tool interface {
+	Name() string
+	Description() string
+	Parameters() map[string]interface{}
+	Execute(ctx context.Context, args map[string]interface{}) (string, error)
+}
+
+func ToolToSchema(tool Tool) map[string]interface{} {
+	return map[string]interface{}{
+		"type": "function",
+		"function": map[string]interface{}{
+			"name":        tool.Name(),
+			"description": tool.Description(),
+			"parameters":  tool.Parameters(),
+		},
+	}
+}

pkg/tools/edit.go

@@ -0,0 +1,148 @@
+package tools
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+)
+
+type EditFileTool struct{}
+
+func NewEditFileTool() *EditFileTool {
+	return &EditFileTool{}
+}
+
+func (t *EditFileTool) Name() string {
+	return "edit_file"
+}
+
+func (t *EditFileTool) Description() string {
+	return "Edit a file by replacing old_text with new_text. The old_text must exist exactly in the file."
+}
+
+func (t *EditFileTool) Parameters() map[string]interface{} {
+	return map[string]interface{}{
+		"type": "object",
+		"properties": map[string]interface{}{
+			"path": map[string]interface{}{
+				"type":        "string",
+				"description": "The file path to edit",
+			},
+			"old_text": map[string]interface{}{
+				"type":        "string",
+				"description": "The exact text to find and replace",
+			},
+			"new_text": map[string]interface{}{
+				"type":        "string",
+				"description": "The text to replace with",
+			},
+		},
+		"required": []string{"path", "old_text", "new_text"},
+	}
+}
+
+func (t *EditFileTool) Execute(ctx context.Context, args map[string]interface{}) (string, error) {
+	path, ok := args["path"].(string)
+	if !ok {
+		return "", fmt.Errorf("path is required")
+	}
+
+	oldText, ok := args["old_text"].(string)
+	if !ok {
+		return "", fmt.Errorf("old_text is required")
+	}
+
+	newText, ok := args["new_text"].(string)
+	if !ok {
+		return "", fmt.Errorf("new_text is required")
+	}
+
+	filePath := filepath.Clean(path)
+
+	if _, err := os.Stat(filePath); os.IsNotExist(err) {
+		return "", fmt.Errorf("file not found: %s", path)
+	}
+
+	content, err := os.ReadFile(filePath)
+	if err != nil {
+		return "", fmt.Errorf("failed to read file: %w", err)
+	}
+
+	contentStr := string(content)
+
+	if !strings.Contains(contentStr, oldText) {
+		return "", fmt.Errorf("old_text not found in file. Make sure it matches exactly")
+	}
+
+	count := strings.Count(contentStr, oldText)
+	if count > 1 {
+		return "", fmt.Errorf("old_text appears %d times. Please provide more context to make it unique", count)
+	}
+
+	newContent := strings.Replace(contentStr, oldText, newText, 1)
+
+	if err := os.WriteFile(filePath, []byte(newContent), 0644); err != nil {
+		return "", fmt.Errorf("failed to write file: %w", err)
+	}
+
+	return fmt.Sprintf("Successfully edited %s", path), nil
+}
+
+type AppendFileTool struct{}
+
+func NewAppendFileTool() *AppendFileTool {
+	return &AppendFileTool{}
+}
+
+func (t *AppendFileTool) Name() string {
+	return "append_file"
+}
+
+func (t *AppendFileTool) Description() string {
+	return "Append content to the end of a file"
+}
+
+func (t *AppendFileTool) Parameters() map[string]interface{} {
+	return map[string]interface{}{
+		"type": "object",
+		"properties": map[string]interface{}{
+			"path": map[string]interface{}{
+				"type":        "string",
+				"description": "The file path to append to",
+			},
+			"content": map[string]interface{}{
+				"type":        "string",
+				"description": "The content to append",
+			},
+		},
+		"required": []string{"path", "content"},
+	}
+}
+
+func (t *AppendFileTool) Execute(ctx context.Context, args map[string]interface{}) (string, error) {
+	path, ok := args["path"].(string)
+	if !ok {
+		return "", fmt.Errorf("path is required")
+	}
+
+	content, ok := args["content"].(string)
+	if !ok {
+		return "", fmt.Errorf("content is required")
+	}
+
+	filePath := filepath.Clean(path)
+
+	f, err := os.OpenFile(filePath, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0644)
+	if err != nil {
+		return "", fmt.Errorf("failed to open file: %w", err)
+	}
+	defer f.Close()
+
+	if _, err := f.WriteString(content); err != nil {
+		return "", fmt.Errorf("failed to append to file: %w", err)
+	}
+
+	return fmt.Sprintf("Successfully appended to %s", path), nil
+}

pkg/tools/filesystem.go

@@ -0,0 +1,141 @@
+package tools
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"path/filepath"
+)
+
+type ReadFileTool struct{}
+
+func (t *ReadFileTool) Name() string {
+	return "read_file"
+}
+
+func (t *ReadFileTool) Description() string {
+	return "Read the contents of a file"
+}
+
+func (t *ReadFileTool) Parameters() map[string]interface{} {
+	return map[string]interface{}{
+		"type": "object",
+		"properties": map[string]interface{}{
+			"path": map[string]interface{}{
+				"type":        "string",
+				"description": "Path to the file to read",
+			},
+		},
+		"required": []string{"path"},
+	}
+}
+
+func (t *ReadFileTool) Execute(ctx context.Context, args map[string]interface{}) (string, error) {
+	path, ok := args["path"].(string)
+	if !ok {
+		return "", fmt.Errorf("path is required")
+	}
+
+	content, err := os.ReadFile(path)
+	if err != nil {
+		return "", fmt.Errorf("failed to read file: %w", err)
+	}
+
+	return string(content), nil
+}
+
+type WriteFileTool struct{}
+
+func (t *WriteFileTool) Name() string {
+	return "write_file"
+}
+
+func (t *WriteFileTool) Description() string {
+	return "Write content to a file"
+}
+
+func (t *WriteFileTool) Parameters() map[string]interface{} {
+	return map[string]interface{}{
+		"type": "object",
+		"properties": map[string]interface{}{
+			"path": map[string]interface{}{
+				"type":        "string",
+				"description": "Path to the file to write",
+			},
+			"content": map[string]interface{}{
+				"type":        "string",
+				"description": "Content to write to the file",
+			},
+		},
+		"required": []string{"path", "content"},
+	}
+}
+
+func (t *WriteFileTool) Execute(ctx context.Context, args map[string]interface{}) (string, error) {
+	path, ok := args["path"].(string)
+	if !ok {
+		return "", fmt.Errorf("path is required")
+	}
+
+	content, ok := args["content"].(string)
+	if !ok {
+		return "", fmt.Errorf("content is required")
+	}
+
+	dir := filepath.Dir(path)
+	if err := os.MkdirAll(dir, 0755); err != nil {
+		return "", fmt.Errorf("failed to create directory: %w", err)
+	}
+
+	if err := os.WriteFile(path, []byte(content), 0644); err != nil {
+		return "", fmt.Errorf("failed to write file: %w", err)
+	}
+
+	return "File written successfully", nil
+}
+
+type ListDirTool struct{}
+
+func (t *ListDirTool) Name() string {
+	return "list_dir"
+}
+
+func (t *ListDirTool) Description() string {
+	return "List files and directories in a path"
+}
+
+func (t *ListDirTool) Parameters() map[string]interface{} {
+	return map[string]interface{}{
+		"type": "object",
+		"properties": map[string]interface{}{
+			"path": map[string]interface{}{
+				"type":        "string",
+				"description": "Path to list",
+			},
+		},
+		"required": []string{"path"},
+	}
+}
+
+func (t *ListDirTool) Execute(ctx context.Context, args map[string]interface{}) (string, error) {
+	path, ok := args["path"].(string)
+	if !ok {
+		path = "."
+	}
+
+	entries, err := os.ReadDir(path)
+	if err != nil {
+		return "", fmt.Errorf("failed to read directory: %w", err)
+	}
+
+	result := ""
+	for _, entry := range entries {
+		if entry.IsDir() {
+			result += "DIR:  " + entry.Name() + "\n"
+		} else {
+			result += "FILE: " + entry.Name() + "\n"
+		}
+	}
+
+	return result, nil
+}

pkg/tools/message.go

@@ -0,0 +1,87 @@
+package tools
+
+import (
+	"context"
+	"fmt"
+)
+
+type SendCallback func(channel, chatID, content string) error
+
+type MessageTool struct {
+	sendCallback   SendCallback
+	defaultChannel string
+	defaultChatID  string
+}
+
+func NewMessageTool() *MessageTool {
+	return &MessageTool{}
+}
+
+func (t *MessageTool) Name() string {
+	return "message"
+}
+
+func (t *MessageTool) Description() string {
+	return "Send a message to user on a chat channel. Use this when you want to communicate something."
+}
+
+func (t *MessageTool) Parameters() map[string]interface{} {
+	return map[string]interface{}{
+		"type": "object",
+		"properties": map[string]interface{}{
+			"content": map[string]interface{}{
+				"type":        "string",
+				"description": "The message content to send",
+			},
+			"channel": map[string]interface{}{
+				"type":        "string",
+				"description": "Optional: target channel (telegram, whatsapp, etc.)",
+			},
+			"chat_id": map[string]interface{}{
+				"type":        "string",
+				"description": "Optional: target chat/user ID",
+			},
+		},
+		"required": []string{"content"},
+	}
+}
+
+func (t *MessageTool) SetContext(channel, chatID string) {
+	t.defaultChannel = channel
+	t.defaultChatID = chatID
+}
+
+func (t *MessageTool) SetSendCallback(callback SendCallback) {
+	t.sendCallback = callback
+}
+
+func (t *MessageTool) Execute(ctx context.Context, args map[string]interface{}) (string, error) {
+	content, ok := args["content"].(string)
+	if !ok {
+		return "", fmt.Errorf("content is required")
+	}
+
+	channel, _ := args["channel"].(string)
+	chatID, _ := args["chat_id"].(string)
+
+	if channel == "" {
+		channel = t.defaultChannel
+	}
+	if chatID == "" {
+		chatID = t.defaultChatID
+	}
+
+	if channel == "" || chatID == "" {
+		return "Error: No target channel/chat specified", nil
+	}
+
+	if t.sendCallback == nil {
+		return "Error: Message sending not configured", nil
+	}
+
+	if err := t.sendCallback(channel, chatID, content); err != nil {
+		return fmt.Sprintf("Error sending message: %v", err), nil
+	}
+
+	return fmt.Sprintf("Message sent to %s:%s", channel, chatID), nil
+}

pkg/tools/registry.go

@@ -0,0 +1,50 @@
+package tools
+
+import (
+	"context"
+	"fmt"
+	"sync"
+)
+
+type ToolRegistry struct {
+	tools map[string]Tool
+	mu    sync.RWMutex
+}
+
+func NewToolRegistry() *ToolRegistry {
+	return &ToolRegistry{
+		tools: make(map[string]Tool),
+	}
+}
+
+func (r *ToolRegistry) Register(tool Tool) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	r.tools[tool.Name()] = tool
+}
+
+func (r *ToolRegistry) Get(name string) (Tool, bool) {
+	r.mu.RLock()
+	defer r.mu.RUnlock()
+	tool, ok := r.tools[name]
+	return tool, ok
+}
+
+func (r *ToolRegistry) Execute(ctx context.Context, name string, args map[string]interface{}) (string, error) {
+	tool, ok := r.Get(name)
+	if !ok {
+		return "", fmt.Errorf("tool '%s' not found", name)
+	}
+	return tool.Execute(ctx, args)
+}
+
+func (r *ToolRegistry) GetDefinitions() []map[string]interface{} {
+	r.mu.RLock()
+	defer r.mu.RUnlock()
+
+	definitions := make([]map[string]interface{}, 0, len(r.tools))
+	for _, tool := range r.tools {
+		definitions = append(definitions, ToolToSchema(tool))
+	}
+	return definitions
+}

pkg/tools/shell.go

@@ -0,0 +1,202 @@
+package tools
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"regexp"
+	"strings"
+	"time"
+)
+
+type ExecTool struct {
+	workingDir          string
+	timeout             time.Duration
+	denyPatterns        []*regexp.Regexp
+	allowPatterns       []*regexp.Regexp
+	restrictToWorkspace bool
+}
+
+func NewExecTool(workingDir string) *ExecTool {
+	denyPatterns := []*regexp.Regexp{
+		regexp.MustCompile(`\brm\s+-[rf]{1,2}\b`),
+		regexp.MustCompile(`\bdel\s+/[fq]\b`),
+		regexp.MustCompile(`\brmdir\s+/s\b`),
+		regexp.MustCompile(`\b(format|mkfs|diskpart)\b`),
+		regexp.MustCompile(`\bdd\s+if=`),
+		regexp.MustCompile(`>\s*/dev/sd`),
+		regexp.MustCompile(`\b(shutdown|reboot|poweroff)\b`),
+		regexp.MustCompile(`:\(\)\s*\{.*\};\s*:`),
+	}
+
+	return &ExecTool{
+		workingDir:          workingDir,
+		timeout:             60 * time.Second,
+		denyPatterns:        denyPatterns,
+		allowPatterns:       nil,
+		restrictToWorkspace: false,
+	}
+}
+
+func (t *ExecTool) Name() string {
+	return "exec"
+}
+
+func (t *ExecTool) Description() string {
+	return "Execute a shell command and return its output. Use with caution."
+}
+
+func (t *ExecTool) Parameters() map[string]interface{} {
+	return map[string]interface{}{
+		"type": "object",
+		"properties": map[string]interface{}{
+			"command": map[string]interface{}{
+				"type":        "string",
+				"description": "The shell command to execute",
+			},
+			"working_dir": map[string]interface{}{
+				"type":        "string",
+				"description": "Optional working directory for the command",
+			},
+		},
+		"required": []string{"command"},
+	}
+}
+
+func (t *ExecTool) Execute(ctx context.Context, args map[string]interface{}) (string, error) {
+	command, ok := args["command"].(string)
+	if !ok {
+		return "", fmt.Errorf("command is required")
+	}
+
+	cwd := t.workingDir
+	if wd, ok := args["working_dir"].(string); ok && wd != "" {
+		cwd = wd
+	}
+
+	if cwd == "" {
+		wd, err := os.Getwd()
+		if err == nil {
+			cwd = wd
+		}
+	}
+
+	if guardError := t.guardCommand(command, cwd); guardError != "" {
+		return fmt.Sprintf("Error: %s", guardError), nil
+	}
+
+	cmdCtx, cancel := context.WithTimeout(ctx, t.timeout)
+	defer cancel()
+
+	cmd := exec.CommandContext(cmdCtx, "sh", "-c", command)
+	if cwd != "" {
+		cmd.Dir = cwd
+	}
+
+	var stdout, stderr bytes.Buffer
+	cmd.Stdout = &stdout
+	cmd.Stderr = &stderr
+
+	err := cmd.Run()
+	output := stdout.String()
+	if stderr.Len() > 0 {
+		output += "\nSTDERR:\n" + stderr.String()
+	}
+
+	if err != nil {
+		if cmdCtx.Err() == context.DeadlineExceeded {
+			return fmt.Sprintf("Error: Command timed out after %v", t.timeout), nil
+		}
+		output += fmt.Sprintf("\nExit code: %v", err)
+	}
+
+	if output == "" {
+		output = "(no output)"
+	}
+
+	maxLen := 10000
+	if len(output) > maxLen {
+		output = output[:maxLen] + fmt.Sprintf("\n... (truncated, %d more chars)", len(output)-maxLen)
+	}
+
+	return output, nil
+}
+
+func (t *ExecTool) guardCommand(command, cwd string) string {
+	cmd := strings.TrimSpace(command)
+	lower := strings.ToLower(cmd)
+
+	for _, pattern := range t.denyPatterns {
+		if pattern.MatchString(lower) {
+			return "Command blocked by safety guard (dangerous pattern detected)"
+		}
+	}
+
+	if len(t.allowPatterns) > 0 {
+		allowed := false
+		for _, pattern := range t.allowPatterns {
+			if pattern.MatchString(lower) {
+				allowed = true
+				break
+			}
+		}
+		if !allowed {
+			return "Command blocked by safety guard (not in allowlist)"
+		}
+	}
+
+	if t.restrictToWorkspace {
+		if strings.Contains(cmd, "..\\") || strings.Contains(cmd, "../") {
+			return "Command blocked by safety guard (path traversal detected)"
+		}
+
+		cwdPath, err := filepath.Abs(cwd)
+		if err != nil {
+			return ""
+		}
+
+		pathPattern := regexp.MustCompile(`[A-Za-z]:\\[^\\\"']+|/[^\s\"']+`)
+		matches := pathPattern.FindAllString(cmd, -1)
+
+		for _, raw := range matches {
+			p, err := filepath.Abs(raw)
+			if err != nil {
+				continue
+			}
+
+			rel, err := filepath.Rel(cwdPath, p)
+			if err != nil {
+				continue
+			}
+
+			if strings.HasPrefix(rel, "..") {
+				return "Command blocked by safety guard (path outside working dir)"
+			}
+		}
+	}
+
+	return ""
+}
+
+func (t *ExecTool) SetTimeout(timeout time.Duration) {
+	t.timeout = timeout
+}
+
+func (t *ExecTool) SetRestrictToWorkspace(restrict bool) {
+	t.restrictToWorkspace = restrict
+}
+
+func (t *ExecTool) SetAllowPatterns(patterns []string) error {
+	t.allowPatterns = make([]*regexp.Regexp, 0, len(patterns))
+	for _, p := range patterns {
+		re, err := regexp.Compile(p)
+		if err != nil {
+			return fmt.Errorf("invalid allow pattern %q: %w", p, err)
+		}
+		t.allowPatterns = append(t.allowPatterns, re)
+	}
+	return nil
+}

pkg/tools/spawn.go

@@ -0,0 +1,70 @@
+package tools
+
+import (
+	"context"
+	"fmt"
+)
+
+type SpawnTool struct {
+	manager       *SubagentManager
+	originChannel string
+	originChatID  string
+}
+
+func NewSpawnTool(manager *SubagentManager) *SpawnTool {
+	return &SpawnTool{
+		manager:       manager,
+		originChannel: "cli",
+		originChatID:  "direct",
+	}
+}
+
+func (t *SpawnTool) Name() string {
+	return "spawn"
+}
+
+func (t *SpawnTool) Description() string {
+	return "Spawn a subagent to handle a task in the background. Use this for complex or time-consuming tasks that can run independently. The subagent will complete the task and report back when done."
+}
+
+func (t *SpawnTool) Parameters() map[string]interface{} {
+	return map[string]interface{}{
+		"type": "object",
+		"properties": map[string]interface{}{
+			"task": map[string]interface{}{
+				"type":        "string",
+				"description": "The task for subagent to complete",
+			},
+			"label": map[string]interface{}{
+				"type":        "string",
+				"description": "Optional short label for the task (for display)",
+			},
+		},
+		"required": []string{"task"},
+	}
+}
+
+func (t *SpawnTool) SetContext(channel, chatID string) {
+	t.originChannel = channel
+	t.originChatID = chatID
+}
+
+func (t *SpawnTool) Execute(ctx context.Context, args map[string]interface{}) (string, error) {
+	task, ok := args["task"].(string)
+	if !ok {
+		return "", fmt.Errorf("task is required")
+	}
+
+	label, _ := args["label"].(string)
+
+	if t.manager == nil {
+		return "Error: Subagent manager not configured", nil
+	}
+
+	result, err := t.manager.Spawn(ctx, task, label, t.originChannel, t.originChatID)
+	if err != nil {
+		return "", fmt.Errorf("failed to spawn subagent: %w", err)
+	}
+
+	return result, nil
+}

pkg/tools/subagent.go

@@ -0,0 +1,111 @@
+package tools
+
+import (
+	"context"
+	"fmt"
+	"sync"
+	"time"
+)
+
+type SubagentTask struct {
+	ID            string
+	Task          string
+	Label         string
+	OriginChannel string
+	OriginChatID  string
+	Status        string
+	Result        string
+	Created       int64
+}
+
+type SubagentManager struct {
+	tasks     map[string]*SubagentTask
+	mu        sync.RWMutex
+	provider  LLMProvider
+	workspace string
+	nextID    int
+}
+
+func NewSubagentManager(provider LLMProvider, workspace string) *SubagentManager {
+	return &SubagentManager{
+		tasks:     make(map[string]*SubagentTask),
+		provider:  provider,
+		workspace: workspace,
+		nextID:    1,
+	}
+}
+
+func (sm *SubagentManager) Spawn(ctx context.Context, task, label, originChannel, originChatID string) (string, error) {
+	sm.mu.Lock()
+	defer sm.mu.Unlock()
+
+	taskID := fmt.Sprintf("subagent-%d", sm.nextID)
+	sm.nextID++
+
+	subagentTask := &SubagentTask{
+		ID:            taskID,
+		Task:          task,
+		Label:         label,
+		OriginChannel: originChannel,
+		OriginChatID:  originChatID,
+		Status:        "running",
+		Created:       time.Now().UnixMilli(),
+	}
+	sm.tasks[taskID] = subagentTask
+
+	go sm.runTask(ctx, subagentTask)
+
+	if label != "" {
+		return fmt.Sprintf("Spawned subagent '%s' for task: %s", label, task), nil
+	}
+	return fmt.Sprintf("Spawned subagent for task: %s", task), nil
+}
+
+func (sm *SubagentManager) runTask(ctx context.Context, task *SubagentTask) {
+	task.Status = "running"
+	task.Created = time.Now().UnixMilli()
+
+	messages := []Message{
+		{
+			Role:    "system",
+			Content: "You are a subagent. Complete the given task independently and report the result.",
+		},
+		{
+			Role:    "user",
+			Content: task.Task,
+		},
+	}
+
+	response, err := sm.provider.Chat(ctx, messages, nil, sm.provider.GetDefaultModel(), map[string]interface{}{
+		"max_tokens": 4096,
+	})
+
+	sm.mu.Lock()
+	defer sm.mu.Unlock()
+
+	if err != nil {
+		task.Status = "failed"
+		task.Result = fmt.Sprintf("Error: %v", err)
+	} else {
+		task.Status = "completed"
+		task.Result = response.Content
+	}
+}
+
+func (sm *SubagentManager) GetTask(taskID string) (*SubagentTask, bool) {
+	sm.mu.RLock()
+	defer sm.mu.RUnlock()
+	task, ok := sm.tasks[taskID]
+	return task, ok
+}
+
+func (sm *SubagentManager) ListTasks() []*SubagentTask {
+	sm.mu.RLock()
+	defer sm.mu.RUnlock()
+
+	tasks := make([]*SubagentTask, 0, len(sm.tasks))
+	for _, task := range sm.tasks {
+		tasks = append(tasks, task)
+	}
+	return tasks
+}

pkg/tools/types.go

@@ -0,0 +1,52 @@
+package tools
+
+import "context"
+
+type Message struct {
+	Role       string     `json:"role"`
+	Content    string     `json:"content"`
+	ToolCalls  []ToolCall `json:"tool_calls,omitempty"`
+	ToolCallID string     `json:"tool_call_id,omitempty"`
+}
+
+type ToolCall struct {
+	ID        string                 `json:"id"`
+	Type      string                 `json:"type"`
+	Function  *FunctionCall          `json:"function,omitempty"`
+	Name      string                 `json:"name,omitempty"`
+	Arguments map[string]interface{} `json:"arguments,omitempty"`
+}
+
+type FunctionCall struct {
+	Name      string `json:"name"`
+	Arguments string `json:"arguments"`
+}
+
+type LLMResponse struct {
+	Content      string     `json:"content"`
+	ToolCalls    []ToolCall `json:"tool_calls,omitempty"`
+	FinishReason string     `json:"finish_reason"`
+	Usage        *UsageInfo `json:"usage,omitempty"`
+}
+
+type UsageInfo struct {
+	PromptTokens     int `json:"prompt_tokens"`
+	CompletionTokens int `json:"completion_tokens"`
+	TotalTokens      int `json:"total_tokens"`
+}
+
+type LLMProvider interface {
+	Chat(ctx context.Context, messages []Message, tools []ToolDefinition, model string, options map[string]interface{}) (*LLMResponse, error)
+	GetDefaultModel() string
+}
+
+type ToolDefinition struct {
+	Type     string                 `json:"type"`
+	Function ToolFunctionDefinition `json:"function"`
+}
+
+type ToolFunctionDefinition struct {
+	Name        string                 `json:"name"`
+	Description string                 `json:"description"`
+	Parameters  map[string]interface{} `json:"parameters"`
+}

pkg/tools/web.go

@@ -0,0 +1,298 @@
+package tools
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"regexp"
+	"strings"
+	"time"
+)
+
+const (
+	userAgent = "Mozilla/5.0 (compatible; picoclaw/1.0)"
+)
+
+type WebSearchTool struct {
+	apiKey     string
+	maxResults int
+}
+
+func NewWebSearchTool(apiKey string, maxResults int) *WebSearchTool {
+	if maxResults <= 0 || maxResults > 10 {
+		maxResults = 5
+	}
+	return &WebSearchTool{
+		apiKey:     apiKey,
+		maxResults: maxResults,
+	}
+}
+
+func (t *WebSearchTool) Name() string {
+	return "web_search"
+}
+
+func (t *WebSearchTool) Description() string {
+	return "Search the web. Returns titles, URLs, and snippets."
+}
+
+func (t *WebSearchTool) Parameters() map[string]interface{} {
+	return map[string]interface{}{
+		"type": "object",
+		"properties": map[string]interface{}{
+			"query": map[string]interface{}{
+				"type":        "string",
+				"description": "Search query",
+			},
+			"count": map[string]interface{}{
+				"type":        "integer",
+				"description": "Number of results (1-10)",
+				"minimum":     1.0,
+				"maximum":     10.0,
+			},
+		},
+		"required": []string{"query"},
+	}
+}
+
+func (t *WebSearchTool) Execute(ctx context.Context, args map[string]interface{}) (string, error) {
+	if t.apiKey == "" {
+		return "Error: BRAVE_API_KEY not configured", nil
+	}
+
+	query, ok := args["query"].(string)
+	if !ok {
+		return "", fmt.Errorf("query is required")
+	}
+
+	count := t.maxResults
+	if c, ok := args["count"].(float64); ok {
+		if int(c) > 0 && int(c) <= 10 {
+			count = int(c)
+		}
+	}
+
+	searchURL := fmt.Sprintf("https://api.search.brave.com/res/v1/web/search?q=%s&count=%d",
+		url.QueryEscape(query), count)
+
+	req, err := http.NewRequestWithContext(ctx, "GET", searchURL, nil)
+	if err != nil {
+		return "", fmt.Errorf("failed to create request: %w", err)
+	}
+
+	req.Header.Set("Accept", "application/json")
+	req.Header.Set("X-Subscription-Token", t.apiKey)
+
+	client := &http.Client{Timeout: 10 * time.Second}
+	resp, err := client.Do(req)
+	if err != nil {
+		return "", fmt.Errorf("request failed: %w", err)
+	}
+	defer resp.Body.Close()
+
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return "", fmt.Errorf("failed to read response: %w", err)
+	}
+
+	var searchResp struct {
+		Web struct {
+			Results []struct {
+				Title       string `json:"title"`
+				URL         string `json:"url"`
+				Description string `json:"description"`
+			} `json:"results"`
+		} `json:"web"`
+	}
+
+	if err := json.Unmarshal(body, &searchResp); err != nil {
+		return "", fmt.Errorf("failed to parse response: %w", err)
+	}
+
+	results := searchResp.Web.Results
+	if len(results) == 0 {
+		return fmt.Sprintf("No results for: %s", query), nil
+	}
+
+	var lines []string
+	lines = append(lines, fmt.Sprintf("Results for: %s", query))
+	for i, item := range results {
+		if i >= count {
+			break
+		}
+		lines = append(lines, fmt.Sprintf("%d. %s\n   %s", i+1, item.Title, item.URL))
+		if item.Description != "" {
+			lines = append(lines, fmt.Sprintf("   %s", item.Description))
+		}
+	}
+
+	return strings.Join(lines, "\n"), nil
+}
+
+type WebFetchTool struct {
+	maxChars int
+}
+
+func NewWebFetchTool(maxChars int) *WebFetchTool {
+	if maxChars <= 0 {
+		maxChars = 50000
+	}
+	return &WebFetchTool{
+		maxChars: maxChars,
+	}
+}
+
+func (t *WebFetchTool) Name() string {
+	return "web_fetch"
+}
+
+func (t *WebFetchTool) Description() string {
+	return "Fetch a URL and extract readable content (HTML to text). Use this to get weather info, news, articles, or any web content."
+}
+
+func (t *WebFetchTool) Parameters() map[string]interface{} {
+	return map[string]interface{}{
+		"type": "object",
+		"properties": map[string]interface{}{
+			"url": map[string]interface{}{
+				"type":        "string",
+				"description": "URL to fetch",
+			},
+			"maxChars": map[string]interface{}{
+				"type":        "integer",
+				"description": "Maximum characters to extract",
+				"minimum":     100.0,
+			},
+		},
+		"required": []string{"url"},
+	}
+}
+
+func (t *WebFetchTool) Execute(ctx context.Context, args map[string]interface{}) (string, error) {
+	urlStr, ok := args["url"].(string)
+	if !ok {
+		return "", fmt.Errorf("url is required")
+	}
+
+	parsedURL, err := url.Parse(urlStr)
+	if err != nil {
+		return "", fmt.Errorf("invalid URL: %w", err)
+	}
+
+	if parsedURL.Scheme != "http" && parsedURL.Scheme != "https" {
+		return "", fmt.Errorf("only http/https URLs are allowed")
+	}
+
+	if parsedURL.Host == "" {
+		return "", fmt.Errorf("missing domain in URL")
+	}
+
+	maxChars := t.maxChars
+	if mc, ok := args["maxChars"].(float64); ok {
+		if int(mc) > 100 {
+			maxChars = int(mc)
+		}
+	}
+
+	req, err := http.NewRequestWithContext(ctx, "GET", urlStr, nil)
+	if err != nil {
+		return "", fmt.Errorf("failed to create request: %w", err)
+	}
+
+	req.Header.Set("User-Agent", userAgent)
+
+	client := &http.Client{
+		Timeout: 60 * time.Second,
+		Transport: &http.Transport{
+			MaxIdleConns:        10,
+			IdleConnTimeout:     30 * time.Second,
+			DisableCompression:  false,
+			TLSHandshakeTimeout: 15 * time.Second,
+		},
+		CheckRedirect: func(req *http.Request, via []*http.Request) error {
+			if len(via) >= 5 {
+				return fmt.Errorf("stopped after 5 redirects")
+			}
+			return nil
+		},
+	}
+
+	resp, err := client.Do(req)
+	if err != nil {
+		return "", fmt.Errorf("request failed: %w", err)
+	}
+	defer resp.Body.Close()
+
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return "", fmt.Errorf("failed to read response: %w", err)
+	}
+
+	contentType := resp.Header.Get("Content-Type")
+
+	var text, extractor string
+
+	if strings.Contains(contentType, "application/json") {
+		var jsonData interface{}
+		if err := json.Unmarshal(body, &jsonData); err == nil {
+			formatted, _ := json.MarshalIndent(jsonData, "", "  ")
+			text = string(formatted)
+			extractor = "json"
+		} else {
+			text = string(body)
+			extractor = "raw"
+		}
+	} else if strings.Contains(contentType, "text/html") || len(body) > 0 &&
+		(strings.HasPrefix(string(body), "<!DOCTYPE") || strings.HasPrefix(strings.ToLower(string(body)), "<html")) {
+		text = t.extractText(string(body))
+		extractor = "text"
+	} else {
+		text = string(body)
+		extractor = "raw"
+	}
+
+	truncated := len(text) > maxChars
+	if truncated {
+		text = text[:maxChars]
+	}
+
+	result := map[string]interface{}{
+		"url":       urlStr,
+		"status":    resp.StatusCode,
+		"extractor": extractor,
+		"truncated": truncated,
+		"length":    len(text),
+		"text":      text,
+	}
+
+	resultJSON, _ := json.MarshalIndent(result, "", "  ")
+	return string(resultJSON), nil
+}
+
+func (t *WebFetchTool) extractText(htmlContent string) string {
+	re := regexp.MustCompile(`<script[\s\S]*?</script>`)
+	result := re.ReplaceAllLiteralString(htmlContent, "")
+	re = regexp.MustCompile(`<style[\s\S]*?</style>`)
+	result = re.ReplaceAllLiteralString(result, "")
+	re = regexp.MustCompile(`<[^>]+>`)
+	result = re.ReplaceAllLiteralString(result, "")
+
+	result = strings.TrimSpace(result)
+
+	re = regexp.MustCompile(`\s+`)
+	result = re.ReplaceAllLiteralString(result, " ")
+
+	lines := strings.Split(result, "\n")
+	var cleanLines []string
+	for _, line := range lines {
+		line = strings.TrimSpace(line)
+		if line != "" {
+			cleanLines = append(cleanLines, line)
+		}
+	}
+
+	return strings.Join(cleanLines, "\n")
+}

pkg/voice/transcriber.go

@@ -0,0 +1,116 @@
+package voice
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"log"
+	"mime/multipart"
+	"net/http"
+	"os"
+	"path/filepath"
+	"time"
+)
+
+type GroqTranscriber struct {
+	apiKey     string
+	apiBase    string
+	httpClient *http.Client
+}
+
+type TranscriptionResponse struct {
+	Text     string  `json:"text"`
+	Language string  `json:"language,omitempty"`
+	Duration float64 `json:"duration,omitempty"`
+}
+
+func NewGroqTranscriber(apiKey string) *GroqTranscriber {
+	apiBase := "https://api.groq.com/openai/v1"
+	return &GroqTranscriber{
+		apiKey:  apiKey,
+		apiBase: apiBase,
+		httpClient: &http.Client{
+			Timeout: 60 * time.Second,
+		},
+	}
+}
+
+func (t *GroqTranscriber) Transcribe(ctx context.Context, audioFilePath string) (*TranscriptionResponse, error) {
+	log.Printf("Starting transcription for audio file: %s", audioFilePath)
+
+	audioFile, err := os.Open(audioFilePath)
+	if err != nil {
+		return nil, fmt.Errorf("failed to open audio file: %w", err)
+	}
+	defer audioFile.Close()
+
+	fileInfo, err := audioFile.Stat()
+	if err != nil {
+		return nil, fmt.Errorf("failed to get file info: %w", err)
+	}
+
+	var requestBody bytes.Buffer
+	writer := multipart.NewWriter(&requestBody)
+
+	part, err := writer.CreateFormFile("file", filepath.Base(audioFilePath))
+	if err != nil {
+		return nil, fmt.Errorf("failed to create form file: %w", err)
+	}
+
+	if _, err := io.Copy(part, audioFile); err != nil {
+		return nil, fmt.Errorf("failed to copy file content: %w", err)
+	}
+
+	if err := writer.WriteField("model", "whisper-large-v3"); err != nil {
+		return nil, fmt.Errorf("failed to write model field: %w", err)
+	}
+
+	if err := writer.WriteField("response_format", "json"); err != nil {
+		return nil, fmt.Errorf("failed to write response_format field: %w", err)
+	}
+
+	if err := writer.Close(); err != nil {
+		return nil, fmt.Errorf("failed to close multipart writer: %w", err)
+	}
+
+	url := t.apiBase + "/audio/transcriptions"
+	req, err := http.NewRequestWithContext(ctx, "POST", url, &requestBody)
+	if err != nil {
+		return nil, fmt.Errorf("failed to create request: %w", err)
+	}
+
+	req.Header.Set("Content-Type", writer.FormDataContentType())
+	req.Header.Set("Authorization", "Bearer "+t.apiKey)
+
+	log.Printf("Sending transcription request to Groq API (file size: %d bytes)", fileInfo.Size())
+
+	resp, err := t.httpClient.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("failed to send request: %w", err)
+	}
+	defer resp.Body.Close()
+
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, fmt.Errorf("failed to read response: %w", err)
+	}
+
+	if resp.StatusCode != http.StatusOK {
+		return nil, fmt.Errorf("API error (status %d): %s", resp.StatusCode, string(body))
+	}
+
+	var result TranscriptionResponse
+	if err := json.Unmarshal(body, &result); err != nil {
+		return nil, fmt.Errorf("failed to unmarshal response: %w", err)
+	}
+
+	log.Printf("Transcription completed successfully (text length: %d chars)", len(result.Text))
+
+	return &result, nil
+}
+
+func (t *GroqTranscriber) IsAvailable() bool {
+	return t.apiKey != ""
+}

skills/github/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: github
+description: "Interact with GitHub using the `gh` CLI. Use `gh issue`, `gh pr`, `gh run`, and `gh api` for issues, PRs, CI runs, and advanced queries."
+metadata: {"nanobot":{"emoji":"🐙","requires":{"bins":["gh"]},"install":[{"id":"brew","kind":"brew","formula":"gh","bins":["gh"],"label":"Install GitHub CLI (brew)"},{"id":"apt","kind":"apt","package":"gh","bins":["gh"],"label":"Install GitHub CLI (apt)"}]}}
+---
+
+# GitHub Skill
+
+Use the `gh` CLI to interact with GitHub. Always specify `--repo owner/repo` when not in a git directory, or use URLs directly.
+
+## Pull Requests
+
+Check CI status on a PR:
+```bash
+gh pr checks 55 --repo owner/repo
+```
+
+List recent workflow runs:
+```bash
+gh run list --repo owner/repo --limit 10
+```
+
+View a run and see which steps failed:
+```bash
+gh run view <run-id> --repo owner/repo
+```
+
+View logs for failed steps only:
+```bash
+gh run view <run-id> --repo owner/repo --log-failed
+```
+
+## API for Advanced Queries
+
+The `gh api` command is useful for accessing data not available through other subcommands.
+
+Get PR with specific fields:
+```bash
+gh api repos/owner/repo/pulls/55 --jq '.title, .state, .user.login'
+```
+
+## JSON Output
+
+Most commands support `--json` for structured output.  You can use `--jq` to filter:
+
+```bash
+gh issue list --repo owner/repo --json number,title --jq '.[] | "\(.number): \(.title)"'
+```

skills/skill-creator/SKILL.md

@@ -0,0 +1,371 @@
+---
+name: skill-creator
+description: Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
+---
+
+# Skill Creator
+
+This skill provides guidance for creating effective skills.
+
+## About Skills
+
+Skills are modular, self-contained packages that extend the agent's capabilities by providing
+specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific
+domains or tasks—they transform the agent from a general-purpose agent into a specialized agent
+equipped with procedural knowledge that no model can fully possess.
+
+### What Skills Provide
+
+1. Specialized workflows - Multi-step procedures for specific domains
+2. Tool integrations - Instructions for working with specific file formats or APIs
+3. Domain expertise - Company-specific knowledge, schemas, business logic
+4. Bundled resources - Scripts, references, and assets for complex and repetitive tasks
+
+## Core Principles
+
+### Concise is Key
+
+The context window is a public good. Skills share the context window with everything else the agent needs: system prompt, conversation history, other Skills' metadata, and the actual user request.
+
+**Default assumption: the agent is already very smart.** Only add context the agent doesn't already have. Challenge each piece of information: "Does the agent really need this explanation?" and "Does this paragraph justify its token cost?"
+
+Prefer concise examples over verbose explanations.
+
+### Set Appropriate Degrees of Freedom
+
+Match the level of specificity to the task's fragility and variability:
+
+**High freedom (text-based instructions)**: Use when multiple approaches are valid, decisions depend on context, or heuristics guide the approach.
+
+**Medium freedom (pseudocode or scripts with parameters)**: Use when a preferred pattern exists, some variation is acceptable, or configuration affects behavior.
+
+**Low freedom (specific scripts, few parameters)**: Use when operations are fragile and error-prone, consistency is critical, or a specific sequence must be followed.
+
+Think of the agent as exploring a path: a narrow bridge with cliffs needs specific guardrails (low freedom), while an open field allows many routes (high freedom).
+
+### Anatomy of a Skill
+
+Every skill consists of a required SKILL.md file and optional bundled resources:
+
+```
+skill-name/
+├── SKILL.md (required)
+│   ├── YAML frontmatter metadata (required)
+│   │   ├── name: (required)
+│   │   └── description: (required)
+│   └── Markdown instructions (required)
+└── Bundled Resources (optional)
+    ├── scripts/          - Executable code (Python/Bash/etc.)
+    ├── references/       - Documentation intended to be loaded into context as needed
+    └── assets/           - Files used in output (templates, icons, fonts, etc.)
+```
+
+#### SKILL.md (required)
+
+Every SKILL.md consists of:
+
+- **Frontmatter** (YAML): Contains `name` and `description` fields. These are the only fields that the agent reads to determine when the skill gets used, thus it is very important to be clear and comprehensive in describing what the skill is, and when it should be used.
+- **Body** (Markdown): Instructions and guidance for using the skill. Only loaded AFTER the skill triggers (if at all).
+
+#### Bundled Resources (optional)
+
+##### Scripts (`scripts/`)
+
+Executable code (Python/Bash/etc.) for tasks that require deterministic reliability or are repeatedly rewritten.
+
+- **When to include**: When the same code is being rewritten repeatedly or deterministic reliability is needed
+- **Example**: `scripts/rotate_pdf.py` for PDF rotation tasks
+- **Benefits**: Token efficient, deterministic, may be executed without loading into context
+- **Note**: Scripts may still need to be read by the agent for patching or environment-specific adjustments
+
+##### References (`references/`)
+
+Documentation and reference material intended to be loaded as needed into context to inform the agent's process and thinking.
+
+- **When to include**: For documentation that the agent should reference while working
+- **Examples**: `references/finance.md` for financial schemas, `references/mnda.md` for company NDA template, `references/policies.md` for company policies, `references/api_docs.md` for API specifications
+- **Use cases**: Database schemas, API documentation, domain knowledge, company policies, detailed workflow guides
+- **Benefits**: Keeps SKILL.md lean, loaded only when the agent determines it's needed
+- **Best practice**: If files are large (>10k words), include grep search patterns in SKILL.md
+- **Avoid duplication**: Information should live in either SKILL.md or references files, not both. Prefer references files for detailed information unless it's truly core to the skill—this keeps SKILL.md lean while making information discoverable without hogging the context window. Keep only essential procedural instructions and workflow guidance in SKILL.md; move detailed reference material, schemas, and examples to references files.
+
+##### Assets (`assets/`)
+
+Files not intended to be loaded into context, but rather used within the output the agent produces.
+
+- **When to include**: When the skill needs files that will be used in the final output
+- **Examples**: `assets/logo.png` for brand assets, `assets/slides.pptx` for PowerPoint templates, `assets/frontend-template/` for HTML/React boilerplate, `assets/font.ttf` for typography
+- **Use cases**: Templates, images, icons, boilerplate code, fonts, sample documents that get copied or modified
+- **Benefits**: Separates output resources from documentation, enables the agent to use files without loading them into context
+
+#### What to Not Include in a Skill
+
+A skill should only contain essential files that directly support its functionality. Do NOT create extraneous documentation or auxiliary files, including:
+
+- README.md
+- INSTALLATION_GUIDE.md
+- QUICK_REFERENCE.md
+- CHANGELOG.md
+- etc.
+
+The skill should only contain the information needed for an AI agent to do the job at hand. It should not contain auxiliary context about the process that went into creating it, setup and testing procedures, user-facing documentation, etc. Creating additional documentation files just adds clutter and confusion.
+
+### Progressive Disclosure Design Principle
+
+Skills use a three-level loading system to manage context efficiently:
+
+1. **Metadata (name + description)** - Always in context (~100 words)
+2. **SKILL.md body** - When skill triggers (<5k words)
+3. **Bundled resources** - As needed by the agent (Unlimited because scripts can be executed without reading into context window)
+
+#### Progressive Disclosure Patterns
+
+Keep SKILL.md body to the essentials and under 500 lines to minimize context bloat. Split content into separate files when approaching this limit. When splitting out content into other files, it is very important to reference them from SKILL.md and describe clearly when to read them, to ensure the reader of the skill knows they exist and when to use them.
+
+**Key principle:** When a skill supports multiple variations, frameworks, or options, keep only the core workflow and selection guidance in SKILL.md. Move variant-specific details (patterns, examples, configuration) into separate reference files.
+
+**Pattern 1: High-level guide with references**
+
+```markdown
+# PDF Processing
+
+## Quick start
+
+Extract text with pdfplumber:
+[code example]
+
+## Advanced features
+
+- **Form filling**: See [FORMS.md](FORMS.md) for complete guide
+- **API reference**: See [REFERENCE.md](REFERENCE.md) for all methods
+- **Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns
+```
+
+the agent loads FORMS.md, REFERENCE.md, or EXAMPLES.md only when needed.
+
+**Pattern 2: Domain-specific organization**
+
+For Skills with multiple domains, organize content by domain to avoid loading irrelevant context:
+
+```
+bigquery-skill/
+├── SKILL.md (overview and navigation)
+└── reference/
+    ├── finance.md (revenue, billing metrics)
+    ├── sales.md (opportunities, pipeline)
+    ├── product.md (API usage, features)
+    └── marketing.md (campaigns, attribution)
+```
+
+When a user asks about sales metrics, the agent only reads sales.md.
+
+Similarly, for skills supporting multiple frameworks or variants, organize by variant:
+
+```
+cloud-deploy/
+├── SKILL.md (workflow + provider selection)
+└── references/
+    ├── aws.md (AWS deployment patterns)
+    ├── gcp.md (GCP deployment patterns)
+    └── azure.md (Azure deployment patterns)
+```
+
+When the user chooses AWS, the agent only reads aws.md.
+
+**Pattern 3: Conditional details**
+
+Show basic content, link to advanced content:
+
+```markdown
+# DOCX Processing
+
+## Creating documents
+
+Use docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md).
+
+## Editing documents
+
+For simple edits, modify the XML directly.
+
+**For tracked changes**: See [REDLINING.md](REDLINING.md)
+**For OOXML details**: See [OOXML.md](OOXML.md)
+```
+
+the agent reads REDLINING.md or OOXML.md only when the user needs those features.
+
+**Important guidelines:**
+
+- **Avoid deeply nested references** - Keep references one level deep from SKILL.md. All reference files should link directly from SKILL.md.
+- **Structure longer reference files** - For files longer than 100 lines, include a table of contents at the top so the agent can see the full scope when previewing.
+
+## Skill Creation Process
+
+Skill creation involves these steps:
+
+1. Understand the skill with concrete examples
+2. Plan reusable skill contents (scripts, references, assets)
+3. Initialize the skill (run init_skill.py)
+4. Edit the skill (implement resources and write SKILL.md)
+5. Package the skill (run package_skill.py)
+6. Iterate based on real usage
+
+Follow these steps in order, skipping only if there is a clear reason why they are not applicable.
+
+### Skill Naming
+
+- Use lowercase letters, digits, and hyphens only; normalize user-provided titles to hyphen-case (e.g., "Plan Mode" -> `plan-mode`).
+- When generating names, generate a name under 64 characters (letters, digits, hyphens).
+- Prefer short, verb-led phrases that describe the action.
+- Namespace by tool when it improves clarity or triggering (e.g., `gh-address-comments`, `linear-address-issue`).
+- Name the skill folder exactly after the skill name.
+
+### Step 1: Understanding the Skill with Concrete Examples
+
+Skip this step only when the skill's usage patterns are already clearly understood. It remains valuable even when working with an existing skill.
+
+To create an effective skill, clearly understand concrete examples of how the skill will be used. This understanding can come from either direct user examples or generated examples that are validated with user feedback.
+
+For example, when building an image-editor skill, relevant questions include:
+
+- "What functionality should the image-editor skill support? Editing, rotating, anything else?"
+- "Can you give some examples of how this skill would be used?"
+- "I can imagine users asking for things like 'Remove the red-eye from this image' or 'Rotate this image'. Are there other ways you imagine this skill being used?"
+- "What would a user say that should trigger this skill?"
+
+To avoid overwhelming users, avoid asking too many questions in a single message. Start with the most important questions and follow up as needed for better effectiveness.
+
+Conclude this step when there is a clear sense of the functionality the skill should support.
+
+### Step 2: Planning the Reusable Skill Contents
+
+To turn concrete examples into an effective skill, analyze each example by:
+
+1. Considering how to execute on the example from scratch
+2. Identifying what scripts, references, and assets would be helpful when executing these workflows repeatedly
+
+Example: When building a `pdf-editor` skill to handle queries like "Help me rotate this PDF," the analysis shows:
+
+1. Rotating a PDF requires re-writing the same code each time
+2. A `scripts/rotate_pdf.py` script would be helpful to store in the skill
+
+Example: When designing a `frontend-webapp-builder` skill for queries like "Build me a todo app" or "Build me a dashboard to track my steps," the analysis shows:
+
+1. Writing a frontend webapp requires the same boilerplate HTML/React each time
+2. An `assets/hello-world/` template containing the boilerplate HTML/React project files would be helpful to store in the skill
+
+Example: When building a `big-query` skill to handle queries like "How many users have logged in today?" the analysis shows:
+
+1. Querying BigQuery requires re-discovering the table schemas and relationships each time
+2. A `references/schema.md` file documenting the table schemas would be helpful to store in the skill
+
+To establish the skill's contents, analyze each concrete example to create a list of the reusable resources to include: scripts, references, and assets.
+
+### Step 3: Initializing the Skill
+
+At this point, it is time to actually create the skill.
+
+Skip this step only if the skill being developed already exists, and iteration or packaging is needed. In this case, continue to the next step.
+
+When creating a new skill from scratch, always run the `init_skill.py` script. The script conveniently generates a new template skill directory that automatically includes everything a skill requires, making the skill creation process much more efficient and reliable.
+
+Usage:
+
+```bash
+scripts/init_skill.py <skill-name> --path <output-directory> [--resources scripts,references,assets] [--examples]
+```
+
+Examples:
+
+```bash
+scripts/init_skill.py my-skill --path skills/public
+scripts/init_skill.py my-skill --path skills/public --resources scripts,references
+scripts/init_skill.py my-skill --path skills/public --resources scripts --examples
+```
+
+The script:
+
+- Creates the skill directory at the specified path
+- Generates a SKILL.md template with proper frontmatter and TODO placeholders
+- Optionally creates resource directories based on `--resources`
+- Optionally adds example files when `--examples` is set
+
+After initialization, customize the SKILL.md and add resources as needed. If you used `--examples`, replace or delete placeholder files.
+
+### Step 4: Edit the Skill
+
+When editing the (newly-generated or existing) skill, remember that the skill is being created for another instance of the agent to use. Include information that would be beneficial and non-obvious to the agent. Consider what procedural knowledge, domain-specific details, or reusable assets would help another the agent instance execute these tasks more effectively.
+
+#### Learn Proven Design Patterns
+
+Consult these helpful guides based on your skill's needs:
+
+- **Multi-step processes**: See references/workflows.md for sequential workflows and conditional logic
+- **Specific output formats or quality standards**: See references/output-patterns.md for template and example patterns
+
+These files contain established best practices for effective skill design.
+
+#### Start with Reusable Skill Contents
+
+To begin implementation, start with the reusable resources identified above: `scripts/`, `references/`, and `assets/` files. Note that this step may require user input. For example, when implementing a `brand-guidelines` skill, the user may need to provide brand assets or templates to store in `assets/`, or documentation to store in `references/`.
+
+Added scripts must be tested by actually running them to ensure there are no bugs and that the output matches what is expected. If there are many similar scripts, only a representative sample needs to be tested to ensure confidence that they all work while balancing time to completion.
+
+If you used `--examples`, delete any placeholder files that are not needed for the skill. Only create resource directories that are actually required.
+
+#### Update SKILL.md
+
+**Writing Guidelines:** Always use imperative/infinitive form.
+
+##### Frontmatter
+
+Write the YAML frontmatter with `name` and `description`:
+
+- `name`: The skill name
+- `description`: This is the primary triggering mechanism for your skill, and helps the agent understand when to use the skill.
+  - Include both what the Skill does and specific triggers/contexts for when to use it.
+  - Include all "when to use" information here - Not in the body. The body is only loaded after triggering, so "When to Use This Skill" sections in the body are not helpful to the agent.
+  - Example description for a `docx` skill: "Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction. Use when the agent needs to work with professional documents (.docx files) for: (1) Creating new documents, (2) Modifying or editing content, (3) Working with tracked changes, (4) Adding comments, or any other document tasks"
+
+Do not include any other fields in YAML frontmatter.
+
+##### Body
+
+Write instructions for using the skill and its bundled resources.
+
+### Step 5: Packaging a Skill
+
+Once development of the skill is complete, it must be packaged into a distributable .skill file that gets shared with the user. The packaging process automatically validates the skill first to ensure it meets all requirements:
+
+```bash
+scripts/package_skill.py <path/to/skill-folder>
+```
+
+Optional output directory specification:
+
+```bash
+scripts/package_skill.py <path/to/skill-folder> ./dist
+```
+
+The packaging script will:
+
+1. **Validate** the skill automatically, checking:
+
+   - YAML frontmatter format and required fields
+   - Skill naming conventions and directory structure
+   - Description completeness and quality
+   - File organization and resource references
+
+2. **Package** the skill if validation passes, creating a .skill file named after the skill (e.g., `my-skill.skill`) that includes all files and maintains the proper directory structure for distribution. The .skill file is a zip file with a .skill extension.
+
+If validation fails, the script will report the errors and exit without creating a package. Fix any validation errors and run the packaging command again.
+
+### Step 6: Iterate
+
+After testing the skill, users may request improvements. Often this happens right after using the skill, with fresh context of how the skill performed.
+
+**Iteration workflow:**
+
+1. Use the skill on real tasks
+2. Notice struggles or inefficiencies
+3. Identify how SKILL.md or bundled resources should be updated
+4. Implement changes and test again

skills/summarize/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: summarize
+description: Summarize or extract text/transcripts from URLs, podcasts, and local files (great fallback for “transcribe this YouTube/video”).
+homepage: https://summarize.sh
+metadata: {"nanobot":{"emoji":"🧾","requires":{"bins":["summarize"]},"install":[{"id":"brew","kind":"brew","formula":"steipete/tap/summarize","bins":["summarize"],"label":"Install summarize (brew)"}]}}
+---
+
+# Summarize
+
+Fast CLI to summarize URLs, local files, and YouTube links.
+
+## When to use (trigger phrases)
+
+Use this skill immediately when the user asks any of:
+- “use summarize.sh”
+- “what’s this link/video about?”
+- “summarize this URL/article”
+- “transcribe this YouTube/video” (best-effort transcript extraction; no `yt-dlp` needed)
+
+## Quick start
+
+```bash
+summarize "https://example.com" --model google/gemini-3-flash-preview
+summarize "/path/to/file.pdf" --model google/gemini-3-flash-preview
+summarize "https://youtu.be/dQw4w9WgXcQ" --youtube auto
+```
+
+## YouTube: summary vs transcript
+
+Best-effort transcript (URLs only):
+
+```bash
+summarize "https://youtu.be/dQw4w9WgXcQ" --youtube auto --extract-only
+```
+
+If the user asked for a transcript but it’s huge, return a tight summary first, then ask which section/time range to expand.
+
+## Model + keys
+
+Set the API key for your chosen provider:
+- OpenAI: `OPENAI_API_KEY`
+- Anthropic: `ANTHROPIC_API_KEY`
+- xAI: `XAI_API_KEY`
+- Google: `GEMINI_API_KEY` (aliases: `GOOGLE_GENERATIVE_AI_API_KEY`, `GOOGLE_API_KEY`)
+
+Default model is `google/gemini-3-flash-preview` if none is set.
+
+## Useful flags
+
+- `--length short|medium|long|xl|xxl|<chars>`
+- `--max-output-tokens <count>`
+- `--extract-only` (URLs only)
+- `--json` (machine readable)
+- `--firecrawl auto|off|always` (fallback extraction)
+- `--youtube auto` (Apify fallback if `APIFY_API_TOKEN` set)
+
+## Config
+
+Optional config file: `~/.summarize/config.json`
+
+```json
+{ "model": "openai/gpt-5.2" }
+```
+
+Optional services:
+- `FIRECRAWL_API_KEY` for blocked sites
+- `APIFY_API_TOKEN` for YouTube fallback

skills/tmux/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: tmux
+description: Remote-control tmux sessions for interactive CLIs by sending keystrokes and scraping pane output.
+metadata: {"nanobot":{"emoji":"🧵","os":["darwin","linux"],"requires":{"bins":["tmux"]}}}
+---
+
+# tmux Skill
+
+Use tmux only when you need an interactive TTY. Prefer exec background mode for long-running, non-interactive tasks.
+
+## Quickstart (isolated socket, exec tool)
+
+```bash
+SOCKET_DIR="${NANOBOT_TMUX_SOCKET_DIR:-${TMPDIR:-/tmp}/nanobot-tmux-sockets}"
+mkdir -p "$SOCKET_DIR"
+SOCKET="$SOCKET_DIR/nanobot.sock"
+SESSION=nanobot-python
+
+tmux -S "$SOCKET" new -d -s "$SESSION" -n shell
+tmux -S "$SOCKET" send-keys -t "$SESSION":0.0 -- 'PYTHON_BASIC_REPL=1 python3 -q' Enter
+tmux -S "$SOCKET" capture-pane -p -J -t "$SESSION":0.0 -S -200
+```
+
+After starting a session, always print monitor commands:
+
+```
+To monitor:
+  tmux -S "$SOCKET" attach -t "$SESSION"
+  tmux -S "$SOCKET" capture-pane -p -J -t "$SESSION":0.0 -S -200
+```
+
+## Socket convention
+
+- Use `NANOBOT_TMUX_SOCKET_DIR` environment variable.
+- Default socket path: `"$NANOBOT_TMUX_SOCKET_DIR/nanobot.sock"`.
+
+## Targeting panes and naming
+
+- Target format: `session:window.pane` (defaults to `:0.0`).
+- Keep names short; avoid spaces.
+- Inspect: `tmux -S "$SOCKET" list-sessions`, `tmux -S "$SOCKET" list-panes -a`.
+
+## Finding sessions
+
+- List sessions on your socket: `{baseDir}/scripts/find-sessions.sh -S "$SOCKET"`.
+- Scan all sockets: `{baseDir}/scripts/find-sessions.sh --all` (uses `NANOBOT_TMUX_SOCKET_DIR`).
+
+## Sending input safely
+
+- Prefer literal sends: `tmux -S "$SOCKET" send-keys -t target -l -- "$cmd"`.
+- Control keys: `tmux -S "$SOCKET" send-keys -t target C-c`.
+
+## Watching output
+
+- Capture recent history: `tmux -S "$SOCKET" capture-pane -p -J -t target -S -200`.
+- Wait for prompts: `{baseDir}/scripts/wait-for-text.sh -t session:0.0 -p 'pattern'`.
+- Attaching is OK; detach with `Ctrl+b d`.
+
+## Spawning processes
+
+- For python REPLs, set `PYTHON_BASIC_REPL=1` (non-basic REPL breaks send-keys flows).
+
+## Windows / WSL
+
+- tmux is supported on macOS/Linux. On Windows, use WSL and install tmux inside WSL.
+- This skill is gated to `darwin`/`linux` and requires `tmux` on PATH.
+
+## Orchestrating Coding Agents (Codex, Claude Code)
+
+tmux excels at running multiple coding agents in parallel:
+
+```bash
+SOCKET="${TMPDIR:-/tmp}/codex-army.sock"
+
+# Create multiple sessions
+for i in 1 2 3 4 5; do
+  tmux -S "$SOCKET" new-session -d -s "agent-$i"
+done
+
+# Launch agents in different workdirs
+tmux -S "$SOCKET" send-keys -t agent-1 "cd /tmp/project1 && codex --yolo 'Fix bug X'" Enter
+tmux -S "$SOCKET" send-keys -t agent-2 "cd /tmp/project2 && codex --yolo 'Fix bug Y'" Enter
+
+# Poll for completion (check if prompt returned)
+for sess in agent-1 agent-2; do
+  if tmux -S "$SOCKET" capture-pane -p -t "$sess" -S -3 | grep -q "❯"; then
+    echo "$sess: DONE"
+  else
+    echo "$sess: Running..."
+  fi
+done
+
+# Get full output from completed session
+tmux -S "$SOCKET" capture-pane -p -t agent-1 -S -500
+```
+
+**Tips:**
+- Use separate git worktrees for parallel fixes (no branch conflicts)
+- `pnpm install` first before running codex in fresh clones
+- Check for shell prompt (`❯` or `$`) to detect completion
+- Codex needs `--yolo` or `--full-auto` for non-interactive fixes
+
+## Cleanup
+
+- Kill a session: `tmux -S "$SOCKET" kill-session -t "$SESSION"`.
+- Kill all sessions on a socket: `tmux -S "$SOCKET" list-sessions -F '#{session_name}' | xargs -r -n1 tmux -S "$SOCKET" kill-session -t`.
+- Remove everything on the private socket: `tmux -S "$SOCKET" kill-server`.
+
+## Helper: wait-for-text.sh
+
+`{baseDir}/scripts/wait-for-text.sh` polls a pane for a regex (or fixed string) with a timeout.
+
+```bash
+{baseDir}/scripts/wait-for-text.sh -t session:0.0 -p 'pattern' [-F] [-T 20] [-i 0.5] [-l 2000]
+```
+
+- `-t`/`--target` pane target (required)
+- `-p`/`--pattern` regex to match (required); add `-F` for fixed string
+- `-T` timeout seconds (integer, default 15)
+- `-i` poll interval seconds (default 0.5)
+- `-l` history lines to search (integer, default 1000)

skills/tmux/scripts/find-sessions.sh

@@ -0,0 +1,112 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'USAGE'
+Usage: find-sessions.sh [-L socket-name|-S socket-path|-A] [-q pattern]
+
+List tmux sessions on a socket (default tmux socket if none provided).
+
+Options:
+  -L, --socket       tmux socket name (passed to tmux -L)
+  -S, --socket-path  tmux socket path (passed to tmux -S)
+  -A, --all          scan all sockets under NANOBOT_TMUX_SOCKET_DIR
+  -q, --query        case-insensitive substring to filter session names
+  -h, --help         show this help
+USAGE
+}
+
+socket_name=""
+socket_path=""
+query=""
+scan_all=false
+socket_dir="${NANOBOT_TMUX_SOCKET_DIR:-${TMPDIR:-/tmp}/nanobot-tmux-sockets}"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    -L|--socket)      socket_name="${2-}"; shift 2 ;;
+    -S|--socket-path) socket_path="${2-}"; shift 2 ;;
+    -A|--all)         scan_all=true; shift ;;
+    -q|--query)       query="${2-}"; shift 2 ;;
+    -h|--help)        usage; exit 0 ;;
+    *) echo "Unknown option: $1" >&2; usage; exit 1 ;;
+  esac
+done
+
+if [[ "$scan_all" == true && ( -n "$socket_name" || -n "$socket_path" ) ]]; then
+  echo "Cannot combine --all with -L or -S" >&2
+  exit 1
+fi
+
+if [[ -n "$socket_name" && -n "$socket_path" ]]; then
+  echo "Use either -L or -S, not both" >&2
+  exit 1
+fi
+
+if ! command -v tmux >/dev/null 2>&1; then
+  echo "tmux not found in PATH" >&2
+  exit 1
+fi
+
+list_sessions() {
+  local label="$1"; shift
+  local tmux_cmd=(tmux "$@")
+
+  if ! sessions="$("${tmux_cmd[@]}" list-sessions -F '#{session_name}\t#{session_attached}\t#{session_created_string}' 2>/dev/null)"; then
+    echo "No tmux server found on $label" >&2
+    return 1
+  fi
+
+  if [[ -n "$query" ]]; then
+    sessions="$(printf '%s\n' "$sessions" | grep -i -- "$query" || true)"
+  fi
+
+  if [[ -z "$sessions" ]]; then
+    echo "No sessions found on $label"
+    return 0
+  fi
+
+  echo "Sessions on $label:"
+  printf '%s\n' "$sessions" | while IFS=$'\t' read -r name attached created; do
+    attached_label=$([[ "$attached" == "1" ]] && echo "attached" || echo "detached")
+    printf '  - %s (%s, started %s)\n' "$name" "$attached_label" "$created"
+  done
+}
+
+if [[ "$scan_all" == true ]]; then
+  if [[ ! -d "$socket_dir" ]]; then
+    echo "Socket directory not found: $socket_dir" >&2
+    exit 1
+  fi
+
+  shopt -s nullglob
+  sockets=("$socket_dir"/*)
+  shopt -u nullglob
+
+  if [[ "${#sockets[@]}" -eq 0 ]]; then
+    echo "No sockets found under $socket_dir" >&2
+    exit 1
+  fi
+
+  exit_code=0
+  for sock in "${sockets[@]}"; do
+    if [[ ! -S "$sock" ]]; then
+      continue
+    fi
+    list_sessions "socket path '$sock'" -S "$sock" || exit_code=$?
+  done
+  exit "$exit_code"
+fi
+
+tmux_cmd=(tmux)
+socket_label="default socket"
+
+if [[ -n "$socket_name" ]]; then
+  tmux_cmd+=(-L "$socket_name")
+  socket_label="socket name '$socket_name'"
+elif [[ -n "$socket_path" ]]; then
+  tmux_cmd+=(-S "$socket_path")
+  socket_label="socket path '$socket_path'"
+fi
+
+list_sessions "$socket_label" "${tmux_cmd[@]:1}"

skills/tmux/scripts/wait-for-text.sh

@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'USAGE'
+Usage: wait-for-text.sh -t target -p pattern [options]
+
+Poll a tmux pane for text and exit when found.
+
+Options:
+  -t, --target    tmux target (session:window.pane), required
+  -p, --pattern   regex pattern to look for, required
+  -F, --fixed     treat pattern as a fixed string (grep -F)
+  -T, --timeout   seconds to wait (integer, default: 15)
+  -i, --interval  poll interval in seconds (default: 0.5)
+  -l, --lines     number of history lines to inspect (integer, default: 1000)
+  -h, --help      show this help
+USAGE
+}
+
+target=""
+pattern=""
+grep_flag="-E"
+timeout=15
+interval=0.5
+lines=1000
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    -t|--target)   target="${2-}"; shift 2 ;;
+    -p|--pattern)  pattern="${2-}"; shift 2 ;;
+    -F|--fixed)    grep_flag="-F"; shift ;;
+    -T|--timeout)  timeout="${2-}"; shift 2 ;;
+    -i|--interval) interval="${2-}"; shift 2 ;;
+    -l|--lines)    lines="${2-}"; shift 2 ;;
+    -h|--help)     usage; exit 0 ;;
+    *) echo "Unknown option: $1" >&2; usage; exit 1 ;;
+  esac
+done
+
+if [[ -z "$target" || -z "$pattern" ]]; then
+  echo "target and pattern are required" >&2
+  usage
+  exit 1
+fi
+
+if ! [[ "$timeout" =~ ^[0-9]+$ ]]; then
+  echo "timeout must be an integer number of seconds" >&2
+  exit 1
+fi
+
+if ! [[ "$lines" =~ ^[0-9]+$ ]]; then
+  echo "lines must be an integer" >&2
+  exit 1
+fi
+
+if ! command -v tmux >/dev/null 2>&1; then
+  echo "tmux not found in PATH" >&2
+  exit 1
+fi
+
+# End time in epoch seconds (integer, good enough for polling)
+start_epoch=$(date +%s)
+deadline=$((start_epoch + timeout))
+
+while true; do
+  # -J joins wrapped lines, -S uses negative index to read last N lines
+  pane_text="$(tmux capture-pane -p -J -t "$target" -S "-${lines}" 2>/dev/null || true)"
+
+  if printf '%s\n' "$pane_text" | grep $grep_flag -- "$pattern" >/dev/null 2>&1; then
+    exit 0
+  fi
+
+  now=$(date +%s)
+  if (( now >= deadline )); then
+    echo "Timed out after ${timeout}s waiting for pattern: $pattern" >&2
+    echo "Last ${lines} lines from $target:" >&2
+    printf '%s\n' "$pane_text" >&2
+    exit 1
+  fi
+
+  sleep "$interval"
+done

skills/weather/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: weather
+description: Get current weather and forecasts (no API key required).
+homepage: https://wttr.in/:help
+metadata: {"nanobot":{"emoji":"🌤️","requires":{"bins":["curl"]}}}
+---
+
+# Weather
+
+Two free services, no API keys needed.
+
+## wttr.in (primary)
+
+Quick one-liner:
+```bash
+curl -s "wttr.in/London?format=3"
+# Output: London: ⛅️ +8°C
+```
+
+Compact format:
+```bash
+curl -s "wttr.in/London?format=%l:+%c+%t+%h+%w"
+# Output: London: ⛅️ +8°C 71% ↙5km/h
+```
+
+Full forecast:
+```bash
+curl -s "wttr.in/London?T"
+```
+
+Format codes: `%c` condition · `%t` temp · `%h` humidity · `%w` wind · `%l` location · `%m` moon
+
+Tips:
+- URL-encode spaces: `wttr.in/New+York`
+- Airport codes: `wttr.in/JFK`
+- Units: `?m` (metric) `?u` (USCS)
+- Today only: `?1` · Current only: `?0`
+- PNG: `curl -s "wttr.in/Berlin.png" -o /tmp/weather.png`
+
+## Open-Meteo (fallback, JSON)
+
+Free, no key, good for programmatic use:
+```bash
+curl -s "https://api.open-meteo.com/v1/forecast?latitude=51.5&longitude=-0.12&current_weather=true"
+```
+
+Find coordinates for a city, then query. Returns JSON with temp, windspeed, weathercode.
+
+Docs: https://open-meteo.com/en/docs