🌱 Token Sprite

English · 中文

Burning tokens, growing neurons.

Turn your real AI usage into a tiny desktop companion that hatches, evolves, and bonds with you — and recaps what you actually learned each day. Works even if you only use web-based AI.

CODE → HATCH → EVOLVE → COLLECT

Write code, earn real tokens, hatch mystery eggs, evolve through five stages, and complete your collection.

macOS · Windows · Linux · Local-only · Nothing uploaded

🤖 Let your AI agent install it

Paste this to Claude Code, Codex, or any terminal-capable agent:

install and run github.com/shiyubao78/token-sprite

It reads AGENTS.md in the repo and installs it as a real app — no download, no unzip, no Gatekeeper prompt.

Prefer doing it by hand? ⬇️ Download the app — first launch needs right-click → Open (unsigned build, just once).

🥚 Hatch & Evolve

Choose an egg and feed it with the tokens you actually use, from first crack to final form.

Six elements, six complete evolution lines: flora, ocean, magma, thunder, mech, and ice. You won't know who's inside until the egg hatches.

Got duplicate eggs of the same species? Merge them in the incubator — progress stacks and you earn bonus tokens by rarity, fast-tracking a favorite.

✨ Why It's Different

• Powered by real work — it grows from your actual local AI-tool token usage. Not just coding: writing PRDs, building demos, authoring skills, digging through docs — if you asked Claude Code or Codex, it counts.
• A companion, not a counter — it nudges you to rest, reminds you to sleep late at night, and waves when you return. After its final form it forms a growing bond with you the more you code.
• See usage and cost — a Usage Insights panel breaks tokens down by day, tool, and hour, and converts them into a rough dollar value of what you've used.
• Grow yourself, not just the pet — the Growth Journal hands you what's worth learning (explained), the to-dos you mentioned (editable), and a daily history. No Claude Code / Codex required — paste one prompt into whatever AI you're already using and bring its answer back.
• Always on your desktop — floating, always on top, draggable, and able to peek quietly from the screen edge.
• Hatch and collect — achievements unlock eggs; eggs evolve into creatures for your collection.
• Bilingual — full English & 中文, switch anytime from the menu. Follows your system language by default.
• Private by design — usage stays on your machine and is never uploaded; only released builds check GitHub for new versions.

🏆 Achievements & Hatching

Complete achievements to earn egg tickets. Each ticket usually matches its rarity, with a 15% chance to upgrade by one tier. Early achievements are quick, so you can collect the first few species in days and pick a favorite.

Every draw gives you an egg. Keep coding to complete all five stages, and its final "Awakened" form joins your collection.

Balance values live in src/config/achievements.js and src/config/rarities.js.

🖥️ A Look Inside

Fully local, no login — one floating window: rename, draw, hatch, collect, earn achievements, track usage & cost, and bond after final form.

📊 Usage & Cost Insights

Open Usage Insights from the menu to see how many tokens you wrote today and over the last 7 days, each tool's share, and your most productive hours. It also turns usage into a rough dollar estimate (with an adjustable per-million rate) so you get a feel for what your usage is worth. Everything is read from local logs only, never uploaded.

After it reaches its final form, the companionship continues: coding and playful pokes level up your bond, unlocking warmer reactions over time.

🧠 Growth Journal

Burning tokens shouldn't mean outsourcing your brain. Open the Growth Journal and your sprite reviews today's AI-coding chats — through your own local Claude / Codex — and gives you back:

• Takeaways — the concepts you leaned on, actually explained, so you learn them.
• To-dos — things you said you'd do (commit, add tests, book a flight), editable and one-tap done; regenerating refreshes them without overwriting what you touched.
• Daily history — it all persists locally, building a trail of how you grow.

Everything runs through the AI you already use; nothing is uploaded to a third party.

🍃 No CLI installed? Still works

Only use web-based AI (Doubao, ChatGPT, whatever)? Borrow its own strength:

1. Click Copy prompt in the Growth Journal
2. Paste it into the AI you're already chatting with
3. Bring its answer back — press ⌘⇧V or drop it on the sprite

Its context already holds today's conversation, so you never copy the chat itself — just bring the answer back and it lands straight in your journal.

🥢 Feed it anything

Spot something worth keeping? Select and drag it onto the sprite, or copy it and hit ⌘⇧V. It holds onto those until the next recap, then digests them together with the day's chats.

The shortcut reads your clipboard only at the moment you press it — never in the background. Watching your clipboard around the clock would mean reading every password and private message you copy; not worth it.

🚀 Quick Start

Requires Node.js 20+ and runs on macOS, Windows, and Linux.

🤖 Let your agent install it (recommended)

You're already using Claude Code / Codex — skip the download entirely. Send it this:

Install and run github.com/shiyubao78/token-sprite for me.

The repo ships an AGENTS.md, so your agent clones it, builds it, installs it into Applications and launches it — a real app that survives closing your terminal and starts on login.

You'll see ✅ 已安装并重新打开 vX.Y.Z when it's done. No line, no install — ask your agent to check the error.

🔄 Let your agent update it

One line again — your growth data is kept:

Update token-sprite to the latest version for me.

It runs git pull + npm install, and the installed app updates itself automatically (npm install triggers a reinstall). Your data lives in ~/Library/Application Support/token-sprite/, outside the app bundle, so reinstalls never touch it.

⬇️ Prefer to install it yourself?

1. Download the latest .zip from Releases and double-click to unzip.
2. Drag Token Sprite into your Applications folder.
3. Right-click the app → Open, then confirm Open in the dialog.

Step 3 is where people get stuck. If you double-click instead, macOS blocks it and offers only Move to Trash — don't. Right-click once and you're past it permanently.

Why does this happen? Signing a Mac app requires Apple's $99/year developer membership, which this project hasn't paid for. The entire source is public, so you can read it or build it yourself.

Released builds notify you when a new version is out; the menu-bar icon → Check for Updates opens the download page. Your growth data is kept across reinstalls.

git clone https://github.com/shiyubao78/token-sprite.git
cd token-sprite
npm install
npm start        # dev mode — closing the terminal kills it, and it won't start on login

npm run install:local   # build + install into Applications + launch + verify, in one command

🧩 How It Works

The app detects supported AI tools and reads token usage from local logs. Missing tools are skipped automatically, and your data never leaves your computer.

A baseline is recorded on installation. Only new usage counts toward your sprite's growth.

Only tools that store parseable usage logs locally can be counted. Cloud-only usage is not accessible.

Add another tool

If tools like Gemini CLI, OpenCode, or Aider write usage to local logs, add a reader in the READERS array of scripts/usage.mjs:

async function readYourTool() {
  const root = join(homedir(), '.yourtool');
  if (!(await exists(root))) return null;
  let total = 0, recentTokens = 0, todayTokens = 0, lastActivityAt = 0;
  // Parse local logs and accumulate usage.
  return { total, recentTokens, todayTokens, lastActivityAt };
}

export const READERS = [
  /* existing readers */
  { source: 'yourtool', label: 'Your Tool', read: readYourTool },
];

Or just ask your agent:

Inspect my local <tool> usage logs and add a reader to token-sprite.

📦 Package the Desktop App

Run the matching command on the target operating system. Builds are written to release/.

npm run pack              # macOS universal app
npm run pack:mac:release  # macOS universal DMG + ZIP + update metadata
npm run pack:win          # Windows portable app + installer
npm run pack:linux        # Linux AppImage

• macOS: without a Developer ID certificate, builds are unsigned; right-click → Open the first time. Official releases should be signed and notarized.
• Windows: if SmartScreen blocks it, choose More info → Run anyway.
• Linux: make the AppImage executable first; transparency and always-on-top depend on your desktop environment.
• Packaging must run on its target OS. GitHub Actions can also build all three platforms.

🔧 Customize

• Species, rarity, names, and artwork: src/config/species.js
• Achievements, thresholds, and odds: src/config/achievements.js, src/config/rarities.js
• Custom artwork: assets/sprite/<species>/1-seed.png … 5-adult.png

Each stage uses a 512×512 transparent PNG.

📄 License

Noncommercial. Commercial use is not permitted.

• Source code: PolyForm Noncommercial 1.0.0
• Art assets (assets/**): CC BY-NC 4.0

Free for personal, educational, and nonprofit use; assets require attribution. Built-in artwork is AI-generated as an example and can be replaced.