tokmesh-cli 0.1.1

CLI and TUI for tokmesh — AI token usage analytics
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109

# Tokmesh

Local analytics for AI coding token usage: scan session logs, price models, run reports, and explore everything in a full TUI.

Tokmesh is a hard fork of [tokscale](https://github.com/junhoyeo/tokscale). It keeps the local scanner, pricing system, reports, and terminal UI, and can submit daily aggregates to either public leaderboard:

- [tokscale.ai](https://tokscale.ai)
- [tokens.ci](https://tokens.ci)

## Install

Pick one:

```sh
# Cargo
cargo install tokmesh --locked

# npm
npm install -g tokmesh

# pipx / uv / pip
pipx install tokmesh
# uv tool install tokmesh
# pip install tokmesh

# mise (prebuilt binary)
mise use -g github:xxxbrian/tokmesh

# From a clone
cargo build --release -p tokmesh
./target/release/tokmesh --help
```

Prebuilt binaries are also on the [Releases](https://github.com/xxxbrian/tokmesh/releases) page: download the archive for your platform, extract, and put `tokmesh` on your `PATH`.

## Local usage

```sh
tokmesh              # interactive TUI (default)
tokmesh tui
tokmesh models
tokmesh monthly
tokmesh hourly
tokmesh clients
tokmesh pricing <model>
tokmesh graph --json
tokmesh time-metrics
tokmesh wrapped
```

Config and caches live under `~/.config/tokmesh/` (override with `TOKMESH_CONFIG_DIR` for an isolated profile).

Usage is derived from local client logs and databases (Claude Code, Codex, OpenCode, Grok Build, Cursor cache, and many others). The TUI may also fetch public leaderboard statistics.

### Model identity

Local reports and leaderboard submit share one model-id path. Two narrow suffix rewrites:

| Source | Rule |
|--------|------|
| OpenCode | `gpt-…-fast` → base model (e.g. `gpt-5.6-sol-fast` → `gpt-5.6-sol`) |
| Grok | `grok-…-build` → base model (e.g. `grok-4.5-build` → `grok-4.5`) |

## Leaderboards

```sh
tokmesh tokscale login
tokmesh tokscale submit
tokmesh tokscale submit --dry-run
tokmesh tokscale whoami
tokmesh tokscale logout

tokmesh tokensci login
tokmesh tokensci submit
tokmesh tokensci whoami
tokmesh tokensci logout
```

Credentials are stored separately and never mixed:

- `~/.config/tokmesh/tokscale/credentials.json`
- `~/.config/tokmesh/tokensci/credentials.json`

Environment overrides (optional):

| Variable | Purpose |
|----------|---------|
| `TOKMESH_TOKSCALE_API_TOKEN` | tokscale.ai API token |
| `TOKMESH_TOKENSCI_API_TOKEN` | tokens.ci API token |
| `TOKMESH_TOKSCALE_API_URL` | Override tokscale API base URL |
| `TOKMESH_TOKENSCI_API_URL` | Override tokens.ci API base URL |

Submit sends daily usage aggregates and a stable device identifier. It never sends prompts, completions, file contents, or local paths.

```sh
tokmesh tokscale submit --dry-run          # human summary
tokmesh tokensci submit --dry-run --json   # full JSON body (no upload)
```

`tokmesh tokensci submit --replace --client <id> --since YYYY-MM-DD --until YYYY-MM-DD`
authoritatively replaces that client's bounded date range; missing local days are removed remotely.

## TODO

- Optional self-hosted private cloud for detailed personal history (not started)

## License

MIT. Includes work from [tokscale](https://github.com/junhoyeo/tokscale) (Copyright (c) 2025 Junho Yeo) and [tokens.ci](https://github.com/missuo/tokens) (Copyright (c) 2026 Vincent Yang). See [LICENSE](LICENSE).