Tokengotchi
Leer en español: README.es.md
Not affiliated with, endorsed by or sponsored by Anthropic. "Claude" is a trademark of Anthropic.
A tamagotchi-style pet that lives on your AI coding tokens. It sits in the VS Code sidebar and works with Claude Code today (more AI tools may follow).
Feed it cookies, play with it, put it to bed and brush off the crumbs. It grows as it eats, gets tired when Claude Code burns through tokens, gets stressed as you approach your plan limits, and follows Claude Code live while it works.
Features
- 🍪 Classic pet care: cookies, play, sleep and cleaning, with four stats and a mood.
- 🌱 Four growth stages unlocked by cookies eaten, Digimon-style: Bitmon → Tokenmon → Promptmon → a crowned MegaTokenmon.
- 😮💨 Token fatigue: Claude Code token usage (read from local transcripts) drains its energy.
- 😱 Limit stress: the 5-hour session and weekly limits make it stressed, then panicked.
- 💻 Live Claude Code activity: a laptop, a tool chip and code sparks while Claude works.
- 🐣 Mini pets for subagents: a "mini" pops out for every subagent and merges back when it finishes.
- 🔔 Notifications when it is hungry, sleepy or covered in crumbs, and at 80 % of a limit.
- 💾 Reward on save: saving files makes it happy (at most once every 5 minutes).
- 📊 Status bar item with name, face and 5 h usage; it spins while Claude is working.
- 🌐 6 languages, including the VS Code commands and settings.
- ☰ Menu in the panel for language, mode, limits, settings and starting over.
How it works
Open the spark icon in the Activity Bar, or click the Tokengotchi item in the status bar. The pet keeps living while VS Code is closed: when you come back, the elapsed time is applied (up to 48 hours).
Stats and cookies
All stats go from 0 to 100.
| Stat |
Goes down |
How to raise it |
| 🍪 Fullness |
8 per hour |
Cookie (+18) |
| ❤️ Happiness |
5 per hour; faster when hungry or dirty |
Play (+15), cookie (+6), click the pet (+2), save a file (+2), clean (+3) |
| ⚡ Energy |
tokens mode: only Claude Code tokens. time mode: 4 per hour awake and 12 per play |
Sleep (+20 per hour, wakes up by itself when full); a 5 h session reset (+30) |
| ✨ Cleanliness |
3 per hour and 7 per cookie (crumbs) |
Clean (back to 100) |
- When it is full (fullness ≥ 95) it refuses cookies and gets a little grumpy.
- Below 15 energy it does not want to play.
- In
tokens mode, time drains fullness, happiness and cleanliness at a quarter of the speed, and playing costs only 3 fullness.
- While sleeping it does not eat or play, but you can still clean it.
Stages
| Stage |
Cookies eaten |
| 🥚 Bitmon |
0 |
| 🔹 Tokenmon |
10 |
| 💬 Promptmon |
40 |
| 👑 MegaTokenmon (with a crown) |
100 |
Stage names are localized (for example トークンモン in Japanese, 令牌兽 in Chinese).
Token fatigue
In tokens mode (the default), Claude Code's work is what tires the pet the most. The extension reads the local Claude Code transcripts (~/.claude/projects/**/*.jsonl) and adds up the usage numbers of each new response.
effort = input + cache write + output × 5 + cache read × 0.1
- Every
tokengotchi.tokensPorPunto effort tokens (default 40,000) take 1 energy, 0.66 fullness and 0.5 happiness.
- If it works with less than 20 energy, happiness drops twice as fast. The closer you are to a plan limit, the more each token saddens it (up to double).
- If Claude starts working while it sleeps, it wakes up (and does not like it).
- The first run does not count old history: it starts from the moment the extension is installed. Usage that happened while VS Code was closed is applied when you reopen it.
Set tokengotchi.modo to tiempo for the classic tamagotchi, where only time lowers the stats.
Plan limits and mood
Claude Code reports the percentage used of the 5-hour session and of the weekly limit (Pro, Max and Ultra plans). The pet reacts like this:
| Mood |
5-hour session |
Week |
| Stressed 😬 |
≥ 60 % |
≥ 75 % |
| Panicking 😱 (shakes) |
≥ 85 % |
≥ 90 % |
| Out of juice |
100 % |
100 % |
- When the 5 h session resets, it recovers: +30 energy and +10 happiness.
- Above 80 % of the session or the week, a notification tells you when it resets.
- The panel shows both bars with their reset time; the status bar shows the session %.
Where the numbers come from
/usage (main source). The 🔄 button, the ☰ menu or the Check limits (/usage) command run claude -p --no-session-persistence /usage. It is a local Claude Code command: it does not ask the model anything, uses no tokens and leaves no session file. It also runs automatically every 15 minutes while the VS Code window is focused (tokengotchi.consultarUsageCadaMin, 0 = manual only).
- Claude Code statusLine (optional, see below). Claude Code passes the percentages to the script on every response.
- Fallback: the cached copy Claude Code keeps in
~/.claude.json (undocumented). It is used when it is newer, and the panel shows how old the data is.
Live Claude Code activity
The pet watches Claude Code transcripts as they are written (file watching plus a quick read of active sessions every 1.5 s), so it reacts to what happens in the terminal or in the Claude Code panel:
- 💪 You send a prompt: it gets ready to work. If it was asleep, it wakes up.
- 💻 Claude is working: it pulls out a laptop, types, spins its rays and code sparks fly out. A tool chip below says what is going on: running a command, reading, editing, searching, on the web, thinking…
- 🐣 Claude launches a subagent: a mini Tokengotchi pops out, labeled with the agent's short description (or its type). Each mini has its own color, hops every time its agent uses a tool and shows which one.
- 📦 The subagent finishes: the mini flies back and merges into the pet. Background agents come back when they really finish.
- 😬 Something fails: it gets worried.
- 🎉 End of turn: it celebrates with a summary (tools used, minis and tokens). If the turn was heavy, it sweats.
- 🔄 Status bar: a spinning icon while Claude works, plus the number of active minis.
Commands
All commands are in the Command Palette under Tokengotchi.
| Command |
What it does |
Also in |
| Open pet |
Focuses the pet view |
Status bar item |
| Give cookie |
Feeds a cookie |
Panel title bar, panel button |
| Play |
Plays with the pet |
··· menu, panel button |
| Sleep / wake up |
Toggles sleep |
··· menu, panel button |
| Clean crumbs |
Cleans the pet |
··· menu, panel button |
| Check limits (/usage) |
Runs claude -p /usage and updates the limits |
Panel title bar, ☰ menu, panel button |
| Change language |
Language quick pick |
Panel title bar, ☰ menu |
| Open settings |
Opens the extension settings |
Panel title bar, ☰ menu |
| Start over |
Resets the pet (asks for confirmation) |
··· menu, ☰ menu |
Settings
| Setting |
Default |
Description |
tokengotchi.idioma |
auto |
Pet language: auto, es, en, zh-cn, pt-br, fr, ja. auto uses the VS Code language. |
tokengotchi.modo |
tokens |
What drains the stats: tokens (Claude Code usage) or tiempo (time only, classic). |
tokengotchi.tokensPorPunto |
40000 |
Effort tokens that cost 1 energy point (minimum 1000). Lower = tires faster. |
tokengotchi.consultarUsageCadaMin |
15 |
Minutes between automatic /usage queries, only while the window is focused. 0 = manual only. |
tokengotchi.rutaClaude |
"" |
Path to the Claude Code executable. Empty = ~/.local/bin/claude or whichever is on the PATH. |
tokengotchi.carpetaClaude |
"" |
Claude Code data folder. Empty = CLAUDE_CONFIG_DIR or ~/.claude. |
tokengotchi.avisos |
true |
Notifications when the pet is hungry, sleepy or covered in crumbs. |
tokengotchi.premiarAlGuardar |
true |
Saving files makes the pet happy (at most once every 5 minutes). |
Languages
Español, English, 简体中文, Português (Brasil), Français and 日本語. With tokengotchi.idioma set to auto, the pet follows the VS Code display language; if there is no translation for it, it uses English. Commands and settings are localized too.
Privacy
- Everything runs locally. Nothing is sent anywhere.
- From the Claude Code transcripts it reads only usage numbers, event types and tool and agent names (plus the agent's short description to label minis). It never reads or stores conversation content.
- To check limits it runs your local
claude CLI with /usage, which does not use tokens.
- It writes two small files in
~/.claude/tokengotchi/ (limites.json with the limit percentages and mascota.json with the pet's name and face for the statusLine).
Optional statusLine setup
If you use Claude Code in a terminal, statusline.js can show the pet and the limits in Claude Code's status line, and it saves the percentages for the extension on every response. It needs Node.js on the PATH.
Add this to ~/.claude/settings.json:
"statusLine": {
"type": "command",
"command": "node \"<extension-or-repo-folder>/statusline.js\""
}
statusline.js ships inside the extension, but the installed extension folder name includes the version and changes on every update; pointing to a copy of the repository is more stable.
The line looks like 🍪 Claude 😄 · 5h 42% (resets 18:30) · week 18% (Mon 13:00).
Requirements
- VS Code 1.85 or newer.
- Claude Code installed (for token fatigue, live activity and
/usage).
- Plan limits need a Pro, Max or Ultra plan.
Known limitations
- The Claude Code panel inside VS Code does not seem to run the statusLine; it only updates when you use Claude Code from a terminal.
/usage and the ~/.claude.json cache still work.
- The
/usage output is parsed from its English text. If Claude Code changes that text, the query may stop working.
- An interrupted turn has no end event: the pet stops "working" after 90 seconds without activity.
Contributing translations
- Copy
i18n/es.json to i18n/<code>.json and package.nls.es.json to package.nls.<code>.json.
- Translate the values only. Keep the keys and the
{placeholders} ({n}, {tipo}, …) exactly as they are, and set meta.codigo to your code.
- Add the code to the language list in
idioma.js and to the enum of tokengotchi.idioma in package.json.
- Run
node scripts/validar-i18n.js <code>.
Spanish is the base: anything missing from a translation falls back to Spanish.
Development
npm test # unit tests + translation check
npx @vscode/vsce package # build the .vsix
Open the folder in VS Code and press F5 to launch an Extension Development Host with the extension loaded.
License
MIT
| |