marimo-pets 🌱

A little company for your code. Floating, draggable notebook companions built with anywidget: Mo the mossball, Clippy, Jimothy the raccoon, and Crab, in that order.

Your pet can celebrate a finished task, react to Python, and help you ask marimo's AI about the cell you're working on.

Install

From PyPI:

pip install "marimo-pets[marimo]"

From a checkout:

pip install -e ".[marimo]"
marimo edit examples/companions.py

You can also install the source directly:

pip install "marimo-pets[marimo] @ git+https://github.com/ktaletsk/marimo-pets.git"

Requires Python 3.10+. The marimo extra installs the tested marimo 0.24.0 version. Runtime dependencies include anywidget, traitlets, and pydantic-ai.

Meet your companion

from marimo_pets import NotebookPet

pet = NotebookPet()  # Mo by default
pet

Display the instance once per page. Choose an avatar in the dashboard or set mode="clippy", mode="jimothy", or mode="crab" when constructing it.

Drag the avatar, speech bubble, or name bar. Arrow keys move a focused avatar or name bar. Click to pet, give a pep talk, or send your pal for a nap. Wander adds an occasional stroll; movement respects reduced-motion preferences.

pet.say("Let's figure this out.", mood="thinking")
pet.celebrate("The experiment worked!")
pet.snooze()
pet.mode = "crab"
pet.position = [80, 140]
pet.wander = True

with pet.task("Running an experiment…", done="All done!"):
    result = sum(range(100_000))

task() celebrates success and propagates exceptions or cancellation after displaying a supportive message. Speech is rendered as literal text.

Position, mood, and other traits synchronize between Python and rendered views. Each browser clamps the position to its own viewport. Use one displayed instance per page to get one floating pet.

Help with this

Click a notebook cell or select text, then choose Help with this on your pal. The What Mo sees inspector shows the chosen cell, cells in view, code, and selected text. Its title follows the selected avatar.

• Ask marimo AI opens marimo's chat and submits your question with native cell-output or error references. Cells without a usable reference include code in the prompt instead.
• Open as draft prepares a question for review and preserves an existing visible chat draft.
• Question preview shows the prompt and offers a copy button.

The pet uses your configured marimo AI provider and chat settings. Awareness stays local to this browser view until you ask; it is not synchronized to Python or other viewers. It observes this notebook document, not your desktop or other tabs. Marimo may add further notebook context or output images according to its normal chat settings. The generated prompt asks for an answer in chat, without editing or running cells unless you explicitly ask.

Experimental: native chat support currently targets one verified marimo 0.24.0 frontend build. Its adapter uses internal frontend interfaces, so other builds fall back to DOM context and a copyable question. See compatibility and context details.

React to petting in marimo

In the cell that creates the pet:

pet = NotebookPet()
get_pets, set_pets = mo.state(pet.pets)
pet.observe(lambda _: set_pets(pet.pets), names=["pets"])
pet

In another cell:

mo.md(f"**{get_pets()}** pets received.")

The example notebook demonstrates this along with a Python task and contextual help.

Develop

uv sync
uv run marimo edit examples/companions.py
uv run pytest
node --test tests/frontend/*.test.mjs
uv run ruff check .
uv run ruff format --check .
uv run marimo check examples/companions.py
uv build
uv run twine check dist/*

Python lives in src/marimo_pets/pet.py; the bundled frontend is src/marimo_pets/static/widget.js. There is no JavaScript build step. For live frontend updates, launch marimo with ANYWIDGET_HMR=1.

Credits

Inspired by Vincent Warmerdam's wigglystuff FloatingPanel. Mo's body, little feet, and sprout are inspired by Mo the Mossball from Wanderland. Jimothy is the very round raccoon; Crab is a separate mode, for parity. The avatars are SVG illustrations bundled with the widget.

MIT license.