codex-cli-usage 0.1.6__tar.gz → 0.1.8__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_cli_usage-0.1.8/PKG-INFO +113 -0
- codex_cli_usage-0.1.8/README.md +104 -0
- {codex_cli_usage-0.1.6 → codex_cli_usage-0.1.8}/pyproject.toml +2 -2
- codex_cli_usage-0.1.8/src/codex_cli_usage/__init__.py +689 -0
- {codex_cli_usage-0.1.6 → codex_cli_usage-0.1.8}/src/codex_cli_usage/__main__.py +2 -1
- codex_cli_usage-0.1.8/tests/fixtures/duration_variants.json +44 -0
- codex_cli_usage-0.1.8/tests/fixtures/nullable_missing.json +19 -0
- codex_cli_usage-0.1.8/tests/fixtures/primary_5h_secondary_weekly.json +27 -0
- codex_cli_usage-0.1.8/tests/fixtures/primary_weekly_only.json +23 -0
- codex_cli_usage-0.1.8/tests/test_app_server.py +273 -0
- codex_cli_usage-0.1.8/tests/test_auth.py +163 -0
- codex_cli_usage-0.1.8/tests/test_usage.py +118 -0
- codex_cli_usage-0.1.8/uv.lock +20 -0
- codex_cli_usage-0.1.6/PKG-INFO +0 -86
- codex_cli_usage-0.1.6/README.md +0 -77
- codex_cli_usage-0.1.6/src/codex_cli_usage/__init__.py +0 -439
- codex_cli_usage-0.1.6/uv.lock +0 -8
- {codex_cli_usage-0.1.6 → codex_cli_usage-0.1.8}/.github/workflows/publish.yml +0 -0
- {codex_cli_usage-0.1.6 → codex_cli_usage-0.1.8}/.gitignore +0 -0
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: codex-cli-usage
|
|
3
|
+
Version: 0.1.8
|
|
4
|
+
Summary: Codex CLI usage monitor — fetches rate limits through the Codex app-server
|
|
5
|
+
Project-URL: Homepage, https://github.com/wakamex/codex-cli-usage
|
|
6
|
+
Project-URL: Source, https://github.com/wakamex/codex-cli-usage
|
|
7
|
+
Requires-Python: >=3.12
|
|
8
|
+
Description-Content-Type: text/markdown
|
|
9
|
+
|
|
10
|
+
# codex-cli-usage
|
|
11
|
+
|
|
12
|
+
Codex CLI usage monitor. Fetches your rate limit data through Codex and displays it in the terminal.
|
|
13
|
+
|
|
14
|
+
## Example output
|
|
15
|
+
|
|
16
|
+
`codex-cli-usage` command:
|
|
17
|
+
|
|
18
|
+
```
|
|
19
|
+
Plan: plus
|
|
20
|
+
Weekly 39% resets 143h26m
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
Codex statusline (self-caching — refreshes from API when stale, no daemon needed):
|
|
24
|
+
|
|
25
|
+
```
|
|
26
|
+
weekly:39% plus reset:143h26m
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
## Install
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
uv tool install codex-cli-usage
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
Then run:
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
# Check usage once
|
|
39
|
+
codex-cli-usage
|
|
40
|
+
|
|
41
|
+
# Run the daemon (keeps usage-limits.json updated)
|
|
42
|
+
codex-cli-usage daemon
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
## Commands
|
|
46
|
+
|
|
47
|
+
| Command | Description |
|
|
48
|
+
|---------|-------------|
|
|
49
|
+
| `codex-cli-usage` | Show current usage (colored terminal output) |
|
|
50
|
+
| `codex-cli-usage json` | Print raw JSON |
|
|
51
|
+
| `codex-cli-usage daemon [-i SECS]` | Run in foreground, refresh every 5 min (customizable) |
|
|
52
|
+
| `codex-cli-usage statusline` | Compact statusline (self-caching, no daemon needed) |
|
|
53
|
+
| `codex-cli-usage install` | Print setup instructions |
|
|
54
|
+
|
|
55
|
+
## How Codex CLI rate limiting works
|
|
56
|
+
|
|
57
|
+
Discovered by inspecting the Codex CLI and its authentication flow.
|
|
58
|
+
|
|
59
|
+
### Data sources
|
|
60
|
+
|
|
61
|
+
codex-cli-usage gets rate limit data from:
|
|
62
|
+
|
|
63
|
+
1. **`codex app-server --stdio`** — Preferred. Codex owns authentication and returns rate limits through `account/rateLimits/read`.
|
|
64
|
+
2. **`/backend-api/codex/usage` endpoint** — Compatibility fallback when Codex is missing or its app-server does not support the rate-limit method.
|
|
65
|
+
|
|
66
|
+
### Rate limit types
|
|
67
|
+
|
|
68
|
+
| Type | Description |
|
|
69
|
+
|------|-------------|
|
|
70
|
+
| `primary_window` | Primary window; duration comes from `limit_window_seconds` |
|
|
71
|
+
| `secondary_window` | Secondary window; duration comes from `limit_window_seconds` |
|
|
72
|
+
| `additional_rate_limits` | Per-model limits (e.g. specific model caps) |
|
|
73
|
+
| `code_review_rate_limit` | Code review usage limit |
|
|
74
|
+
|
|
75
|
+
Window names are derived from `limit_window_seconds`, not from whether the
|
|
76
|
+
backend calls a window primary or secondary. Approximately 5-hour, daily,
|
|
77
|
+
weekly, monthly, and annual windows receive duration labels. Other or missing
|
|
78
|
+
durations are shown as `Primary` or `Secondary`. Additional per-model limits
|
|
79
|
+
remain available in JSON for compatibility but are not shown in normal output.
|
|
80
|
+
|
|
81
|
+
### Cache format
|
|
82
|
+
|
|
83
|
+
Schema version 2 stores aggregate windows by their backend role while retaining
|
|
84
|
+
their actual duration:
|
|
85
|
+
|
|
86
|
+
```json
|
|
87
|
+
{
|
|
88
|
+
"schema_version": 2,
|
|
89
|
+
"primary": {
|
|
90
|
+
"pct": 39,
|
|
91
|
+
"resets_at": "2026-07-18T20:00:00+00:00",
|
|
92
|
+
"window_secs": 604800
|
|
93
|
+
}
|
|
94
|
+
}
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
Legacy `5h` and `7d` aliases are written only when the corresponding aggregate
|
|
98
|
+
window actually classifies as 5-hour or weekly. Readers should prefer
|
|
99
|
+
`primary` and `secondary`.
|
|
100
|
+
|
|
101
|
+
### Authentication
|
|
102
|
+
|
|
103
|
+
The OAuth tokens live at `~/.codex/auth.json`, written by the Codex CLI on login.
|
|
104
|
+
|
|
105
|
+
Codex owns automatic token refresh and credential persistence. The compatibility
|
|
106
|
+
fallback reads `auth.json` but never modifies credentials.
|
|
107
|
+
|
|
108
|
+
### Local files
|
|
109
|
+
|
|
110
|
+
| File | Written by | Contains |
|
|
111
|
+
|------|-----------|----------|
|
|
112
|
+
| `~/.codex/auth.json` | Codex CLI | OAuth tokens (access, refresh, id_token) |
|
|
113
|
+
| `~/.codex/usage-limits.json` | codex-cli-usage daemon | Cached API usage data (this tool) |
|
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
# codex-cli-usage
|
|
2
|
+
|
|
3
|
+
Codex CLI usage monitor. Fetches your rate limit data through Codex and displays it in the terminal.
|
|
4
|
+
|
|
5
|
+
## Example output
|
|
6
|
+
|
|
7
|
+
`codex-cli-usage` command:
|
|
8
|
+
|
|
9
|
+
```
|
|
10
|
+
Plan: plus
|
|
11
|
+
Weekly 39% resets 143h26m
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
Codex statusline (self-caching — refreshes from API when stale, no daemon needed):
|
|
15
|
+
|
|
16
|
+
```
|
|
17
|
+
weekly:39% plus reset:143h26m
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
## Install
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
uv tool install codex-cli-usage
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
Then run:
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
# Check usage once
|
|
30
|
+
codex-cli-usage
|
|
31
|
+
|
|
32
|
+
# Run the daemon (keeps usage-limits.json updated)
|
|
33
|
+
codex-cli-usage daemon
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
## Commands
|
|
37
|
+
|
|
38
|
+
| Command | Description |
|
|
39
|
+
|---------|-------------|
|
|
40
|
+
| `codex-cli-usage` | Show current usage (colored terminal output) |
|
|
41
|
+
| `codex-cli-usage json` | Print raw JSON |
|
|
42
|
+
| `codex-cli-usage daemon [-i SECS]` | Run in foreground, refresh every 5 min (customizable) |
|
|
43
|
+
| `codex-cli-usage statusline` | Compact statusline (self-caching, no daemon needed) |
|
|
44
|
+
| `codex-cli-usage install` | Print setup instructions |
|
|
45
|
+
|
|
46
|
+
## How Codex CLI rate limiting works
|
|
47
|
+
|
|
48
|
+
Discovered by inspecting the Codex CLI and its authentication flow.
|
|
49
|
+
|
|
50
|
+
### Data sources
|
|
51
|
+
|
|
52
|
+
codex-cli-usage gets rate limit data from:
|
|
53
|
+
|
|
54
|
+
1. **`codex app-server --stdio`** — Preferred. Codex owns authentication and returns rate limits through `account/rateLimits/read`.
|
|
55
|
+
2. **`/backend-api/codex/usage` endpoint** — Compatibility fallback when Codex is missing or its app-server does not support the rate-limit method.
|
|
56
|
+
|
|
57
|
+
### Rate limit types
|
|
58
|
+
|
|
59
|
+
| Type | Description |
|
|
60
|
+
|------|-------------|
|
|
61
|
+
| `primary_window` | Primary window; duration comes from `limit_window_seconds` |
|
|
62
|
+
| `secondary_window` | Secondary window; duration comes from `limit_window_seconds` |
|
|
63
|
+
| `additional_rate_limits` | Per-model limits (e.g. specific model caps) |
|
|
64
|
+
| `code_review_rate_limit` | Code review usage limit |
|
|
65
|
+
|
|
66
|
+
Window names are derived from `limit_window_seconds`, not from whether the
|
|
67
|
+
backend calls a window primary or secondary. Approximately 5-hour, daily,
|
|
68
|
+
weekly, monthly, and annual windows receive duration labels. Other or missing
|
|
69
|
+
durations are shown as `Primary` or `Secondary`. Additional per-model limits
|
|
70
|
+
remain available in JSON for compatibility but are not shown in normal output.
|
|
71
|
+
|
|
72
|
+
### Cache format
|
|
73
|
+
|
|
74
|
+
Schema version 2 stores aggregate windows by their backend role while retaining
|
|
75
|
+
their actual duration:
|
|
76
|
+
|
|
77
|
+
```json
|
|
78
|
+
{
|
|
79
|
+
"schema_version": 2,
|
|
80
|
+
"primary": {
|
|
81
|
+
"pct": 39,
|
|
82
|
+
"resets_at": "2026-07-18T20:00:00+00:00",
|
|
83
|
+
"window_secs": 604800
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
Legacy `5h` and `7d` aliases are written only when the corresponding aggregate
|
|
89
|
+
window actually classifies as 5-hour or weekly. Readers should prefer
|
|
90
|
+
`primary` and `secondary`.
|
|
91
|
+
|
|
92
|
+
### Authentication
|
|
93
|
+
|
|
94
|
+
The OAuth tokens live at `~/.codex/auth.json`, written by the Codex CLI on login.
|
|
95
|
+
|
|
96
|
+
Codex owns automatic token refresh and credential persistence. The compatibility
|
|
97
|
+
fallback reads `auth.json` but never modifies credentials.
|
|
98
|
+
|
|
99
|
+
### Local files
|
|
100
|
+
|
|
101
|
+
| File | Written by | Contains |
|
|
102
|
+
|------|-----------|----------|
|
|
103
|
+
| `~/.codex/auth.json` | Codex CLI | OAuth tokens (access, refresh, id_token) |
|
|
104
|
+
| `~/.codex/usage-limits.json` | codex-cli-usage daemon | Cached API usage data (this tool) |
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
[project]
|
|
2
2
|
name = "codex-cli-usage"
|
|
3
|
-
version = "0.1.
|
|
4
|
-
description = "Codex CLI usage monitor — fetches rate limits
|
|
3
|
+
version = "0.1.8"
|
|
4
|
+
description = "Codex CLI usage monitor — fetches rate limits through the Codex app-server"
|
|
5
5
|
readme = "README.md"
|
|
6
6
|
requires-python = ">=3.12"
|
|
7
7
|
dependencies = []
|