Tamagooshi: how to use

Components

Broadly there are 3 main components:

stickFirmware on the M5Stick. PlatformIO envs: m5sticks3, m5stickc-plus, m5stickc-plus-se. Flash over USB. hubhub/backend process, hub/console UI. Link over BLE or MQTT (Not recommended). brandbrands/<id>/config.yaml. Selected by TAMA_BRAND.→

System overview

Tooling

Install once before local firmware build and hub.

repoClone. Fork recommended for custom branding. Commands below run from the repo root. platformiopip install platformio. Builds and flashes firmware/. pythonPython 3.13+. Create and activate a .venv before hub install. hubpip install -e hub/backend. Optional extras: [voice,claude,cursor]. boardM5StickC Plus, Plus SE, or StickS3 (recommended). USB data cable (not charge-only).

git clone https://github.com/addu390/tamagooshi.git  # or fork first, then clone your fork
cd tamagooshi

python3 -m venv .venv                                # create .venv
source .venv/bin/activate                            # activate it
pip install platformio                               # firmware builds
pip install -e "hub/backend[voice,claude,cursor]"    # hub (drop extras you do not need)

Build & flash

Compile a brand and flash the stick over USB.

brandTAMA_BRAND selects brands/<id>/config.yaml. Default gooshi. Prebuild writes headers into firmware/.gen/current. envm5sticks3 (recommended), m5stickc-plus, or m5stickc-plus-se. uploadFrom firmware/: pio run -e <env> -t upload. Drop -t upload to compile only. simOptional. make sim TAMA_BRAND=<id> runs the same UI on the desktop first.

Custom brand:

Set brand.id to match the folder. Use gooshi or shapey as reference.

mkdir brands/<id>
cp brands/template.yaml brands/<id>/config.yaml

config builderinteractive form that outputs config.yaml→ config referencefield docs and examples for each section→

cd firmware
TAMA_BRAND=<id> pio run -e m5sticks3 -t upload  # or -e m5stickc-plus / m5stickc-plus-se
pio device monitor                              # optional serial log

Run hub

Start the hub after flash. Match the brand on the stick.

brandSame TAMA_BRAND as the flash. Default gooshi. startmake hub from the repo root. Pairs over BLE. consolehttp://localhost:8000. Change with TAMA_HUB_PORT.

export CURSOR_API_KEY=...                    # optional, set env variables before start
make hub TAMA_BRAND=<id>                     # BLE. Console at http://localhost:8000
# or prefix envs on that line, e.g. TAMA_HUB_PORT=9090 make hub ...

environment TAMA_BRANDBrand the hub runs. Must match the stick. Default gooshi. TAMA_TRANSPORTLink channel. make hub sets ble:gatt. Use wifi:mqtt for MQTT. TAMA_HUB_PORTConsole port. Default 8000. TAMA_BROKERMQTT broker. Default localhost:1883. TAMA_DEVICE_IDDevice id for MQTT routing. DATADOG_API_KEYWith DATADOG_APP_KEY for a Datadog source. POSTHOG_API_KEYPersonal API key for a PostHog source. CURSOR_API_KEYRequired by the Cursor voice agent. Claude uses the local claude CLI login. TAMA_AGENT_CWDWorking directory for voice agents. TAMA_CURSOR_MODELCursor model override. TAMA_CLAUDE_MODEL for Claude.

Docker

Broker plus hub on any OS. Console at the same URL. Use TAMA_PORT if 8000 is taken.

make up
TAMA_PORT=9090 make up

Controls

M5Stick buttons map to intents.

Power clickStart Power double clickOff A clickSelect / confirm B clickNext / cycle A holdHome B holdBack

Simulator keys

Enter / SpaceSelect Right / DownNext Left / UpPrev BackspaceBack HHome

Bluetooth

Pair the stick with the hub over BLE. Metrics and agents use this link.

pair

host Turn Bluetooth on in the OS.
stick Settings → Connect → Bluetooth. Set Power to ON.
hub Scan for devices. Pick the stick name (<brand>-XXXX). Connect.
stick Passkey shows on the stick. Confirm it in the OS pairing prompt.

clean slate

hub Forget device. Disconnect if it still shows linked.
host Forget or remove the stick in OS Bluetooth settings.
stick On the Bluetooth screen, FORGET if it still shows paired.
stick Power OFF, then Power ON.
Repeat the pair steps from the top.

HID

Some apps present the stick to the host as a gamepad, keyboard, mouse, or media keys. One HID mode is active at a time. Those roles cannot coexist.

Default is gamepad. Apps that need another mode stay locked on the stick until the mode changes. Set the mode in the hub, then reboot, forget the device on the host, and re-pair so the new descriptors apply.

HID mode

On macOS, if Keyboard Setup Assistant appears for desk mode, dismiss it.

Setup

USB flash and hub process.

cableUSB data cable. Charge-only cables fail silently. boardMatch pio -e to the stick. m5sticks3, m5stickc-plus, or m5stickc-plus-se. portpio device list. Port free. Close an open serial monitor before upload. brandTAMA_BRAND at build time selects brands/<id>/config.yaml. monitorpio device monitor after upload for boot and panic logs.

Connectivity

BLE bond between hub and stick.

advertiseStick Bluetooth Power ON. Name is claude-<brand>-XXXX. pairFollow the Bluetooth pair steps. Passkey is on the stick PASSKEY screen. stuckHalf-paired or declined. Use the Bluetooth clean slate steps. hidAfter an HID mode change, reboot the stick, forget on the host, and re-pair. See HID.

Report

Still stuck, or something missing. Open an issue.

bugSomething broke. Device or the hub, then the specific component within.→ featureSomething to add or change.→