token-face

token-face is a CLI application that watches local AI usage activity and turns it into a terminal character whose status and facial expression change with usage pressure.

The code is split by responsibility: CLI entrypoint, provider adapters, status calculation, rendering, diagnostics, notifications, and JSON serving are separated so new providers can be added without rewriting the UI.

It reads local Codex state from ~/.codex by default, so after installation anyone can run it on their own machine without editing the source.

Install

npm install -g @ippei523/token-usage-face

Or from a local directory:

npm install -g .

After install, run:

token-face

Usage

token-face
token-face status
token-face watch
token-face json
token-face help
token-face status --provider codex
token-face status --provider claude
token-face doctor
token-face notify
token-face serve --port 4311
token-face watch --theme robot --notify-at 70,85,100

token-face without arguments stays resident and refreshes the expression view every 5 seconds.

Optional environment variables

CODEX_HOME : Override the Codex data directory. Default is ~/.codex.

TOKEN_FACE_DAILY_TOKEN_LIMIT : Optional daily token cap. Used for rate and limit.

TOKEN_FACE_USD_PER_1M_TOKENS : Optional flat token price used only for estimated cost.

TOKEN_FACE_DAILY_BUDGET_USD : Optional daily budget. If set together with TOKEN_FACE_USD_PER_1M_TOKENS, the pet reacts more strongly to overspending.

TOKEN_FACE_PROVIDER : Optional default provider. Supported values are auto, codex, and claude.

TOKEN_FACE_THEME : Theme name for the character. Supported values are default, wa, office, shojo, and robot.

TOKEN_FACE_NOTIFY_AT : Comma-separated notify thresholds, for example 70,90,100.

TOKEN_FACE_PORT : Default port for serve and daemon.

Notes

• The app uses local Codex session data and requires the sqlite3 command to be available in your environment.
• If actual billing data is not available locally, the pet falls back to token pressure and activity density.
• claude is scaffolded as a provider adapter, but its local usage parsing still needs to be implemented against your actual Claude data files.
• doctor checks local prerequisites and provider detection.
• serve and daemon expose the current snapshot at /snapshot for future menu bar or GUI clients.