Your API quota is rotting. Mom is disappointed.
A desktop mascot that guilt-trips you into using your Claude Code tokens β just like a real Korean mom.
| Angry | Worried | Happy | Proud |
|---|---|---|---|
| π‘ "You haven't used any today?!" | π "Everyone else is using theirs..." | π "That's my kid!" | π₯Ή "Mom's buying chicken tonight~" |
| < 15% usage | 15β50% usage | 50β85% usage | 85%+ usage |
Claude Mama is a tiny desktop widget that monitors your Claude Code API usage and reacts with the emotional range of a Korean mother who just found out you skipped dinner.
- Using too little? She's angry. She didn't raise you to waste a perfectly good API quota.
- Using a moderate amount? She's worried. The neighbors' kids are using more.
- Using a healthy amount? She's happy. Finally, some return on investment.
- Maxing it out? She's proud. Tears are streaming. Chicken is being ordered.
"Other moms worry their kids use too much computer. Claude Mama worries you don't use enough."
- Real-time usage tracking β Pulls 7-day and 5-hour utilization from the Anthropic OAuth API, with smart JSONL session fallback when rate limited
- Pixel art character β A pixel-art mama with curler hair and 6 mood expressions (angry, worried, happy, proud, confused, sleeping)
- Guilt-powered messages β Randomized mom-style messages that rotate every 2 minutes
- Contextual messages β Situation-aware messages for weekends, unused streaks, usage spikes, and reset warnings (200+ new localized messages across 4 languages)
- 5-hour burnout warning β "Take a break~ You're almost at the limit!" (she cares, in her own way)
- Achievement Badges β Unlock 9 badges across Bronze, Silver, and Gold tiers for streaks, milestones, and achievements
- Share Report Card β Save a shareable PNG card with your current mood, usage stats, and reset countdown
- Quote Collection (λκ°) β Collect 86 unique mama quotes across 4 rarity tiers (Common, Rare, Legendary, Secret)
- Custom Character Skins β Upload your own character images with single, per-mood, or sprite sheet modes
- Always on Top β Toggle in Settings or tray menu (default ON) to keep mama visible above other windows
- System tray β Lives quietly in your taskbar, judging you silently
- Settings panel β Position, auto-start, language selection, collection viewer, and skin customization
- 4 languages β νκ΅μ΄, English, ζ₯ζ¬θͺ, δΈζ
- Auto-start β Boots with your OS so you can never escape mom's watchful eye
- Auto-update β Mom keeps herself up to date via GitHub Releases
Save your current mama status as a PNG image β perfect for sharing on social media.
The card includes mood, quote, 7-day/5-hour usage bars with reset countdowns, and a UTC timestamp.
Mama has 86 unique quotes spread across 4 rarity tiers:
| Rarity | Count | How to Unlock |
|---|---|---|
| βͺ Common | 73 | Displayed during normal use |
| π΅ Rare | 5 | Hit specific usage milestones (0%, 50%, 100% of 5hr, etc.) |
| π‘ Legendary | 3 | Achieve streaks and lifetime milestones |
| π΄ Secret | 5 | Use the app on holidays or at 3 AM |
Unlock badges for hitting milestones and maintaining streaks. View your collection in Collection tab β Badges.
| Tier | Badge | How to Unlock |
|---|---|---|
| π₯ Bronze | First Steps | Make your first API call |
| π₯ Bronze | 3-Day Streak | Use Claude Code on 3 consecutive days |
| π₯ Bronze | 7 Days with Mom | Use the app for 7 consecutive days |
| π₯ Silver | Halfway There | Hit 50% of your weekly quota |
| π₯ Silver | 7-Day Streak | Maintain a 7-day usage streak |
| π₯ Silver | Mom's Pride | Get 10 "proud" expressions (85%+ usage) |
| π₯ Gold | Full Power | Reach 100% of your weekly quota |
| π₯ Gold | 30-Day Streak | Maintain a 30-day usage streak |
| π₯ Gold | Survivor | Get 10 "angry" expressions AND keep using the app |
Give mama a new look with custom character images:
- Single Image Mode β One image displayed for all moods
- Per-Mood Mode β 6 images (one for each mood expression: angry, worried, happy, proud, confused, sleeping)
- Sprite Sheet Mode β Advanced mode with one image and grid configuration for frame positioning
Upload your custom skins in Settings β Skins and switch between them anytime. Mom might judge your art choices, but she'll wear them anyway.
- Claude Code must be installed and logged in (OAuth)
- That's it. Mom doesn't ask for much.
Grab the latest installer from Releases:
| Platform | File | Arch |
|---|---|---|
| Windows | Claude Mama Setup x.x.x.exe |
x64 |
| macOS | Claude Mama-x.x.x.dmg |
Universal (Intel + Apple Silicon) |
| Linux | Claude Mama-x.x.x.AppImage |
x64 |
| Linux | claude-mama_x.x.x_amd64.deb |
x64 |
β οΈ Not code-signed: Claude Mama is not code-signed yet, so your OS will show a security warning on first install.
- Windows: SmartScreen will say "Windows protected your PC." Click More info β Run anyway.
- macOS: You'll see "cannot be opened because the developer cannot be verified." Go to System Settings β Privacy & Security β Open Anyway.
- Linux (AppImage):
chmod +x Claude\ Mama-*.AppImage && ./Claude\ Mama-*.AppImage- Linux (deb):
sudo dpkg -i claude-mama_*.deb
- Make sure Claude Code is installed and logged in (
claudein terminal) - Claude Mama will automatically detect your API usage via OAuth
- If rate-limited (429), it falls back to local JSONL session parsing β no extra config needed
- Mama starts polling every 5 minutes. Just let her do her thing.
- Auto-start: Enabled by default. Claude Mama starts with your OS. Toggle in Settings if you dare.
- Auto-update: Updates are downloaded automatically from GitHub Releases. When a new version is ready, mama will ask you to restart.
βββββββββββββββββββ ββββββββββββββββ βββββββββββββββ
β Anthropic OAuth βββββ>β Usage Tracker ββββ>β Mood Engine β
β Usage API β β (5min poll) β β β
βββββββββββββββββββ ββββββββ¬ββββββββ ββββββββ¬βββββββ
β β
ββββββββ΄ββββββββ βββββββββ
β JSONL Sessionβ β
β Parser (429) β v
ββββββββββββββββ ββββββββββββββββ
β Pixel Art β
ββββββββββββββββ ββββββββββββββββ β Character β
β Speech β β Usage Bar β ββββββββββββββββ
β Bubble β β Indicator β
ββββββββββββββββ ββββββββββββββββ
- Polls the Anthropic usage API every 5 minutes
- Falls back to JSONL session parsing when rate limited (429) β scans
~/.claude/projects/session files to estimate usage with dynamic calibration - Computes mood based on weekly utilization thresholds
- Renders a pixel-art mama character with mood-appropriate expression and message
- Nags you until you use your tokens like a responsible adult
| Weekly Usage | Mood | Mom Says |
|---|---|---|
| 0β14% | π‘ Angry | "Your quota is rotting away!" |
| 15β49% | π Worried | "Mom is worried about you..." |
| 50β84% | π Happy | "Now that's what I like~" |
| 85β100% | π₯Ή Proud | "Perfect! I'm tearing up..." |
| 5hr > 90% | "Take a break~ 5-hour limit almost reached!" | |
| Rate limited | π΅ Confused | Uses local session data, or "Collecting data..." while calibrating |
| API error | π΅ Confused | "Something went wrong..." |
| No login | π΄ Sleeping | "Log in first!" |
Note: The Claude Code usage API (
api/oauth/usage) has strict rate limits. When rate limited (429), Claude Mama parses local session JSONL files (~/.claude/projects/) to estimate usage. It learns the token-to-percent ratio from successful API responses (dynamic calibration), so estimates improve over time. While waiting for the first successful calibration, mama shows "Collecting data..." and retries every 10 seconds.
# Install dependencies
npm install
# Run in development mode
npm run dev
# Run tests
npm test
# Build for production
npm run build
# Build Windows installer
npm run build:win
# Build macOS installer (requires macOS)
npm run build:macQ: Can I hide from Claude Mama? A: No. She auto-starts with your OS. You can disable it in settings, but she'll know.
Q: Why does she speak Korean by default? A: Because Korean moms are the gold standard of guilt-tripping. You can switch to English, Japanese, or Chinese in settings if your guilt receptors are calibrated differently.
Q: My usage is at 0% but I've been coding all day? A: Make sure Claude Code is logged in. Mom can't monitor what she can't see.
Q: How do I unlock secret quotes? A: Use the app on holidays (New Year, Chuseok, Christmas) or stay up coding past 3 AM. Mom notices everything.
Q: Is this a joke? A: The guilt is real. The chicken reward is not (yet).
Q: Will there be a Claude Dad version? A: Claude Dad went out for tokens and never came back.
PRs welcome! Whether it's new languages, more guilt-inducing messages, or pixel art improvements β mom appreciates the help.
- Fork this repo
- Create your feature branch (
git checkout -b feature/more-guilt) - Commit your changes
- Push to the branch
- Open a Pull Request
This program will not transfer any information to other networked systems unless specifically requested by the user or the person installing or operating it.
- Anthropic API: The app calls the Anthropic OAuth Usage API to retrieve your token usage statistics. This is initiated by you when you log in with your Claude Code credentials.
- GitHub (Auto-Update): The app checks GitHub Releases for new versions. No personal data is transmitted.
- Local Storage: Your API credentials and settings are stored locally on your machine using
electron-store. They are never sent to any third-party server.
Free code signing provided by SignPath.io, certificate by SignPath Foundation.
Team roles:
ISC β Free as in "mom's love" (unconditional, but with expectations).
Built with guilt and β€οΈ
If this made you mass-consume your Claude API quota, please star the repo. Mom would be proud.