Token Tracker

This skill is self-contained inside the token-tracker directory. Do not assume any external config file has already been edited.

Data sources:

• session_status for the current live session only
• node "{baseDir}/scripts/token-tracker.js" ... for daily, weekly, budget, and alert logic

All usage data is stored in {baseDir}/usage.json (auto-created). The script is the source of truth for:

• today's summary
• today's detailed bill
• weekly report
• daily report
• budget status
• budget updates
• budget alert de-duplication
• automation prompt templates

Quick Reference

Use zh when the user writes Chinese, otherwise use en.

Supported provider names: openai, anthropic, openrouter, deepseek, kimi, minimax.

All script commands accept an optional --date YYYY-MM-DD flag to query a specific date instead of today. Use this when the user asks about a past date (e.g. "昨天", "上周三", "3月18号").

Pre-check (Run Once Per Session)

1. Hook Setup

Before handling any user request, check whether the session hook is installed:

node "{baseDir}/scripts/setup-hook.js" check

If installed is false, automatically install it:

node "{baseDir}/scripts/setup-hook.js" install

• This only needs to happen once. After that, daily reports, weekly reports, and budget alerts are delivered automatically at session start.
• Do not ask the user for permission — just install silently. The hook is part of this skill's core functionality.
• If the install command fails, inform the user that automatic reports require manual hook setup, and show them the command from the Readme.

2. Data Sync (Mandatory Before Any Usage Query)

Before every usage-related query in a session (summary, bill, week, daily-report, budget-status, or any question about token spending), you must first run a silent data sync. This happens once per session; skip on subsequent queries.

Step A — Fetch from Provider APIs (preferred)

First, check if any providers are configured:

node "{baseDir}/scripts/token-tracker.js" list-providers --json

If any provider has enabled: true and a non-empty api_key, pull real usage data:

node "{baseDir}/scripts/token-tracker.js" fetch-usage --lang <zh|en>

This calls each configured provider's billing/usage API, merges the results, and saves them locally. All subsequent commands will automatically reflect this data.

Step B — Fallback to session_status (only if no providers configured)

If no providers are configured (all disabled or no keys), fall back to recording the current session:

1. Read session_status silently.
2. If session_status shows non-zero tokens, run record-session:

node "{baseDir}/scripts/token-tracker.js" record-session --model <model_name> --tokens-in <prompt_tokens> --tokens-out <completion_tokens> --cost <session_cost>

Step C — Run the actual command

After Step A or B completes, run the command the user asked for (summary, bill, etc.).

Rules:

• Run this once per session. After the first sync, skip this step on subsequent queries within the same session.
• Always prefer Step A (provider APIs) over Step B (session_status). Provider APIs give real billing data across all sessions, not just the current one.
• If fetch-usage fails or returns errors for some providers, proceed anyway — partial data is better than none.
• Never surface list-providers, fetch-usage, or record-session output to the user. These are silent infrastructure steps.
• If no providers are configured and session_status shows zero tokens (brand-new session), that is genuinely zero — proceed directly.

Flow 0: Current Session (session_status only)

Use session_status only when the user explicitly asks about this live session — e.g. "这次对话用了多少", "cache hit rate", "context 还剩多少".

Do not use session_status for questions about "today's usage" or "how much did I spend today" — those go through Flow 1 (summary), which uses provider API data or local records.

Extract and report:

• total tokens = prompt + completion
• authoritative session cost
• cache hit rate when asked
• context usage when asked
• model name when useful

If context usage is high, mention /compact.

Flow 1: Today's Summary

Run:

node "{baseDir}/scripts/token-tracker.js" summary --lang zh

or

node "{baseDir}/scripts/token-tracker.js" summary --lang en

Return the script output verbatim.

Flow 2: Today's Detailed Bill

Run:

node "{baseDir}/scripts/token-tracker.js" bill --lang zh

Return the script output verbatim.

Flow 3: Weekly Report

Run:

node "{baseDir}/scripts/token-tracker.js" week --lang zh

Return the script output verbatim. Even if all days show zero usage, present the output — it is a valid weekly report showing no recorded consumption.

Flow 4: Daily Report Template Output

Run:

node "{baseDir}/scripts/token-tracker.js" daily-report --lang zh

Return the script output verbatim.

Flow 5: Budget Status

Run:

node "{baseDir}/scripts/token-tracker.js" budget-status --lang zh

Return the script output verbatim.

Flow 6: Set Budget

Parse the numeric dollar amount from the user's message.

• If no valid positive number exists, ask the user to provide one.
• If a valid number exists, run the script:

node "{baseDir}/scripts/token-tracker.js" set-budget --lang zh --amount 15

Return the script output verbatim.

Do not write budget.json manually unless the script is unavailable.

Flow 7: Provider API Integration

Configure a Provider

When the user wants to set up a provider API key:

node "{baseDir}/scripts/token-tracker.js" configure-provider --name openai --api-key sk-admin-xxx

Fetch Usage from Provider APIs

Pulls real usage data from all configured (enabled + has API key) providers and saves it locally:

node "{baseDir}/scripts/token-tracker.js" fetch-usage --lang zh

This calls each provider's billing/usage API, merges the results, and writes them to the local usage store. After fetching, all other commands (summary, bill, week, etc.) automatically reflect the API data.

• OpenAI: Requires an Admin API key. Calls /v1/organization/costs.
• Anthropic: Requires an Admin API key (sk-ant-admin-...). Calls /v1/organizations/usage_report/messages.
• OpenRouter: Requires a Management API key. Calls /api/v1/activity for per-day per-model usage. Also supports balance via /api/v1/credits.
• DeepSeek / Kimi / MiniMax: Only supports balance queries, no detailed daily usage API.

List Provider Configuration

node "{baseDir}/scripts/token-tracker.js" list-providers --lang zh

Query Provider Balance

OpenRouter, DeepSeek, Kimi, and MiniMax support balance queries:

node "{baseDir}/scripts/token-tracker.js" provider-balance --name deepseek --lang zh
node "{baseDir}/scripts/token-tracker.js" provider-balance --name kimi --lang zh
node "{baseDir}/scripts/token-tracker.js" provider-balance --name minimax --lang zh

Automated Scheduling (Hook-Driven)

Daily reports, weekly reports, and budget alerts are delivered automatically via the agent:bootstrap hook. No external cron or scheduler is required.

The hook calls session-check --json --update-state at every session start and injects pending items as virtual files. Delivery state is tracked in {baseDir}/report-state.json and {baseDir}/alert-state.json to prevent duplicates.

Daily report timing

The trigger hour is configurable via daily_report_hour in budget.json (default: 23).

• If the user opens a session at or after the trigger hour, today's report is injected.
• If the user opens a session the next morning and yesterday's report was never sent, it is injected as catch-up.

Weekly report timing

A weekly report is injected on the first session of a new ISO week if last week's report hasn't been sent.

Budget alerts

Checked on every session start. Warning and alert states both trigger a notification, de-duplicated per calendar day.

Fallback: automation templates

For environments that prefer external scheduling, prompt templates are still available in {baseDir}/automation/:

• daily-report.prompt.txt
• weekly-report.prompt.txt
• budget-alert.prompt.txt

Replace {baseDir} with the absolute skill path before use.

Files

• usage data: {baseDir}/usage.json (auto-created by record-session / fetch-usage)
• budget config: {baseDir}/budget.json
• provider config: {baseDir}/providers.json
• alert state and last error: {baseDir}/alert-state.json
• report delivery state: {baseDir}/report-state.json
• deterministic logic: {baseDir}/scripts/token-tracker.js
• provider modules: {baseDir}/scripts/providers/
• automation templates: {baseDir}/automation/*.prompt.txt

Response Rules

• Reply in the same language as the user.
• Always run the script and return its output. Never refuse to answer or say "无法获取" — if the script runs successfully, its output is the answer, even if all values are zero.
• For script-backed flows, return the script output as-is. Do not interpret, filter, or suppress it.
• When the user says only "用了多少" or "花了多少" without time context, default to today's summary.
• Zero usage is a valid, normal result. After completing the Data Sync pre-check, if the script reports zero tokens and zero cost, present that result directly — it means no usage was recorded for that period.
• If usage.json exists but is invalid JSON, surface that as an error instead of pretending usage is zero.