tokencheck

name	tokencheck
description	Use when the user asks how to install, configure, run, troubleshoot, or integrate the tokencheck/tkc CLI for local Claude Code, Codex, and OpenCode token usage reports, snapshots, pricing, terminal charts, or Obsidian dashboards.

Tokencheck

Use this skill to help users operate the tokencheck Rust CLI. The crate is published as ethan-tkc; installed binaries are tkc and tokencheck.

First Checks

1. Prefer tkc --version and tkc --help to confirm the installed CLI.
2. Use tkc doctor when the user has missing data, wrong paths, unreadable snapshots, pricing-file issues, or Obsidian integration problems.
3. Use tkc config show before changing persistent settings.
4. Distinguish report commands from write commands:
   • tkc fetch writes or updates the JSON snapshot.
   • summary, days, heatmap, projects, models, and tools read and render reports.
   • tkc obsidian writes or updates the Obsidian dashboard Markdown file.

Installation

Install or update from crates.io:

cargo install ethan-tkc
cargo install ethan-tkc --force

Install only this Codex Skill without cloning the source repository:

python3 ~/.codex/skills/.system/skill-installer/scripts/install-skill-from-github.py \
  --repo hanlife02/token-check \
  --path skills/tokencheck

If old local binaries conflict:

cargo uninstall tokencheck
cargo install ethan-tkc

From a source checkout:

cargo run --bin tkc -- summary
cargo install --path .

Core Usage

Fast overview:

tkc
tkc summary

Persist scan results:

tkc fetch

Read only from the saved snapshot:

tkc summary --from-json
tkc days --from-json --limit 30

Source filters:

tkc summary --source claude
tkc models --source codex
tkc days --source opencode

Date filters are inclusive and affect report commands only:

tkc summary --since 30d
tkc days --since 2026-05-01 --until today
tkc models --from-json --since 2026-01-01 --until 2026-03-31

Terminal visualizations:

tkc days --chant --limit 30
tkc heatmap --months 12

Configuration

Interactive configuration:

tkc config

Show or reset config:

tkc config show
tkc config reset

Blank input keeps and saves the current value. none, null, or - clears optional path fields.

Important config fields:

• source: default data source, one of all, claude, codex, or opencode.
• data_file: default JSON snapshot path used by fetch and --from-json.
• pricing_file: optional custom pricing JSON.
• obsidian_snapshot_file: JSON snapshot path for Obsidian integration.
• obsidian_dashboard_file: Markdown dashboard path for Obsidian integration.
• limit: default row/chart count.
• heatmap_months: default heatmap month count.
• language: en or zh.

Custom Pricing

Use --pricing-file or configure pricing_file when unknown proxy models need prices or built-in prices need overrides.

Pricing file format, dollars per 1M tokens:

{
  "models": {
    "my-proxy-model": {
      "input": 2.0,
      "cached_input": 0.5,
      "cache_creation_5m": 3.0,
      "cache_creation_1h": 4.0,
      "output": 8.0
    }
  }
}

Rules:

• input and output are required.
• cached_input defaults to input.
• cache_creation_5m and cache_creation_1h default to 0.
• Model names are normalized like built-in prices: case-insensitive, _ becomes -, and provider/model matches by the last segment.
• Custom prices override same-name built-in prices.

Obsidian Workflow

Configure both Obsidian paths via tkc config:

Obsidian snapshot file: /path/to/Vault/data/tokencheck.json
Obsidian dashboard file: /path/to/Vault/2 - Docs/token-check/Token Usage Dashboard.md

Generate or update the dashboard:

tkc obsidian

Refresh the snapshot first, then update the dashboard:

tkc obsidian --fetch

The generated dashboard file is a lightweight index. tkc obsidian also writes adjacent section notes for Summary, Recent Days, Top Models, Top Projects, and Top Tools. Each section note uses DataviewJS and reads the snapshot with a vault-relative path when possible, usually data/tokencheck.json.

Obsidian requirements:

• Install and enable the Dataview community plugin.
• Enable Dataview JavaScript queries.
• Open the configured dashboard Markdown file, then follow a section link.

Troubleshooting

Start with:

tkc doctor

Common fixes:

• Missing Claude data: confirm $HOME/.claude/projects exists or pass --home.
• Missing Codex data: confirm $HOME/.codex/sessions exists or pass --home.
• Missing OpenCode data: confirm $HOME/.local/share/opencode exists or pass --home.
• No saved history: run tkc fetch.
• Obsidian dashboard missing data: run tkc obsidian --fetch, then reopen or refresh the note.
• JSON file is hidden in Obsidian: enable Files and links -> Detect all file extensions, or use the Dashboard Markdown instead of opening JSON directly.
• Pricing warnings: add a custom pricing_file or verify model names in tkc models.

Development And Release Checks

When modifying the project, run:

cargo fmt --all -- --check
cargo test
cargo clippy --all-targets -- -D warnings
cargo publish --dry-run --allow-dirty

For releases, bump Cargo.toml, ensure Cargo.lock follows, commit, and push to main to trigger the Cargo publish workflow.