Everything about Mischi

Install

Mischi is a free, native Mac app. It's in public beta, so expect frequent updates and the occasional rough edge.

Download and install

1. Download Mischi-0.9.11.dmg (5.9 MB).
2. Open it from your Downloads folder. A window shows Mischi next to your Applications folder.
3. Drag Mischi onto Applications.
4. Open Mischi from Applications, Launchpad or Spotlight.

First launch

A short welcome tour covers the basics, and your pet appears on the desktop. Mischi comes with a pet built in, so there's nothing to set up before you can play.

Mischi is a menu bar app. Look for its icon at the top right of your screen. It stays out of the Dock unless you turn on Preferences → Advanced → Show Dock icon. To watch the tour again, go to Preferences → About → Welcome tour.

Updating

Download the latest version from the download page, quit Mischi, and drag the new copy into Applications, replacing the old one. Your pets, settings, reminders and API key are kept. Join the newsletter to hear when a new version is out.

Everyday use

Your pet lives in a transparent window above your other apps. It follows you to every Space and over full-screen apps, and it never steals focus from what you're doing.

The Mischi menu

The menu is the same wherever you open it: on the pet, in the menu bar, or on the Dock icon if you've turned it on.

• Show / hide the pet.
• Animation: play any animation you've named, or go back to the default loop.
• Speed, Scale and Behavior: quick versions of the settings below.
• Library: switch pets, reveal one in Finder, or delete it.
• Import Pet Folder… and Import Pet .zip…
• Preferences… and Quit Mischi.

Preferences has seven tabs: Pet, Behavior, Animations, Reminders, Window, Advanced and About. The sections below cover them.

Pets & library

A pet is a folder containing a pet.json and a spritesheet.webp. It's the same format OpenAI Codex uses, so every Codex pet works in Mischi.

Add pets

All three live in Preferences → Pet, and folder and .zip imports are in the Mischi menu too. Mischi copies each pet into its own library and never changes the original.

Switch and manage

Pick a pet in Preferences → Pet, or use Library → Switch to…in the menu. Deleting a pet only removes Mischi's copy.

Your library is in ~/Library/Application Support/mischi/Pets/. To open it, go to Preferences → Advanced → Pet library folder → Reveal in Finder.

If an import fails

Behavior & animations

Modes

Preferences → Behavior → Mode sets what your pet does when you leave it alone. No mode plays the same animation twice in a row.

Other behavior settings

• On click: No action, Random animation, Toggle running, or any animation you've named.
• Playback speed: 0.5×, 0.75×, 1× or 1.5× for every animation.
• Idle chatter: the occasional speech bubble while you're inactive, using the chat lines you've written.
• Ask input: whether Ask Mischi opens in Text or Voice mode.

Character

At the top of the Behavior tab, each pet gets its own character: a name, a tone and a personality. The character shapes Ask Mischi's replies and any chatter Groq writes. ✨ Enhance turns a quick sketch into a fuller description, and When you're talking to it picks an animation to loop while the Ask prompt is open.

Animations

Mischi finds every row of a pet's spritesheet that has frames. In Preferences → Animations you can:

• Name each row, like “Wave” or “Drink water”. Names show up in the menu, the click action, reminders, and Ask Mischi (“wave hello”).
• Add chat lines, one per line. When the animation plays, the pet says one at random.
• Generate chatter with Groq: one request writes in-character lines for every named animation. Replace overwrites existing lines and Append adds to them. It needs a personality to write from.
• Swap left / right movement: turn this on if your pet runs backwards while wandering or being dragged.

Reminders

Mischi can nudge you to stretch, drink water or join a call. When a reminder fires, your pet says it in a chat bubble and can play an animation.

In Preferences → Reminders, a reminder has:

• What: the words your pet will say.
• When: the date and time it first goes off.
• Repeats: Once, Every minute, Hourly, Daily, Weekly, or Custom (every so many seconds, minutes, hours, days or weeks).
• Animation: optional, played when it fires.

You can edit or delete reminders at any time. With a Groq key you can also just ask: “remind me in 20 minutes to stretch”.

Window & startup

AI with Groq

Mischi's AI features are optional, and you bring your own key. Your pet, animations and reminders all work without them. A Groq key adds:

• Ask Mischi, an assistant that can take actions on your Mac
• Voice mode, so you can talk instead of type
• Generated chatter and ✨ Enhance for your pet's character

Set up your key

1. Create a free API key at console.groq.com.
2. Open Preferences → Advanced → Groq · BYOK, then paste and save the key.
3. Choose a Model. Mischi fetches the current list from Groq and only offers models that can use its tools.
4. Click Test next to Connection to check everything works.

Seeing “too many requests”? You've hit your Groq plan's rate limit. Wait a minute or pick a smaller, faster model. Groq retires models from time to time, so if one stops working, choose another from the same list.

Ask Mischi

Press ⌘ K in any app, or hold ⌘ and double-click your pet. A prompt opens above the pet. Type your question and press ⏎, and Mischi answers in character.

Mischi decides by itself when to use one of its tools:

Notes are saved on your Mac in ~/Library/Application Support/Standalone Codex Pets/notes.json.

Voice mode

Switch between text and voice with the badge on the prompt, or set the default in Preferences → Behavior → Ask input. In voice mode, just talk and pause when you're done. Groq's Whisper model transcribes the recording and Mischi sends your question. The audio is thrown away afterwards.

The first time, macOS asks for microphone access. If you declined, turn it on in System Settings → Privacy & Security → Microphone.

Create your own pet

Mischi uses the Codex pet format, so a pet you make works in both Mischi and Codex. It's a folder with two files:

biscuit/
├── pet.json
└── spritesheet.webp

Hatch one with Codex

The quickest way to a new pet is to let Codex draw it. OpenAI's hatch-pet skill turns a description or a reference image into a finished pet with every animation.

1. In the Codex app, open Settings → Pets and choose Create pet. Codex installs the hatch-pet skill and starts a new chat.
2. Describe your pet, or attach a picture: your cat, a mascot, a doodle. You can ask for a style too, like pixel, plush, clay or sticker.
3. Codex draws every animation and saves the pet to ~/.codex/pets/<name>/.
4. In Mischi, open Preferences → Pet and click Scan Codex.

OpenAI's Codex pets guide has the details, including the sprite sheet rules Codex checks.

The spritesheet

To draw a pet yourself, or to check one before sharing it, here's the layout:

Each row is one animation, with frames running left to right. Codex orders the rows like this:

Mischi doesn't rely on that exact order. It plays row 0 as the default loop, works out how many frames each row has, and lets you name every row in Preferences → Animations.

pet.json

A Codex pet needs only a few fields:

{
  "id": "biscuit",
  "displayName": "Biscuit",
  "description": "A sleepy corgi who supervises your commits.",
  "spritesheetPath": "spritesheet.webp"
}

For finer control, Mischi also reads frameWidth, frameHeight, columns and an animations map. Each entry takes a row, frameCount, fps and loop, keyed by idle, waving, jumping, failed, review, running, running-right or running-left. Mischi ignores fields it doesn't know, so the file still works in Codex.

"animations": {
  "idle":   { "row": 0, "frameCount": 6, "fps": 8,  "loop": true },
  "waving": { "row": 3, "frameCount": 4, "fps": 10, "loop": false }
}

Draw one by hand

Any pixel art or animation tool works, such as Aseprite, Pixelorama or Photoshop. Set up a 1536 × 1872 canvas with a 192 × 208 grid, draw each animation left to right in its own row, and export a transparent WebP or PNG. Write a pet.json next to it, then import the folder.

Troubleshooting

Still stuck? Tell us what's happening.

Uninstall & reset

Choose Quit Mischi from the menu, then drag Mischi from Applications to the Trash.

Your pets and settings stay on your Mac in case you reinstall. To remove everything, quit Mischi first and run this in Terminal:

rm -rf ~/Library/Application\ Support/mischi
rm -rf ~/Library/Application\ Support/Standalone\ Codex\ Pets
defaults delete app.mischi.mac

If you added a Groq key, open Keychain Access, search for app.mischi.mac and delete the entry.

Get help

Found a bug or have an idea? In Mischi, go to Preferences → About → Found a bug? and click Report it. It opens our contact page with your app and macOS versions already filled in.

You can also write to us directly, or check the FAQ for quick answers.