Boba Pet

An always-on-top pixel-art desktop pet for Windows that talks to Claude Code (and Codex, Antigravity, Gemini or Groq). Click it, type or say "Hey Boba", and the answer pops up in a speech bubble. It watches your Claude Code sessions, reacts when they finish or fail, and keeps you on track with tasks, focus timers and a hackathon mode.

Install (one line)

Open PowerShell and run:

irm https://raw.githubusercontent.com/AbdulRahmanAzam/boba-pet/main/install.ps1 | iex

That's it. The installer:

1. installs uv if you don't have it,
2. installs Boba Pet with its own private Python 3.12 (your Python is untouched),
3. downloads the offline voice and search models (about 200 MB, one time),
4. adds Boba Pet to the Start menu and starts the pet.

No admin rights, no git clone. To also start the pet with Windows, run $env:BOBA_PET_AUTOSTART="1" before the line above, or later run boba-pet-setup --autostart.

Already have Python 3.11+?

Install it in its own environment, not into the Python you use for other projects:

pipx install boba-pet        # or: uv tool install boba-pet
boba-pet

or, with uv, just uvx boba-pet. The first start downloads the voice models in the background; run boba-pet-setup once to get them right away and add a Start menu shortcut.

Seeing pip's dependency resolver does not currently take into account all the packages that are installed? That means pip install boba-pet went into a Python shared with other projects (for example one with transformers or streamlit-authenticator). Boba itself installed fine, but it pulled a newer huggingface-hub that an older transformers doesn't accept. To fix it, remove Boba from that Python and put the old version back (pip uninstall boba-pet then pip install "huggingface-hub<1.0"), then install Boba with pipx or uv tool as above. Warnings about packages Boba doesn't use (such as cryptography) were already there before Boba was installed.

Updates

Boba updates itself. Once you've linked an AI, it checks for a new release and asks Update now or Later (Later asks again the next day). Update now restarts the pet on the new version in a few seconds. You can also check any time: right-click > Check for updates.

On v1.0.0 (before self-updates existed)? Update once by hand: pip install -U boba-pet, or run the install line again.

Uninstall

boba-pet-setup --uninstall-shortcuts; uv tool uninstall boba-pet   # remove

Your settings and models stay in %USERPROFILE%\.boba-pet and %USERPROFILE%\.claude-pet*.json; delete them to remove everything.

Requirements

• Windows 10 or 11
• One AI to talk through (the pet has no key of its own; pick it from the right-click menu > AI provider):
  • Claude Code (recommended): irm https://claude.ai/install.ps1 | iex, then sign in once with claude
  • Codex CLI (ChatGPT plan), Antigravity CLI (Google account), or a free Groq / Gemini API key

What it does

• Chat in a speech bubble; the chat keeps context, shows tokens used (↑ input, ↓ output) and has a cheap Compact button that rolls the chat into a short note.
• Quick menu: click the ✱ in the ask box for ask, talk, screenshot, new chat, compact, history, model, effort level and more.
• Model and effort next to the ask box: click to switch, e.g. Haiku, Sonnet or Opus on Claude Code (Haiku is the default and the cheapest).
• Voice, fully offline: talk with the mic button (Whisper), say "Hey Boba" to wake it (Vosk), and have replies read aloud (Windows TTS).
• Claude Code companion: it looks busy while a session works, celebrates when it finishes, sweats when tests fail and waves when Claude needs your permission. A usage meter shows your plan limits and today's tokens.
• Projects: "open my portfolio project" finds the folder and opens it in VS Code with Claude Code running.
• Tasks, reminders and focus timer, with a gentle distraction guard.
• Water reminder: every hour Boba rings a chime and tells you to drink a glass of water, and counts your glasses for the day (goal 8). It waits while you're away from the PC.
• Keystroke counter: counts the keys you press each day and adds them to an all-time total, with a 7-day chart, best-day records and 100k milestones. Only the number is stored, never which keys; software-typed keys don't count.
• Hackathons: track deadlines, and click one for a workspace with a checklist, notes, focus sprints, idea/pitch/judge helpers and a prompt coach that suggests better Claude Code prompts while you build.
• News briefings, 3 a day: a morning briefing with your tasks and the top AI & tech news, then a short update with anything new every 4 hours. Real news feeds, every item linked to its source, and no story is shown twice.
• Screenshots: snip part of the screen and ask about it.
• Computer tools (optional): the AI can open apps, change volume, type and so on. By default it asks you first for anything risky; set the mode in the menu, or turn it off.
• Characters: several pixel-art pets; add your own with one file (see below).

Privacy

• API keys you paste are saved only in %USERPROFILE%\.boba-pet\.env on your PC.
• Speech recognition and the wake word run locally; audio never leaves the PC.
• The pet reads Claude Code transcripts locally to react to sessions; their text is not sent anywhere.
• Requests to the AI go through the provider you linked, on your own account.

Run from source (for contributors)

git clone https://github.com/AbdulRahmanAzam/boba-pet
cd boba-pet
uv venv --python 3.12 .venv
uv pip install --python .venv\Scripts\python.exe -r requirements.txt
.venv\Scripts\python.exe launch.py --setup   # optional: models + Start menu shortcut
.venv\Scripts\pythonw.exe claude_pet.py

In a clone, the pet keeps .env, models/ and shots/ next to the code (all git-ignored). Copy .env.example to .env if you use Groq or Gemini keys. Set BOBA_PET_PROJECTS (folders separated by ;) to choose where it looks for your projects.

Layout

Add a character

Drop a sprite_<name>.py file next to sprites.py with a compose_<name>(...) function (copy sprite_bluebot.py to start), an optional NAME for the menu and an optional EXTRA_PALETTE. It shows up in the menu on the next start.

Contributing

Pull requests are welcome; see CONTRIBUTING.md.

License

MIT