tokenidle
v0.1.1
Published
Turn your Claude Code and Codex token usage into a space factory idle game.
Maintainers
Readme
tokenidle
Turn your Claude Code and Codex token usage into a space factory idle game at tokenidle.dev.
npx tokenidle loginlogin signs you in with GitHub in your browser and runs the first sync. Then open your factory at https://tokenidle.dev/play.
Commands
| Command | What it does |
| --- | --- |
| tokenidle login | Sign in with GitHub and run the first sync |
| tokenidle sync [--dry-run] [--stage] | Upload new usage. --dry-run prints the payload without sending it; --stage holds new cargo at the dock for manual release |
| tokenidle autosync on\|off | Sync every hour in the background (launchd on macOS, cron on Linux) |
| tokenidle logout | Sign out on this machine |
What gets uploaded
Only hourly token counts. For each hour, source (claude-code or codex) and model, the CLI sends input, output, cache-read and cache-write token totals. Run npx tokenidle sync --dry-run to see the exact payload.
Prompts, responses, file paths, project names and code never leave your machine.
Files it reads and changes
Reads (never modified):
- Claude Code logs in
~/.claude/projects(or$CLAUDE_CONFIG_DIR/projects). - Codex logs in
~/.codex/sessions(or$CODEX_HOME/sessions).
Writes, in ~/.tokenidle (or $TOKENIDLE_HOME). The directory is mode 700, and the files are readable only by you (600, or 700 for the script).
credentials: the login token for tokenidle.dev.logoutasks the server to revoke it, then deletes it locally even if the server can't be reached.state.json: sync progress. It holds the paths of the log files it has read, a read position for each file, running hourly token totals, and recent message and request IDs used to avoid counting a message twice, and for Codex the current model name. It never holds log contents.autosync.sh(Linux only, while autosync is on): the script cron runs.
autosync on also schedules npx -y tokenidle@latest sync --quiet every hour. autosync off removes the schedule.
- macOS: writes
~/Library/LaunchAgents/dev.tokenidle.sync.plistand loads it withlaunchctl. - Linux: adds one line marked
# tokenidle-autosyncto your crontab. Other crontab lines are left alone.
Requires Node.js 20 or later.
License
MIT
