### Create .security.yml from Example

Source: https://github.com/sipeed/picoclaw/blob/main/docs/security/security_configuration.md

Copy the example security configuration file to your PicClaw directory.

```bash
cp security.example.yml ~/.picoclaw/.security.yml
```

--------------------------------

### Start Isolated tmux Session

Source: https://github.com/sipeed/picoclaw/blob/main/workspace/skills/tmux/SKILL.md

Quickstart for starting an isolated tmux session, attaching a Python REPL, and capturing pane output. Ensure the NANOBOT_TMUX_SOCKET_DIR environment variable is set or a default temporary directory will be used.

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

--------------------------------

### Docker Compose Setup for PicoClaw Launcher

Source: https://github.com/sipeed/picoclaw/blob/main/README.md

Set up and run the PicoClaw launcher using Docker Compose. This involves cloning the repo, initial setup, configuring API keys, and starting the service.

```bash
# 1. Clone this repo
git clone https://github.com/sipeed/picoclaw.git
cd picoclaw

# 2. First run — auto-generates docker/data/config.json then exits
#    (only triggers when both config.json and workspace/ are missing)
docker compose -f docker/docker-compose.yml --profile launcher up
# The container prints "First-run setup complete." and stops.

# 3. Set your API keys
vim docker/data/config.json

# 4. Start
docker compose -f docker/docker-compose.yml --profile launcher up -d
# Open http://localhost:18800
```

--------------------------------

### Quick Start Examples for Summarize CLI

Source: https://github.com/sipeed/picoclaw/blob/main/workspace/skills/summarize/SKILL.md

Demonstrates basic usage for summarizing a URL, a local PDF file, and a YouTube link. The `--model` flag specifies the AI model to use, and `--youtube auto` is used for YouTube links.

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

--------------------------------

### Suite Environment File Example

Source: https://github.com/sipeed/picoclaw/blob/main/integration/README.md

Example of a suite.env file, defining the command to be executed within the integration runner container.

```bash
TEST_COMMAND='go test ./pkg/mcp -run TestIntegration_RealConfiguredServer -v'
```

--------------------------------

### Full PicoClaw Configuration Example

Source: https://github.com/sipeed/picoclaw/blob/main/docs/guides/providers.md

A comprehensive configuration example demonstrating agents, session settings, multiple providers (OpenRouter, Groq), voice models, channel integrations (Telegram, Discord), and tool configurations (web search, cron).

```json
{
  "agents": {
    "defaults": {
      "model_name": "claude-opus-4-5"
    }
  },
  "session": {
    "dm_scope": "per-channel-peer"
  },
  "providers": {
    "openrouter": {
      "api_key": "sk-or-v1-xxx"
    },
    "groq": {
      "api_key": "gsk_xxx"
    }
  },
  "voice": {
    "model_name": "voice-gemini",
    "echo_transcription": false
  },
  "channel_list": {
    "telegram": {
      "enabled": true,
      "type": "telegram",
      "token": "123456:ABC...",
      "allow_from": ["123456789"]
    },
    "discord": {
      "enabled": true,
      "type": "discord",
      "token": "",
      "allow_from": [""]
    },
    "whatsapp": {
      "enabled": false,
      "type": "whatsapp",
      "bridge_url": "ws://localhost:3001",
      "use_native": false,
      "session_store_path": "",
      "allow_from": []
    },
    "feishu": {
      "enabled": false,
      "type": "feishu",
      "app_id": "cli_xxx",
      "app_secret": "xxx",
      "encrypt_key": "",
      "verification_token": "",
      "allow_from": []
    },
    "qq": {
      "enabled": false,
      "type": "qq",
      "app_id": "",
      "app_secret": "",
      "allow_from": []
    }
  },
  "tools": {
    "web": {
      "brave": {
        "enabled": false,
        "api_key": "BSA...",
        "max_results": 5
      },
      "duckduckgo": {
        "enabled": true,
        "max_results": 5
      },
      "perplexity": {
        "enabled": false,
        "api_key": "",
        "max_results": 5
      },
      "searxng": {
        "enabled": false,
        "base_url": "http://localhost:8888",
        "max_results": 5
      }
    },
    "cron": {
      "exec_timeout_minutes": 5
    }
  },
  "heartbeat": {
    "enabled": true,
    "interval": 30
  }
}
```

--------------------------------

### Run Built Launcher

Source: https://github.com/sipeed/picoclaw/blob/main/web/README.md

Examples of running the built launcher binary with different flags and configurations.

```bash
./build/picoclaw-launcher
```

```bash
./build/picoclaw-launcher -console
```

```bash
./build/picoclaw-launcher -public
```

```bash
./build/picoclaw-launcher -port 19999 /path/to/config.json
```

--------------------------------

### Example V3 Configuration (JSON)

Source: https://github.com/sipeed/picoclaw/blob/main/docs/reference/config-versioning.md

An example of a PicoClaw configuration file in JSON format, representing version 3. This structure includes a 'model_list' with 'model_name', 'model', and an example of a 'new_option' field that might be added during migration.

```json
{
  "version": 3,
  "model_list": [
    {
      "model_name": "gpt-5.4",
      "model": "openai/gpt-5.4",
      "new_option": true
    }
  ]
}
```

--------------------------------

### Clone Repository and Initial Docker Compose Setup

Source: https://github.com/sipeed/picoclaw/blob/main/docs/guides/docker.md

Clone the PicoClaw repository and perform the initial Docker Compose setup. This step automatically generates the configuration file if it's missing.

```bash
git clone https://github.com/sipeed/picoclaw.git
cd picoclaw

docker compose -f docker/docker-compose.yml --profile gateway up
```

--------------------------------

### Start Pico Echo Server for Testing

Source: https://github.com/sipeed/picoclaw/blob/main/examples/pico-echo-server/README.md

Start the echo server with a specific token for testing purposes.

```bash
go run ./examples/pico-echo-server -token mytoken
```

--------------------------------

### Example config.json

Source: https://github.com/sipeed/picoclaw/blob/main/docs/security/security_configuration.md

A sample configuration file for PicoClaw, defining agents, models, channels, and tools.

```json
{
  "version": 3,
  "agents": {
    "defaults": {
      "workspace": "~/picoclaw-workspace",
      "model_name": "gpt-5.4"
    }
  },
  "model_list": [
    {
      "model_name": "gpt-5.4",
      "model": "openai/gpt-5.4",
      "api_base": "https://api.openai.com/v1"
    },
    {
      "model_name": "claude-sonnet-4.6",
      "model": "anthropic/claude-sonnet-4.6",
      "api_base": "https://api.anthropic.com/v1"
    }
  ],
  "channel_list": {
    "telegram": {
      "enabled": true,
      "type": "telegram"
    }
  },
  "tools": {
    "web": {
      "brave": {
        "enabled": true
      }
    }
  }
}
```

--------------------------------

### Install Skills from ClawHub

Source: https://github.com/sipeed/picoclaw/blob/main/README.md

Use these commands to search for and install skills from the ClawHub registry. Ensure you have the ClawHub CLI installed.

```bash
picoclaw skills search "web scraping"
picoclaw skills install <skill-name>
```

--------------------------------

### Initialize PicClaw Onboarding

Source: https://github.com/sipeed/picoclaw/blob/main/README.md

Run this command to initialize the PicClaw setup, which creates the configuration file and workspace directory.

```bash
picoclaw onboard
```

--------------------------------

### Full PicoClaw Configuration Example

Source: https://github.com/sipeed/picoclaw/blob/main/docs/guides/configuration.md

A comprehensive configuration example demonstrating agent defaults, session settings, channel configurations, tool enablement, and heartbeat settings. Sensitive fields can be stored in a separate `.security.yml` file.

```json
{
  "agents": {
    "defaults": {
      "model_name": "claude-opus-4-5"
    }
  },
  "session": {
    "dm_scope": "per-channel-peer",
    "backlog_limit": 20
  },
  "channel_list": {
    "telegram": {
      "enabled": true,
      "type": "telegram",
      "allow_from": ["123456789"]
    }
  },
  "tools": {
    "web": {
      "duckduckgo": {
        "enabled": true,
        "max_results": 5
      }
    }
  },
  "heartbeat": {
    "enabled": true,
    "interval": 30
  }
}
```

--------------------------------

### QQ Quick Setup Configuration

Source: https://github.com/sipeed/picoclaw/blob/main/docs/guides/chat-apps.md

Configure PicoClaw for QQ integration using App ID and App Secret obtained from the QQ Open Platform quick setup.

```json
{
  "channel_list": {
    "qq": {
      "enabled": true,
      "type": "qq",

```

--------------------------------

### Configure Local vLLM Deployment

Source: https://github.com/sipeed/picoclaw/blob/main/README.md

Example configuration for connecting to a local vLLM deployment. Verify the model name and API base URL match your vLLM setup.

```json
{
  "model_list": [
    {
      "model_name": "local-vllm",
      "model": "vllm/your-model",
      "api_base": "http://localhost:8000/v1"
    }
  ]
}
```

--------------------------------

### Install Frontend Dependencies

Source: https://github.com/sipeed/picoclaw/blob/main/web/README.md

Installs frontend dependencies using pnpm. Ensure Node.js and pnpm are installed.

```bash
cd frontend
pnpm install
```

--------------------------------

### Setup MaixCAM I2C-5

Source: https://github.com/sipeed/picoclaw/blob/main/workspace/skills/hardware/references/board-pinout.md

This snippet outlines the setup for I2C-5 on the MaixCAM. It involves loading the `i2c-dev` module. Pin configuration is handled by a separate `pinmap` utility, and users should refer to the MaixCAM wiki for specific commands.

```bash
# Configure pins using pinmap utility
# (MaixCAM uses a pinmap tool instead of devmem)
# Refer to: https://wiki.sipeed.com/hardware/en/maixcam/gpio.html

# Load i2c-dev
modprobe i2c-dev

# Verify
ls /dev/i2c-*
```

--------------------------------

### Build PicoClaw from Source

Source: https://github.com/sipeed/picoclaw/blob/main/README.md

Build the core binary and Web UI launcher for PicoClaw. Ensure Go and Node.js are installed.

```bash
git clone https://github.com/sipeed/picoclaw.git

cd picoclaw
make deps

# Install frontend dependencies
(cd web/frontend && pnpm install --frozen-lockfile)

# Build the core binary for the current platform
make build

# Build the Web UI Launcher (required for WebUI mode)
make build-launcher

# Build core binaries for all Makefile-managed platforms
make build-all

# Build for Raspberry Pi Zero 2 W
# 32-bit: make build-linux-arm
# 64-bit: make build-linux-arm64
make build-pi-zero

# Build and install
make install
```

--------------------------------

### Install bubblewrap on Fedora

Source: https://github.com/sipeed/picoclaw/blob/main/pkg/isolation/README.md

Install the bubblewrap utility on Fedora systems using dnf.

```bash
dnf install bubblewrap
```

--------------------------------

### Install bubblewrap on Debian/Ubuntu

Source: https://github.com/sipeed/picoclaw/blob/main/pkg/isolation/README.md

Install the bubblewrap utility on Debian-based systems using apt.

```bash
apt install bubblewrap
```

--------------------------------

### Example: Add SQLite MCP Server

Source: https://github.com/sipeed/picoclaw/blob/main/docs/reference/mcp-cli.md

An example demonstrating how to add a 'sqlite' MCP server using the stdio transport. This command configures a server that runs via npx.

```bash
picoclaw mcp add sqlite npx -y @modelcontextprotocol/server-sqlite --db ./mydb.db
```

--------------------------------

### Start Pico Echo Server

Source: https://github.com/sipeed/picoclaw/blob/main/examples/pico-echo-server/README.md

Run the pico-echo-server with a specified address and authentication token.

```bash
go run ./examples/pico-echo-server -addr :9090 -token secret
```

--------------------------------

### Install bubblewrap on Alpine Linux

Source: https://github.com/sipeed/picoclaw/blob/main/pkg/isolation/README.md

Install the bubblewrap utility on Alpine Linux systems using apk.

```bash
apk add bubblewrap
```

--------------------------------

### Example Matrix Channel Configuration

Source: https://github.com/sipeed/picoclaw/blob/main/docs/channels/matrix/README.md

This JSON snippet shows a complete example of how to configure the Matrix channel in your `config.json` file. Ensure you replace placeholder values like access tokens and user IDs with your actual credentials.

```json
{
  "channel_list": {
    "matrix": {
      "enabled": true,
      "type": "matrix",
      "homeserver": "https://matrix.org",
      "user_id": "@your-bot:matrix.org",
      "access_token": "YOUR_MATRIX_ACCESS_TOKEN",
      "device_id": "",
      "join_on_invite": true,
      "allow_from": [],
      "group_trigger": {
        "mention_only": true
      },
      "placeholder": {
        "enabled": true,
        "text": ["Thinking...", "Processing...", "Typing..."]
      },
      "reasoning_channel_id": "",
      "message_format": "richtext",
      "crypto_database_path": "",
      "crypto_passphrase": "YOUR_MATRIX_CRYPTO_PICKLE_KEY"
    }
  }
}
```

--------------------------------

### Example Skill and MCP Commands

Source: https://github.com/sipeed/picoclaw/blob/main/docs/guides/configuration.md

These are example commands for interacting with skills and MCP servers within a chat channel. They demonstrate listing skills and MCP servers, showing server details, forcing skill usage, and asking side questions.

```text
/list skills
/list mcp
/show mcp github
/use git explain how to squash the last 3 commits
/btw remind me what we already decided about the deploy plan
/use italiapersonalfinance
dammi le ultime news
```

--------------------------------

### Example web_search Tool Call

Source: https://github.com/sipeed/picoclaw/blob/main/docs/reference/tools_configuration.md

Demonstrates how to call the web_search tool with a query, count, and time range.

```json
{
  "query": "ai agent news",
  "count": 10,
  "range": "w"
}
```

--------------------------------

### Example MCP Server Output

Source: https://github.com/sipeed/picoclaw/blob/main/docs/reference/mcp-cli.md

An example of the styled output from `picoclaw mcp show` on a wide terminal, detailing server information and tools.

```text
╭──────────────────────────────────────────────────────────╮
│ ⬡  filesystem                                            │
│                                                          │
│ Type        stdio                                        │
│ Target      npx -y @modelcontextprotocol/server-fs /tmp  │
│ Enabled     yes                                          │
│ Deferred    no                                           │
│                                                          │
│ Tools (3)                                                │
│                                                          │
│   read_file  [1/3]                                       │
│   Read the complete contents of a file from the disk     │
│                                                          │
│     path  <string>  required                             │
│       Path to the file to read                           │
│ ──────────────────────────────────────────────────────── │
│   ...                                                    │
╰──────────────────────────────────────────────────────────╯
```

--------------------------------

### Example: Add Deferred SQLite MCP Server

Source: https://github.com/sipeed/picoclaw/blob/main/docs/reference/mcp-cli.md

An example of adding the 'sqlite' MCP server with the `--deferred` flag. This flag influences how the server is loaded and discovered.

```bash
picoclaw mcp add --deferred sqlite npx -y @modelcontextprotocol/server-sqlite --db ./mydb.db
```

--------------------------------

### New Configuration Format

Source: https://github.com/sipeed/picoclaw/blob/main/docs/design/provider-refactoring.md

Example of the new configuration structure using 'model_list' and 'agents.defaults.model'.

```json
{
  "model_list": [
    {
      "model_name": "deepseek-chat",
      "model": "openai/deepseek-chat",
      "api_base": "https://api.deepseek.com/v1",
      "api_key": "sk-xxx"
    }
  ],
  "agents": {
    "defaults": {
      "model": "deepseek-chat"
    }
  }
}
```

--------------------------------

### Old Configuration Format

Source: https://github.com/sipeed/picoclaw/blob/main/docs/design/provider-refactoring.md

Example of the previous configuration structure using 'providers' and 'agents.defaults.provider'.

```json
{
  "providers": {
    "deepseek": {
      "api_keys": ["sk-xxx"],
      "api_base": "https://api.deepseek.com/v1"
    }
  },
  "agents": {
    "defaults": {
      "provider": "deepseek",
      "model": "deepseek-chat"
    }
  }
}
```

--------------------------------

### Setup MaixCAM2 I2C-6

Source: https://github.com/sipeed/picoclaw/blob/main/workspace/skills/hardware/references/board-pinout.md

This snippet shows the basic setup for I2C-6 on MaixCAM2. It involves loading the `i2c-dev` module. Specific pinmap commands for configuring pins A1 (SCL) and A0 (SDA) should be consulted from the MaixCAM2 documentation.

```bash
# Configure pinmap for I2C-6
# A1 → I2C6_SCL, A0 → I2C6_SDA
# Refer to MaixCAM2 documentation for pinmap commands

modprobe i2c-dev
ls /dev/i2c-*
```

--------------------------------

### V2 to V3 Migration Logic Example

Source: https://github.com/sipeed/picoclaw/blob/main/docs/reference/config-versioning.md

An example Go function demonstrating the core logic for migrating a configuration from V2 to V3. This snippet focuses on updating the version field and includes a placeholder for adding new fields with default values. This function should be part of your configuration loading mechanism.

```go
func (c *configV2) Migrate() (*Config, error) {
    migrated := &c.Config
    migrated.Version = 3

    // Add new field with default value if not set
    // ...

    return migrated, nil
}
```

--------------------------------

### Example JSON Configuration with Exposed Paths

Source: https://github.com/sipeed/picoclaw/blob/main/pkg/isolation/README.md

Example of enabling isolation and exposing specific host paths with read-only and read-write modes. 'source' is the host path, 'target' is the path within the isolated environment.

```json
{
  "isolation": {
    "enabled": true,
    "expose_paths": [
      {
        "source": "/opt/toolchains/go",
        "target": "/opt/toolchains/go",
        "mode": "ro"
      },
      {
        "source": "/data/shared-assets",
        "target": "/opt/picoclaw-instance-a/workspace/assets",
        "mode": "rw"
      }
    ]
  }
}
```

--------------------------------

### Tool Execution Feedback Example

Source: https://github.com/sipeed/picoclaw/blob/main/docs/channels/discord/README.md

This example shows the format for tool execution feedback messages sent by the bot, indicating which tool is being used and a brief description of its action.

```text
🔧 `web_search`
Checking the latest PicoClaw release notes before I answer.
```

--------------------------------

### Start PicoClaw Launcher Mode (Web Console)

Source: https://github.com/sipeed/picoclaw/blob/main/docs/guides/docker.md

Start PicoClaw in launcher mode using Docker Compose to access the web console. The web console provides a browser-based UI for configuration and chat.

```bash
docker compose -f docker/docker-compose.yml --profile launcher up -d
```

--------------------------------

### Start/Stop Lifecycle Management

Source: https://github.com/sipeed/picoclaw/blob/main/pkg/channels/README.md

Shows the updated Start and Stop methods using 'SetRunning' for atomic state management before and after initialization/cleanup.

```go
// New code: use SetRunning atomic operation
func (c *TelegramChannel) Start(ctx context.Context) error {
    // ... initialize bot, webhook, etc.
    c.SetRunning(true)    // Must be called after ready
    go bh.Start()
    return nil
}

func (c *TelegramChannel) Stop(ctx context.Context) error {
    c.SetRunning(false)   // Must be called before cleanup
    // ... stop bot handler, cancel context
    return nil
}
```

--------------------------------

### Agent Configuration Example

Source: https://github.com/sipeed/picoclaw/blob/main/docs/design/provider-refactoring.md

Defines the structure for configuring multiple agents with different models and system prompts.

```json
{
  "model_list": [...],

  "agents": {
    "defaults": {
      "model": "deepseek-chat"
    },
    "coder": {
      "model": "gpt-5.4",
      "system_prompt": "You are a coding assistant..."
    },
    "translator": {
      "model": "claude-sonnet-4.6"
    }
  }
}
```

--------------------------------

### PicoClaw Core CLI Commands

Source: https://github.com/sipeed/picoclaw/blob/main/workspace/skills/picoclaw-agent/SKILL.md

Basic commands for initializing, running the agent, starting the gateway, checking status, and migrating.

```bash
picoclaw onboard
picoclaw agent [-m MESSAGE] [--session KEY] [--model MODEL] [--debug]
picoclaw gateway [--debug] [--no-truncate] [--allow-empty] [--host HOST]
picoclaw status
picoclaw version
picoclaw migrate
```

--------------------------------

### Start WebUI Launcher

Source: https://github.com/sipeed/picoclaw/blob/main/README.md

Launch the PicoClaw WebUI Launcher from the command line. Access the interface at http://localhost:18800.

```bash
picoclaw-launcher
```

--------------------------------

### Monitor tmux Session

Source: https://github.com/sipeed/picoclaw/blob/main/workspace/skills/tmux/SKILL.md

Commands to monitor an active tmux session by attaching to it and capturing pane output. Use this after starting a session with the quickstart example.

```bash
To monitor:
  tmux -S "$SOCKET" attach -t "$SESSION"
  tmux -S "$SOCKET" capture-pane -p -J -t "$SESSION":0.0 -S -200
```

--------------------------------

### Explore Skills and MCP Servers

Source: https://github.com/sipeed/picoclaw/blob/main/workspace/skills/picoclaw-agent/SKILL.md

List installed skills and Model Context Protocol (MCP) servers.

```bash
# Explore installed skills and MCP servers
picoclaw skills list
picoclaw mcp list
```

--------------------------------

### Recommended Development Workflow

Source: https://github.com/sipeed/picoclaw/blob/main/web/README.md

Starts the Go backend, Vite frontend dev server, and builds the launcher binary for development. Run from the web/ directory.

```bash
make dev
```

--------------------------------

### Gateway Startup Sequence

Source: https://github.com/sipeed/picoclaw/blob/main/pkg/channels/README.md

Illustrates the complete bootstrap flow for the gateway, including creating core components, setting up the channel manager, and starting services.

```go
// 1. Create core components
msgBus     := bus.NewMessageBus()
provider   := providers.CreateProvider(cfg)
agentLoop  := agent.NewAgentLoop(cfg, msgBus, provider)

// 2. Create media store (with TTL cleanup)
mediaStore := media.NewFileMediaStoreWithCleanup(cleanerConfig)
mediaStore.Start()

// 3. Create Channel Manager (triggers initChannels → factory lookup → construct → inject MediaStore/PlaceholderRecorder/Owner)
channelManager := channels.NewManager(cfg, msgBus, mediaStore)

// 4. Inject references
agentLoop.SetChannelManager(channelManager)
agentLoop.SetMediaStore(mediaStore)

// 5. Configure shared HTTP server
channelManager.SetupHTTPServer(addr, healthServer)

// 6. Start
channelManager.StartAll(ctx)  // Start channels + workers + dispatchers + HTTP server
go agentLoop.Run(ctx)          // Start Agent message loop

// 7. Shutdown (signal-triggered)
cancel()                       // Cancel context
msgBus.Close()                 // Signal close + drain
channelManager.StopAll(shutdownCtx)  // Stop HTTP + workers + channels
mediaStore.Stop()              // Stop TTL cleanup
agentLoop.Stop()               // Stop Agent
```

--------------------------------

### Install and Run PicClaw via Termux on Android

Source: https://github.com/sipeed/picoclaw/blob/main/README.md

This snippet guides through installing Termux, downloading, extracting, and running the PicClaw binary within a chrooted environment. It's suitable for resource-constrained devices.

```bash
# Download the latest release
wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz
tar xzf picoclaw_Linux_arm64.tar.gz
pkg install proot
termux-chroot ./picoclaw onboard   # chroot provides a standard Linux filesystem layout
```

--------------------------------

### Extract Text with pdfplumber

Source: https://github.com/sipeed/picoclaw/blob/main/workspace/skills/skill-creator/SKILL.md

Demonstrates how to extract text from a PDF using the pdfplumber library. This is a quick start example for PDF processing.

```python
import pdfplumber

with pdfplumber.open("example.pdf") as pdf:
    for page in pdf.pages:
        text = page.extract_text()
        print(text)
```

--------------------------------

### Interact with PicClaw Agents

Source: https://github.com/sipeed/picoclaw/blob/main/README.md

Examples of how to use the PicClaw agent for a one-shot question or in an interactive chat mode, and how to start the gateway for chat app integration.

```bash
# One-shot question
picoclaw agent -m "What is 2+2?"

# Interactive mode
picoclaw agent

# Start gateway for chat app integration
picoclaw gateway
```

--------------------------------

### I2C and SPI Quick Start Commands

Source: https://github.com/sipeed/picoclaw/blob/main/workspace/skills/hardware/SKILL.md

These commands demonstrate the basic workflow for interacting with I2C and SPI devices. Ensure pinmux is configured and necessary modules are loaded before use.

```bash
# 1. Find available buses
i2c detect

# 2. Scan for connected devices
i2c scan  (bus: "1")

# 3. Read from a sensor (e.g. AHT20 temperature/humidity)
i2c read  (bus: "1", address: 0x38, register: 0xAC, length: 6)

# 4. SPI devices
spi list
spi read  (device: "2.0", length: 4)
```

--------------------------------

### Python Weather Plugin Example

Source: https://github.com/sipeed/picoclaw/blob/main/docs/architecture/hooks/plugin-tool-injection.md

This Python script defines a weather plugin with functions to get weather data and handle PicoClaw hooks. It simulates weather data and integrates with PicoClaw's 'before_llm' and 'before_tool' hooks to inject the weather query tool and process its calls.

```python
WEATHER_DATA = {
    "Beijing": {"temp": 15, "weather": "Sunny", "humidity": 45},
    "Shanghai": {"temp": 18, "weather": "Cloudy", "humidity": 60},
    "Guangzhou": {"temp": 25, "weather": "Sunny", "humidity": 70},
    "Shenzhen": {"temp": 26, "weather": "Cloudy", "humidity": 75},
}

def get_weather(city: str) -> dict:
    """Get weather data (simulated)"""
    data = WEATHER_DATA.get(city)
    if data:
        return {
            "for_llm": f"{city} weather: {data['weather']}, temperature {data['temp']}°C, humidity {data['humidity']}%",
            "for_user": "",
            "silent": False,
            "is_error": False,
        }
    return {
        "for_llm": f"Weather data not found for city {city}",
        "for_user": "",
        "silent": False,
        "is_error": True,
    }

def handle_hello(params: dict) -> dict:
    return {"ok": True, "name": "weather-plugin"}

def handle_before_llm(params: dict) -> dict:
    """Inject weather query tool definition"""
    tools = params.get("tools", [])

    # Add weather query tool
    tools.append({
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Query weather information for a specified city",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {
                        "type": "string",
                        "description": "City name, e.g.: Beijing, Shanghai, Guangzhou"
                    }
                },
                "required": ["city"]
            }
        }
    })

    return {
        "action": "modify",
        "request": {
            "model": params.get("model"),
            "messages": params.get("messages", []),
            "tools": tools,
            "options": params.get("options", {}),
        }
    }

def handle_before_tool(params: dict) -> dict:
    """Handle tool call, return result directly"""
    tool = params.get("tool", "")
    args = params.get("arguments", {})

    if tool == "get_weather":
        city = args.get("city", "")
        result = get_weather(city)

        # Use respond action to return result directly, skip ToolRegistry
        return {
            "action": "respond",
            "result": result,
        }

    # Other tools continue normal flow
    return {"action": "continue"}

def handle_request(method: str, params: dict) -> dict:
    if method == "hook.hello":
        return handle_hello(params)
    if method == "hook.before_llm":
        return handle_before_llm(params)
    if method == "hook.before_tool":
        return handle_before_tool(params)
    if method == "hook.after_llm":
        return {"action": "continue"}
    if method == "hook.after_tool":
        return {"action": "continue"}
    if method == "hook.approve_tool":
        return {"approved": True}
    raise KeyError(f"method not found: {method}")

def send_response(message_id: int, result: Any | None = None, error: str | None = None) -> None:
    payload: dict[str, Any] = {
        "jsonrpc": "2.0",
        "id": message_id,
    }
    if error is not None:
        payload["error"] = {"code": -32000, "message": error}
    else:
        payload["result"] = result if result is not None else {}

    sys.stdout.write(json.dumps(payload, ensure_ascii=True) + "\n")
    sys.stdout.flush()

def main() -> int:
    for raw_line in sys.stdin:
        line = raw_line.strip()
        if not line:
            continue

        try:
            message = json.loads(line)
        except json.JSONDecodeError:
            continue

        method = message.get("method")
        message_id = message.get("id", 0)
        params = message.get("params") or {}

        if not message_id:
            continue

        try:
            result = handle_request(str(method or ""), params)
            send_response(int(message_id), result=result)
        except KeyError as exc:
            send_response(int(message_id), error=str(exc))
        except Exception as exc:
            send_response(int(message_id), error=f"unexpected error: {exc}")

    return 0


if __name__ == "__main__":
    signal.signal(signal.SIGINT, lambda *_: raise SystemExit(0))
    signal.signal(signal.SIGTERM, lambda *_: raise SystemExit(0))
    raise SystemExit(main())
```

--------------------------------

### Factory Registration for New Channels

Source: https://github.com/sipeed/picoclaw/blob/main/pkg/channels/README.md

Example of creating an 'init.go' file for registering a new channel implementation, which is a required step for the factory pattern.

```go
// pkg/channels/telegram/init.go
package telegram

import (

```

--------------------------------

### Download, Initialize, and Test PicoClaw on Linux

Source: https://github.com/sipeed/picoclaw/blob/main/docs/guides/hardware-compatibility.md

This snippet shows the basic steps to download a PicoClaw build for your architecture, initialize it, and run a test command. Ensure you download the correct binary for your system's architecture.

```bash
# 1. Download for your architecture
wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz
tar xzf picoclaw_Linux_arm64.tar.gz

# 2. Initialize
./picoclaw onboard

# 3. Test
./picoclaw agent -m "Hello, what board am I running on?"
```

--------------------------------

### Initialize PicoClaw and Authenticate Provider

Source: https://github.com/sipeed/picoclaw/blob/main/workspace/skills/picoclaw-agent/SKILL.md

Quickly set up PicoClaw configuration and authenticate with a provider like OpenAI.

```bash
picoclaw onboard

picoclaw auth login --provider openai
```

--------------------------------

### Full Flow Example of Steering

Source: https://github.com/sipeed/picoclaw/blob/main/docs/architecture/steering.md

Illustrates the step-by-step process from an initial user request to an LLM response, including tool execution, user steering, and subsequent LLM re-evaluation.

```text
1. User: "search for info on X, write a file, and send me a message"

2. LLM responds with 3 tool calls: [web_search, write_file, message]

3. web_search is executed → result saved

4. [polling] → User called Steer("no, search for Y instead")

5. write_file is skipped → "Skipped due to queued user message."
   message is skipped    → "Skipped due to queued user message."

6. Message "search for Y instead" injected into context

7. LLM receives the full updated context and responds accordingly
```

--------------------------------

### Install bubblewrap on CentOS/RHEL

Source: https://github.com/sipeed/picoclaw/blob/main/pkg/isolation/README.md

Install the bubblewrap utility on CentOS or RHEL systems using yum.

```bash
yum install bubblewrap
```

--------------------------------

### Build Launcher with Custom Output Path

Source: https://github.com/sipeed/picoclaw/blob/main/web/README.md

Builds the launcher binary and allows specifying a custom output path. Run from the web/ directory.

```bash
make build OUTPUT=/tmp/picoclaw-launcher
```

--------------------------------

### Install bubblewrap on Arch Linux

Source: https://github.com/sipeed/picoclaw/blob/main/pkg/isolation/README.md

Install the bubblewrap utility on Arch Linux systems using pacman.

```bash
pacman -S bubblewrap
```

--------------------------------

### Create and Secure .security.yml

Source: https://github.com/sipeed/picoclaw/blob/main/docs/security/security_configuration.md

These commands show how to create the .security.yml file from an example, populate it with your actual credentials, and set restrictive file permissions for enhanced security.

```bash
cp security.example.yml ~/.picoclaw/.security.yml
```

```bash
chmod 600 ~/.picoclaw/.security.yml
```

--------------------------------

### Start PicoClaw Gateway in Detached Mode

Source: https://github.com/sipeed/picoclaw/blob/main/docs/guides/docker.md

Start the PicoClaw gateway service in detached mode after configuring API keys.

```bash
docker compose -f docker/docker-compose.yml --profile gateway up -d
```

--------------------------------

### Start PicoClaw Gateway

Source: https://github.com/sipeed/picoclaw/blob/main/docs/channels/mqtt/README.md

Initiate the PicoClaw gateway service. This command starts the PicoClaw application, enabling it to process messages through configured channels.

```bash
picoclaw gateway
```

--------------------------------

### Build Standalone Launcher Binary

Source: https://github.com/sipeed/picoclaw/blob/main/web/README.md

Builds the frontend into the Go backend and produces a standalone launcher binary. Run from the web/ directory.

```bash
make build
```

--------------------------------

### Restricted SubTurn Configuration Example

Source: https://github.com/sipeed/picoclaw/blob/main/docs/architecture/subturn.md

An example of configuring a SubTurn with a specific model and a limited set of tools, such as a read-only tool, to enhance security and focus.

```go
cfg := agent.SubTurnConfig{
    Model: "gpt-4o-mini",
    Tools: []tools.Tool{readOnlyTool}, // Only read-only access
    SystemPrompt: "Analyze the file structure...",
}
```

--------------------------------

### Dispatch Rule Example

Source: https://github.com/sipeed/picoclaw/blob/main/docs/architecture/routing-system.md

An example of dispatch rules configuration in JSON format, specifying agent assignments based on channel, chat, and mention status.

```json
{
  "agents": {
    "dispatch": {
      "rules": [
        {
          "name": "support-group",
          "agent": "support",
          "when": {
            "channel": "telegram",
            "chat": "group:-100123"
          }
        },
        {
          "name": "slack-mentions",
          "agent": "support",
          "when": {
            "channel": "slack",
            "space": "workspace:t001",
            "mentioned": true
          }
        }
      ]
    }
  }
}
```

--------------------------------

### Start Matrix Channel

Source: https://github.com/sipeed/picoclaw/blob/main/pkg/channels/README.md

Starts the Matrix channel by setting its running state and initializing context for cancellation. This method should be called to begin channel operations.

```go
func (c *MatrixChannel) Start(ctx context.Context) error {
    c.ctx, c.cancel = context.WithCancel(ctx)

    // 1. Initialize Matrix client
    // 2. Start listening for messages
    // 3. Mark as running
    c.SetRunning(true)

    logger.InfoC("matrix", "Matrix channel started")
    return nil
}
```

--------------------------------

### PicoClaw CLI Reference - Skills Commands

Source: https://github.com/sipeed/picoclaw/blob/main/README.md

Reference for PicoClaw CLI commands related to managing installed skills, including listing and installing new skills.

```bash
picoclaw skills list
```

```bash
picoclaw skills install
```

--------------------------------

### Pull and Start Docker Compose Services

Source: https://github.com/sipeed/picoclaw/blob/main/README.md

Use these commands to pull the latest Docker images and start the services defined in the docker-compose.yml file in detached mode.

```bash
docker compose -f docker/docker-compose.yml pull
docker compose -f docker/docker-compose.yml --profile launcher up -d
```

--------------------------------

### Customized PicoClaw Setup

Source: https://github.com/sipeed/picoclaw/blob/main/docs/guides/configuration.md

Combine PICOCLAW_HOME and PICOCLAW_CONFIG environment variables for a fully customized PicoClaw setup, specifying both data directory and configuration file locations.

```bash
PICOCLAW_HOME=/srv/picoclaw PICOCLAW_CONFIG=/srv/picoclaw/main.json picoclaw gateway
```

--------------------------------

### Provider and Model Resolution Examples

Source: https://github.com/sipeed/picoclaw/blob/main/docs/guides/providers.md

Illustrates how PicoClaw resolves provider and runtime model IDs based on configuration. Examples cover cases where 'provider' is set and omitted.

```json
"provider": "openai", "model": "gpt-5.4"
```

```json
"model": "openai/gpt-5.4"
```

```json
"provider": "openrouter", "model": "openai/gpt-5.4"
```

```json
"model": "openrouter/openai/gpt-5.4"
```

--------------------------------

### Constructor with Functional Options

Source: https://github.com/sipeed/picoclaw/blob/main/pkg/channels/README.md

Demonstrates the new constructor pattern using 'NewBaseChannel' and functional options for configuration, replacing direct field assignment.

```go
// Old code: direct assignment
func NewTelegramChannel(cfg *config.Config, bus *bus.MessageBus) (*TelegramChannel, error) {
    return &TelegramChannel{
        bus:       bus,
        config:    cfg,
        allowList: cfg.Channels.Telegram.AllowFrom,
        // ...
    },
}

// New code: use NewBaseChannel + functional options
func NewTelegramChannel(cfg *config.Config, bus *bus.MessageBus) (*TelegramChannel, error) {
    base := channels.NewBaseChannel(
        "telegram",                    // Name
        cfg.Channels.Telegram,         // Raw config (any type)
        bus,                           // Message bus
        cfg.Channels.Telegram.AllowFrom, // Allow list
        channels.WithMaxMessageLength(4096),                     // Platform message length limit
        channels.WithGroupTrigger(cfg.Channels.Telegram.GroupTrigger), // Group trigger config
        channels.WithReasoningChannelID(cfg.Channels.Telegram.ReasoningChannelID), // Reasoning chain routing
    )
    return &TelegramChannel{
        BaseChannel: base,
        bot:         bot,
        config:      cfg,
    },
}
```

--------------------------------

### Example Commit Message for Squash Merge

Source: https://github.com/sipeed/picoclaw/blob/main/CONTRIBUTING.md

This is an example of how a commit message appears after a squash merge, typically including the type of change and the associated pull request number.

```git
feat: Add Ollama provider support (#491)
```

--------------------------------

### Manager Lifecycle Management: StartAll

Source: https://github.com/sipeed/picoclaw/blob/main/pkg/channels/README.md

Details the steps involved in starting all registered channels and their associated workers and services within the manager.

```text
StartAll:
  1. Iterate registered channels → channel.Start(ctx)
  2. Create channelWorker for each successfully started channel
  3. Start goroutines:
     - runWorker (per-channel outbound text)
     - runMediaWorker (per-channel outbound media)
     - dispatchOutbound (route from bus to worker queues)
     - dispatchOutboundMedia (route from bus to media worker queues)
     - runTTLJanitor (every 10s clean up expired typing/reaction/placeholder)
  4. Start shared HTTP server (if configured)
```

--------------------------------

### Clone Repository and Setup Remotes

Source: https://github.com/sipeed/picoclaw/blob/main/CONTRIBUTING.md

Clone your fork of the PicoClaw repository and add the upstream remote for tracking the main project.

```bash
git clone https://github.com/<your-username>/picoclaw.git
cd picoclaw
git remote add upstream https://github.com/sipeed/picoclaw.git
```

--------------------------------

### Telegram Built-in Command Examples

Source: https://github.com/sipeed/picoclaw/blob/main/docs/channels/telegram/README.md

Examples of using built-in commands for listing skills, MCP servers, showing server details, and using skills for specific requests or future messages.

```text
/list skills
/list mcp
/show mcp github
/use git explain how to squash the last 3 commits
/use git
explain how to squash the last 3 commits
```

--------------------------------

### Make Build Frontend Details

Source: https://github.com/sipeed/picoclaw/blob/main/web/README.md

Details the actions of the `make build-frontend` target, including dependency installation and building the embeddable frontend.

```bash
make build-frontend
```