tokenstats 1.0.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- tokenstats-1.0.0/LICENSE +21 -0
- tokenstats-1.0.0/PKG-INFO +151 -0
- tokenstats-1.0.0/README.md +133 -0
- tokenstats-1.0.0/pyproject.toml +29 -0
- tokenstats-1.0.0/setup.cfg +4 -0
- tokenstats-1.0.0/tokenstats.egg-info/PKG-INFO +151 -0
- tokenstats-1.0.0/tokenstats.egg-info/SOURCES.txt +9 -0
- tokenstats-1.0.0/tokenstats.egg-info/dependency_links.txt +1 -0
- tokenstats-1.0.0/tokenstats.egg-info/entry_points.txt +2 -0
- tokenstats-1.0.0/tokenstats.egg-info/top_level.txt +1 -0
- tokenstats-1.0.0/tokenstats.py +2049 -0
tokenstats-1.0.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 ehharris
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,151 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: tokenstats
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: Permanent local record of OpenCode AI token usage.
|
|
5
|
+
Author: ehharris
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Keywords: tokens,opencode,usage,cost,cli,sqlite
|
|
8
|
+
Classifier: Development Status :: 5 - Production/Stable
|
|
9
|
+
Classifier: Environment :: Console
|
|
10
|
+
Classifier: Intended Audience :: Developers
|
|
11
|
+
Classifier: Operating System :: OS Independent
|
|
12
|
+
Classifier: Programming Language :: Python :: 3
|
|
13
|
+
Classifier: Topic :: Utilities
|
|
14
|
+
Requires-Python: >=3.9
|
|
15
|
+
Description-Content-Type: text/markdown
|
|
16
|
+
License-File: LICENSE
|
|
17
|
+
Dynamic: license-file
|
|
18
|
+
|
|
19
|
+
# tokenstats - An AI token usage record keeper
|
|
20
|
+
|
|
21
|
+
`tokenstats` snapshots OpenCode's session database (opened read-only) into its
|
|
22
|
+
own SQLite store (`~/.tokenstats/usage.db`) and reports it filtered by model,
|
|
23
|
+
date, and token counts. OpenCode prunes its own history over time; your copy in
|
|
24
|
+
`usage.db` never shrinks, so this machine's full token history survives.
|
|
25
|
+
|
|
26
|
+
Single Python file, stdlib only. Runs on Linux, macOS, and Windows and finds
|
|
27
|
+
OpenCode's database automatically for your OS.
|
|
28
|
+
|
|
29
|
+

|
|
30
|
+
|
|
31
|
+
## Install
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
pipx install tokenstats # recommended: a `tokenstats` command on PATH
|
|
35
|
+
# or
|
|
36
|
+
pip install --user tokenstats # the same command, into your user site
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
Installing is optional — the script also runs straight from the file:
|
|
40
|
+
|
|
41
|
+
```bash
|
|
42
|
+
python3 tokenstats.py [options]
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
Everything below uses the installed `tokenstats` command; substitute
|
|
46
|
+
`python3 tokenstats.py` when running from the file.
|
|
47
|
+
|
|
48
|
+
## Use
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
tokenstats # dashboard: totals, top models, recent sessions
|
|
52
|
+
tokenstats --model qwen # sessions from models matching "qwen"
|
|
53
|
+
tokenstats --total --model qwen # all-time totals per matching model
|
|
54
|
+
tokenstats --since 2026-11-01 --until 2026-11-13 # date window (both days inclusive)
|
|
55
|
+
tokenstats --daily # per-day totals
|
|
56
|
+
tokenstats --total # one all-time grand-total row
|
|
57
|
+
tokenstats --sessions=10 # the 10 most recent sessions
|
|
58
|
+
tokenstats --cost=claude # reference $ overlay — families: claude, codex, openai, deepseek, qwen
|
|
59
|
+
tokenstats --cache # combined cache read+write column (session views)
|
|
60
|
+
tokenstats --json | jq '.[].total' # machine-readable rows
|
|
61
|
+
tokenstats record # snapshot OpenCode, no report
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
Every query snapshots OpenCode first, so reports are always current. If the
|
|
65
|
+
database is missing or locked, you get a warning and your stored history, not
|
|
66
|
+
a failure. `--help` lists the options;
|
|
67
|
+
[docs/reference.md](docs/reference.md) documents every one of them, including
|
|
68
|
+
the hidden filters (`--db`, `--src`, `--min-in`, `--min-out`).
|
|
69
|
+
|
|
70
|
+
Per-model totals (`--total --model`, or just `--model`) end with a share
|
|
71
|
+
column — percent plus a bar scaled to the biggest row:
|
|
72
|
+
|
|
73
|
+

|
|
74
|
+
|
|
75
|
+
Opt-in overlays add columns without changing any number: `--cost[=TIER]` (a
|
|
76
|
+
reference dollar estimate at one model's list prices), `--real-cost` (the real
|
|
77
|
+
USD OpenCode stored), `--cache` (combined cache-read/write tokens, as a column
|
|
78
|
+
and a hero stat). Color is
|
|
79
|
+
decoration only: piped output, `NO_COLOR`, and `--json` stay plain.
|
|
80
|
+
|
|
81
|
+

|
|
82
|
+
|
|
83
|
+
## Themes
|
|
84
|
+
|
|
85
|
+
Ten themes are built in: `neon-midnight` (default), `tokyo-night`, `dracula`,
|
|
86
|
+
`nord`, `gruvbox-dark`, `solarized-dark`, `monokai`, `one-dark`,
|
|
87
|
+
`solarized-light`, `paper`.
|
|
88
|
+
|
|
89
|
+
```bash
|
|
90
|
+
tokenstats --theme=nord # paint this run
|
|
91
|
+
tokenstats --theme # list all slugs, mark the default
|
|
92
|
+
tokenstats --theme-default=nord # save nord as the default for later runs
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
### Your own theme
|
|
96
|
+
|
|
97
|
+
Drop one `.json` file into `~/.tokenstats/themes/`. The filename stem is the
|
|
98
|
+
slug — `copper-dusk.json` gives you `--theme=copper-dusk` — and it joins the
|
|
99
|
+
list on the next run, no code change. A file named like a built-in shadows it.
|
|
100
|
+
|
|
101
|
+
```json
|
|
102
|
+
{
|
|
103
|
+
"name": "Copper Dusk",
|
|
104
|
+
"colors": {
|
|
105
|
+
"border": "#5A4A42", "accent": "#F2A65A",
|
|
106
|
+
"label": "#9A8B80", "num": "#F5EDE4",
|
|
107
|
+
"tin": "#6FB3D2", "tout": "#E8747C",
|
|
108
|
+
"tcach": "#A9C46C", "ttotal": "#C792EA",
|
|
109
|
+
"tshare": "#5FD3C4"
|
|
110
|
+
}
|
|
111
|
+
}
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
All nine roles are required; every color is a `#rrggbb` string. A broken file
|
|
115
|
+
is skipped with a one-line warning — it never breaks a run. What each role
|
|
116
|
+
paints, and worked examples to copy, are in
|
|
117
|
+
[themes/README.md](themes/README.md).
|
|
118
|
+
|
|
119
|
+

|
|
120
|
+
|
|
121
|
+
## Optional: scheduled snapshots
|
|
122
|
+
|
|
123
|
+
You do **not** need a scheduler for up-to-date stats — every query snapshots
|
|
124
|
+
OpenCode first. Schedule an hourly `record` only as insurance for weeks you
|
|
125
|
+
never run the tool: OpenCode prunes its own tables, and a session that was
|
|
126
|
+
pruned before ever being recorded is lost.
|
|
127
|
+
|
|
128
|
+
**Linux / macOS** — add to `crontab -e` (point the path at the script, or use
|
|
129
|
+
the installed `tokenstats` command):
|
|
130
|
+
|
|
131
|
+
```cron
|
|
132
|
+
0 * * * * /usr/bin/python3 $HOME/path/to/tokenstats.py record >> $HOME/.tokenstats/record.log 2>&1
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
**Windows** — create an hourly task with Task Scheduler:
|
|
136
|
+
|
|
137
|
+
```bat
|
|
138
|
+
schtasks /Create /SC HOURLY /TN tokenstats /TR "python %USERPROFILE%\path\to\tokenstats.py record"
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
## Tests
|
|
142
|
+
|
|
143
|
+
```bash
|
|
144
|
+
python3 -m unittest test_tokenstats -v # ~400 tests, no dependencies, ~0.5 s
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
## More
|
|
148
|
+
|
|
149
|
+
- [docs/reference.md](docs/reference.md) — full option list, data locations,
|
|
150
|
+
OpenCode-database discovery, how every number is computed, guarantees
|
|
151
|
+
- [themes/README.md](themes/README.md) — theme file format reference
|
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
# tokenstats - An AI token usage record keeper
|
|
2
|
+
|
|
3
|
+
`tokenstats` snapshots OpenCode's session database (opened read-only) into its
|
|
4
|
+
own SQLite store (`~/.tokenstats/usage.db`) and reports it filtered by model,
|
|
5
|
+
date, and token counts. OpenCode prunes its own history over time; your copy in
|
|
6
|
+
`usage.db` never shrinks, so this machine's full token history survives.
|
|
7
|
+
|
|
8
|
+
Single Python file, stdlib only. Runs on Linux, macOS, and Windows and finds
|
|
9
|
+
OpenCode's database automatically for your OS.
|
|
10
|
+
|
|
11
|
+

|
|
12
|
+
|
|
13
|
+
## Install
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
pipx install tokenstats # recommended: a `tokenstats` command on PATH
|
|
17
|
+
# or
|
|
18
|
+
pip install --user tokenstats # the same command, into your user site
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
Installing is optional — the script also runs straight from the file:
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
python3 tokenstats.py [options]
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
Everything below uses the installed `tokenstats` command; substitute
|
|
28
|
+
`python3 tokenstats.py` when running from the file.
|
|
29
|
+
|
|
30
|
+
## Use
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
tokenstats # dashboard: totals, top models, recent sessions
|
|
34
|
+
tokenstats --model qwen # sessions from models matching "qwen"
|
|
35
|
+
tokenstats --total --model qwen # all-time totals per matching model
|
|
36
|
+
tokenstats --since 2026-11-01 --until 2026-11-13 # date window (both days inclusive)
|
|
37
|
+
tokenstats --daily # per-day totals
|
|
38
|
+
tokenstats --total # one all-time grand-total row
|
|
39
|
+
tokenstats --sessions=10 # the 10 most recent sessions
|
|
40
|
+
tokenstats --cost=claude # reference $ overlay — families: claude, codex, openai, deepseek, qwen
|
|
41
|
+
tokenstats --cache # combined cache read+write column (session views)
|
|
42
|
+
tokenstats --json | jq '.[].total' # machine-readable rows
|
|
43
|
+
tokenstats record # snapshot OpenCode, no report
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
Every query snapshots OpenCode first, so reports are always current. If the
|
|
47
|
+
database is missing or locked, you get a warning and your stored history, not
|
|
48
|
+
a failure. `--help` lists the options;
|
|
49
|
+
[docs/reference.md](docs/reference.md) documents every one of them, including
|
|
50
|
+
the hidden filters (`--db`, `--src`, `--min-in`, `--min-out`).
|
|
51
|
+
|
|
52
|
+
Per-model totals (`--total --model`, or just `--model`) end with a share
|
|
53
|
+
column — percent plus a bar scaled to the biggest row:
|
|
54
|
+
|
|
55
|
+

|
|
56
|
+
|
|
57
|
+
Opt-in overlays add columns without changing any number: `--cost[=TIER]` (a
|
|
58
|
+
reference dollar estimate at one model's list prices), `--real-cost` (the real
|
|
59
|
+
USD OpenCode stored), `--cache` (combined cache-read/write tokens, as a column
|
|
60
|
+
and a hero stat). Color is
|
|
61
|
+
decoration only: piped output, `NO_COLOR`, and `--json` stay plain.
|
|
62
|
+
|
|
63
|
+

|
|
64
|
+
|
|
65
|
+
## Themes
|
|
66
|
+
|
|
67
|
+
Ten themes are built in: `neon-midnight` (default), `tokyo-night`, `dracula`,
|
|
68
|
+
`nord`, `gruvbox-dark`, `solarized-dark`, `monokai`, `one-dark`,
|
|
69
|
+
`solarized-light`, `paper`.
|
|
70
|
+
|
|
71
|
+
```bash
|
|
72
|
+
tokenstats --theme=nord # paint this run
|
|
73
|
+
tokenstats --theme # list all slugs, mark the default
|
|
74
|
+
tokenstats --theme-default=nord # save nord as the default for later runs
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
### Your own theme
|
|
78
|
+
|
|
79
|
+
Drop one `.json` file into `~/.tokenstats/themes/`. The filename stem is the
|
|
80
|
+
slug — `copper-dusk.json` gives you `--theme=copper-dusk` — and it joins the
|
|
81
|
+
list on the next run, no code change. A file named like a built-in shadows it.
|
|
82
|
+
|
|
83
|
+
```json
|
|
84
|
+
{
|
|
85
|
+
"name": "Copper Dusk",
|
|
86
|
+
"colors": {
|
|
87
|
+
"border": "#5A4A42", "accent": "#F2A65A",
|
|
88
|
+
"label": "#9A8B80", "num": "#F5EDE4",
|
|
89
|
+
"tin": "#6FB3D2", "tout": "#E8747C",
|
|
90
|
+
"tcach": "#A9C46C", "ttotal": "#C792EA",
|
|
91
|
+
"tshare": "#5FD3C4"
|
|
92
|
+
}
|
|
93
|
+
}
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
All nine roles are required; every color is a `#rrggbb` string. A broken file
|
|
97
|
+
is skipped with a one-line warning — it never breaks a run. What each role
|
|
98
|
+
paints, and worked examples to copy, are in
|
|
99
|
+
[themes/README.md](themes/README.md).
|
|
100
|
+
|
|
101
|
+

|
|
102
|
+
|
|
103
|
+
## Optional: scheduled snapshots
|
|
104
|
+
|
|
105
|
+
You do **not** need a scheduler for up-to-date stats — every query snapshots
|
|
106
|
+
OpenCode first. Schedule an hourly `record` only as insurance for weeks you
|
|
107
|
+
never run the tool: OpenCode prunes its own tables, and a session that was
|
|
108
|
+
pruned before ever being recorded is lost.
|
|
109
|
+
|
|
110
|
+
**Linux / macOS** — add to `crontab -e` (point the path at the script, or use
|
|
111
|
+
the installed `tokenstats` command):
|
|
112
|
+
|
|
113
|
+
```cron
|
|
114
|
+
0 * * * * /usr/bin/python3 $HOME/path/to/tokenstats.py record >> $HOME/.tokenstats/record.log 2>&1
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
**Windows** — create an hourly task with Task Scheduler:
|
|
118
|
+
|
|
119
|
+
```bat
|
|
120
|
+
schtasks /Create /SC HOURLY /TN tokenstats /TR "python %USERPROFILE%\path\to\tokenstats.py record"
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
## Tests
|
|
124
|
+
|
|
125
|
+
```bash
|
|
126
|
+
python3 -m unittest test_tokenstats -v # ~400 tests, no dependencies, ~0.5 s
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
## More
|
|
130
|
+
|
|
131
|
+
- [docs/reference.md](docs/reference.md) — full option list, data locations,
|
|
132
|
+
OpenCode-database discovery, how every number is computed, guarantees
|
|
133
|
+
- [themes/README.md](themes/README.md) — theme file format reference
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=77"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "tokenstats"
|
|
7
|
+
version = "1.0.0"
|
|
8
|
+
description = "Permanent local record of OpenCode AI token usage."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.9"
|
|
11
|
+
license = "MIT"
|
|
12
|
+
license-files = ["LICENSE"]
|
|
13
|
+
authors = [{ name = "ehharris" }]
|
|
14
|
+
keywords = ["tokens", "opencode", "usage", "cost", "cli", "sqlite"]
|
|
15
|
+
classifiers = [
|
|
16
|
+
"Development Status :: 5 - Production/Stable",
|
|
17
|
+
"Environment :: Console",
|
|
18
|
+
"Intended Audience :: Developers",
|
|
19
|
+
"Operating System :: OS Independent",
|
|
20
|
+
"Programming Language :: Python :: 3",
|
|
21
|
+
"Topic :: Utilities",
|
|
22
|
+
]
|
|
23
|
+
dependencies = []
|
|
24
|
+
|
|
25
|
+
[project.scripts]
|
|
26
|
+
tokenstats = "tokenstats:cli_main"
|
|
27
|
+
|
|
28
|
+
[tool.setuptools]
|
|
29
|
+
py-modules = ["tokenstats"]
|
|
@@ -0,0 +1,151 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: tokenstats
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: Permanent local record of OpenCode AI token usage.
|
|
5
|
+
Author: ehharris
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Keywords: tokens,opencode,usage,cost,cli,sqlite
|
|
8
|
+
Classifier: Development Status :: 5 - Production/Stable
|
|
9
|
+
Classifier: Environment :: Console
|
|
10
|
+
Classifier: Intended Audience :: Developers
|
|
11
|
+
Classifier: Operating System :: OS Independent
|
|
12
|
+
Classifier: Programming Language :: Python :: 3
|
|
13
|
+
Classifier: Topic :: Utilities
|
|
14
|
+
Requires-Python: >=3.9
|
|
15
|
+
Description-Content-Type: text/markdown
|
|
16
|
+
License-File: LICENSE
|
|
17
|
+
Dynamic: license-file
|
|
18
|
+
|
|
19
|
+
# tokenstats - An AI token usage record keeper
|
|
20
|
+
|
|
21
|
+
`tokenstats` snapshots OpenCode's session database (opened read-only) into its
|
|
22
|
+
own SQLite store (`~/.tokenstats/usage.db`) and reports it filtered by model,
|
|
23
|
+
date, and token counts. OpenCode prunes its own history over time; your copy in
|
|
24
|
+
`usage.db` never shrinks, so this machine's full token history survives.
|
|
25
|
+
|
|
26
|
+
Single Python file, stdlib only. Runs on Linux, macOS, and Windows and finds
|
|
27
|
+
OpenCode's database automatically for your OS.
|
|
28
|
+
|
|
29
|
+

|
|
30
|
+
|
|
31
|
+
## Install
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
pipx install tokenstats # recommended: a `tokenstats` command on PATH
|
|
35
|
+
# or
|
|
36
|
+
pip install --user tokenstats # the same command, into your user site
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
Installing is optional — the script also runs straight from the file:
|
|
40
|
+
|
|
41
|
+
```bash
|
|
42
|
+
python3 tokenstats.py [options]
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
Everything below uses the installed `tokenstats` command; substitute
|
|
46
|
+
`python3 tokenstats.py` when running from the file.
|
|
47
|
+
|
|
48
|
+
## Use
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
tokenstats # dashboard: totals, top models, recent sessions
|
|
52
|
+
tokenstats --model qwen # sessions from models matching "qwen"
|
|
53
|
+
tokenstats --total --model qwen # all-time totals per matching model
|
|
54
|
+
tokenstats --since 2026-11-01 --until 2026-11-13 # date window (both days inclusive)
|
|
55
|
+
tokenstats --daily # per-day totals
|
|
56
|
+
tokenstats --total # one all-time grand-total row
|
|
57
|
+
tokenstats --sessions=10 # the 10 most recent sessions
|
|
58
|
+
tokenstats --cost=claude # reference $ overlay — families: claude, codex, openai, deepseek, qwen
|
|
59
|
+
tokenstats --cache # combined cache read+write column (session views)
|
|
60
|
+
tokenstats --json | jq '.[].total' # machine-readable rows
|
|
61
|
+
tokenstats record # snapshot OpenCode, no report
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
Every query snapshots OpenCode first, so reports are always current. If the
|
|
65
|
+
database is missing or locked, you get a warning and your stored history, not
|
|
66
|
+
a failure. `--help` lists the options;
|
|
67
|
+
[docs/reference.md](docs/reference.md) documents every one of them, including
|
|
68
|
+
the hidden filters (`--db`, `--src`, `--min-in`, `--min-out`).
|
|
69
|
+
|
|
70
|
+
Per-model totals (`--total --model`, or just `--model`) end with a share
|
|
71
|
+
column — percent plus a bar scaled to the biggest row:
|
|
72
|
+
|
|
73
|
+

|
|
74
|
+
|
|
75
|
+
Opt-in overlays add columns without changing any number: `--cost[=TIER]` (a
|
|
76
|
+
reference dollar estimate at one model's list prices), `--real-cost` (the real
|
|
77
|
+
USD OpenCode stored), `--cache` (combined cache-read/write tokens, as a column
|
|
78
|
+
and a hero stat). Color is
|
|
79
|
+
decoration only: piped output, `NO_COLOR`, and `--json` stay plain.
|
|
80
|
+
|
|
81
|
+

|
|
82
|
+
|
|
83
|
+
## Themes
|
|
84
|
+
|
|
85
|
+
Ten themes are built in: `neon-midnight` (default), `tokyo-night`, `dracula`,
|
|
86
|
+
`nord`, `gruvbox-dark`, `solarized-dark`, `monokai`, `one-dark`,
|
|
87
|
+
`solarized-light`, `paper`.
|
|
88
|
+
|
|
89
|
+
```bash
|
|
90
|
+
tokenstats --theme=nord # paint this run
|
|
91
|
+
tokenstats --theme # list all slugs, mark the default
|
|
92
|
+
tokenstats --theme-default=nord # save nord as the default for later runs
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
### Your own theme
|
|
96
|
+
|
|
97
|
+
Drop one `.json` file into `~/.tokenstats/themes/`. The filename stem is the
|
|
98
|
+
slug — `copper-dusk.json` gives you `--theme=copper-dusk` — and it joins the
|
|
99
|
+
list on the next run, no code change. A file named like a built-in shadows it.
|
|
100
|
+
|
|
101
|
+
```json
|
|
102
|
+
{
|
|
103
|
+
"name": "Copper Dusk",
|
|
104
|
+
"colors": {
|
|
105
|
+
"border": "#5A4A42", "accent": "#F2A65A",
|
|
106
|
+
"label": "#9A8B80", "num": "#F5EDE4",
|
|
107
|
+
"tin": "#6FB3D2", "tout": "#E8747C",
|
|
108
|
+
"tcach": "#A9C46C", "ttotal": "#C792EA",
|
|
109
|
+
"tshare": "#5FD3C4"
|
|
110
|
+
}
|
|
111
|
+
}
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
All nine roles are required; every color is a `#rrggbb` string. A broken file
|
|
115
|
+
is skipped with a one-line warning — it never breaks a run. What each role
|
|
116
|
+
paints, and worked examples to copy, are in
|
|
117
|
+
[themes/README.md](themes/README.md).
|
|
118
|
+
|
|
119
|
+

|
|
120
|
+
|
|
121
|
+
## Optional: scheduled snapshots
|
|
122
|
+
|
|
123
|
+
You do **not** need a scheduler for up-to-date stats — every query snapshots
|
|
124
|
+
OpenCode first. Schedule an hourly `record` only as insurance for weeks you
|
|
125
|
+
never run the tool: OpenCode prunes its own tables, and a session that was
|
|
126
|
+
pruned before ever being recorded is lost.
|
|
127
|
+
|
|
128
|
+
**Linux / macOS** — add to `crontab -e` (point the path at the script, or use
|
|
129
|
+
the installed `tokenstats` command):
|
|
130
|
+
|
|
131
|
+
```cron
|
|
132
|
+
0 * * * * /usr/bin/python3 $HOME/path/to/tokenstats.py record >> $HOME/.tokenstats/record.log 2>&1
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
**Windows** — create an hourly task with Task Scheduler:
|
|
136
|
+
|
|
137
|
+
```bat
|
|
138
|
+
schtasks /Create /SC HOURLY /TN tokenstats /TR "python %USERPROFILE%\path\to\tokenstats.py record"
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
## Tests
|
|
142
|
+
|
|
143
|
+
```bash
|
|
144
|
+
python3 -m unittest test_tokenstats -v # ~400 tests, no dependencies, ~0.5 s
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
## More
|
|
148
|
+
|
|
149
|
+
- [docs/reference.md](docs/reference.md) — full option list, data locations,
|
|
150
|
+
OpenCode-database discovery, how every number is computed, guarantees
|
|
151
|
+
- [themes/README.md](themes/README.md) — theme file format reference
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
tokenstats
|