xiao

name

xiao

description

Control a Xiaomi Robot Vacuum X20+ (model xiaomi.vacuum.c102gl) through the `xiao` CLI. Use this skill whenever the user mentions anything vacuum-related: robot vacuum, Xiaomi, Roborock, cleaning the house, mopping, sweeping, dock, base station, consumables (brush, filter, mop pad), rooms, map, zones, DND mode, fan speed, vacuum status, battery, cleaning schedule. Also trigger on Spanish equivalents (aspiradora, limpiar, trapear, cargar, habitaciones, cepillo, filtro, base, programar limpieza) and casual phrasings (limpia la casa, pon la aspiradora, qué batería tiene, mándala al dock). When in doubt, trigger — the CLI handles all vacuum ops.

xiao — Xiaomi Vacuum CLI Skill

The xiao CLI controls a Xiaomi Robot Vacuum X20+ via Xiaomi Cloud. Full reference lives in AGENTS.md at the repo root — read that first for canonical commands, intent mapping, and error recovery.

Prerequisites

Before any command will succeed:

1. pip install xiao-cli && playwright install chromium (once per machine).
2. xiao setup cloud completed — produces config.toml.
3. Chromium on port 18800 with an active account.xiaomi.com session:

   chromium --remote-debugging-port=18800 --user-data-dir=~/.xiao-chromium
   

Workflow for any user request

1. Parse intent. Check the "Intent mapping" table in AGENTS.md.
2. Resolve room IDs with xiao map rooms before any xiao clean -r <id>. Never guess. IDs are per-vacuum and regenerate when the Xiaomi Home app re-maps the house.
3. Run the command. Prefer --json for status-type commands so you can parse deterministically:

   xiao status --json
   xiao consumables --json
   

4. On error, apply the recovery protocol in AGENTS.md#error-recovery before asking the user:
   • Exit 77 or stderr contains token/401 → retry once; if still bad, xiao cloud-login and retry.
   • Exit 2 or stderr says "Cloud mode enabled but not configured" → guide user through xiao setup cloud.
   • Cannot connect to browser CDP on port 18800 → launch the Chromium instance described above and have the user log in once.
   • State 21 / "WashingMopPause" → user must refill clean water / empty dirty water, then xiao start.

Exit codes (agent-meaningful)

Code	Meaning	Action
0	Success	Continue
2	Not configured	Run xiao setup cloud
77	Cloud auth failed	Run xiao cloud-login
Other non-zero	Generic failure	Parse stderr / ask user

Hard rules

• Never print or commit the contents of config.toml — it holds the user's Xiaomi password hash and service tokens.
• Never call xiao raw unless the user explicitly asks. It's an unchecked escape hatch into MIoT that can brick settings.
• Always verify room IDs with xiao map rooms before using them in a clean -r call.
• xiao start always triggers a mop wash first. Warn the user if they asked for sweep-only; there's no flag to skip the wash.