codex-usage-limits 0.1.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.
- codex_usage_limits-0.1.0/LICENSE +21 -0
- codex_usage_limits-0.1.0/PKG-INFO +235 -0
- codex_usage_limits-0.1.0/README.md +215 -0
- codex_usage_limits-0.1.0/pyproject.toml +33 -0
- codex_usage_limits-0.1.0/setup.cfg +4 -0
- codex_usage_limits-0.1.0/src/codex_usage/__init__.py +3 -0
- codex_usage_limits-0.1.0/src/codex_usage/__main__.py +8 -0
- codex_usage_limits-0.1.0/src/codex_usage/api.py +167 -0
- codex_usage_limits-0.1.0/src/codex_usage/auth.py +110 -0
- codex_usage_limits-0.1.0/src/codex_usage/cli.py +66 -0
- codex_usage_limits-0.1.0/src/codex_usage/report.py +155 -0
- codex_usage_limits-0.1.0/src/codex_usage_limits.egg-info/PKG-INFO +235 -0
- codex_usage_limits-0.1.0/src/codex_usage_limits.egg-info/SOURCES.txt +17 -0
- codex_usage_limits-0.1.0/src/codex_usage_limits.egg-info/dependency_links.txt +1 -0
- codex_usage_limits-0.1.0/src/codex_usage_limits.egg-info/entry_points.txt +2 -0
- codex_usage_limits-0.1.0/src/codex_usage_limits.egg-info/top_level.txt +1 -0
- codex_usage_limits-0.1.0/tests/test_auth.py +165 -0
- codex_usage_limits-0.1.0/tests/test_report.py +238 -0
- codex_usage_limits-0.1.0/tests/test_sources.py +319 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 codex-usage contributors
|
|
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,235 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: codex-usage-limits
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: CLI for Codex plan usage and rate limits, with session-log fallback and warning thresholds.
|
|
5
|
+
Author: codex-usage contributors
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/javaisbetterthanpython/codex-usage
|
|
8
|
+
Project-URL: Issues, https://github.com/javaisbetterthanpython/codex-usage/issues
|
|
9
|
+
Keywords: codex,openai,chatgpt,usage,rate-limit,weekly-usage,subscription,cli
|
|
10
|
+
Classifier: Development Status :: 4 - Beta
|
|
11
|
+
Classifier: Environment :: Console
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: Operating System :: OS Independent
|
|
14
|
+
Classifier: Programming Language :: Python :: 3
|
|
15
|
+
Classifier: Topic :: Utilities
|
|
16
|
+
Requires-Python: >=3.9
|
|
17
|
+
Description-Content-Type: text/markdown
|
|
18
|
+
License-File: LICENSE
|
|
19
|
+
Dynamic: license-file
|
|
20
|
+
|
|
21
|
+
<h1 align="center">๐ codex-usage</h1>
|
|
22
|
+
|
|
23
|
+
<p align="center">
|
|
24
|
+
<b>Your Codex plan limits โ right from your terminal.</b>
|
|
25
|
+
</p>
|
|
26
|
+
|
|
27
|
+
<p align="center">
|
|
28
|
+
<a href="https://pypi.org/project/codex-usage-limits/"><img alt="PyPI" src="https://img.shields.io/pypi/v/codex-usage-limits?color=blue&label=PyPI"></a>
|
|
29
|
+
<img alt="Python" src="https://img.shields.io/badge/python-3.9%2B-blue">
|
|
30
|
+
<img alt="Platforms" src="https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey">
|
|
31
|
+
<img alt="Dependencies" src="https://img.shields.io/badge/dependencies-zero-brightgreen">
|
|
32
|
+
<img alt="License" src="https://img.shields.io/badge/license-MIT-green">
|
|
33
|
+
</p>
|
|
34
|
+
|
|
35
|
+
<p align="center">
|
|
36
|
+
<img src="https://raw.githubusercontent.com/javaisbetterthanpython/codex-usage/main/docs/demo.gif" alt="codex-usage demo" width="760">
|
|
37
|
+
</p>
|
|
38
|
+
|
|
39
|
+
---
|
|
40
|
+
|
|
41
|
+
Codex shows your plan limits only in the interactive `/status` screen.
|
|
42
|
+
**`codex-usage` gives you plan usage from the shell** โ for scripts, hooks, and
|
|
43
|
+
AI agents deciding when to back off. It uses the Codex login already on your
|
|
44
|
+
machine.
|
|
45
|
+
|
|
46
|
+
The 5-hour window appears when your plan has one and the usage source reports
|
|
47
|
+
it. Some plans have weekly limits only.
|
|
48
|
+
|
|
49
|
+
**Install `codex-usage-limits` from PyPI. The command is `codex-usage`.**
|
|
50
|
+
|
|
51
|
+
```text
|
|
52
|
+
$ codex-usage
|
|
53
|
+
7-day: 59% used, resets Sun 03:00 (in 12h29m)
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
## โจ Features
|
|
57
|
+
|
|
58
|
+
- **Usage windows** โ 5-hour and weekly usage when available, additional limits, and local reset times.
|
|
59
|
+
- **๐ฆ Thresholds for scripts** โ `--warn [N]` checks any usage window. `--warn-7d [N]` checks the main weekly window. Both exit 1 at or above N%.
|
|
60
|
+
- **๐ Extra detail** โ `--all` shows limit status, code-review usage, and the plan and credits when available.
|
|
61
|
+
- **๐ Session logs** โ a local fallback when the endpoint and its saved answer are unavailable.
|
|
62
|
+
- **๐งพ Plain, JSON, or short** โ readable in a terminal and easy to use from scripts.
|
|
63
|
+
- **๐ Cross-platform** โ macOS, Linux, and Windows with Python 3.9+.
|
|
64
|
+
- **๐ Zero dependencies** โ pure Python standard library.
|
|
65
|
+
- **๐ Local & private** โ reads your existing login and sends the token only to ChatGPT.
|
|
66
|
+
|
|
67
|
+
## ๐ Quickstart
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
pip install codex-usage-limits
|
|
71
|
+
codex-usage
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
Sign in with ChatGPT using `codex login` on this machine first. Open `codex` if
|
|
75
|
+
the access token needs to refresh.
|
|
76
|
+
|
|
77
|
+
## ๐งโ๐ป Usage
|
|
78
|
+
|
|
79
|
+
| Command | What it does |
|
|
80
|
+
|---|---|
|
|
81
|
+
| `codex-usage` | Available usage windows and their reset times |
|
|
82
|
+
| `codex-usage --json` | Raw usage JSON with identity fields removed (alias for `--format json`) |
|
|
83
|
+
| `codex-usage --warn [N]` | Exit 1 when any usage window reaches N% (default 70) |
|
|
84
|
+
| `codex-usage --warn-7d [N]` | Exit 1 at or above N% of the main 7-day window (default 70) |
|
|
85
|
+
| `codex-usage --all` | Add per-limit details and the account summary in plain format |
|
|
86
|
+
| `codex-usage --format {plain,json,short}` | Choose output format (default plain) |
|
|
87
|
+
| `codex-usage -v`, `--verbose` | Print credential and usage sources and the plan, when available, to stderr |
|
|
88
|
+
| `codex-usage -V`, `--version` | Print the version |
|
|
89
|
+
| `codex-usage -h`, `--help` | Show help |
|
|
90
|
+
|
|
91
|
+
Flags combine. For example, run `codex-usage --format short --warn 70 --warn-7d 90`.
|
|
92
|
+
`--json` and `--format` set the same option, and the last one wins. `--all` adds
|
|
93
|
+
detail in plain format.
|
|
94
|
+
|
|
95
|
+
<details>
|
|
96
|
+
<summary><b>๐ Example <code>--all</code> output</b></summary>
|
|
97
|
+
|
|
98
|
+
```text
|
|
99
|
+
5-hour: 23% used, resets 14:00 (in 2h41m)
|
|
100
|
+
7-day: 59% used, resets Sun 03:00 (in 15h41m)
|
|
101
|
+
limit window percent status reset
|
|
102
|
+
------------------------------------------------------------------------------
|
|
103
|
+
codex 5-hour 23% allowed resets 14:00 (in 2h41m)
|
|
104
|
+
codex 7-day 59% allowed resets Sun 03:00 (in 15h41m)
|
|
105
|
+
code review 7-day 4% allowed resets Sun 03:00 (in 15h41m)
|
|
106
|
+
plan pro ยท credits 0 ยท reset credits 2 available
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
Detail fields depend on the account and endpoint response. With a session-log
|
|
110
|
+
answer, the CLI adds `(details not available from the session-log source)`.
|
|
111
|
+
</details>
|
|
112
|
+
|
|
113
|
+
## ๐ค Using it from scripts and agents
|
|
114
|
+
|
|
115
|
+
```bash
|
|
116
|
+
codex-usage --warn 70 || echo "back off"
|
|
117
|
+
codex-usage --warn 70 --warn-7d 90 --format short
|
|
118
|
+
codex-usage --json
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
The usual output is printed even when a threshold trips. Exit codes are **0**
|
|
122
|
+
for success, **1** when a threshold trips or no source answers, and **2** for an
|
|
123
|
+
argument error. Thresholds are inclusive, so `--warn` exits 1 at exactly 70%.
|
|
124
|
+
Missing or null windows are skipped. `--warn` includes additional usage limits,
|
|
125
|
+
and `--warn-7d` checks only the main 7-day window. Code-review limits appear
|
|
126
|
+
under `--all`.
|
|
127
|
+
|
|
128
|
+
## ๐ Codex session logs
|
|
129
|
+
|
|
130
|
+
Codex records rate-limit snapshots in `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl`
|
|
131
|
+
while you use it. When the endpoint and saved answer are unavailable, the CLI
|
|
132
|
+
reads the last Codex rate-limit snapshot from the newest session log. It uses
|
|
133
|
+
the event time to show the age and leaves out windows whose reset time has passed.
|
|
134
|
+
|
|
135
|
+
```text
|
|
136
|
+
$ codex-usage
|
|
137
|
+
5-hour: 23% used, resets 14:00 (in 2h41m)
|
|
138
|
+
7-day: 59% used, resets Sun 03:00 (in 15h41m)
|
|
139
|
+
(from the session log, 3 min ago)
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
With `--format short`, a session-log answer includes the model when available.
|
|
143
|
+
|
|
144
|
+
```text
|
|
145
|
+
gpt-6.2-sol ยท 5h 23% ยท 7d 59%
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
## ๐ค How it works
|
|
149
|
+
|
|
150
|
+
Sources are tried in this order.
|
|
151
|
+
|
|
152
|
+
1. `last-usage.json` if less than **5 minutes** old.
|
|
153
|
+
2. One live `GET https://chatgpt.com/backend-api/wham/usage`, saved on success.
|
|
154
|
+
3. `last-usage.json` if less than **60 minutes** old.
|
|
155
|
+
4. The newest Codex session log if its selected usage event is less than **60 minutes** old.
|
|
156
|
+
|
|
157
|
+
The cache and logs live in `~/.codex`, or `CODEX_HOME` when set. Cache writes
|
|
158
|
+
are atomic. Cached answers at least a minute old show their source and age, for
|
|
159
|
+
example `(from the endpoint, 3 min ago)`. Session-log answers always show their
|
|
160
|
+
age in plain output. If every source fails, the distinct reasons appear once
|
|
161
|
+
each on stderr.
|
|
162
|
+
|
|
163
|
+
Five-minute reuse avoids repeating requests. The single request times out
|
|
164
|
+
after 15 seconds and the CLI never polls or retries.
|
|
165
|
+
|
|
166
|
+
<details>
|
|
167
|
+
<summary><b>๐ Where credentials live (per OS)</b></summary>
|
|
168
|
+
|
|
169
|
+
The CLI looks for credentials in this order.
|
|
170
|
+
|
|
171
|
+
1. `CODEX_ACCESS_TOKEN` environment override, used as-is. Set `CODEX_ACCOUNT_ID`
|
|
172
|
+
to override the account ID from the token.
|
|
173
|
+
2. The `auth.json` credentials file.
|
|
174
|
+
3. macOS Keychain service **`Codex Auth`**, read with
|
|
175
|
+
`security find-generic-password -s "Codex Auth" -w` when the file is missing.
|
|
176
|
+
|
|
177
|
+
| OS | Credentials file |
|
|
178
|
+
|---|---|
|
|
179
|
+
| macOS / Linux | `~/.codex/auth.json` |
|
|
180
|
+
| Windows | `%USERPROFILE%\.codex\auth.json` |
|
|
181
|
+
|
|
182
|
+
`CODEX_HOME` changes the credentials, cache, and session-log paths. The token is
|
|
183
|
+
`tokens.access_token`. If the token has expired, open `codex` so it refreshes.
|
|
184
|
+
|
|
185
|
+
For the protocol and a recipe to rebuild the tool, see
|
|
186
|
+
**[docs/HOW_THIS_WAS_BUILT.md](docs/HOW_THIS_WAS_BUILT.md)**.
|
|
187
|
+
</details>
|
|
188
|
+
|
|
189
|
+
## ๐ Privacy & security
|
|
190
|
+
|
|
191
|
+
- Reads existing credentials and session logs. Codex handles token refresh.
|
|
192
|
+
- Sends the token only to **`chatgpt.com`**, with the usage request.
|
|
193
|
+
- Removes `email`, `user_id`, and `account_id` before writing the cache or printing JSON.
|
|
194
|
+
- Keeps tokens, request headers, and identities out of errors and verbose output.
|
|
195
|
+
- **No telemetry or third-party calls.**
|
|
196
|
+
|
|
197
|
+
## โ ๏ธ Good to know
|
|
198
|
+
|
|
199
|
+
- The usage endpoint is **undocumented**. Codex itself calls it, and the format may change.
|
|
200
|
+
- API-key logins have no ChatGPT plan limits. Use `codex login` to sign in with ChatGPT.
|
|
201
|
+
- Session logs update only while Codex runs. Old readings and reset windows age out.
|
|
202
|
+
- Plans differ. Some report a 5-hour and a weekly window, while others report only the weekly window.
|
|
203
|
+
|
|
204
|
+
## ๐ ๏ธ Install options
|
|
205
|
+
|
|
206
|
+
```bash
|
|
207
|
+
pip install codex-usage-limits # from PyPI
|
|
208
|
+
pipx install codex-usage-limits # isolated command installation
|
|
209
|
+
pip install . # from a local clone
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
Requires Python 3.9+. The PyPI distribution is **`codex-usage-limits`** because
|
|
213
|
+
`codex-usage` is taken on PyPI. The command and GitHub repo are `codex-usage`,
|
|
214
|
+
and the import package is `codex_usage`.
|
|
215
|
+
|
|
216
|
+
## ๐ค Contributing
|
|
217
|
+
|
|
218
|
+
Issues and PRs are welcome. After installing the local project with `pip install -e .`,
|
|
219
|
+
run the tests with:
|
|
220
|
+
|
|
221
|
+
```bash
|
|
222
|
+
pip install pytest && pytest -q
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
Tests use temporary config directories and mocked HTTP. They never contact the
|
|
226
|
+
endpoint or read your real credentials.
|
|
227
|
+
|
|
228
|
+
Regenerate the demo with `python3 docs/record_demo.py` after installing
|
|
229
|
+
[agg](https://github.com/asciinema/agg/releases) and the DejaVu Sans Mono font. The
|
|
230
|
+
recorder runs the CLI against an illustrative cache and session log with network
|
|
231
|
+
access disabled; it needs no credentials. The README embeds the resulting `docs/demo.gif`.
|
|
232
|
+
|
|
233
|
+
## ๐ License
|
|
234
|
+
|
|
235
|
+
[MIT](LICENSE) โ do whatever you like.
|
|
@@ -0,0 +1,215 @@
|
|
|
1
|
+
<h1 align="center">๐ codex-usage</h1>
|
|
2
|
+
|
|
3
|
+
<p align="center">
|
|
4
|
+
<b>Your Codex plan limits โ right from your terminal.</b>
|
|
5
|
+
</p>
|
|
6
|
+
|
|
7
|
+
<p align="center">
|
|
8
|
+
<a href="https://pypi.org/project/codex-usage-limits/"><img alt="PyPI" src="https://img.shields.io/pypi/v/codex-usage-limits?color=blue&label=PyPI"></a>
|
|
9
|
+
<img alt="Python" src="https://img.shields.io/badge/python-3.9%2B-blue">
|
|
10
|
+
<img alt="Platforms" src="https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey">
|
|
11
|
+
<img alt="Dependencies" src="https://img.shields.io/badge/dependencies-zero-brightgreen">
|
|
12
|
+
<img alt="License" src="https://img.shields.io/badge/license-MIT-green">
|
|
13
|
+
</p>
|
|
14
|
+
|
|
15
|
+
<p align="center">
|
|
16
|
+
<img src="https://raw.githubusercontent.com/javaisbetterthanpython/codex-usage/main/docs/demo.gif" alt="codex-usage demo" width="760">
|
|
17
|
+
</p>
|
|
18
|
+
|
|
19
|
+
---
|
|
20
|
+
|
|
21
|
+
Codex shows your plan limits only in the interactive `/status` screen.
|
|
22
|
+
**`codex-usage` gives you plan usage from the shell** โ for scripts, hooks, and
|
|
23
|
+
AI agents deciding when to back off. It uses the Codex login already on your
|
|
24
|
+
machine.
|
|
25
|
+
|
|
26
|
+
The 5-hour window appears when your plan has one and the usage source reports
|
|
27
|
+
it. Some plans have weekly limits only.
|
|
28
|
+
|
|
29
|
+
**Install `codex-usage-limits` from PyPI. The command is `codex-usage`.**
|
|
30
|
+
|
|
31
|
+
```text
|
|
32
|
+
$ codex-usage
|
|
33
|
+
7-day: 59% used, resets Sun 03:00 (in 12h29m)
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
## โจ Features
|
|
37
|
+
|
|
38
|
+
- **Usage windows** โ 5-hour and weekly usage when available, additional limits, and local reset times.
|
|
39
|
+
- **๐ฆ Thresholds for scripts** โ `--warn [N]` checks any usage window. `--warn-7d [N]` checks the main weekly window. Both exit 1 at or above N%.
|
|
40
|
+
- **๐ Extra detail** โ `--all` shows limit status, code-review usage, and the plan and credits when available.
|
|
41
|
+
- **๐ Session logs** โ a local fallback when the endpoint and its saved answer are unavailable.
|
|
42
|
+
- **๐งพ Plain, JSON, or short** โ readable in a terminal and easy to use from scripts.
|
|
43
|
+
- **๐ Cross-platform** โ macOS, Linux, and Windows with Python 3.9+.
|
|
44
|
+
- **๐ Zero dependencies** โ pure Python standard library.
|
|
45
|
+
- **๐ Local & private** โ reads your existing login and sends the token only to ChatGPT.
|
|
46
|
+
|
|
47
|
+
## ๐ Quickstart
|
|
48
|
+
|
|
49
|
+
```bash
|
|
50
|
+
pip install codex-usage-limits
|
|
51
|
+
codex-usage
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
Sign in with ChatGPT using `codex login` on this machine first. Open `codex` if
|
|
55
|
+
the access token needs to refresh.
|
|
56
|
+
|
|
57
|
+
## ๐งโ๐ป Usage
|
|
58
|
+
|
|
59
|
+
| Command | What it does |
|
|
60
|
+
|---|---|
|
|
61
|
+
| `codex-usage` | Available usage windows and their reset times |
|
|
62
|
+
| `codex-usage --json` | Raw usage JSON with identity fields removed (alias for `--format json`) |
|
|
63
|
+
| `codex-usage --warn [N]` | Exit 1 when any usage window reaches N% (default 70) |
|
|
64
|
+
| `codex-usage --warn-7d [N]` | Exit 1 at or above N% of the main 7-day window (default 70) |
|
|
65
|
+
| `codex-usage --all` | Add per-limit details and the account summary in plain format |
|
|
66
|
+
| `codex-usage --format {plain,json,short}` | Choose output format (default plain) |
|
|
67
|
+
| `codex-usage -v`, `--verbose` | Print credential and usage sources and the plan, when available, to stderr |
|
|
68
|
+
| `codex-usage -V`, `--version` | Print the version |
|
|
69
|
+
| `codex-usage -h`, `--help` | Show help |
|
|
70
|
+
|
|
71
|
+
Flags combine. For example, run `codex-usage --format short --warn 70 --warn-7d 90`.
|
|
72
|
+
`--json` and `--format` set the same option, and the last one wins. `--all` adds
|
|
73
|
+
detail in plain format.
|
|
74
|
+
|
|
75
|
+
<details>
|
|
76
|
+
<summary><b>๐ Example <code>--all</code> output</b></summary>
|
|
77
|
+
|
|
78
|
+
```text
|
|
79
|
+
5-hour: 23% used, resets 14:00 (in 2h41m)
|
|
80
|
+
7-day: 59% used, resets Sun 03:00 (in 15h41m)
|
|
81
|
+
limit window percent status reset
|
|
82
|
+
------------------------------------------------------------------------------
|
|
83
|
+
codex 5-hour 23% allowed resets 14:00 (in 2h41m)
|
|
84
|
+
codex 7-day 59% allowed resets Sun 03:00 (in 15h41m)
|
|
85
|
+
code review 7-day 4% allowed resets Sun 03:00 (in 15h41m)
|
|
86
|
+
plan pro ยท credits 0 ยท reset credits 2 available
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
Detail fields depend on the account and endpoint response. With a session-log
|
|
90
|
+
answer, the CLI adds `(details not available from the session-log source)`.
|
|
91
|
+
</details>
|
|
92
|
+
|
|
93
|
+
## ๐ค Using it from scripts and agents
|
|
94
|
+
|
|
95
|
+
```bash
|
|
96
|
+
codex-usage --warn 70 || echo "back off"
|
|
97
|
+
codex-usage --warn 70 --warn-7d 90 --format short
|
|
98
|
+
codex-usage --json
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
The usual output is printed even when a threshold trips. Exit codes are **0**
|
|
102
|
+
for success, **1** when a threshold trips or no source answers, and **2** for an
|
|
103
|
+
argument error. Thresholds are inclusive, so `--warn` exits 1 at exactly 70%.
|
|
104
|
+
Missing or null windows are skipped. `--warn` includes additional usage limits,
|
|
105
|
+
and `--warn-7d` checks only the main 7-day window. Code-review limits appear
|
|
106
|
+
under `--all`.
|
|
107
|
+
|
|
108
|
+
## ๐ Codex session logs
|
|
109
|
+
|
|
110
|
+
Codex records rate-limit snapshots in `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl`
|
|
111
|
+
while you use it. When the endpoint and saved answer are unavailable, the CLI
|
|
112
|
+
reads the last Codex rate-limit snapshot from the newest session log. It uses
|
|
113
|
+
the event time to show the age and leaves out windows whose reset time has passed.
|
|
114
|
+
|
|
115
|
+
```text
|
|
116
|
+
$ codex-usage
|
|
117
|
+
5-hour: 23% used, resets 14:00 (in 2h41m)
|
|
118
|
+
7-day: 59% used, resets Sun 03:00 (in 15h41m)
|
|
119
|
+
(from the session log, 3 min ago)
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
With `--format short`, a session-log answer includes the model when available.
|
|
123
|
+
|
|
124
|
+
```text
|
|
125
|
+
gpt-6.2-sol ยท 5h 23% ยท 7d 59%
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
## ๐ค How it works
|
|
129
|
+
|
|
130
|
+
Sources are tried in this order.
|
|
131
|
+
|
|
132
|
+
1. `last-usage.json` if less than **5 minutes** old.
|
|
133
|
+
2. One live `GET https://chatgpt.com/backend-api/wham/usage`, saved on success.
|
|
134
|
+
3. `last-usage.json` if less than **60 minutes** old.
|
|
135
|
+
4. The newest Codex session log if its selected usage event is less than **60 minutes** old.
|
|
136
|
+
|
|
137
|
+
The cache and logs live in `~/.codex`, or `CODEX_HOME` when set. Cache writes
|
|
138
|
+
are atomic. Cached answers at least a minute old show their source and age, for
|
|
139
|
+
example `(from the endpoint, 3 min ago)`. Session-log answers always show their
|
|
140
|
+
age in plain output. If every source fails, the distinct reasons appear once
|
|
141
|
+
each on stderr.
|
|
142
|
+
|
|
143
|
+
Five-minute reuse avoids repeating requests. The single request times out
|
|
144
|
+
after 15 seconds and the CLI never polls or retries.
|
|
145
|
+
|
|
146
|
+
<details>
|
|
147
|
+
<summary><b>๐ Where credentials live (per OS)</b></summary>
|
|
148
|
+
|
|
149
|
+
The CLI looks for credentials in this order.
|
|
150
|
+
|
|
151
|
+
1. `CODEX_ACCESS_TOKEN` environment override, used as-is. Set `CODEX_ACCOUNT_ID`
|
|
152
|
+
to override the account ID from the token.
|
|
153
|
+
2. The `auth.json` credentials file.
|
|
154
|
+
3. macOS Keychain service **`Codex Auth`**, read with
|
|
155
|
+
`security find-generic-password -s "Codex Auth" -w` when the file is missing.
|
|
156
|
+
|
|
157
|
+
| OS | Credentials file |
|
|
158
|
+
|---|---|
|
|
159
|
+
| macOS / Linux | `~/.codex/auth.json` |
|
|
160
|
+
| Windows | `%USERPROFILE%\.codex\auth.json` |
|
|
161
|
+
|
|
162
|
+
`CODEX_HOME` changes the credentials, cache, and session-log paths. The token is
|
|
163
|
+
`tokens.access_token`. If the token has expired, open `codex` so it refreshes.
|
|
164
|
+
|
|
165
|
+
For the protocol and a recipe to rebuild the tool, see
|
|
166
|
+
**[docs/HOW_THIS_WAS_BUILT.md](docs/HOW_THIS_WAS_BUILT.md)**.
|
|
167
|
+
</details>
|
|
168
|
+
|
|
169
|
+
## ๐ Privacy & security
|
|
170
|
+
|
|
171
|
+
- Reads existing credentials and session logs. Codex handles token refresh.
|
|
172
|
+
- Sends the token only to **`chatgpt.com`**, with the usage request.
|
|
173
|
+
- Removes `email`, `user_id`, and `account_id` before writing the cache or printing JSON.
|
|
174
|
+
- Keeps tokens, request headers, and identities out of errors and verbose output.
|
|
175
|
+
- **No telemetry or third-party calls.**
|
|
176
|
+
|
|
177
|
+
## โ ๏ธ Good to know
|
|
178
|
+
|
|
179
|
+
- The usage endpoint is **undocumented**. Codex itself calls it, and the format may change.
|
|
180
|
+
- API-key logins have no ChatGPT plan limits. Use `codex login` to sign in with ChatGPT.
|
|
181
|
+
- Session logs update only while Codex runs. Old readings and reset windows age out.
|
|
182
|
+
- Plans differ. Some report a 5-hour and a weekly window, while others report only the weekly window.
|
|
183
|
+
|
|
184
|
+
## ๐ ๏ธ Install options
|
|
185
|
+
|
|
186
|
+
```bash
|
|
187
|
+
pip install codex-usage-limits # from PyPI
|
|
188
|
+
pipx install codex-usage-limits # isolated command installation
|
|
189
|
+
pip install . # from a local clone
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
Requires Python 3.9+. The PyPI distribution is **`codex-usage-limits`** because
|
|
193
|
+
`codex-usage` is taken on PyPI. The command and GitHub repo are `codex-usage`,
|
|
194
|
+
and the import package is `codex_usage`.
|
|
195
|
+
|
|
196
|
+
## ๐ค Contributing
|
|
197
|
+
|
|
198
|
+
Issues and PRs are welcome. After installing the local project with `pip install -e .`,
|
|
199
|
+
run the tests with:
|
|
200
|
+
|
|
201
|
+
```bash
|
|
202
|
+
pip install pytest && pytest -q
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
Tests use temporary config directories and mocked HTTP. They never contact the
|
|
206
|
+
endpoint or read your real credentials.
|
|
207
|
+
|
|
208
|
+
Regenerate the demo with `python3 docs/record_demo.py` after installing
|
|
209
|
+
[agg](https://github.com/asciinema/agg/releases) and the DejaVu Sans Mono font. The
|
|
210
|
+
recorder runs the CLI against an illustrative cache and session log with network
|
|
211
|
+
access disabled; it needs no credentials. The README embeds the resulting `docs/demo.gif`.
|
|
212
|
+
|
|
213
|
+
## ๐ License
|
|
214
|
+
|
|
215
|
+
[MIT](LICENSE) โ do whatever you like.
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=77"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "codex-usage-limits"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "CLI for Codex plan usage and rate limits, with session-log fallback and warning thresholds."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = "MIT"
|
|
11
|
+
license-files = ["LICENSE"]
|
|
12
|
+
requires-python = ">=3.9"
|
|
13
|
+
authors = [{ name = "codex-usage contributors" }]
|
|
14
|
+
keywords = ["codex", "openai", "chatgpt", "usage", "rate-limit", "weekly-usage", "subscription", "cli"]
|
|
15
|
+
classifiers = [
|
|
16
|
+
"Development Status :: 4 - Beta",
|
|
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
|
+
codex-usage = "codex_usage.cli:main"
|
|
27
|
+
|
|
28
|
+
[project.urls]
|
|
29
|
+
Homepage = "https://github.com/javaisbetterthanpython/codex-usage"
|
|
30
|
+
Issues = "https://github.com/javaisbetterthanpython/codex-usage/issues"
|
|
31
|
+
|
|
32
|
+
[tool.setuptools.packages.find]
|
|
33
|
+
where = ["src"]
|