Picobot

The AI agent that runs anywhere — even on a $5 VPS.

---

Love the idea of open-source AI agents like OpenClaw but tired of the bloat? Picobot gives you the same power — persistent memory, tool calling, skills, Telegram and Discord integration — in a single ~9MB binary that boots in milliseconds.

No Python. No Node. No 500MB container. Just one Go binary and a config file.

Why Picobot?

	Picobot	Typical Agent Frameworks
Binary size	~9MB	200MB+ (Python + deps)
Docker image	~29MB (Alpine)	500MB–1GB+
Cold start	Instant	5–30 seconds
RAM usage	~10MB idle	200MB–1GB
Dependencies	Zero (single binary)	Python, pip, venv, Node…

Picobot runs happily on a $5/mo VPS, a Raspberry Pi, or even an old Android phone via Termux.

Quick Start — 30 seconds

Docker Run

docker run -d --name picobot \
  -e OPENAI_API_KEY="your-key" \
  -e OPENAI_API_BASE="https://openrouter.ai/api/v1" \
  -e PICOBOT_MODEL="openrouter/free" \
  -e PICOBOT_MAX_TOKENS=8192 \
  -e PICOBOT_MAX_TOOL_ITERATIONS=100 \
  -e TELEGRAM_BOT_TOKEN="your-telegram-token" \
  -v ./picobot-data:/home/picobot/.picobot \
  --restart unless-stopped \
  louisho5/picobot:latest

All config, memory, and skills are persisted in ./picobot-data on your host.

Docker Compose

Create a docker-compose.yml:

services:
  picobot:
    image: louisho5/picobot:latest
    container_name: picobot
    restart: unless-stopped
    environment:
      - OPENAI_API_KEY=your-key
      - OPENAI_API_BASE=https://openrouter.ai/api/v1
      - PICOBOT_MODEL=openrouter/free
      - PICOBOT_MAX_TOKENS=8192
      - PICOBOT_MAX_TOOL_ITERATIONS=100
      - TELEGRAM_BOT_TOKEN=your-telegram-token
      - TELEGRAM_ALLOW_FROM=your-user-id
    volumes:
      - ./picobot-data:/home/picobot/.picobot

Then run:

docker compose up -d

From Source

go build -o picobot ./cmd/picobot
./picobot onboard                     # creates ~/.picobot config + workspace
./picobot agent -m "Hello!"           # single-shot query
./picobot channels login              # login to channels (Telegram, Discord, Slack, WhatsApp)
./picobot gateway                     # long-running mode with Telegram

Architecture

Actually the logic is simple and straightforward. Messages flow through a Chat Hub (inbound/outbound channels) into the Agent Loop, which builds context from memory/sessions/skills, calls the LLM via OpenAI-compatible API, and executes tools (filesystem, exec, web, etc.) before sending replies back through the hub.

Notes: Channel refers to communication channels (e.g., Telegram, Discord, Slack, WhatsApp, etc.).

Features

16 Built-in Tools + MCP Extensions

The agent can take real actions — not just chat:

Tool	What it does
filesystem	Read, write, list files
exec	Run shell commands
web	Fetch web pages and APIs
web_search	Search the web via DuckDuckGo
message	Send messages to channels
spawn	Launch background subagents
cron	Schedule recurring tasks
write_memory	Persist information across sessions
list_memory	List all memory files
read_memory	Read a specific memory file
edit_memory	Find and replace text in a memory file
delete_memory	Delete a daily memory file
create_skill	Create reusable skill packages
list_skills	List available skills
read_skill	Read a skill's content
delete_skill	Remove a skill

MCP Servers: extend the agent with any MCP-compliant server — npx, uvx, a plain binary, docker run, or an HTTP endpoint. Tools are registered automatically as mcp_{server}_{tool} at startup. See CONFIG.md.

Persistent Memory

Picobot remembers things between conversations:

• Daily notes — auto-organized by date
• Long-term memory — survives restarts
• Ranked recall — retrieves the most relevant memories for each query

picobot memory recent --days 7     # what happened this week?
picobot memory rank -q "meeting"   # find relevant memories

Skills System

Teach your agent new tricks. Skills are modular knowledge packages that extend the agent:

You: "Create a skill for checking weather using curl wttr.in"
Agent: Created skill "weather" — I'll use it from now on.

Skills are just markdown files in ~/.picobot/workspace/skills/. Create them via the agent or manually.

Telegram Integration

Chat with your agent from your phone. Set up in 2 minutes:

1. Message @BotFather — /newbot — copy the token
2. Add the token to config or pass as TELEGRAM_BOT_TOKEN env var
3. Start the communication gateway

See HOW_TO_START.md for a detailed BotFather walkthrough.

Discord Integration

Connect your agent to Discord servers:

1. Go to Discord Developer Portal
2. Create a new application and bot
3. Enable Message Content Intent in Bot settings
4. Copy the bot token
5. Add to config under channels.discord in your config.json

The bot will respond when mentioned in servers, or to all messages in DMs.

See HOW_TO_START.md for a detailed Discord Bot walkthrough.

Slack Integration

Connect your agent to Slack via Socket Mode:

1. Go to Slack API Apps and create an app
2. Enable Socket Mode and generate an App-Level Token (xapp-...)
3. Add Bot Token scopes: app_mentions:read, chat:write, channels:history, groups:history, im:history, mpim:history, files:read
4. Enable Event Subscriptions and subscribe to: app_mention, message.im
5. Install the app to your workspace and copy the Bot Token (xoxb-...)
6. Add to config under channels.slack in your config.json

The bot responds when mentioned in channels, and responds to all DMs from allowed users (DMs ignore the channel allowlist).

Heartbeat

A configurable periodic check (default: 60s) that reads HEARTBEAT.md for scheduled tasks — like a personal cron with natural language.

Configuration

Picobot uses a single JSON config at ~/.picobot/config.json:

{
  "agents": {
    "defaults": {
      "model": "google/gemini-2.5-flash",
      "maxTokens": 8192,
      "temperature": 0.7,
      "maxToolIterations": 200
    }
  },
  "providers": {
    "openai": {
      "apiKey": "sk-or-v1-YOUR_KEY",
      "apiBase": "https://openrouter.ai/api/v1"
    }
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "YOUR_TELEGRAM_BOT_TOKEN",
      "allowFrom": ["YOUR_TELEGRAM_USER_ID"]
    },
    "discord": {
      "enabled": true,
      "token": "YOUR_DISCORD_BOT_TOKEN",
      "allowFrom": ["YOUR_DISCORD_USER_ID"]
    }
  }
}

Supports any OpenAI-compatible API (OpenAI, OpenRouter, Ollama, etc.). See CONFIG.md for more details.

CLI Reference

picobot version                        # print version
picobot onboard                        # create config + workspace
picobot agent -m "..."                 # one-shot query
picobot agent -M model -m "..."        # query with specific model
picobot channels login                 # login to channels (Telegram, Discord, Slack, WhatsApp)
picobot gateway                        # start long-running agent
picobot memory read today|long         # read memory
picobot memory append today|long -c "" # append to memory
picobot memory write long -c ""        # overwrite long-term memory
picobot memory recent --days N         # recent N days
picobot memory rank -q "query"         # semantic memory search

Run on Minimal Hardware

Picobot was designed for constrained environments:

# Raspberry Pi / ARM device
GOARCH=arm64 CGO_ENABLED=0 go build -ldflags="-s -w" -o picobot ./cmd/picobot

# Old x86 VPS
GOARCH=amd64 CGO_ENABLED=0 go build -ldflags="-s -w" -o picobot ./cmd/picobot

Works on any Linux with 256MB RAM. No runtime dependencies. Just copy the binary and run.

Tech Stack

Layer	Technology
Language	Go 1.26+
CLI framework	Cobra
LLM providers	OpenAI-compatible API (OpenAI, OpenRouter, Ollama, etc.)
Telegram	Raw Bot API
Discord	discordgo library
WhatsApp	whatsmeow and modernc.org/sqlite
Container	Alpine Linux 3.20 (multi-stage Docker build)

Picobot is written 100% in pure Go, without any CGO dependencies. All required libraries and assets are statically embedded into the final binary. This design ensures zero external runtime dependencies, fast cold start times, and full portability across all platforms supported by Go.

Project Structure

cmd/picobot/          CLI entry point
embeds/               Embedded assets (sample skills)
internal/
  agent/              Agent loop, context, tools, skills
  chat/               Chat message hub
  channels/           Telegram, Discord, Slack, WhatsApp
  config/             Config schema, loader, onboarding
  cron/               Cron scheduler
  heartbeat/          Periodic task checker
  memory/             Memory read/write/rank
  providers/          OpenAI-compatible provider
  session/            Session manager
docker/               Dockerfile, compose, entrypoint

Roadmap

Task	Status
Add Telegram support	✔️ Completed
Add Discord support	✔️ Completed
Add Slack support	✔️ Completed
Add WhatsApp support	✔️ Completed
AI agent with skill creation capability	✔️ Completed
Integrate with MCP Servers	✔️ Completed
Integrate useful default skills	🔄 In Progress
Add more tools (file processing, etc.)	🔄 In Progress

Want to contribute? Open an issue or PR with your ideas!

Docs

• HOW_TO_START.md — step-by-step getting started guide
• CONFIG.md — full configuration reference
• DEVELOPMENT.md — development, testing, and Docker publishing
• docker/README.md — Docker deployment guide

License

MIT — use it however you want.