dotty-stackchan: Instructions file for Claude Code

Dotty

AI transparency (binding on agents)

This is a human-focused project, made by humans, for humans, that is openly AI-assisted. If you are an AI agent working here, the project's AI policy (AI_TRANSPARENCY.md) is binding on you, not just descriptive. The core rule: anything you author is acknowledged as such. In practice:

• Keep the Co-Authored-By: trailer naming your model on every commit you help write (the global commit/PR conventions already require this — honour them, never strip them).
• Note AI assistance in PR bodies you draft, and mark substantial AI-drafted docs as such.
• Never present agent work as unaided human work, and never remove existing attribution. Leave the human-accountability chain intact: you propose, a human reviews and is accountable for what lands. Don't merge to main unattended.

What This Is

Your self-hosted StackChan robot assistant. A fully self-hosted voice stack for the M5Stack StackChan desktop robot. The default persona is "Dotty" (customizable via make setup). Voice I/O routes through a self-hosted xiaozhi-esp32-server; the brain is a pi coding agent running in the dotty-pi container. No cloud AI services — fully self-hosted except for the LLM call (replaceable with local Ollama).

Architecture

The voice path runs through a single LLM provider — PiVoiceLLM, selected via selected_module.LLM in data/.config.yaml. One alternate provider ships as a fallback (OpenAICompat). (The former Tier1Slim two-tier provider was removed in the 2026-05-29 alignment pass — its tool escalation depended on the retired ZeroClaw bridge.)

                 StackChan hardware → configured persona
                   │  ESP32-S3, xiaozhi firmware (pinned BrettKinny/StackChan@dotty fork)
                   │  WiFi / WebSocket (Xiaozhi protocol)
                   ▼
                 xiaozhi-esp32-server (Docker)
                   ├─ ASR: FunASR SenseVoiceSmall / WhisperLocal (local)
                   ├─ TTS: LocalPiper; EdgeTTS / StreamingEdgeTTS alternates
                   └─ LLM: PiVoiceLLM
                        │  PiClient → `docker exec -i dotty-pi pi --mode rpc …`  (JSONL over stdio)
                        ▼
                 dotty-pi container — the pi coding agent (the brain)
                   ├─ outer loop: qwen3.5:4b on llama-swap
                   └─ dotty-pi-ext extension → 7 voice tools:
                        memory_lookup · remember · recall_person · remember_person · think_hard (→ qwen3.6:27b-think) · take_photo · play_song
                   only TTS-bound text streams back to xiaozhi-server

  Perception + ambient behaviour:  firmware `event` frames → xiaozhi relay → dotty-behaviour (FastAPI, :8090)
  Admin dashboard:                 bridge.py (FastAPI, :8081, served at /ui)