@simonesiega/codex-limits 0.1.4 → 0.1.5
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.
- package/CHANGELOG.md +32 -0
- package/README.md +87 -49
- package/SECURITY.md +7 -1
- package/dist/THIRD_PARTY_NOTICES.txt +738 -0
- package/dist/cli.js +169 -156
- package/dist/index.js +5 -3
- package/docs/photos/logo/title-animation.svg +34 -0
- package/package.json +19 -10
- package/scripts/postinstall.cjs +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -16,6 +16,38 @@ All notable changes to codex-limits are documented in this file.
|
|
|
16
16
|
|
|
17
17
|
### Security
|
|
18
18
|
|
|
19
|
+
## [0.1.5] - 2026-07-22
|
|
20
|
+
|
|
21
|
+
### Breaking Changes
|
|
22
|
+
|
|
23
|
+
### Added
|
|
24
|
+
|
|
25
|
+
- Added bundled third-party license notices to published package artifacts.
|
|
26
|
+
- Added the `codex-limits agents` command group with named, interactive, and all-agent integration installation while keeping the existing `init` syntax supported.
|
|
27
|
+
|
|
28
|
+
### Changed
|
|
29
|
+
|
|
30
|
+
- Changed CI to run source checks once and validate packed artifacts across Node.js 20, 22, and 24 on Linux and Windows.
|
|
31
|
+
- Changed CLI parsing and help to use one command definition source, with generated nested help and order-independent supported options.
|
|
32
|
+
|
|
33
|
+
### Fixed
|
|
34
|
+
|
|
35
|
+
- Fixed authenticated request cancellation when a caller abort coincided with request startup.
|
|
36
|
+
- Fixed CLI help to describe credential overrides for both live usage and reset-credit requests.
|
|
37
|
+
- Fixed very small text dashboards to stay within the available terminal rows when coupon entries are truncated.
|
|
38
|
+
- Fixed Windows checkouts to preserve LF line endings so local formatting checks remain stable.
|
|
39
|
+
- Fixed weekly-only usage data to use declared window durations across live and local sources, avoid stale local fallback for recognized live windows, and omit unavailable 5-hour sections from terminal dashboards and the OpenCode integration.
|
|
40
|
+
- Fixed clean production builds and kept terminal rendering compatible with Node.js 20.
|
|
41
|
+
|
|
42
|
+
### Removed
|
|
43
|
+
|
|
44
|
+
### Security
|
|
45
|
+
|
|
46
|
+
- Refused symbolic-link files and path-replacement races when reading bounded local files, including agent configurations.
|
|
47
|
+
- Disabled dependency lifecycle scripts during CI installs, pinned workflow actions to immutable commits, and explicitly requested npm provenance for published packages.
|
|
48
|
+
- Shortened agent configuration paths under the user home to `~/...` and redacted paths outside it before printing installation results.
|
|
49
|
+
- Sanitized and bounded command and agent errors, and rejected control characters in command metadata before terminal output.
|
|
50
|
+
|
|
19
51
|
## [0.1.4] - 2026-07-13
|
|
20
52
|
|
|
21
53
|
### Added
|
package/README.md
CHANGED
|
@@ -1,7 +1,5 @@
|
|
|
1
1
|
<h1 align="center">
|
|
2
|
-
<img src="docs/photos/logo/
|
|
3
|
-
<br />
|
|
4
|
-
Codex Limits
|
|
2
|
+
<img src="docs/photos/logo/title-animation.svg" alt="Codex Limits" width="650" />
|
|
5
3
|
</h1>
|
|
6
4
|
|
|
7
5
|
<p align="center">
|
|
@@ -22,6 +20,12 @@
|
|
|
22
20
|
<img src="https://img.shields.io/badge/Bun-toolchain-black?logo=bun" alt="Bun toolchain" />
|
|
23
21
|
</p>
|
|
24
22
|
|
|
23
|
+
<p align="center">
|
|
24
|
+
<a href="#local-development">
|
|
25
|
+
<img src="https://img.shields.io/badge/test_coverage-95.9%25_lines-brightgreen" alt="Test coverage: 95.9% lines" />
|
|
26
|
+
</a>
|
|
27
|
+
</p>
|
|
28
|
+
|
|
25
29
|
## Preview 🚀
|
|
26
30
|
|
|
27
31
|
<p align="center">
|
|
@@ -29,7 +33,7 @@
|
|
|
29
33
|
<img src="docs/photos/terminal/final_result_small.png" alt="Final codex-limits smaller terminal dashboard" width="400" />
|
|
30
34
|
</p>
|
|
31
35
|
|
|
32
|
-
The screenshots show the **`codex-limits`** terminal dashboards: clean, read-only TUIs that summarize Codex usage limits and reset-credit coupons in one place. The top section displays the
|
|
36
|
+
The screenshots show the **`codex-limits`** terminal dashboards: clean, read-only TUIs that summarize Codex usage limits and reset-credit coupons in one place. The top section displays the usage windows currently supplied by Codex—weekly usage and, when available, the 5-hour window—with remaining percentages, visual progress bars, and reset times, while the lower section shows available reset coupons, their expiration dates, and the next coupon deadline.
|
|
33
37
|
|
|
34
38
|
## Contents
|
|
35
39
|
|
|
@@ -41,11 +45,18 @@ The screenshots show the **`codex-limits`** terminal dashboards: clean, read-onl
|
|
|
41
45
|
- [Environment](#environment)
|
|
42
46
|
- [Usage](#usage)
|
|
43
47
|
- [Troubleshooting](#troubleshooting)
|
|
48
|
+
- [Documentation](#documentation)
|
|
49
|
+
- [JSON output](docs/readme/json-output.md)
|
|
50
|
+
- [Agent integrations](docs/readme/agent-integrations.md)
|
|
51
|
+
- [Compatibility](docs/readme/compatibility.md)
|
|
44
52
|
- [Local development](#local-development)
|
|
45
53
|
- [Security](#security)
|
|
46
54
|
- [License](#license)
|
|
47
55
|
- [Contributors](#contributors)
|
|
48
56
|
|
|
57
|
+
> Last verified against: `@simonesiega/codex-limits` v0.1.5
|
|
58
|
+
> Verification date: 2026-07-22
|
|
59
|
+
|
|
49
60
|
## Quick start
|
|
50
61
|
|
|
51
62
|
The package is available on npm as [`@simonesiega/codex-limits`](https://www.npmjs.com/package/@simonesiega/codex-limits) and supports Node.js 20 or newer.
|
|
@@ -66,18 +77,20 @@ codex-limits
|
|
|
66
77
|
|
|
67
78
|
The list of available commands is shown when you run `codex-limits --help` or in the [Usage](#usage) section.
|
|
68
79
|
|
|
69
|
-
Install optional agent
|
|
80
|
+
Install an optional agent integration by name:
|
|
70
81
|
|
|
71
82
|
```bash
|
|
72
|
-
codex-limits
|
|
83
|
+
codex-limits agents install <agent-name>
|
|
73
84
|
```
|
|
74
85
|
|
|
75
86
|
For example, install the OpenCode integration:
|
|
76
87
|
|
|
77
88
|
```bash
|
|
78
|
-
codex-limits
|
|
89
|
+
codex-limits agents install opencode
|
|
79
90
|
```
|
|
80
91
|
|
|
92
|
+
The existing `codex-limits init --<agent-name>` syntax remains supported as a compatibility command.
|
|
93
|
+
|
|
81
94
|
## Requirements
|
|
82
95
|
|
|
83
96
|
| Requirement | Details |
|
|
@@ -91,25 +104,29 @@ codex-limits init --opencode
|
|
|
91
104
|
|
|
92
105
|
When you are working with Codex or agent-based coding tools, usage limits can interrupt your flow if you do not know what is left or when the next reset happens.
|
|
93
106
|
|
|
94
|
-
**`codex-limits`** gives you that information in one clean terminal view. It shows
|
|
107
|
+
**`codex-limits`** gives you that information in one clean terminal view. It shows the usage windows currently supplied by Codex, including weekly usage and the 5-hour window when available, together with remaining percentages, progress bars, reset times, and reset-credit coupons, so you can quickly check your status and continue coding without leaving the terminal.
|
|
95
108
|
|
|
96
|
-
It also includes plain-text commands for quick checks, JSON output for scripts and automation, optional agent integrations through `codex-limits
|
|
109
|
+
It also includes plain-text commands for quick checks, JSON output for scripts and automation, optional agent integrations through `codex-limits agents`, and safe output that never prints tokens, account IDs, auth headers, cookies, or raw local files.
|
|
97
110
|
|
|
98
111
|
## Agent integrations
|
|
99
112
|
|
|
113
|
+
Optional integrations make Codex limit information available directly inside supported coding agents while reusing the same read-only core and safety model as the CLI.
|
|
114
|
+
|
|
115
|
+
For installation details, adapter behavior, architecture, and contribution guidance, see the detailed [Agent integrations guide](docs/readme/agent-integrations.md).
|
|
116
|
+
|
|
100
117
|
### Supported agents
|
|
101
118
|
|
|
102
|
-
| Agent | Status | Agent command |
|
|
103
|
-
| -------- | --------- | --------------- |
|
|
104
|
-
| OpenCode | Supported | `/codex-limits` |
|
|
119
|
+
| Agent | Status | Agent command | Guide | Description |
|
|
120
|
+
| -------- | --------- | --------------- | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
|
|
121
|
+
| OpenCode | Supported | `/codex-limits` | [Installation and usage](docs/readme/agents/opencode.md) | Opens a fast, read-only Codex limits dashboard directly inside OpenCode without sending the request to the LLM. |
|
|
105
122
|
|
|
106
|
-
Agent integrations are not enabled automatically during package installation. They must be installed with `codex-limits init` and are only available in the agent terminal after a restart. See [Adding new agents](#adding-new-agents) if you want to add support for another agent.
|
|
123
|
+
Agent integrations are not enabled automatically during package installation. They must be installed with `codex-limits agents install` (or the compatible `codex-limits init` syntax) and are only available in the agent terminal after a restart. See [Adding new agents](#adding-new-agents) if you want to add support for another agent.
|
|
107
124
|
|
|
108
125
|
### Selected agent integration screenshots
|
|
109
126
|
|
|
110
127
|
#### OpenCode
|
|
111
128
|
|
|
112
|
-
The OpenCode integration adds a `/codex-limits` command that opens a compact modal inside the agent interface. It gives a quick read-only summary of the
|
|
129
|
+
The OpenCode integration adds a `/codex-limits` command that opens a compact modal inside the agent interface. It gives a quick read-only summary of the available usage windows and reset-credit coupons, then lets you close the view and return immediately to the conversation.
|
|
113
130
|
|
|
114
131
|
<p align="center">
|
|
115
132
|
<img src="docs/photos/agents/opencode/opencode_result.png" alt="OpenCode codex-limits integration screenshot" width="740" />
|
|
@@ -127,11 +144,11 @@ See the [Contributing](./CONTRIBUTING.md) guide if you want to add support for a
|
|
|
127
144
|
|
|
128
145
|
| Area | Path | Purpose |
|
|
129
146
|
| ------------------ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
130
|
-
| CLI entry | `src/package/cli.ts` | Starts the `codex-limits` command and
|
|
147
|
+
| CLI entry | `src/package/cli.ts` | Starts the `codex-limits` command and delegates to the shared command registry. |
|
|
131
148
|
| Core logic | `src/package/core` | Detects Codex data, reads local usage, fetches optional live information, normalizes usage windows, and keeps sensitive values out of the output. |
|
|
132
|
-
| CLI commands | `src/package/commands` |
|
|
149
|
+
| CLI commands | `src/package/commands` | Defines command metadata, shared parsing and help, scoped runtime services, and focused command handlers. |
|
|
133
150
|
| Terminal UI | `src/package/tui` | Renders the clean Ink-based dashboard from normalized usage data. |
|
|
134
|
-
| Agent integrations | `src/agents` | Contains optional coding-agent adapters
|
|
151
|
+
| Agent integrations | `src/agents` | Contains optional coding-agent adapters used by the `codex-limits agents` command group. |
|
|
135
152
|
| Tests | `tests` | Contains the test suite used to validate core behavior, CLI output, safety rules, and integration logic. |
|
|
136
153
|
|
|
137
154
|
This structure keeps the project easy to extend: the core decides what the data means, while the CLI, TUI, and agents only decide how that information is shown.
|
|
@@ -157,28 +174,32 @@ Local Codex data is inspected read-only with bounded file, directory, JSONL, and
|
|
|
157
174
|
|
|
158
175
|
## Usage
|
|
159
176
|
|
|
160
|
-
| Command
|
|
161
|
-
|
|
|
162
|
-
| `codex-limits`
|
|
163
|
-
| `codex-limits status`
|
|
164
|
-
| `codex-limits coupons`
|
|
165
|
-
| `codex-limits coupons --json`
|
|
166
|
-
| `codex-limits --json`
|
|
167
|
-
| `codex-limits
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
|
177
|
-
|
|
|
178
|
-
| `codex-limits
|
|
179
|
-
| `codex-limits
|
|
180
|
-
|
|
181
|
-
|
|
177
|
+
| Command | Description |
|
|
178
|
+
| ---------------------------------------- | ------------------------------------------------------ |
|
|
179
|
+
| `codex-limits` | Opens the interactive terminal dashboard. |
|
|
180
|
+
| `codex-limits status` | Prints a plain usage summary. |
|
|
181
|
+
| `codex-limits coupons` | Prints reset-credit coupon information. |
|
|
182
|
+
| `codex-limits coupons --json` | Prints machine-readable reset-credit coupon data only. |
|
|
183
|
+
| `codex-limits --json` | Prints machine-readable usage and coupon data. |
|
|
184
|
+
| `codex-limits agents` | Lists the available agent-management subcommands. |
|
|
185
|
+
| `codex-limits agents install <agent...>` | Installs one or more named agent integrations. |
|
|
186
|
+
| `codex-limits agents install --all` | Installs every supported agent integration. |
|
|
187
|
+
| `codex-limits init` | Runs the compatible interactive installation flow. |
|
|
188
|
+
|
|
189
|
+
### Agent management
|
|
190
|
+
|
|
191
|
+
Use `codex-limits agents install` to install optional integrations. Installation only updates the selected agent configuration; it does not send a prompt to an LLM or modify Codex data.
|
|
192
|
+
|
|
193
|
+
| Command | What it does |
|
|
194
|
+
| --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
195
|
+
| `codex-limits agents` | Prints help for the agent-management command group. |
|
|
196
|
+
| `codex-limits agents install` | Prompts for every supported integration when stdin and stdout are interactive terminals. If no integration is selected, nothing is installed. |
|
|
197
|
+
| `codex-limits agents install <agent...>` | Installs one or more named supported integrations without prompting. |
|
|
198
|
+
| `codex-limits agents install --all` | Installs every supported integration without prompting. |
|
|
199
|
+
| `codex-limits agents install --help` or `-h` | Prints generated installation help without changing any configuration. |
|
|
200
|
+
| `codex-limits init --<agent-name>` or `codex-limits init --all` | Preserves the existing initialization syntax as a compatibility command. |
|
|
201
|
+
|
|
202
|
+
`--all` cannot be combined with agent names. Duplicate and unknown agent names, unknown options, and extra positional arguments are rejected before any integration is installed. In a non-interactive terminal, provide `--all` or at least one agent name.
|
|
182
203
|
|
|
183
204
|
## Troubleshooting
|
|
184
205
|
|
|
@@ -194,9 +215,17 @@ Run `codex-limits status` to view the safe warning summary. Confirm that Codex a
|
|
|
194
215
|
|
|
195
216
|
Confirm that your user can read the selected Codex directory and its session files. Do not run the CLI with elevated privileges unless your Codex installation explicitly requires it. Prefer correcting the directory permissions or selecting the correct directory with `CODEX_LIMITS_HOME`.
|
|
196
217
|
|
|
197
|
-
### Agent command not appearing after
|
|
218
|
+
### Agent command not appearing after installation
|
|
198
219
|
|
|
199
|
-
Run the named
|
|
220
|
+
Run the named installer again, for example `codex-limits agents install opencode`, and confirm that it reports the integration as installed or already installed. Restart the target agent terminal so it reloads its configuration. If the command is still missing, verify that the displayed configuration paths belong to the agent installation you are using.
|
|
221
|
+
|
|
222
|
+
## Documentation
|
|
223
|
+
|
|
224
|
+
The README provides an overview of the main features, commands, and configuration options. For more detailed technical information, see the following guides:
|
|
225
|
+
|
|
226
|
+
- [JSON output](docs/readme/json-output.md) — Learn about the machine-readable output format, available fields, warnings, examples, and scripting behavior.
|
|
227
|
+
- [Agent integrations](docs/readme/agent-integrations.md) — Learn how agent integrations work, how they are installed, and how to develop and contribute new agent adapters.
|
|
228
|
+
- [Compatibility](docs/readme/compatibility.md) — View the supported operating systems, Node.js versions, terminals, Codex environments, and agent versions.
|
|
200
229
|
|
|
201
230
|
## Local development
|
|
202
231
|
|
|
@@ -211,17 +240,26 @@ bun run dev
|
|
|
211
240
|
|
|
212
241
|
Useful development commands:
|
|
213
242
|
|
|
214
|
-
| Command | Description
|
|
215
|
-
| ---------------------- |
|
|
216
|
-
| `bun run dev` | Runs the CLI in development mode.
|
|
217
|
-
| `bun run check` | Runs formatting, types, tests, builds, and package smoke checks. |
|
|
218
|
-
| `bun
|
|
219
|
-
| `bun run
|
|
220
|
-
| `bun run
|
|
221
|
-
| `bun
|
|
243
|
+
| Command | Description |
|
|
244
|
+
| ---------------------- | ------------------------------------------------------------------------------- |
|
|
245
|
+
| `bun run dev` | Runs the CLI in development mode. |
|
|
246
|
+
| `bun run check` | Runs formatting, documentation, types, tests, builds, and package smoke checks. |
|
|
247
|
+
| `bun run docs:link` | Checks local documentation links and heading anchors. |
|
|
248
|
+
| `bun run docs:schema` | Validates the JSON Schema and its example output. |
|
|
249
|
+
| `bun run docs:check` | Runs both documentation checks. |
|
|
250
|
+
| `bun test` | Runs the test suite. |
|
|
251
|
+
| `bun run build` | Builds the package. |
|
|
252
|
+
| `bun run format` | Formats the repository with Prettier. |
|
|
253
|
+
| `bun run format:check` | Checks formatting without changing files. |
|
|
222
254
|
|
|
223
255
|
## Security
|
|
224
256
|
|
|
257
|
+
| Operation | Reads | Writes | Network |
|
|
258
|
+
| ------------------------- | ----------------------------------------------- | --------------------------------- | ------------------------------- |
|
|
259
|
+
| `codex-limits` | Recognized Codex state and bounded session data | Nothing | Live usage and coupon endpoints |
|
|
260
|
+
| `status` / `coupons` | Shared read-only core | Nothing | When live data is requested |
|
|
261
|
+
| `agents install` / `init` | Selected agent configuration | Adds the integration registration | Does not send an LLM prompt |
|
|
262
|
+
|
|
225
263
|
For vulnerability reports and local data safety details, see [`SECURITY.md`](./SECURITY.md).
|
|
226
264
|
|
|
227
265
|
## License
|
package/SECURITY.md
CHANGED
|
@@ -59,7 +59,7 @@ Please do not publicly disclose the vulnerability until a fix is available or di
|
|
|
59
59
|
|
|
60
60
|
## Local data and network behavior
|
|
61
61
|
|
|
62
|
-
`codex-limits` is designed to keep Codex
|
|
62
|
+
`codex-limits` is designed to keep raw local Codex files and sensitive values on your machine. It makes authenticated requests to the documented ChatGPT Codex endpoints only when retrieving live usage or reset-credit information.
|
|
63
63
|
|
|
64
64
|
The CLI performs bounded, read-only inspection of recognized Codex home candidates. It reads small non-sensitive JSON state files, bounded `sessions/**/rollout-*.jsonl` logs, and `auth.json` only for credential resolution. Traversal depth, directory entries, file counts, file sizes, JSONL line sizes, and response sizes are limited; nested symbolic links are skipped. Raw local files and credentials are never returned by the public CLI or JSON contracts.
|
|
65
65
|
|
|
@@ -67,6 +67,12 @@ For live usage and coupon information, the project contacts the default ChatGPT
|
|
|
67
67
|
|
|
68
68
|
Agent integrations follow the same safety model: they should display a read-only summary by reusing the shared core, not send private Codex data to the agent, and not expose sensitive values inside the agent UI.
|
|
69
69
|
|
|
70
|
+
### Command safety boundaries
|
|
71
|
+
|
|
72
|
+
Every CLI command declares one enforced safety category. Dashboard, status, coupon, and agent-inspection commands are read-only and receive no write or account-mutation services. Agent installation is a local-write operation scoped to the selected agent configuration. Any future remote account mutation must use the separate `remote-mutation` category and declare an explicit boolean confirmation option before the router will execute it.
|
|
73
|
+
|
|
74
|
+
The existing `codex-limits init` compatibility command and the preferred `codex-limits agents install` command share the same local-write implementation. Neither command modifies Codex data or sends an LLM prompt.
|
|
75
|
+
|
|
70
76
|
## What to report
|
|
71
77
|
|
|
72
78
|
Please report any issue that could expose private data or break the read-only safety model of the project.
|