Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/chamilonster/Piumy/llms.txt

Use this file to discover all available pages before exploring further.

This guide follows Contract #001 — the zero-risk PC demo path. The Go core writes a status.json file describing the board’s current mood; the Python file display adapter reads it and renders the kaomoji face to display.png. No WhatsApp number, no ARM board, no physical hardware of any kind is required. It’s the fastest way to see Piumy’s face engine working and to verify that your environment can build and run the stack.

​
Prerequisites

1

Clone the repository

git clone https://github.com/chamilonster/Piumy.git
cd Piumy
2

Write a mood to status.json

The state subcommand writes status.json with the mood you specify. This is the same file the display adapter and the dashboard read — the core’s single source of truth for what the board is doing right now.
cd core
go run . state responding
You should see output like:
status.json written to status.json (mood=responding)
Valid moods are: idle zero new_msg few swamped thinking working responding ai_online vip sleeping alert error qr
3

Render the face

Switch to the file display adapter, install its dependencies, and run the renderer. It reads status.json and outputs display.png — a 250×122 px 1-bit image, the same dimensions as the e-paper panel.
cd ../adapters/display/file
pip install -r requirements.txt
python render.py
Open display.png to see the kaomoji face for the responding mood. Every mood produces a distinct face with eyes, expression, and context-aware detail.
4

Try other moods

Go back to the core directory and try different moods to see how the face changes:
cd ../../..
cd core

go run . state thinking
cd ../adapters/display/file && python render.py

cd ../../..
cd core
go run . state swamped
cd ../adapters/display/file && python render.py

cd ../../..
cd core
go run . state ai_online
cd ../adapters/display/file && python render.py
The eye engine rotates through three eye types and twelve gaze directions — each render may show a slightly different gaze even for the same mood.
5

Seed demo data (optional)

The seed subcommand inserts two demo chats into the SQLite store so you can explore the REST API without a real WhatsApp connection.
cd core
go run . seed
Output:
seed OK at pimywa.db
You can then query the REST API (once serve is running in the next step) with curl http://localhost:8080/api/chats to see the demo data.
6

Start serve mode

The serve subcommand starts the full switchboard: MCP server on :8081, REST API on :8080, and the web dashboard on :80. Setting PIMYWA_GATEWAY=none tells the core to skip the WhatsApp connection — everything else starts normally.
cd core
PIMYWA_GATEWAY=none go run . serve
You should see:
Piumy REST API on :8080
Piumy dashboard on :80 (user=admin)
Piumy switchboard — MCP (streamable HTTP) on :8081 · db=pimywa.db
Piumy gateway: none (no WhatsApp connection; start via dashboard)
Open http://localhost in your browser to reach the dashboard. The MCP server at http://localhost:8081/mcp is ready to accept connections from an MCP client, but will reject all requests until you configure a bearer token — see Connecting the MCP agent.
The MCP endpoint is fail-closed: every request is rejected until PIMYWA_MCP_KEY is set. Run go run . auth setup to generate a token, or pass PIMYWA_MCP_KEY=dev-token on the command line for local testing only.

​
What’s next

Install on Raspberry Pi

Deploy Piumy on a Raspberry Pi Zero 2 W with the e-paper display and CW2015 battery gauge.

Connect WhatsApp

Link a dedicated WhatsApp number by scanning the QR code on the e-paper or the dashboard.

Configure MCP Auth

Generate a bearer token and wire your MCP client (Claude Code / OpenCode) to the board.

MCP Reference

Browse every MCP tool the agent can call: list_chats, get_messages, send_message, and more.

Build docs developers (and LLMs) love

Get started for freeTalk to us