Tokenmon

Tokenmon is a macOS-first, offline-first companion that turns local AI coding activity into a passive creature-collection loop.

It observes documented Claude Code and Codex usage surfaces, converts usage into exploration, creates encounters automatically, and stores Seen/Captured Dex progress in a shared local SQLite database.

Project Status

This repository is in a working pre-release state.

Implemented:

• shared gameplay/domain core
• SQLite persistence and migrations
• encounter and capture pipeline
• Seen Dex and Captured Dex aggregation
• native menubar app shell
• terminal CLI surface
• Claude status line adapter
• Claude hook metadata enrichment
• Claude transcript backfill recovery path
• Codex exec --json adapter
• Codex interactive hook metadata path (advanced manual opt-in)
• repo-scoped Codex skills, agents, hooks, and rules contract
• encounter event audit chain through spawn/capture/Dex updates
• menubar startup inbox ingest and file-watch refresh
• local release build script
• repository verification through ./scripts/run-ai-verify

This is usable locally, but it is not yet positioned as a polished public release.

Screenshots

What Tokenmon Does

• turns normalized token usage into exploration steps
• triggers automatic encounters at fixed thresholds
• resolves captures to captured or escaped
• keeps menubar and terminal views on the same source of truth
• stores game state locally with no account or cloud dependency
• avoids storing prompt or response text for gameplay

Core loop:

Provider usage observed
-> normalized usage sample recorded
-> exploration steps accumulated
-> encounter threshold crossed
-> field + rarity + species selected
-> capture auto-resolved
-> Seen/Captured Dex updated
-> app and CLI read the same stored state

Default gameplay values:

• 1 exploration step = 200 normalized tokens
• 1 encounter = 15 exploration steps
• capture odds:
  • common 96%
  • uncommon 82%
  • rare 60%
  • epic 32%
  • legendary 12%

Requirements

• macOS 14+
• Swift 6 toolchain
• sqlite3 for local inspection/debugging

Optional:

• Claude Code CLI
• OpenAI Codex CLI
• gh GitHub CLI with project scope
• tmux / OMX for local operator workflows

Repo Codex Workflow

Tokenmon now treats repo-local Codex workflow assets as a first-class development surface.

Canonical discovery contract:

• AGENTS.md
• .agents/skills/
• .codex/agents/
• .codex/config.toml
• .codex/hooks.json
• codex/rules/

Important boundary:

• these repo-local assets are development tooling only
• gameplay observation still comes from documented provider surfaces such as Claude status line and Codex exec --json
• .codex/skills/ exists only as an OMX compatibility alias; canonical repo skills live in .agents/skills/

Workflow helpers:

• ./scripts/tokenmon-dev-workflow
• ./scripts/audit-codex-global-setup

Quick Start

30-second local try:

swift build
swift run tokenmon db init
swift run tokenmon seed species
swift run tokenmon status
swift run TokenmonApp

If you want the fast confidence check instead:

./scripts/run-ai-verify

Build:

swift build

Run the repository verification lane:

./scripts/run-ai-verify

Initialize local state:

swift run tokenmon db init
swift run tokenmon seed species

Open the menubar app:

swift run TokenmonApp

Inspect the CLI surface:

swift run tokenmon --help

CLI Surface

Current commands:

tokenmon db init
tokenmon seed species
tokenmon ingest inbox
tokenmon summary
tokenmon status
tokenmon watch
tokenmon dex seen
tokenmon dex captured
tokenmon diagnose
tokenmon backfill <claude|codex> transcript ...
tokenmon setup <claude|codex|all> --validate
tokenmon provider claude hook import
tokenmon provider claude statusline import
tokenmon provider codex hook import
tokenmon provider codex hook print-config
tokenmon provider codex exec-json import
tokenmon provider codex exec-json run

Common examples:

swift run tokenmon status
swift run tokenmon watch --iterations 1 --interval-ms 0
swift run tokenmon dex seen
swift run tokenmon diagnose
swift run tokenmon setup all --validate

Provider Support

Reliable paths

• Claude: status line helper
• Codex: codex exec --json

Metadata / best-effort paths

• Claude hooks enrichment
• Codex interactive hook metadata (advanced manual opt-in)

Recovery posture

• Claude transcript-assisted backfill is implemented as a recovery path for usage-bearing assistant steps
• Codex transcript-assisted tail/backfill is implemented for interactive sessions as an experimental best-effort path when the menubar app is running

Important boundary

• hooks are metadata/diagnostic support, not the primary gameplay authority
• transcript backfill is not marketed here as a fully authoritative live gameplay path

Setup

On first launch, the app can detect Claude/Codex installations and offer provider onboarding guidance from Settings or from the menubar when setup attention is required.

Provider setup guidance is built into the CLI:

swift run tokenmon setup all --validate

Useful provider entrypoints:

Claude status line:

tokenmon provider claude statusline import --out "$HOME/Library/Application Support/Tokenmon/Inbox/claude.ndjson" --verbose

Claude hooks:

tokenmon provider claude hook import --db "$HOME/Library/Application Support/Tokenmon/tokenmon.sqlite" --verbose

Codex managed mode:

tokenmon provider codex exec-json run "<prompt>" --out "$HOME/Library/Application Support/Tokenmon/Inbox/codex.ndjson"

Codex interactive hooks (advanced manual opt-in):

tokenmon provider codex hook print-config --db "$HOME/Library/Application Support/Tokenmon/tokenmon.sqlite"

When interactive hooks are enabled, the menubar app can follow the active Codex transcript as a best-effort live path. This remains experimental and is not equivalent to managed codex exec --json.

Global Codex audit:

./scripts/audit-codex-global-setup

Diagnostics

Use:

swift run tokenmon diagnose

Current diagnose output includes:

• provider support level
• active source mode
• health state
• last observed event time
• last error summary
• last backfill result
• suggested next step
• lightweight idle-footprint summary

Menubar App

Current app state:

• AppKit NSStatusItem menubar strip with animated pixel-scene playback
• startup inbox replay plus inbox file-watch debounce refresh
• compact first layer for current state, progress, and quick actions
• first-run provider setup prompts for Claude and Codex when available
• Codex onboarding no longer auto-installs global ~/.codex hooks
• latest encounter summary with provider attention routed into Settings
• unified Dex window with captured, missed, and unknown collection states
• lightweight state-driven grass + wild-cat dummy scene to prove motion and state transitions in the shell
• pane-based Settings UI for launch-at-login, notifications preference storage, terminal verbosity, provider status visibility, and provider diagnostics/setup guidance
• RunCat-style animated status bar strip driven by encounter playback and resting field motion

The app reads shared persistence projections and is covered by smoke checks in ./scripts/run-ai-verify.

Release Build

Generate unsigned local release artifacts:

./scripts/build-release

Default output: .build/release-artifacts

Artifacts produced:

• bin/tokenmon
• Tokenmon.app
• RELEASE_NOTES.txt
• FIRST_RUN_CHECKLIST.txt

This is a local build path, not a signed or notarized distribution.

Placeholder Assets

For shell-level animation testing and quick developer iteration, the repo also includes a minimal placeholder asset path:

• checked-in dummy asset:
  • assets/placeholders/activity-dots.svg
• generator utility:
  • ./scripts/generate-dot-asset

Example:

./scripts/generate-dot-asset --size 16 --count 3 --gap 4 --color "#4B9B6B" --output /tmp/activity-dots.svg

This is intended for lightweight placeholder/testing use, not as the final production sprite pipeline.

Verification

Canonical verification entrypoint:

./scripts/run-ai-verify

It currently covers:

• Swift build
• CLI surface smoke
• menubar app smoke
• provider adapter fixture imports
• diagnose/setup checks
• gameplay ingest and encounter invariants
• restart/resume/replay safety
• release artifact generation

Contributing

Contributions are welcome, but this repository has a few hard boundaries:

• provider-specific logic stays inside adapters
• gameplay stays provider-agnostic
• SQLite remains the local source of truth
• prompt/response text is not required for gameplay

Start here:

• CONTRIBUTING.md
• ROADMAP.md

Scope Boundaries

Out of scope for this version:

• accounts
• cloud sync
• prompt-content gameplay
• manual battle flow
• item/economy systems
• social or multiplayer features

Roadmap

What would most likely come next:

• public-release polish
• signing / notarization
• installer packaging
• more refined UI polish
• stronger backfill and recovery support

Development Notes

This repo intentionally keeps a hard boundary between layers:

• provider-specific logic stays in adapters
• gameplay stays provider-agnostic
• SQLite is the local source of truth
• menubar and CLI are renderers over the same stored state

The repository also uses local private operator state under .omx/, but the product runtime must not depend on it.