Skip to content
maskostudioDocs

All pages

  • Overview/docs/use-cases
  • Mobile app/docs/use-cases#mobile
  • Website/docs/use-cases#website
  • Desktop/docs/use-cases#desktop
  • AI agents/docs/use-cases#agents
  • Videos/docs/use-cases#videos
  • Brand/docs/use-cases#brand
  • Start building/docs/ai-agents
  • Set up once/docs/ai-agents#set-up-once
  • Ask in plain words/docs/ai-agents#ask-in-plain-words
  • What your agent does/docs/ai-agents#what-your-agent-does
  • MCP server/docs/mcp
  • Agent guide: create a mascot/docs/ai-agents/create-mascot
  • Agent guide: animate a mascot/docs/ai-agents/animate-mascot
  • Agent guide: interactive mascot/docs/ai-agents/build-interactive-mascot
  • Agent guide: website or app/docs/ai-agents/integrate-mascot
  • Agent guide: desktop pet/docs/ai-agents/desktop-pet
  • Masko for Cursor/docs/ai-tools/cursor
  • Masko in ChatGPT/docs/ai-tools/chatgpt
  • Masko in Lovable/docs/ai-tools/lovable
  • Masko in Devin/docs/ai-tools/devin
  • Masko in n8n/docs/ai-tools/n8n
  • Masko in Hermes Agent/docs/ai-tools/hermes
  • Masko in OpenClaw/docs/ai-tools/openclaw
  • Start here/docs/tutorials#start-here
  • All tutorials/docs/tutorials
  • Create your first mascot/docs/tutorials/first-mascot
  • Create an animated character/docs/tutorials/first-animation
  • Make a character talk/docs/tutorials/make-it-talk
  • Put your mascot on your website/docs/tutorials/mascot-on-your-website
  • Guide onboarding with a talking mascot/docs/tutorials/web-onboarding-mascot
  • Add a mascot that celebrates progress and welcomes users back/docs/tutorials/web-progress-companion
  • Add a talking support mascot in the bottom right/docs/tutorials/web-support-mascot
  • Show a mascot while your AI thinks/docs/tutorials/ai-loading-mascot
  • Give your AI agent a face/docs/tutorials/ai-agent-face
  • Animate the mascot you already have/docs/tutorials/animate-your-mascot
  • How to make Telegram stickers/docs/tutorials/telegram-stickers
  • How to make Discord stickers/docs/tutorials/discord-stickers
  • Quickstart: your first animation/docs/quickstart
  • Terminal quickstart/docs/terminal
  • API keys and workspaces/docs/authentication
  • CLI browser login/docs/authentication/cli
  • How mascots work/docs/how-mascots-work
  • Credits and costs/docs/credits
  • From text/docs/create/from-text
  • From an image/docs/create/from-image
  • From a website/docs/create/from-website
  • From a brand book/docs/create/from-brand-book
  • Reference images/docs/manage/references
  • Props/docs/manage/props
  • What you can generate/docs/generation
  • Pose-to-animation walkthrough/docs/generate/workflow
  • Images and poses/docs/generate/images
  • Animations/docs/generate/animations
  • Talking animations/docs/generate/talking
  • Sounds/docs/generate/sounds
  • Motion/docs/generate/motion
  • Animation presets/docs/generate/presets
  • Write good requests/docs/generate/requests
  • Logos, backgrounds and stickers/docs/generate/design-assets
  • Cursor follower/docs/generate/cursor-follower
  • Batch generation/docs/generate/batch
  • Image and video exports/docs/manage/media-exports
  • Canvases and releases/docs/canvas
  • Build a canvas/docs/canvas/build
  • Canvas templates/docs/canvas/templates
  • Generate canvas assets/docs/canvas/generate-all
  • Export a canvas/docs/canvas/export
  • Overview and demo/docs/player
  • Play one animation/docs/player/one-animation
  • Play a canvas/docs/player/canvas
  • Ship in an app with an app key/docs/player/app-keys
  • Play on an ESP32 board/docs/player/esp32
  • Hosting and file formats/docs/generate/cdn
  • File sizes/docs/generate/file-sizes
  • Float a mascot on your Mac/docs/integrations/desktop
  • Jobs and polling/docs/manage/jobs
  • Webhooks/docs/manage/webhooks
  • Manage mascots and assets/docs/manage/collections
  • All endpoints/docs/reference
  • Requests and responses/docs/reference/conventions
  • Errors and recovery/docs/reference/errors
  • Command line reference/docs/terminal/commands
  • TypeScript SDK/docs/sdk/typescript
  • Changelog/docs/reference/changelog
  • Migrate to mascots and canvases/docs/manage/studio-migration
Get an API key
Documentation

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:

  1. Which mascot: one of theirs (list_mascots, then the exact one by id) or a new one (ai-agents/create-mascot).
  2. How it gets around, from what the character is: walks, hops, flies, floats, swims, or stays in one place.
  3. 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.
  4. 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 MaskoPlayer and MaskoOverlay products, 0.1.22 or later: MaskoOverlay(player:size:) holds the pet above every app and keeps it still when desktops swipe. Move it with setFrameOrigin.
  • Windows: an Electron app with @masko/player 0.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 the touch.
  • The part tracks and whole: where the feet, the seat and the hands are, to line them up with an edge or a button.
  • duration and facing: 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.