Claudia

Claudia is a palm-sized voice assistant box you build yourself: Raspberry Pi Zero 2 W + PiSugar Whisplay HAT, powered by the Claude API. Press the button, ask anything, Claude talks back.

This repo is the builder kit — the build guide, the configuration files that go on the device, and a Windows-side console for flashing/updating/configuring it once it's on your LAN.

The actual chatbot runtime is the upstream PiSugar/whisplay-ai-chatbot; this repo doesn't fork it.

---

What's in here

Claudia/
├── Claudia.md              # The build guide (canonical source of truth)
├── Claudia.htm             # Auto-generated self-contained page (inlined CSS+JS+images, light/dark theme)
├── README.md                  # ← you are here
├── Claudia.Console.bat        # Top-level shortcut to scripts/Claudia.Console.bat
├── package.json               # Two deps: marked (markdown) + highlight.js (syntax)
│
├── .claude/
│   ├── settings.json          # Hook: regenerate .htm on every .md edit
│   └── commands/
│       ├── commit.md          # /commit slash command
│       └── do.md              # /do slash command (continue current task)
│
├── config/
│   ├── env.template           # Example .env for the Pi
│   ├── asoundrc.usbmic        # ~/.asoundrc for USB-mic builds
│   ├── parts.json             # Parts catalog (Amazon/official/reputable URLs per part)
│   ├── console.json           # Saved Pi host/user (created on first detect)
│   ├── images/                # OPTIONAL local overrides for gallery photos (<part-id>.<ext>)
│   └── images-cache/          # Downloaded part photos (git-ignored)
│
├── index.htm                  # Forwards to Claudia.htm (so /claudia/ serves the guide)
│
└── scripts/
    ├── Claudia.Console.ps1    # Multi-command console (local + remote Pi)
    ├── Claudia.Console.bat    # Launcher
    ├── build-html.js          # Node: markdown -> self-contained .htm with theme toggle
    ├── build-html.ps1 / .bat  # PowerShell wrapper for build-html.js
    ├── bump-version.ps1 / .bat# Stamp Claudia.md with a new date + rebuild .htm
    ├── deploy.ps1 / .bat      # Build + FTP upload to /mindattic.com/claudia/
    ├── deploy.settings.json.template # Copy to deploy.settings.json (gitignored)
    ├── on-md-change.ps1       # Hook handler - auto-rebuild .htm on .md edits
    ├── pull-latest-finisher.ps1 # Detached helper for self-update (locked-file safe)
    ├── healthcheck.sh         # End-to-end smoke test (runs on the Pi)
    └── install-claudia.sh     # Automates Parts 4-9 (runs on the Pi)

---

Getting started (Windows builder side)

You need Node.js (nodejs.org) and PowerShell 5+ (ships with Windows).

# 1. one-time: install the local deps the PDF pipeline uses
.\scripts\Claudia.Console.bat update

# 2. open the interactive console
.\Claudia.Console.bat

You'll see something like:

  Claudia Console
  ---------------
  target Pi  : pi@claudia.local

  Commands:
    help           List available commands.
    detect         Find Claudia (the Pi) on the LAN. Saves the host for later commands.
    set-host       Override the Pi hostname/IP.
    shell          Open an interactive SSH session to Claudia.
    status         Show chatbot.service status on Claudia.
    restart        Restart chatbot.service on Claudia.
    logs           Tail Claudia chatbot logs.
    healthcheck    Copy scripts/healthcheck.sh to Claudia and run it.
    set-wakeword   Set WAKE_WORD on the Pi.
    set-model      Set ANTHROPIC_MODEL on the Pi.
    set-prompt     Set SYSTEM_PROMPT on the Pi.
    set-apikey     Set ANTHROPIC_API_KEY on the Pi.
    show-config    Print the remote .env (api key masked).
    update         Install/refresh local Node deps.
    build-html     Render the latest Claudia.md to a self-contained .htm.
    fetch-images   Force-refresh every part image from its remote URL.
    bump           Stamp Claudia.md with today's date and rebuild the .htm.
    deploy         Build Claudia.htm and FTP-upload .md/.htm/index.htm.
    list-parts     List parts catalog + which have a chosen URL.
    find-deals     Open Amazon/official/reputable tabs per part; save your picks.
    apply-deals    Stamp chosen URLs into the latest Claudia.md.
    pull-latest    git fetch + overlay latest source (handles locked .ps1 files).
    self-update    Refresh node_modules + open "newer version?" searches per part.

Shopping flow (find-deals → apply-deals)

The Console doubles as a price-comparison assistant for the parts in config/parts.json. For every part it opens browser tabs in this order:

1. Search for a Google query (broad fallback)
2. Amazon (filtered for price-asc)
3. Official retailer (raspberrypi.com, pisugar.com, seeedstudio.com, etc.)
4. Reputable secondaries (Adafruit, Pi Hut, Sparkfun, Mouser, DigiKey, B&H, Tindie)

You pick the best URL, paste it back into the prompt, and apply-deals rewrites the latest Claudia.md so each part line becomes a Markdown link to the URL you chose. The hook then auto-regenerates the PDF.

.\Claudia.Console.bat find-deals               # walk the whole catalog
.\Claudia.Console.bat find-deals smarthome     # just the smart-plug category
.\Claudia.Console.bat apply-deals              # write the chosen URLs into the .md

Self-update (pull-latest + self-update)

• pull-latest — git fetch then mirror origin/<branch> into the working tree. Because Windows keeps the running Claudia.Console.ps1 open, the command stages the new files into %TEMP% and spawns a detached helper (scripts/pull-latest-finisher.ps1) that waits for this PowerShell to exit before robocopying the temp tree over the repo. Progress goes to .claude/pull-latest.log.
• self-update — runs npm outdated / npm update / npm audit fix, then opens "is there a newer version of <part>?" searches for every catalog entry, then opens the official Claude model catalog. Use it monthly to catch silently-aging dependencies, deprecated parts, and new model IDs.

You can also call commands directly:

.\Claudia.Console.bat detect
.\Claudia.Console.bat set-model claude-sonnet-4-6
.\Claudia.Console.bat logs
.\Claudia.Console.bat update --clean

---

Build the device

1. Open Claudia.md (or the PDF if you'd rather read it printed).
2. Follow Parts 1–3 to buy parts, assemble, and flash the SD card.
3. SSH in. Then either:
   • Manual path: follow Parts 4–9 by hand.
   • Scripted path: copy scripts/install-claudia.sh to the Pi and run it. It walks the same steps end-to-end and prompts you when it needs a reboot or your API key.
4. Once it's running, plug Claudia onto your LAN and run Claudia.Console detect from this machine — every command after that targets it over SSH.

---

HTML workflow

The .htm is derived: never hand-edit Claudia.htm, always edit the .md. The output is one self-contained file — inline CSS, inline JS, inline (base64) part photos. No CDN, no <link>, no <script src>. Styling and the light/dark theme toggle follow mindattic.com's single-file convention.

Two ways the page gets refreshed:

1. Automatic — .claude/settings.json registers a PostToolUse hook that fires scripts/on-md-change.ps1 whenever Claude Code edits a Claudia.md. The hook re-renders the matching .htm and logs to .claude/html-rebuild.log. No-op for any other file edit.

2. Manual —

   .\scripts\build-html.bat              # latest version
   .\scripts\build-html.bat -Source .\Claudia.md

Theming

The page ships with both palettes. The toggle button (top-right corner) flips data-theme on <html>; CSS custom properties drive every color so the rest of the cascade follows. The choice persists via localStorage under the key claudia-theme. First-time visitors get the palette implied by prefers-color-scheme.

Part images (base64-embedded)

build-html.js builds a "Parts gallery" section. For every entry in config/parts.json it tries to:

1. Use a local override at config/images/<part-id>.<ext> if present (always wins).
2. Otherwise look up the part in the script's URL map, download once, and cache to config/images-cache/ (git-ignored).
3. Fall back to a generated SVG placeholder with the part name baked in.

Either way, the result is base64-encoded into a .part-card[data-pid="<id>"] .part-image { background-image: url(data:...) } rule and inlined in the page CSS — so once you open the .htm, no further network requests fire.

Tune which images get embedded:

.\Claudia.Console.bat fetch-images        # force-refresh every URL
node scripts/build-html.js --no-images    # skip embedding entirely (placeholders only)

Bumping the version

The file path is stable — Claudia.md and Claudia.htm never get renamed, so external links to them never rot. The revision date lives inside the file (in the H1, the "What's new in " heading, and the footer). Bumping means rewriting those dates in place; historical revisions are recoverable from git history.

.\scripts\bump-version.bat                    # stamp today's date (YYYY.MM.DD)
.\scripts\bump-version.bat -To 2026.06.01     # forward-date explicitly

The bumper finds the current date from the H1, replaces it everywhere it appears in the file, then regenerates Claudia.htm.

Deploying to mindattic.com/claudia/

The repo includes an FTP deploy that mirrors mindattic.com's pattern.

# one-time setup
copy scripts\deploy.settings.json.template scripts\deploy.settings.json
# edit deploy.settings.json with real FTP creds (it's gitignored)

# every release
.\scripts\deploy.bat
# or, from the Console:
.\Claudia.Console.bat deploy

What deploy.ps1 does, in order:

1. Builds — runs build-html.js so Claudia.htm reflects the current .md. Skip with -NoBuild if you just ran it.
2. Stamps — inserts/replaces a <!-- Last Updated: ISO8601 --> comment at the top of index.htm.
3. Uploads — curl.exe --ssl-reqd --ftp-pasv pushes Claudia.md, Claudia.htm, and index.htm to FtpRemotePath (defaults to /mindattic.com/claudia).

Credentials never leave your machine: scripts/deploy.settings.json is in .gitignore. Only the placeholder template gets committed.

---

Slash commands (/commit, /do)

Two project-scoped commands live under .claude/commands/:

• /commit — stages and commits the current working tree with a concise, log-style-matching message. Never git add -A, never --amend, never --no-verify.
• /do — explicit version of the "bare do means continue" rule. Resumes whatever Claude was in the middle of when you stepped away.

Either of these can be hoisted to your global ~/.claude/commands/ later if you want them everywhere.

---

Cost / time / parts

The full breakdown lives in Claudia.md (Part 1). At a glance:

Build	What you get	Total
Desktop	Core + Whisplay's mics + wall power	~$77
Desktop + budget mic	+ SunFounder USB mic + OTG	~$97
Desktop + premium mic	+ reSpeaker XVF3800 + OTG	~$144
Portable + premium mic	All of the above + PiSugar 3 battery	~$184

Assembly is ~5 minutes (no soldering); first-boot software install is ~30–60 minutes wall-clock (most of it apt and npm chugging on a 512 MB Pi).

---

Upstream references

• Build guide: Claudia.md in this repo
• Chatbot runtime: https://github.com/PiSugar/whisplay-ai-chatbot
• Whisplay driver: https://github.com/PiSugar/Whisplay
• Wake-word wiki: https://github.com/PiSugar/whisplay-ai-chatbot/wiki/Wakeword
• Claude API docs: https://docs.claude.com
• Claude pricing: https://anthropic.com/pricing

---

Built by MindAttic LLC. The guide carries the canonical version; this README just points at it.