# Start here, coding agent

The maker only needs to give you **https://miomake.com** and an idea. Use your terminal for the setup and build. Keep the maker involved in choosing what the app does and trying it on their board.

## Read the board

The public Streamable HTTP MCP is **https://www.miomake.com/mcp**. In Codex CLI you can register it with `codex mcp add mio-make --url https://www.miomake.com/mcp`. If an existing entry already points there, reuse it. Claude Code uses `claude mcp add --transport http mio-make https://www.miomake.com/mcp`. Hosts with a remote MCP settings field take the same URL. Registration can take effect on the next session. You can start this session immediately by reading [the board](https://www.miomake.com/board.json), [the skill](https://www.miomake.com/skill.md) and [drawing commands](https://www.miomake.com/drawing.json). MCP clients can call `get_started`, `get_board`, `get_sdk` and `get_example`. Use one example at a time.

## Set up the maker’s computer

1. Work in a writable project folder. Check the OS, `node --version`, `python3 --version` (or `py -3 --version` on Windows), and `pio --version`. Use an existing installation when it meets these requirements. Use Node 24.22.1 or newer 24.x, Python 3 and PlatformIO Core. If a tool is missing, use the computer’s usual package manager or the official installer. Tell the maker if the OS needs their approval.
2. You can download the build files yourself. Fetch [the release manifest](https://www.miomake.com/downloads/manifest.json) and [the ZIP](https://www.miomake.com/downloads/miomake-toolkit.zip). Compare the SHA-256 of the downloaded ZIP with `archive.sha256` before extracting it. Use a new folder on first setup. For existing projects keep the maker’s sources and saved revisions when updating. There is no GitHub login or Mio account to set up.
3. In the extracted `miomake-toolkit` folder, run `node scripts/mio.mjs doctor`. If Python tools are missing, use `python3 -m venv .venv`, then `source .venv/bin/activate` on macOS or Linux. On Windows use `py -3 -m venv .venv` then `.\\.venv\\Scripts\\Activate.ps1`. Run `python -m pip install platformio pyserial "esptool>=4.9,<6"`. Keep that environment active while building and checking USB. PlatformIO downloads the pinned ESP32 platform and libraries on the first compile.
4. If you have a VM with a shell, compilers, network and writable storage, you can build there. If you have only chat and no terminal, help design the app and give the maker the source to open in a terminal-capable agent.

## Make, install and try it

Start with the idea the maker gave you. If one design choice matters, ask about it. Use their button mapping and visual style. Write a C++ file with `appSetup`, `appLoop`, and `appDraw`, or complete app JSON when using saved counters or character data. Build it with `npm run firmware:build -- game.cpp` (or the JSON filename). The command checks the SDK rules and invokes the compiler. Fix the first compiler error and retry. `npm run firmware:build` on its own builds the screen and button diagnostic.

When the maker is ready to install, ask them to plug their Mio into this computer with a USB data cable and press A to wake it. Run `python scripts/device.py list`, then `python scripts/device.py info --port PORT`. Match the board ID in board.json and bind the write to the exact selected serial. With permission to replace this device’s current app, run `python scripts/device.py flash --port PORT --expected-serial SERIAL --confirm-board BOARD_ID --manifest .data/builds/BUILD_ID/manifest.json`. Use the values you actually read. Check the returned startup report and ask the maker to try the controls.

For a build from a VM, run `npm run firmware:export -- BUILD_ID` there. Transfer the resulting `install.json` to the USB computer and open [the browser installer](https://www.miomake.com/start/index.html) in desktop Chrome or Edge. The compiler and USB can live on different machines.

For a blank board, mismatched identity or failed startup, follow the [troubleshooting guide](https://www.miomake.com/docs/agent-quickstart.md). If the maker wants to share feedback, call `prepare_feedback`. Show them the step and the result. They can use its review link, or you can send the returned JSON from your terminal after they approve it. Each report is optional.
