Make a desktop pet
This guide is for an AI agent working with Masko's MCP tools; read_docs reads the other guides and docs pages it names. A desktop pet is a mascot that lives on the person's screen, outside any window, and reacts to what they do. It is a canvas release played by the Masko player in a small app of its own, built and run on the person's own computer.
A nice pet
People keep a pet open all day when it feels like a small living character, and close it within an hour when it is noisy or in the way. Aim for that first:
- It has a personality, from the mascot's description: how it moves, what it does when nothing happens, how it reacts.
- It is always alive: a resting loop with a few calm extras, never a frozen picture, never the same short loop for an hour.
- It never teleports: every change of place or state plays an animation that gets it there.
- It is small and stays out of the way: on edges, corners, the Dock or the taskbar, never over what the person is reading or typing.
- It reacts at the right moment, timed to the animation, and calms down after.
- It is quiet by default. Sounds and speech come only when the person wants them.
- It does nothing to the person's apps or files unless they asked for it, and they can turn each such behavior off.
Ask first
Ask only what you cannot see:
- Which mascot: one of theirs (
list_mascots, then the exact one by id) or a new one (ai-agents/create-mascot). - How it gets around, from what the character is: walks, hops, flies, floats, swims, or stays in one place.
- What it reacts to, in their own words. If they have no idea, give a few examples to start from, not a menu: it sits on the window in front, works when they work, sleeps when they are away, cheers when something finishes, comes to the pointer, closes an app that distracts them.
- Mac, Windows or both, and whether it is only for them.
Turn each wish into "when this happens, the pet does that", and start with the smallest pet that does one wish well. More can come in later releases, which the pet picks up without being reinstalled.
What a pet can notice
Anything the app can learn: the app in front and its window, windows opening, moving, closing or going full screen, the pointer, clicks and drags on the pet, how long the person has been idle, the time of day, a desktop or display change, and whatever their own tools report, such as a build, a download, a calendar or an AI agent. Read each one in the app and turn it into a canvas input. Some need the person's permission: on Mac, Accessibility for other apps' windows and buttons, and Automation to quit an app. Say which wish needs which before asking.
The canvas
Every animation lives in one canvas, and the app only sets its inputs: read ai-agents/build-interactive-mascot and design it from the wishes. Plan the poses the pet rests in (sitting, standing, flying, sleeping), how it moves between them, the loop that carries it from place to place, and how it arrives. When the place it rests on goes away, a closed window for example, it leaves the way this character moves: one that walks falls and lands on its feet, one with wings flies down, a ghost floats. Ask if the character does not say.
Hold with set what lasts (walking, working, falling) and fire what happens once. Check each new clip before building on it: a clip can add a prop or a step the pet never had. Remake it with a clearer request rather than hiding it in code.
Building it
- Mac: a Swift app with the Swift package's
MaskoPlayerandMaskoOverlayproducts, 0.1.22 or later:MaskoOverlay(player:size:)holds the pet above every app and keeps it still when desktops swipe. Move it withsetFrameOrigin. - Windows: an Electron app with
@masko/player0.1.22 or later in a transparent, frameless, always-on-top window that lets clicks through except on the pet. Read other windows through the Windows API, and keep the pet above the taskbar's work area.
Play the release from its link with the key already in it (get_release_delivery gives the code). Ask the delivery for include=motion,motion.timeline and read it in the running app, never as numbers typed into the code:
travel, on a clip that moves in place: move the window by it at the clip's time and the foot on the ground stays still. Never slide the window at a speed of your own.moments(touch,takeoff,landing,turn): act at those times, such as closing an app at thetouch.- The part tracks and
whole: where the feet, the seat and the hands are, to line them up with an edge or a button. durationandfacing: each clip's real length, and when to mirror the pet. A reversed clip, such as stopping a walk, has its own motion: the clip it reverses, read backwards.
Rules that keep it alive
- Never stuck: every wait has a time limit and a way on that still moves. A clip that fails to load is retried by the player; meanwhile the pet keeps playing. The first download takes a few seconds and is not a freeze.
- Never off screen: if no screen shows the pet, bring it back to its home spot.
- Trust windows carefully: while desktops slide, or a window opens, closes or goes full screen, the system reports windows at in-between positions, often far off screen. Wait about a second after such a change, use only windows that are mostly on a screen, and act once two readings in a row agree.
- Wait for the animation, not the state: a pose's name changes when its move starts. Start the next move, such as a jump, when the clip it needs is actually playing.
- Sleep and wake: pause while the screens are off, and after a wake check where the pet is before it moves.
- Its own app only: it never closes, types into or changes another app unless the person asked for that behavior.
Check it
Run it on the computer it is for. An agent on a Mac cannot test a Windows pet: build and run it on that PC, or a Windows runner that takes screenshots. Check each wish, then the basics: quick switches between apps, desktops swiped one after another, one app full screen, dragging and resizing the window the pet sits on, closing that window, a second display, sleep and wake. Watch it with screenshots and logs and confirm it is visible and in the right place each time. Ask before taking over the person's screen to test. Say what you actually ran: never claim it works from written code alone.
More detail: ai-agents/integrate-mascot, player/canvas and generate/motion.
