Tokemon

A terminal-native companion raised from how you actually work — not how loud you prompt, but how well you build. Tokemon turns the metadata of your real dev work (Claude Code sessions, git commits, shell signals) into quality-weighted XP for an ASCII creature that hatches from a hidden-rarity egg and settles into the truth of how you work.

Local-first. Metadata only. It has never phoned home, and it never will.

  your tokemon · Prime Logimantle
        ╲ ╱
      ─ ╳ ·          stage   Settled
        ╱ ╲          rarity  rare · Prime Logimantle
                     fingerprint  debugger ▰▰▰▰▰▰▰▱▱▱ 60%

Install

npm i -g tokemon-cli
tokemon setup      # one command: creates your egg, injects the Claude Code hooks,
                  # watches the current repo, then verifies the install
tokemon status     # see it

tokemon setup is idempotent — safe to re-run anytime. Run tokemon doctor any time to check that tokemon is on PATH, the egg exists, the DB is migrated, the hooks are wired, the daemon is installed, and a repo is watched.

Requires Node ≥ 22. Installs a native better-sqlite3 addon (prebuilt on most platforms). macOS, Linux, and Windows are all first-class: the background daemon installs as launchd, systemd --user, or Task Scheduler respectively, and the shell signal shim speaks zsh and PowerShell. Everything lives under ~/.tokemon/ (override the DB path with TOKEMON_DB).

Install by environment

| Environment | Notes | | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | macOS (Apple Silicon + Intel) | npm i -g tokemon-cli — prebuilt native addon, nothing to compile. Daemon installs as a launchd agent. The card's PNG uses your installed Chrome/Chromium/Edge/Brave (CHROME_PATH overrides). | | Linux | npm i -g tokemon-cli — prebuilds cover common x64/arm64 glibc distros; if yours compiles from source you need python3 + a C toolchain (build-essential). Daemon installs as a systemd --user unit. Headless server without a browser? tokemon card still writes the HTML and says so honestly. | | Windows | npm i -g tokemon-cli in PowerShell. Data lives in %USERPROFILE%\.tokemon. Daemon installs as a Task Scheduler task (tokemon daemon install); the shell shim targets your PowerShell $PROFILE (tokemon shell-init --shell powershell). WSL counts as Linux. | | bun / pnpm / yarn | Same package, same registry: bun add -g tokemon-cli · pnpm add -g tokemon-cli · yarn global add tokemon-cli. The CLI itself runs under Node via its shebang. | | Claude Code (MCP) | claude mcp add tokemon -- tokemon mcp, then restart your sessions (servers and hooks load at session start). | | Claude Desktop (MCP) | Settings → Developer → Edit Config, add to mcpServers: { "tokemon": { "command": "tokemon", "args": ["mcp"] } }, then restart the app. | | Standalone binary (no Node, no npm) | Build it yourself today: npm run build:bin (requires bun ≥ 1.3) emits a fully self-contained single file to dist-bin/. Prebuilt downloads via scripts/install.sh are not live yet — see Standalone binary. |

Commands

First-run & health

| Command | What it does | | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | tokemon setup [--seed] | Guided first-run: init the egg + inject hooks + watch the cwd, then verify. --seed opts into the metadata-only back-scan below. | | tokemon seed [--budget <n>] [--repo <path>] [--verbose] | Opt-in "reveal your shape": back-scan your existing local git history + AI-CLI sessions so the first status shows a real, leaning creature. Reads commit counts + timestamps + tool names only — never diffs, prompts, or filenames. The consent line prints before any scan; skipped/bounded stores surface as aggregate counts (never a path — --verbose restores the per-store stderr detail); a mid-read hatch gets its "first light" beat. The head-start is capped strictly below the lv25 settle (you still earn the settle yourself); re-runnable and idempotent. | | tokemon doctor | Read-only install health check (PATH · egg · db · hooks · daemon · watched). | | tokemon doctor --report | Metadata-only diagnostic bundle: versions · schema version · table row counts · detected collectors · last db-error class. Numbers/booleans/enums only — zero paths, safe to paste into a bug report. | | tokemon install [--greet] | Inject the Claude Code hooks into ~/.claude/settings.json. --greet also wires the opt-in SessionStart greeting (tokemon greet --line, one plain-text line per session, 10s timeout); tokemon uninstall removes it with the rest. | | tokemon init | Lay the egg — a sealed creature keyed to this machine. Ends with the state-aware next step (as do a young status and every seed run) — the footer picks the ONE most useful command from the den's real state, and a healthy den gets no footer at all. | | tokemon shell-init [--shell zsh\|powershell] [--greet] | Print the opt-in shell-signal snippet (metadata only; add to your shell profile). --greet appends the once-a-day greeting line (tokemon greet 2>/dev/null — silent on any failure by contract). | | tokemon uninstall [--purge] | The exit door: remove the injected hooks + OS daemon. --purge also deletes ~/.tokemon (irreversible); without it your creature's data is kept. |

Daily view

| Command | What it does | | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | tokemon status | The hearth view: sprite, stage, level, Cycles, the rarity band. A still-young den ends with its next step. | | tokemon progress | The five progression bars: level · class mastery · bestiary · battle rank · molt. | | tokemon feed [--since <when>] [--all] | The narrated ledger of Cycle awards. Defaults to the last 7 days with dated day separators; --all is the whole ledger, --since today\|YYYY-MM-DD a specific window. | | tokemon dispatch [--day <date>] | A once-a-day, in-character read of the prior day's work-shape (axis movement, band tightening, class lean, notable events). Read-only — mints zero Cycles and changes no genome. Auto-shown on the first status of a new day; run it any time on demand (never consumes the daily gate). | | tokemon greet [--line] | The once-a-day session greeting: one creature line (~ ◍ Vocabkin · settling lv13 · leaning scribe), the pending dispatch if one waits (same daily gate as status — never double-shown), and at most one pointer (an evolution that's ready, or the untamed tray count). Never ticks, never mints — pure reads plus two date stamps. --line prints the one-liner only and consumes no gate (the always-on form). On any failure — no den, locked den, anything — it prints nothing and exits 0, so it is safe in a shell rc or a session hook. | | tokemon bestiary | The 7-class dex — what you've settled, seen, and have yet to find. | | tokemon achievements | Hidden achievements — earned ones revealed, the rest stay ???. |

Gameplay

| Command | What it does | | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | tokemon evolve | The settle ceremony, once you've earned it (lv25). | | tokemon wild | The understory tray — wild patterns waiting to be dueled (≤3/day). | | tokemon battle <id> | Duel a wild in a deterministic, seed-replayable stat-fight. Every action line names actor → target and the HP it left; the aftermath banks the bond honestly (+N — N / threshold), counts the fresh tray, and points at the next step (a loss costs nothing — bond never decays). | | tokemon replay <battleId\|latest> | Replay a recorded duel — the identical fight back from its stored seed + snapshot, read-only (mints nothing, banks nothing; the aftermath was narrated once, at fight time). Fights from before v1.4.x were never pressed and are refused honestly, exit 1. | | tokemon tame <id> | Spend Shards to tame a wild you've beaten — into a separate bestiary. A missing id points back at the tray (see the tray: tokemon wild) and exits 1, same as battle. | | tokemon hearth | Keep vigil — the creature breathing live on the alternate screen, pulsing one fixed line when real work lands. Strictly read-only (SELECTs only — it never ticks, mints nothing). q steps away; without a living terminal it refuses in one line, exit 1. | | tokemon card [--face both\|front\|back] [--out <path>] [--open] | Press the live creature into a shareable specimen card (html + png). |

tokemon card writes a self-contained, offline HTML card to ~/.tokemon/cards/ (specimen plate on the front, monospace fingerprint receipt on the back) and a PNG next to it when a system Chrome/Chromium is found (CHROME_PATH overrides; no browser bundled, ever). The card carries exactly what tokemon status shows — no username, no hostname, no network: raised on one machine · never left it.

Background daemon

| Command | What it does | | -------------------------------------- | ------------------------------------------------------------------------------------------------------ | | tokemon watch [path] | Register a git repo for the daemon to scan (or list watched repos). | | tokemon daemon run | Run one collect+score cycle and exit (cron/launchd entry). | | tokemon daemon start [--interval ms] | Run resident: collect+score every <ms> until stopped. | | tokemon daemon status | Show the daemon heartbeat. | | tokemon daemon install [--dry-run] | Install the daemon as an OS service (launchd / systemd --user / Task Scheduler) so it survives reboot. | | tokemon daemon uninstall | Stop and remove the OS-managed daemon. |

Input & internal

| Command | What it does | | ----------------------------------- | ------------------------------------------------------------------ | | tokemon scan [--repo <path>] | Read a git repo's commits (metadata only) into events. | | tokemon hook <source> --event <E> | Internal: consumes hook JSON on stdin (hidden from --help). | | tokemon tick | Internal: drain + score unprocessed events (hidden from --help). |

MCP (talk to it from your agent)

tokemon mcp serves the same views and gameplay over the Model Context Protocol (stdio, local-only — stdout is the wire). Register it with Claude Code:

claude mcp add tokemon -- tokemon mcp

| Tool | What it shows / does | | ----------------------- | ------------------------------------------------------------------------------------------------- | | tokemon_status | The hearth view: sprite, stage, level, Cycles, token genome, rarity band. | | tokemon_feed | The narrated ledger of Cycle awards (since: today · all · YYYY-MM-DD). | | tokemon_dispatch | A once-a-day, in-character read of the latest active day's work-shape. Read-only — mints nothing. | | tokemon_progress | The five progression bars: level · mastery · bestiary · battle rank · molt. | | tokemon_bestiary | The 7-class dex: settled, seen, and locked species. | | tokemon_wild | The understory tray — wilds waiting to be dueled (pull-only, ≤3/day). | | tokemon_battle | Duel a wild from the tray (wild_id) — deterministic, seed-replayable. | | tokemon_tame | Spend Shards (earned, never bought) to tame a wild you've beaten. | | tokemon_evolve | The settle ceremony once earned (lv25+) — answers honestly if called early. | | tokemon_scan_repo | Ingest a local git repo's commit metadata (counts only) into cycles. | | tokemon_scan_sessions | Ingest token usage from local AI-CLI session stores. Metadata only. | | tokemon_card | The specimen card as a PNG image, right in chat (face: both · front · back). |

No MCP tool can mint XP — feeding happens only through hooks and scans of real local files. There is no hook/init/setup/install/daemon surface over MCP, and the .strict() metadata-only payload boundary applies unchanged.

animations

In a real terminal the creature moves: tokemon status opens with a ≤600ms breath — the sprite sways once, then the exact static status rests in your scrollback. What plays is a memory, not a slot machine: which breath a creature has is fixed forever by its frozen salt + founding seed (seeded tables, zero ambient randomness), and the command's answer is fully computed before the first frame draws — the clock only paces frames, never picks them.

The big moments hold ceremonies (each ≤3s, each a fixed keyed variant, forever):

• hatch — when a tokemon seed / tokemon setup --seed back-scan brings first light, the egg cracks (one of three fixed crack paths, keyed to the creature), light gets in, and the unsettled blur is revealed before the seed report.
• settle — tokemon evolve on a settled creature dissolves the blur and sweeps the class sprite in its rarity's fixed ANSI-256 color (common gray → mythic magenta — color, never power), resting at the plain ceremony text.
• branch / molt — a diverged creature's sprite splits along its midline and re-forms changed, keyed to its frozen branch id; a molted creature (lv 250+) replays the same ceremony as a molt-flavored variant — the shed shell drifting off. Same surface, no new gate.

Refusal and too-soon answers play no frames — words only; no ceremony was earned.

Duels play out live: tokemon battle (and tokemon replay) draws each round in place — two 20-cell HP bars draining at ~350ms a round, every number read straight from the resolver's own log, a crit flashing inverse-video for one frame — then rests at the unchanged static duel text. The outcome is fully decided before the first frame; the show never edits the fight. The aftermath (bond banked, next step) belongs to the final text only — it never appears in a frame, and replay never re-claims it.

And for the quiet hours there is tokemon hearth: a read-only vigil on the alternate screen — the creature breathing its own seeded breath while you work, pulsing once (inverse-video, one fixed in-voice line) when real work lands in the ledgers. It polls with pure SELECTs every ~2s and can mint nothing — the hearth never ticks; the hooks and daemon own that. q (or ctrl-c) steps away cleanly, leaving your scrollback exactly as it was.

The fallback contract. Anywhere animation could be unwelcome, the output is byte-identical to the plain static render — piped/non-TTY output, NO_COLOR, TERM=dumb, TOKEMON_ANIMATE=0, legacy Windows conhost without VT, or the global --instant flag (tokemon status --instant). Scripts, hooks, and MCP tools never see a frame or an ANSI byte; the MCP server and hook don't even link the player. Any key skips the show straight to the answer; ctrl-c aborts cleanly with the cursor restored. The one command that IS its animation, hearth, falls back by refusing honestly — one line, exit 1, the database untouched.

Talking to it from your AI session

Once tokemon setup has run, there are three ways to reach your creature without leaving a session — pick whichever fits the moment:

1. Just ask. With the MCP server registered (claude mcp add tokemon -- tokemon mcp), your assistant has the tools natively. Say things like:
   • "how's my tokemon doing?" → it calls tokemon_status
   • "what did it eat today?" → tokemon_feed
   • "any wilds in the tray? duel the rare one" → tokemon_wild + tokemon_battle
   • "show me my card" → tokemon_card, the specimen card as an image in chat
2. Bang commands (Claude Code): type ! tokemon status in the prompt — the ! prefix runs the shell command right in your session and drops the output into the conversation. Works for every command in the tables above.
3. Any normal terminal. It is just a CLI; every session and terminal shares the same creature at ~/.tokemon.

And if you'd rather it spoke first: the opt-in session greeting. The first shell (or session) of the day opens with one line of creature plus the pending dispatch — tokemon shell-init --greet prints the shell-rc form, tokemon install --greet wires it as a Claude Code SessionStart hook (tokemon greet --line, one plain-text line, every session). It is read-only, sub-100ms, and silent on any failure — it will never break a shell or block a session.

Two setup notes: hooks and MCP servers load when a session starts, so restart your sessions once after tokemon setup and once after registering MCP. Claude Desktop uses the same one-liner via its MCP settings.

How to battle (60 seconds)

tokemon wild            # the understory tray — up to 3 wild patterns surface per day
tokemon battle 3f9a12c4 # duel one by the id shown in the tray (short id is fine)
tokemon battle 3f9a12c4 # win again — each win banks bond toward taming
tokemon tame 3f9a12c4   # bond above threshold + matching shards -> it joins your bestiary

• Duels are deterministic and seed-replayable — same seed, same fight, no dice.
• Losing costs nothing. No decay, no death; the wild stays in the tray and echoes recur. Winning banks bond; taming spends shards (dropped by your real work, never bought).
• Wilds mirror your own work-residue at fight time, so even an unsettled creature fights hard-but-winnable duels. Your battle rank climbs a peak-sealed ladder (Drift → Token → Embed → Attention → Logit → Softmax → Apex) and never decays.
• Over MCP, all of this is one sentence: "check the tray and battle the epic."

How it works

claude-code hooks (PostToolUse / PostToolUseFailure / SessionEnd)
  + opt-in shell signals (first command word, exit code, duration)
  + git scans
  → normalize to a canonical (metadata-only) Event
  → idempotent ingest → scoring engine drains events into the xp_ledger (quality-weighted Cycles)
  → level + stage advance → fingerprint EWMA bends toward your real work-shape
  → at lv25 it settles: one of 7 classes locks, a species + rarity is assigned

The resident daemon (tokemon daemon start, or tokemon daemon install to keep it alive across reboots) runs collect+score cycles on a timer so events are scored without you asking. The Claude Code hooks are the primary feed and need no daemon.

• Three live signals from Claude Code. file_changed is derived from the Edit/Write tool_input line deltas; bug_fixed is minted on a real red→green test transition (a failed run followed by a passing one); long_agent_session fires when a session lasted ≥ 30 min and shipped a file. All from metadata only — see Privacy.
• Quality-weighted Cycles. finalCycles = round(base × multiplier), multiplier clamped [0.25, 3.0]. A first-try, test-backed bug fix lands ×1.8; spammed noise drips to the 0.25 floor and plateaus at a daily soft cap. You can't farm a tokemon — you can only earn one.
• Hidden-rarity eggs. Your egg's tier is sealed and fated from your founding fingerprint. The confidence band can only ever narrow, never widen — nothing to lose, only a shape to find.
• Settling. Class is a percentile of your work-fingerprint, frozen at lv25; rarity is your distance from the population, not a dice roll. Earned, never rolled.
• Battle & wilds. Seven battle stats derive from your fingerprint + level (rarity never affects power). Wild patterns condense from your local work-state in four origins (Drift / Stray / Glitch / Echo); beat one and spend Shards (dropped by real work, never money) to tame it. Losing costs nothing; nothing decays or dies. Wilds mirror your own residue at fight time, so an unsettled creature fights hard but winnable duels. Battle rank climbs a peak-sealed division ladder (Drift → Token → Embed → Attention → Logit → Softmax → Apex) that never decays.
• Deep identity. At settle your creature draws a cosmetic strain from its genome shape (25 token-lore strains — never power). At lv40 a branch evolution opens, chosen deterministically from how you actually worked. Hidden achievements reveal themselves only when earned; every settle and branch ceremony reads differently across the strain × rarity × class space.

Privacy

Metadata only, by construction. The Event payload schema accepts numeric / boolean / enum fields exclusively and is .strict(), so a prompt, a diff, a commit-message body, or a filename cannot reach the database — proven by an e2e test that plants a secret in a commit message and asserts it never lands on disk.

The collectors touch content only to extract counts, never to store it:

• file_changed reads tool_input strings solely to count inserted/deleted lines; the strings themselves are discarded.
• long_agent_session derives a session's duration from the transcript file's first and last timestamps via a 64KB head+tail read — the conversation content is never read or stored. shipped_artifact is derived from tokemon's own already-ingested file_changed events, not by scanning the transcript.
• Shell signals capture only the first command word, the exit code, and the duration — never arguments, paths, env, or secrets.

Everything is local: the DB lives at ~/.tokemon/tokemon.db. A battle ships only a derived stat-vector + seed. Nothing phones home.

Development

npm install        # compiles native better-sqlite3
npm run build      # esbuild → a single minified bundle at dist/cli/index.js
npm test           # vitest (955 node + 17 bun tests, incl. compiled-binary e2e)
npm run typecheck
npm run format     # prettier --write .

The design specs and task-by-task implementation plans live in docs/superpowers/; the security audit and SOC 2 controls map live in docs/. PROGRESS.md is the living source of truth. The marketing site (Next.js) is in site/ (npm run dev, npm run test:gate).

Standalone binary

tokemon can compile to a single self-contained executable — no Node, no npm, no node_modules on the machine that runs it. The runtime-adaptive sqlite driver picks better-sqlite3 under Node (the npm path) and bun:sqlite under Bun, which is built into the runtime, so the compiled file carries everything it needs. Both runtimes share one write seam: a transient SQLITE_BUSY/locked write (a sibling session or the daemon holding the lock) retries with bounded, deterministic exponential backoff, and any db failure — at open OR mid-operation, corrupt/locked/permission-denied — answers with one honest line and exit 1, never a stack trace.

npm run build:bin       # current platform → dist-bin/tokemon-<platform>-<arch>
npm run build:bin:all   # darwin-arm64, darwin-x64, linux-x64, linux-arm64, win32-x64 (.exe)

Requires bun ≥ 1.3 on PATH (only to build; the artifact needs nothing). Cross-compiling downloads each target's bun runtime once, so --all needs network the first time. Honesty note: from one machine, foreign-platform artifacts are compile-verified only — they are executed and fully verified on matching platforms (CI), while the host-platform artifact is exercised end-to-end by the test suite (test/e2e/binary.e2e.test.ts), including a self-containment proof and locked-database parity.

scripts/install.sh is the eventual curl | sh path: it detects uname platform/arch, downloads tokemon-<platform>-<arch> from RELEASES_BASE_URL, and installs to ~/.local/bin (override with TOKEMON_INSTALL_DIR). It is a template for now: no binaries are published to GitHub Releases yet, so its default URL serves nothing — point RELEASES_BASE_URL at your own build until releases carry binaries:

npm run build:bin
RELEASES_BASE_URL="file://$PWD/dist-bin" sh scripts/install.sh

The npm install path is unchanged by all of this: npm i -g tokemon-cli still runs under Node ≥ 22 with better-sqlite3, byte-identical to before.

Support & bug reports

Questions, ideas, or something broke? Open an issue at the community repo: github.com/michaelgriffin-cloud/tokemon-community.

License

Proprietary, free to use — see LICENSE. The license explicitly permits reverse engineering to the extent needed to verify the privacy claims (metadata only, local only, never phones home).