OWNER'S MANUAL • V0.2
MUNCHLING
A VIRTUAL PET FOR YOUR CLAUDE CODE SESSIONS (OR JUST YOUR DESK)
SPECIES: NOMLING VORAX • DIET: TOKIVORE
The original blob. Eats tokens plain, and plenty of them.
1 Anatomy of the Screen
- LEVEL:⌊√XP⌋ + 1, top left.
- XP BAR:progress to the next evolution stage.
- THE PET:mood, animation, current business.
- FULLNESS / ENERGY:bottom pips. Left 5: how fed. Right 5: how rested.
2 Feeding & Care
The Nomling is a tokivore: its natural diet is the tokens your Claude sessions burn. No sessions, no dinner.
What the stats do
| Stat | Goes up when… | Goes down when… |
|---|---|---|
| Hunger | time passes | Claude burns tokens; you feed snacks |
| Energy | the pet rests (idle) | sessions are running |
| Mood | tasks finish, pokes, meals | tool errors; hungry or exhausted |
| XP | tools +1, tasks +10, egg pokes +1 (companion: tasks +10, feed +1, play +2) | never |
Snacks
Every completed Claude task drops one snack, and your nomling also forages one on its own every 30 minutes. Even while the app is closed (max. 5 stored). The FEED button in settings spends one: −15 hunger, +3 mood, and a very satisfied chewing animation. A full or snackless pet refuses with a shake.
3 Evolution
The pet physically grows on the screen: babies render at 2×, teens and adults at 3×. A teen sprouts a single antenna; the adult grows a full pair. Each threshold plays the evolve animation, sparkles included.
4 Moods & Sprite Gallery
| You see… | Because… |
|---|---|
| WORKING | Claude is mid-task, tools firing |
| CELEBRATE | Claude just finished a task (+10 XP, +1 snack) |
| GRUMPY | a tool call errored (−4 mood) |
| ALERT | Claude is waiting for you, go answer it |
| EATING | a big token meal just landed |
| SLEEPY | the session has run past 90 minutes |
| SLEEPING | no session and energy is low, it recovers on its own |
| HUNGRY | fullness is nearly empty; work or feed a snack |
| DANCING | DANCE TO MUSIC is on and your PC is playing audio |
5 Controls
| Action | Effect |
|---|---|
| Click the pet or shell | Poke (eggs: +1 XP toward hatching) |
| Press and move | Drag the widget, it sticks to your cursor |
| Right-click | Open the settings window |
| Drag settings title bar | Park the panel anywhere on your desktop |
| Tray icon | Settings, show/hide, click-through, quit |
6 Companion Mode
Don't use Claude Code? On first launch, Nomlings asks which kind of
pet you want. Pick companion mode and the hook
server and transcript watcher never start: nothing is written into
~/.claude, and there's no server.json
either. Everything below replaces Claude activity as the pet's food
source.
| Source | Reward | Limit |
|---|---|---|
| Check off a task or habit | +10 XP, +1 snack | once per task per day |
| PLAY | mood boost, +2 XP | +2 XP at most once every 30 minutes |
| FEED | −15 hunger, +3 mood, +1 XP | needs a snack |
Tasks & habits
Add a one-off task or a DAILY habit from the TASKS
section in settings. Daily habits reset at your local midnight.
Completing one is final for the day: unchecking it doesn't refund the
XP, and rechecking it doesn't pay out twice.
Switch modes any time from the MODE section in settings; the change takes effect after a restart (a button offers to do that for you).
7 Settings Reference
| Setting | What it does |
|---|---|
| FEED | Spend a snack (−15 hunger, +3 mood; companion: +1 XP too) |
| PLAY | Mood boost any time; +2 XP at most once every 30 minutes |
| PET TYPE | Claude pet or companion pet; takes effect after a restart |
| SIZE | Scale the widget 70–130% (applies on release) |
| MENU | Scale this settings panel 80–180% |
| CHARACTER | Swap the pet's body from your cosmetic pack; XP and snacks stay put |
| SHELL | Pick the device's shell style |
| SCREEN / PET / SHELL COLOR | Recolor the LCD, the pet, and the shell; RESET COLORS restores the stock green |
| FLOAT | The gentle bobbing; off freezes the device |
| HINTS | Orange 8-bit hint text and button tooltips |
| DANCE TO MUSIC | The pet grooves to whatever your PC is playing |
| ALWAYS ON TOP | Keep the pet above other windows |
| CLICK-THROUGH | Clicks pass through the pet; return via the tray |
| RUN AT STARTUP | Launch Nomlings at login |
| CHECK UPDATES | Look for new versions on GitHub; updating stays your call |
| NEW EGG | Fresh start (asks SURE? first) |
8 Troubleshooting
| Symptom | Fix |
|---|---|
nomling not found | Open a new terminal (the installer adds it to PATH), or
run nomling setup from the install folder. |
| Pet ignores my sessions | nomling setup, then start a new Claude session,
since hooks load at session start. |
| Widget vanished | Tray → Show / Hide. |
| Clicks do nothing | Click-through is on; turn it off from the tray. |
| Starving after a holiday | Working feeds it fastest; snacks help now. It cannot die. |
| settings.json won't merge | Nomlings refuses to touch invalid JSON. Your backup: settings.json.nomling.bak. |
9 Files & Privacy
| File | Purpose |
|---|---|
~/.nomling/state.json | Pet stats |
~/.nomling/settings.json | Widget preferences |
~/.nomling/window.json | Last position |
~/.nomling/server.json | Local event port (deleted on quit) |
Your sessions stay on your machine. Nomlings reads token counts and event types (never the content of your prompts, code, or conversations) and sends none of it anywhere. The app only reaches the network to check for a new version and to activate the cosmetic pack.
THANK YOU FOR ADOPTING A NOMLING