Skip to main content

Coding Guide 3 — Code your Butter Bot with Claude Code

Describe the change you want in plain English and let Anthropic's Claude Code write the C++, build it and flash it for you.

K
Written by Karla Trstenjak

What is Claude Code?

Claude Code is Anthropic's AI coding assistant that runs in your terminal. You type what you want in plain English ("add a new joke", "make the LED breathe faster"), and it reads the Butter Bot's source code, writes the change, and can even build and flash the firmware for you.

It's a real programmer-grade tool — but you don't need to be a programmer to use it. You'll be the ideas person; Claude does the C++.

What you need

Item

Notes

Everything from Guide 2

Working ESP-IDF setup + the cloned ButterBot-Firmware project. Do Guide 2 first — you need to have built and flashed the stock firmware once.

A Claude account

A Claude Pro subscription (~$20/month) or higher includes Claude Code — the free Claude.ai plan does not. There's also pay-as-you-go API billing via Anthropic Console.

15 minutes

Seriously, that's it.

Step 1 — Install Claude Code

No prerequisites — the installer brings everything it needs. (Official docs, if you want the long version: https://code.claude.com/docs/en/quickstart)

Claude Code quickstart docs

Claude Code quickstart docs

macOS / Linux

Open a terminal and paste:

curl -fsSL https://claude.ai/install.sh | bash

When it finishes, it may tell you to add a line to your shell profile so the claude command is found, e.g.:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc

(Copy the exact command from your installer output — on Linux with bash, it will say ~/.bashrc instead.)

Windows

Open PowerShell (Start menu → type powershell → Enter) and paste:

irm https://claude.ai/install.ps1 | iex

Claude Code runs natively on Windows 10/11 — no WSL required. Having Git for Windows installed (you have it from Guide 2) is recommended; Claude Code uses it for running shell commands.

Make sure you're in PowerShell, not the old Command Prompt — the prompt should start with PS C:\. (If you see 'irm' is not recognized, you're in the wrong one.)

Prefer a package manager? brew install --cask claude-code (macOS) and winget install Anthropic.ClaudeCode (Windows) install the same thing.

Check it worked

Open a new terminal and run:

claude --version

You should see a version number, e.g. 2.1.201 (Claude Code). If anything seems off later, claude doctor runs a full health check.

Step 2 — Log in

  1. In the terminal, go to your Butter Bot project folder: - macOS/Linux: cd ~/Projects/ButterBot-Firmware - Windows: cd C:\Projects\ButterBot-Firmware

  2. Run: claude

  3. The first time, it will say you're not logged in — type /login and press Enter.

  4. Pick Claude account with subscription (or Console account if you use API billing). Your browser opens; log in and click Authorize.

  5. Back in the terminal you're now in a chat with Claude, inside your project.

To leave Claude Code at any time, type /exit or press Ctrl+C twice.

Is it safe to let an AI touch my code? Claude Code asks for your permission before it edits files or runs commands — you'll see exactly what it wants to do and approve or reject each action. And because the project is under git, any change can be undone (see the troubleshooting table below). Your robot can always be restored (Guide 2, FAQ).

Step 3 — Open the right terminal (so Claude can build)

Claude Code can only run the build tools if the terminal it lives in can. The easiest way on every OS:

  1. Open the ButterBot-Firmware folder in VS Code (as in Guide 2).

  2. Press F1 → "ESP-IDF: Open ESP-IDF Terminal" — in this terminal, idf.py works.

  3. In that same terminal, run claude.

  4. (Optional) Run /init command to create an initial context for Claude that will be used on all subsequent runs. It will also help you save on tokens as Claude will not need to regenerate context for entire project every time.

That's it — now Claude can edit code and compile/flash it.

(Alternative for terminal fans: any shell where you've loaded the ESP-IDF environment works — source the export.sh from wherever the installer put ESP-IDF; the exact path is version-specific, e.g. ~/esp/esp-idf-v5.5.3/export.sh on macOS/Linux.)

Step 4 — The fun part: give your robot a new joke

The Butter Bot picks its jokes from a list in the firmware and reads them out with its text-to-speech voice. Let's add yours. With Claude running inside the project, paste this prompt (change the joke to whatever you like!):

Add a new joke to the Butter Bot's joke list: "What do you call a robot that always takes the longest route. R2 detour". Look at how the existing jokes are defined in components/ButterBot-Common/src/Phrases.cpp and follow the same pattern exactly, including the trailing comma. Write it the way the text-to-speech engine can pronounce it.

What you'll see (this is a real session, shortened):

Example Claude Code session

Example Claude Code session

Claude will: 1. Read Phrases.cpp to understand the pattern. 2. Propose an edit: your joke added to JokePhrases, formatted exactly like its neighbors and written so the text-to-speech engine pronounces it right — exactly the kind of detail beginners miss and AIs catch. 3. Ask for your approval — press Enter (or y) to accept the change.

Want to double-check what changed? Ask Claude: "show me the diff of what you changed".

Step 5 — Let Claude build and flash it

Still in the same chat, type:

Build the firmware with idf.py and fix any compile errors you caused. Then flash it to the robot on port <YOUR-PORT> and tell me when it's done.

(Replace the port with yours from Guide 2, Step 7 — on Windows it's e.g. COM5.)

Claude will run idf.py build (about 20 seconds, since only one file changed), show you the output, ask permission to flash, and run idf.py -p <port> flash.

Step 6 — Test it on the robot

  1. Unplug the robot (or leave it plugged in — up to you).

  2. Short-press the power button — the robot starts listening.

  3. Say: "Tell me a joke."

  4. Jokes are picked at random, so ask a few times until your masterpiece comes up.

More fun things to ask Claude

Each of these is a real, doable change in this codebase — same workflow: ask → approve → build → flash → try.

  • "Add three new responses to the list the robot uses when someone says 'pass the butter'. Match the existing dry, existential tone." (PassTheButterPhrases — the robot's signature move)

  • "Make the robot tell me a fun fact about butter when I ask for a fact." (FactRoutine + Phrases.cpp)

  • "When the robot is picked up, make it protest more dramatically." (PickedUpPhrases)

  • "List all the voice commands the robot understands." (Claude will read ListenState.cpp and give you the full menu — great for exploring!)

  • "Explain, like I'm twelve, what happens in the firmware between me saying 'tell me a joke' and the robot speaking." (Claude Code is also a fantastic tour guide through the code.)

A note on adding brand-new voice commands: the list of spoken phrases the robot recognizes uses special phoneme strings (you'll see things like "TfL Mm c qbK" in ListenState.cpp). Adding new responses is easy; adding new voice commands is an advanced project — Guide 5 — Program Your Butter Bot walks through it step by step, including generating the phoneme strings, and every section of it works as a spec you can paste straight into Claude Code.

Troubleshooting

Symptom

Fix

claude: command not found

Open a new terminal, or add the install dir to PATH (the installer printed the exact command)

Claude says it can't run idf.py

You started claude in a normal terminal → exit, open the ESP-IDF Terminal in VS Code, run claude there (Step 3)

"Not logged in"

Type /login inside Claude Code

Build fails after Claude's change

Paste the error back into the chat: "the build failed with this error, please fix it" — fixing its own mistakes is one of the things Claude is best at

Flash fails

Same checklist as Guide 2, Step 8 (close monitor, right port, power-cycle, direct USB)

Worried the code is now a mess

Ask Claude: "show me everything that changed". To reset everything to stock (including your joke!): git checkout -- . && git submodule foreach --recursive git checkout -- . — the phrase files live in a submodule, so the second half matters

Prefer OpenAI's tools? The exact same workflow with ChatGPT's coding agent is in Guide 4 — Code your Butter Bot with OpenAI Codex. Ready to go deeper than jokes? Guide 5 — Program Your Butter Bot walks through new voice commands, object detection, and controller mods in full detail.

Did this answer your question?