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.
@@ -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
+ ![dashboard](docs/images/dashboard.png)
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
+ ![per-model share bars](docs/images/share-bars.png)
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
+ ![daily totals with a cost overlay](docs/images/theme-tokyo-night.png)
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
+ ![nord, with the --cache and --real-cost columns](docs/images/theme-nord.png)
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
+ ![dashboard](docs/images/dashboard.png)
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
+ ![per-model share bars](docs/images/share-bars.png)
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
+ ![daily totals with a cost overlay](docs/images/theme-tokyo-night.png)
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
+ ![nord, with the --cache and --real-cost columns](docs/images/theme-nord.png)
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,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -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
+ ![dashboard](docs/images/dashboard.png)
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
+ ![per-model share bars](docs/images/share-bars.png)
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
+ ![daily totals with a cost overlay](docs/images/theme-tokyo-night.png)
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
+ ![nord, with the --cache and --real-cost columns](docs/images/theme-nord.png)
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,9 @@
1
+ LICENSE
2
+ README.md
3
+ pyproject.toml
4
+ tokenstats.py
5
+ tokenstats.egg-info/PKG-INFO
6
+ tokenstats.egg-info/SOURCES.txt
7
+ tokenstats.egg-info/dependency_links.txt
8
+ tokenstats.egg-info/entry_points.txt
9
+ tokenstats.egg-info/top_level.txt
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ tokenstats = tokenstats:cli_main
@@ -0,0 +1 @@
1
+ tokenstats