🌱 Token 小精灵 / Token Sprite

English · 中文

烧的是 token，长的是脑子。

Every token you write helps it grow.

把真实的 AI 编程用量变成一只住在桌面角落、一路破壳进化的小精灵——化形后和你结下羁绊，还顺手告诉你写了多少、花了多少。

Turn your real AI-coding usage into a tiny desktop companion that hatches, evolves, and bonds with you—while showing how much you have written and roughly spent.

CODE → HATCH → EVOLVE → COLLECT

写代码获得真实 Token → 达成成就抽精灵蛋 → 五段进化 → 收进图鉴。

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

macOS · Windows · Linux · 本地读取 / Local-only · 不上传 / Nothing uploaded

🤖 让你的 AI Agent 帮你装 / Let your AI agent install it

把这句话发给 Claude Code、Codex 或任何能操作终端的 Agent：

帮我安装并运行 github.com/shiyubao78/token-sprite

它会读仓库里的 AGENTS.md，直接装成常驻 app——不用下载、不用解压、也不会被系统拦。

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

想自己动手？⬇️ 也能下载安装包：第一次打开要右键点图标 → 选「打开」（未签名，只需这一次）。

🥚 孵化与进化 / Hatch & Evolve

选一颗蛋，它会吸收你真实使用掉的 Token，从破壳一路成长到最终化形。

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 will not know who is inside until the egg hatches.

抽到重复的同类蛋？在孵化器里一键合并——喂养进度全累加，还按稀有度额外送 token，加速孵一只喜欢的。

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：读取本地 AI 编程工具的真实 Token 用量，用多少就长多少。不限于写代码——你拿 Claude Code / Codex 写 PRD、做 demo、写 skill、查资料，一样在喂它。 / It grows from your actual local AI-tool usage — not just coding: writing PRDs, building demos, authoring skills all count.
• 会陪你 / A companion, not a counter：连续工作会劝你休息，深夜会提醒早点睡，久别重逢会向你招手；化形后还会和你结下羁绊，越写越亲。 / It nudges you to rest, sleep, and come back—and after final form it forms a growing bond with you the more you code.
• 看得见用量和花费 / See usage and cost：用量洞察面板显示今日/近 7 天写了多少 token、按工具占比、活跃时段，还能折算成约多少钱（美元、粗略估算），当作「你的用量值多少钱」的参考。 / A panel breaks down tokens by day, tool, and hour, and converts them into a rough dollar value of what you've used.
• 桌面常驻 / Always on your desktop：悬浮置顶、自由拖动，也能缩成侧边探头。 / 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.
• 借 AI 的力，长自己的筋骨 / Grow yourself, not just the pet：成长日记用你本机的 AI 回顾今天和 AI 的对话，把值得学的知识点讲给你、把你说过要做的事收成可编辑的待办，还能每天回看——用 AI 帮你长本事，而不只是烧 token。 / The Growth Journal reviews today's AI-coding chats through your own local AI and gives you what's worth learning (explained), editable to-dos, and a daily history — so you grow your own skills, not just burn tokens.
• 全本地私密 / Private by design：只读本机日志，用量绝不上传；仅正式版会向 GitHub 查询有无新版本。 / Usage stays on your machine and is never uploaded; only released builds check GitHub for new versions.

🏆 成就与抽蛋 / Achievements & Hatching

达成成就获得抽蛋券；每张券大概率开出对应稀有度，并有 15% 概率提升一档。新手期门槛低、发券快，前几天就能集齐前 4 只、挑一只重点养。

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 add its final form to your collection.

数值可在 src/config/achievements.js 与 src/config/rarities.js 调整。

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

菜单 → 用量洞察：看今日 / 最近 7 天写了多少 Token、每个工具各占多少、你几点最能写。还能把用量折成约多少钱（粗略估算，每百万 token 的单价可自己调），当作「你的用量值多少钱」的参考。全部只读本机日志，不联网、不上传。

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 bond continues: coding and playful pokes level up your bond, unlocking warmer reactions over time.

🧠 成长日记 / Growth Journal

烧 token 不该等于把脑子外包出去。打开成长日记，小精灵会用你本机的 Claude / Codex 回顾你今天和 AI 的对话，给你：

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 back:

• 知识点 / Takeaways：你依赖 AI 的地方，把要点直接讲给你，看完就学到。 / the concepts you leaned on, actually explained.
• 待办 / To-dos：你说过要做的事（发版、加测试、订机票），可编辑、可一键勾掉；重新生成会刷新、但不覆盖你动过的。 / editable and one-tap done; regenerating refreshes without overwriting what you touched.
• 每日回看 / Daily history：全部存在本地，攒成你的成长轨迹。 / persists locally, a trail of how you grow.

全程只走你已经在用的那个 AI，不上传任何第三方。

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

🚀 快速开始 / Quick Start

需要 Node.js 20+，支持 macOS、Windows 与 Linux。

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

🤖 让 Agent 帮你装（推荐）/ Let Your Agent Install It (recommended)

你既然在用 Claude Code / Codex，就别自己下载解压了。把这句发给它：

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

帮我安装并运行 github.com/shiyubao78/token-sprite

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

仓库里有 AGENTS.md，Agent 会照着它克隆、打包、装进「应用程序」并启动——
装成常驻 app，关掉终端也在，还会开机自启。

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

装完你会看到它打印 ✅ 已安装并重新打开 vX.Y.Z，桌宠就在桌面右下角。
没看到这行就是没装成，让 Agent 去看报错。

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

🔄 让 Agent 帮你更新 / Let Your Agent Update It

同样一句话，成长数据不会丢：

One line again — your growth data is kept:

帮我把 token-sprite 更新到最新版

Update token-sprite to the latest version for me.

Agent 会 git pull + npm install，装好的版本会自动跟着更新（npm install 会触发重装）。
成长数据存在 ~/Library/Application Support/token-sprite/，覆盖安装不受影响。

It runs git pull + npm install; the installed app updates itself automatically. Your data lives outside the app bundle and survives reinstalls.

1. 从 Releases 下载最新的 .zip，双击解压。
2. 把 Token 小精灵拖进「应用程序」文件夹。
3. 右键点图标 → 选「打开」，弹窗里再点一次「打开」。

第 3 步是最多人卡住的地方。直接双击的话，macOS 会拦住并且只给「移到废纸篓」——别点。右键绕一次，之后永久生效。

为什么会被拦？ 给 Mac 应用签名要向 Apple 交每年 $99 的开发者费，这个项目还没交。全部代码开源，你可以自己翻、自己编译。

Download the latest .zip from Releases, unzip, drag Token Sprite into Applications, then right-click → Open and confirm. Unsigned build, so you only do this once.

有新版时正式版会弹窗提醒；菜单栏图标 → 检查更新 也能打开下载页。成长数据保留。

Released builds notify you of new versions; the menu-bar icon → Check for Updates opens the download page. Your growth data is kept.

git clone https://github.com/shiyubao78/token-sprite.git
cd token-sprite
npm install
npm start        # 开发态：关掉终端桌宠就没了，也不会开机自启

npm start 只适合开发调试。想让它常驻，用这个：

npm start is for development only. To install it for real:

npm run install:local   # 打包 + 装进「应用程序」+ 启动 + 核对，一条命令

如果小精灵不在桌面上，点菜单栏图标 → 召回小精灵。显示器拔插、分辨率变化或睡眠恢复后窗口跑出屏幕，应用也会自动把它带回来。

If your sprite disappears, choose Recall Sprite from the menu-bar icon.

🧩 工作原理 / How It Works

应用会自动检测本机支持的 AI 工具，读取本地日志中的 Token 用量。没安装的工具会自动跳过，数据不会离开你的电脑。

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.

安装时会记录基准，此后从 0 开始养；你新使用多少 Token，它就成长多少。

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

如果 Gemini CLI、OpenCode、Aider 等工具会把用量写进本地日志，可以在 scripts/usage.mjs 的 READERS 中增加读取器：

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 },
];

也可以直接让你的 Agent 完成：

You can also ask your agent to do it:

查看我本地 <工具> 的用量日志格式，为 token-sprite 添加读取器。

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

📦 打包桌面应用 / Package the Desktop App

在目标系统上运行对应命令，产物会写入 release/：

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 本地构建：没有 Developer ID 凭证时仍是未签名版本，首次运行可能需要右键选择“打开”。正式 Release 必须经过签名和 Apple 公证。
• Windows：SmartScreen 拦截时选择“更多信息 → 仍要运行”。
• Linux：先为 AppImage 添加执行权限；透明和置顶效果取决于桌面环境。
• 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

每个阶段使用 512×512 透明 PNG。

Each stage uses a 512×512 transparent PNG.

📄 License

非商业授权 / Noncommercial. 本项目禁止商业使用。

• 源代码 / Source code: PolyForm Noncommercial 1.0.0
• 美术素材 / Art assets（assets/**）: CC BY-NC 4.0

可自由用于个人、学习、非营利用途；使用素材需署名。内置形象为 AI 生成，仅作示例，可自行替换。

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