@simonesiega/codex-limits 1.1.0 → 1.2.0
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 +23 -14
- package/CODE_OF_CONDUCT.md +120 -0
- package/CONTRIBUTING.md +44 -41
- package/README.md +119 -143
- package/SECURITY.md +27 -10
- package/dist/cli.js +148 -137
- package/dist/copilot.mjs +3 -3
- package/dist/opencode.js +3 -3
- package/dist/pi.js +3 -3
- package/docs/README.md +36 -29
- package/docs/examples/codex-limits-coupons-output.example.json +25 -0
- package/docs/examples/codex-limits-doctor-output.example.json +14 -0
- package/docs/readme/agent-integrations.md +36 -15
- package/docs/readme/agents/copilot.md +20 -38
- package/docs/readme/agents/opencode.md +23 -29
- package/docs/readme/agents/pi.md +20 -29
- package/docs/readme/compatibility.md +34 -42
- package/docs/readme/json-output.md +70 -35
- package/docs/readme/troubleshooting.md +160 -0
- package/docs/schema/codex-limits-coupons.schema.json +107 -0
- package/docs/schema/codex-limits-doctor.schema.json +50 -0
- package/docs/schema/codex-limits.schema.json +2 -1
- package/package.json +11 -3
package/README.md
CHANGED
|
@@ -7,7 +7,7 @@
|
|
|
7
7
|
</p>
|
|
8
8
|
|
|
9
9
|
<p align="center">
|
|
10
|
-
|
|
10
|
+
<a href="#requirements">Requirements</a> · <a href="#quick-start">Installation</a> · <a href="#usage">Commands</a>
|
|
11
11
|
</p>
|
|
12
12
|
|
|
13
13
|
<p align="center">
|
|
@@ -21,7 +21,7 @@
|
|
|
21
21
|
<p align="center">
|
|
22
22
|
<img src="https://img.shields.io/npm/v/@simonesiega/codex-limits?label=npm" alt="npm version" />
|
|
23
23
|
<a href="https://www.npmjs.com/package/@simonesiega/codex-limits">
|
|
24
|
-
<img src="https://img.shields.io/npm/
|
|
24
|
+
<img src="https://img.shields.io/npm/dt/@simonesiega/codex-limits?label=total%20downloads" alt="Total npm downloads"/>
|
|
25
25
|
</a>
|
|
26
26
|
<a href="https://github.com/simonesiega/codex-limits/actions/workflows/check.yml?query=branch%3Amain"><img src="https://img.shields.io/github/actions/workflow/status/simonesiega/codex-limits/check.yml?branch=main&label=tests" alt="Automated test status" /></a>
|
|
27
27
|
</p>
|
|
@@ -42,15 +42,22 @@
|
|
|
42
42
|
|
|
43
43
|
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.
|
|
44
44
|
|
|
45
|
+
## Overview
|
|
46
|
+
|
|
47
|
+
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.
|
|
48
|
+
|
|
49
|
+
**`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.
|
|
50
|
+
|
|
51
|
+
It also includes plain-text commands for quick checks, an explicitly confirmed `codex-limits reset` action for using one reset coupon, a safe `codex-limits doctor` diagnostic report, 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, private paths, or raw local files.
|
|
52
|
+
|
|
45
53
|
## Contents
|
|
46
54
|
|
|
47
55
|
- [Quick start](#quick-start)
|
|
48
56
|
- [Requirements](#requirements)
|
|
49
|
-
- [
|
|
57
|
+
- [Usage](#usage)
|
|
50
58
|
- [Agent integrations](#agent-integrations)
|
|
51
59
|
- [How it works](#how-it-works)
|
|
52
60
|
- [Environment](#environment)
|
|
53
|
-
- [Usage](#usage)
|
|
54
61
|
- [Troubleshooting](#troubleshooting)
|
|
55
62
|
- [Documentation](#documentation)
|
|
56
63
|
- [Documentation hub](docs/README.md)
|
|
@@ -64,7 +71,7 @@ The screenshots show the **`codex-limits`** terminal dashboards: clean, read-onl
|
|
|
64
71
|
|
|
65
72
|
## Quick start
|
|
66
73
|
|
|
67
|
-
The package is available on npm as [`@simonesiega/codex-limits`](https://www.npmjs.com/package/@simonesiega/codex-limits)
|
|
74
|
+
The package is available on npm as [`@simonesiega/codex-limits`](https://www.npmjs.com/package/@simonesiega/codex-limits). Review the [Compatibility guide](docs/readme/compatibility.md#runtime-and-installation) for the current runtime and installation requirements.
|
|
68
75
|
|
|
69
76
|
Install **`codex-limits`** globally from npm:
|
|
70
77
|
|
|
@@ -82,40 +89,89 @@ codex-limits
|
|
|
82
89
|
|
|
83
90
|
The list of available commands is shown when you run `codex-limits --help` or in the [Usage](#usage) section.
|
|
84
91
|
|
|
85
|
-
|
|
92
|
+
Optional agent integrations are installed separately. Use the dedicated setup guide for [OpenCode](docs/readme/agents/opencode.md#installation), [pi](docs/readme/agents/pi.md#installation), or [GitHub Copilot CLI](docs/readme/agents/copilot.md#installation).
|
|
93
|
+
|
|
94
|
+
## Requirements
|
|
95
|
+
|
|
96
|
+
The canonical [Compatibility guide](docs/readme/compatibility.md) documents supported runtimes, installation methods, operating systems, Codex data, network access, terminals, automation, and agent hosts. Check it before installation or when choosing an optional integration.
|
|
97
|
+
|
|
98
|
+
## Usage
|
|
99
|
+
|
|
100
|
+
| Command | Description |
|
|
101
|
+
| ------------------------------------------ | ------------------------------------------------------ |
|
|
102
|
+
| `codex-limits` | Opens the interactive terminal dashboard. |
|
|
103
|
+
| `codex-limits status` | Prints a plain usage summary. |
|
|
104
|
+
| `codex-limits coupons` | Prints reset-credit coupon information. |
|
|
105
|
+
| `codex-limits coupons --json` | Prints machine-readable reset-credit coupon data only. |
|
|
106
|
+
| `codex-limits reset <coupon-index>` | Reviews and uses the numbered available reset coupon. |
|
|
107
|
+
| `codex-limits reset --soonest` | Reviews and uses the coupon that expires first. |
|
|
108
|
+
| `codex-limits --json` | Prints machine-readable usage and coupon data. |
|
|
109
|
+
| `codex-limits doctor` | Prints safe environment and connectivity diagnostics. |
|
|
110
|
+
| `codex-limits doctor --json` | Prints machine-readable diagnostics only. |
|
|
111
|
+
| `codex-limits agents` | Lists the available agent-management subcommands. |
|
|
112
|
+
| `codex-limits agents install <agent...>` | Installs one or more named agent integrations. |
|
|
113
|
+
| `codex-limits agents install --all` | Installs every supported agent integration. |
|
|
114
|
+
| `codex-limits agents uninstall <agent...>` | Safely removes one or more named agent integrations. |
|
|
115
|
+
| `codex-limits agents uninstall --all` | Safely removes every recognized agent integration. |
|
|
116
|
+
| `codex-limits init` | Runs the compatible interactive installation flow. |
|
|
117
|
+
|
|
118
|
+
### Resetting usage
|
|
119
|
+
|
|
120
|
+
Use one available reset coupon by the number shown in `codex-limits coupons`, or let the command select the available coupon that expires first:
|
|
86
121
|
|
|
87
122
|
```bash
|
|
88
|
-
codex-limits
|
|
123
|
+
codex-limits reset <coupon-index>
|
|
124
|
+
codex-limits reset --soonest
|
|
89
125
|
```
|
|
90
126
|
|
|
91
|
-
|
|
127
|
+
Reset is an irreversible remote mutation and works only in an interactive terminal. The command refreshes the coupon list, prints a recap, and sends the consume request only after an explicit `y` or `yes`; every other answer cancels. If a coupon cannot be selected or the result cannot be confirmed, it does not claim success.
|
|
128
|
+
|
|
129
|
+
See [Command safety boundaries](SECURITY.md#command-safety-boundaries) for the canonical selection, confirmation, idempotency, and failure-safety behavior.
|
|
130
|
+
|
|
131
|
+
### Diagnostics
|
|
132
|
+
|
|
133
|
+
Run the read-only doctor command when Codex data, live usage, or an agent integration is unavailable:
|
|
92
134
|
|
|
93
135
|
```bash
|
|
94
|
-
codex-limits
|
|
95
|
-
codex-limits agents install pi
|
|
96
|
-
codex-limits agents install copilot
|
|
136
|
+
codex-limits doctor
|
|
97
137
|
```
|
|
98
138
|
|
|
99
|
-
|
|
139
|
+
```text
|
|
140
|
+
Codex Limits diagnostics
|
|
100
141
|
|
|
101
|
-
|
|
142
|
+
Package version: 1.2.0
|
|
143
|
+
Node.js version: 22.0.0
|
|
144
|
+
Operating system: Windows
|
|
145
|
+
Codex home detected: Yes
|
|
146
|
+
Authentication found: Yes
|
|
147
|
+
Local usage found: Yes
|
|
148
|
+
Live endpoint: Reachable
|
|
149
|
+
OpenCode integration: Installed
|
|
150
|
+
pi integration: Installed
|
|
151
|
+
GitHub Copilot CLI integration: Installed
|
|
102
152
|
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
| Node.js | Node.js 20 or newer is required to run the published CLI. Bun is only required for local development. |
|
|
106
|
-
| Codex | For normal use, Codex should already be installed and authenticated so `codex-limits` can discover its local data and credentials. Advanced setups can provide supported environment overrides instead. |
|
|
107
|
-
| Operating systems | Windows, macOS, and Linux are supported through their standard Codex data locations. Use `CODEX_LIMITS_HOME` or `CODEX_HOME` if your data is stored elsewhere. |
|
|
108
|
-
| Internet connection | Local usage fallback can work offline. An internet connection is required for current live usage and reset-credit coupon information; unavailable network data is reported safely without breaking the dashboard. |
|
|
153
|
+
No sensitive values were displayed.
|
|
154
|
+
```
|
|
109
155
|
|
|
110
|
-
The
|
|
156
|
+
The doctor reports bounded availability statuses for Codex and every registered agent integration. Use `codex-limits doctor --json` for the stable machine-readable form documented in [JSON output](docs/readme/json-output.md#doctor-document), and see the [Security policy](SECURITY.md#local-data-and-network-behavior) for its canonical data-exposure and network safeguards.
|
|
111
157
|
|
|
112
|
-
|
|
158
|
+
### Agent management
|
|
113
159
|
|
|
114
|
-
|
|
160
|
+
Use `codex-limits agents install` and `codex-limits agents uninstall` to manage optional integrations. Both are local-write operations scoped to recognized agent configuration; neither sends a prompt to an LLM or modifies Codex data.
|
|
115
161
|
|
|
116
|
-
|
|
162
|
+
| Command | What it does |
|
|
163
|
+
| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
|
|
164
|
+
| `codex-limits agents` | Prints help for the agent-management command group. |
|
|
165
|
+
| `codex-limits agents install` | Prompts for every supported integration in an interactive terminal. If none is selected, nothing is installed. |
|
|
166
|
+
| `codex-limits agents install <agent...>` | Installs one or more named supported integrations without prompting. |
|
|
167
|
+
| `codex-limits agents install --all` | Installs every supported integration without prompting. |
|
|
168
|
+
| `codex-limits agents uninstall` | Prompts only for integrations currently recognized as installed. An empty answer keeps each integration installed. |
|
|
169
|
+
| `codex-limits agents uninstall <agent...>` | Removes recognized Codex Limits configuration for one or more named integrations without prompting. |
|
|
170
|
+
| `codex-limits agents uninstall --all` | Attempts safe removal for every registered integration without prompting. |
|
|
171
|
+
| `codex-limits agents <action> --help` or `-h` | Prints generated help for the selected lifecycle action without changing configuration. |
|
|
172
|
+
| `codex-limits init --<agent-name>` or `codex-limits init --all` | Preserves the existing initialization syntax as a compatibility installation command. |
|
|
117
173
|
|
|
118
|
-
|
|
174
|
+
For either lifecycle action, `--all` cannot be combined with agent names. Duplicate and unknown names, unknown options, and extra positional arguments are rejected before any configuration is changed. In a non-interactive terminal, provide `--all` or at least one agent name. Uninstall reports `not installed` without failing when a selected integration is absent, continues to report each selected agent when another fails, and refuses malformed, symbolic-link, or unrecognized targets rather than rewriting or deleting them.
|
|
119
175
|
|
|
120
176
|
## Agent integrations
|
|
121
177
|
|
|
@@ -125,13 +181,13 @@ For installation details, adapter behavior, architecture, and contribution guida
|
|
|
125
181
|
|
|
126
182
|
### Supported agents
|
|
127
183
|
|
|
128
|
-
| Agent | Status | Agent command | Guide
|
|
129
|
-
| ------------------ | --------- | --------------- |
|
|
130
|
-
| OpenCode | Supported | `/codex-limits` | [
|
|
131
|
-
| pi | Supported | `/codex-limits` | [
|
|
132
|
-
| GitHub Copilot CLI | Supported | `/codex-limits` | [
|
|
184
|
+
| Agent | Status | Agent command | Guide | Description |
|
|
185
|
+
| ------------------ | --------- | --------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
|
|
186
|
+
| OpenCode | Supported | `/codex-limits` | [Setup, usage, and removal](docs/readme/agents/opencode.md) | Opens a fast, read-only dashboard without sending the request or limit data to the LLM. |
|
|
187
|
+
| pi | Supported | `/codex-limits` | [Setup, usage, and removal](docs/readme/agents/pi.md) | Opens a themed, read-only overlay without sending the request or limit data to the LLM. |
|
|
188
|
+
| GitHub Copilot CLI | Supported | `/codex-limits` | [Setup, usage, and removal](docs/readme/agents/copilot.md) | Logs a compact, read-only timeline summary without sending the request or limit data to the LLM. |
|
|
133
189
|
|
|
134
|
-
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.
|
|
190
|
+
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. Remove them with `codex-limits agents uninstall`; restart the agent after either lifecycle change. See [Adding new agents](#adding-new-agents) if you want to add support for another agent.
|
|
135
191
|
|
|
136
192
|
### Selected agent integration screenshots
|
|
137
193
|
|
|
@@ -161,7 +217,7 @@ The GitHub Copilot CLI integration adds a `/codex-limits` command that displays
|
|
|
161
217
|
|
|
162
218
|
### Adding new agents
|
|
163
219
|
|
|
164
|
-
New agents use the same four-file adapter layout under `src/agents/<agent-name>`: `format.ts`, `install.ts`, `integration.ts`, and `plugin.ts`. The integration descriptor owns its metadata, environment help,
|
|
220
|
+
New agents use the same four-file adapter layout under `src/agents/<agent-name>`: `format.ts`, `install.ts`, `integration.ts`, and `plugin.ts`. The integration descriptor owns its metadata, environment help, install, uninstall, and read-only inspection behavior; registering that descriptor in `src/agents/index.ts` automatically connects shared lifecycle commands, compatibility help, and doctor diagnostics. Every registered agent must also use a matching `src/package/<agent-name>.ts` host wrapper and expose `@simonesiega/codex-limits/<agent-name>` through the shared package-entry build. Each integration should show Codex limit information quickly and safely without exposing tokens, account IDs, cookies, auth headers, or raw local files.
|
|
165
221
|
|
|
166
222
|
See the [Contributing](./CONTRIBUTING.md) guide if you want to add support for another agent.
|
|
167
223
|
|
|
@@ -191,6 +247,7 @@ The npm module exports are reserved for supported agent hosts:
|
|
|
191
247
|
| ------------------------------------ | ----------------------------------------------------------------------------------------- |
|
|
192
248
|
| `@simonesiega/codex-limits` | OpenCode plugin entry point retained at the package root for plugin-loader compatibility. |
|
|
193
249
|
| `@simonesiega/codex-limits/opencode` | Explicit alias for the same OpenCode plugin module. |
|
|
250
|
+
| `@simonesiega/codex-limits/tui` | Loader-reserved alias for OpenCode TUI plugin discovery. |
|
|
194
251
|
| `@simonesiega/codex-limits/pi` | Host-only entry point for the bundled pi extension. |
|
|
195
252
|
| `@simonesiega/codex-limits/copilot` | Host-only entry point for the bundled GitHub Copilot CLI extension. |
|
|
196
253
|
|
|
@@ -217,108 +274,24 @@ Environment variables are only used as a fallback when automatic discovery is no
|
|
|
217
274
|
|
|
218
275
|
Local Codex data is always inspected read-only with bounded file, directory, JSONL, and response limits. Credentials, raw files, and private paths are excluded from public output. Live requests require HTTPS, except for loopback HTTP during local testing. Only `codex-limits reset` mutates the remote account, and it requires an interactive recap followed by an explicit `y` or `yes` confirmation. See [`SECURITY.md`](./SECURITY.md#local-data-and-network-behavior) for the complete data-access and network-safety model.
|
|
219
276
|
|
|
220
|
-
## Usage
|
|
221
|
-
|
|
222
|
-
| Command | Description |
|
|
223
|
-
| ---------------------------------------- | ------------------------------------------------------ |
|
|
224
|
-
| `codex-limits` | Opens the interactive terminal dashboard. |
|
|
225
|
-
| `codex-limits status` | Prints a plain usage summary. |
|
|
226
|
-
| `codex-limits coupons` | Prints reset-credit coupon information. |
|
|
227
|
-
| `codex-limits coupons --json` | Prints machine-readable reset-credit coupon data only. |
|
|
228
|
-
| `codex-limits reset <coupon-index>` | Reviews and uses the numbered available reset coupon. |
|
|
229
|
-
| `codex-limits reset --soonest` | Reviews and uses the coupon that expires first. |
|
|
230
|
-
| `codex-limits --json` | Prints machine-readable usage and coupon data. |
|
|
231
|
-
| `codex-limits doctor` | Prints safe environment and connectivity diagnostics. |
|
|
232
|
-
| `codex-limits doctor --json` | Prints machine-readable diagnostics only. |
|
|
233
|
-
| `codex-limits agents` | Lists the available agent-management subcommands. |
|
|
234
|
-
| `codex-limits agents install <agent...>` | Installs one or more named agent integrations. |
|
|
235
|
-
| `codex-limits agents install --all` | Installs every supported agent integration. |
|
|
236
|
-
| `codex-limits init` | Runs the compatible interactive installation flow. |
|
|
237
|
-
|
|
238
|
-
### Resetting usage
|
|
239
|
-
|
|
240
|
-
Use one available reset coupon by the number shown in `codex-limits coupons`, or let the command select the available coupon that expires first:
|
|
241
|
-
|
|
242
|
-
```bash
|
|
243
|
-
codex-limits reset <coupon-index>
|
|
244
|
-
codex-limits reset --soonest
|
|
245
|
-
```
|
|
246
|
-
|
|
247
|
-
Reset is an irreversible remote mutation and works only in an interactive terminal. The command refreshes the coupon list, rejects missing or unavailable indexes, prints a recap with the selected coupon and expiration, and asks `Type y to confirm [y/N]`. Only `y` or `yes` sends the consume request; every other answer cancels without using a coupon. The request carries the coupon's internal service ID and a fresh idempotency key so an internal retry cannot consume a second coupon.
|
|
248
|
-
|
|
249
|
-
If no coupon is available, the command reports that nothing was used. If the selected index is absent, coupon details cannot be verified, or the final service result is ambiguous, it exits without claiming success.
|
|
250
|
-
|
|
251
|
-
### Diagnostics
|
|
252
|
-
|
|
253
|
-
Run the read-only doctor command when Codex data, live usage, or an agent integration is unavailable:
|
|
254
|
-
|
|
255
|
-
```bash
|
|
256
|
-
codex-limits doctor
|
|
257
|
-
```
|
|
258
|
-
|
|
259
|
-
```text
|
|
260
|
-
Codex Limits diagnostics
|
|
261
|
-
|
|
262
|
-
Package version: 1.1.0
|
|
263
|
-
Node.js version: 22.0.0
|
|
264
|
-
Operating system: Windows
|
|
265
|
-
Codex home detected: Yes
|
|
266
|
-
Authentication found: Yes
|
|
267
|
-
Local usage found: Yes
|
|
268
|
-
Live endpoint: Reachable
|
|
269
|
-
OpenCode integration: Installed
|
|
270
|
-
pi integration: Installed
|
|
271
|
-
GitHub Copilot CLI integration: Installed
|
|
272
|
-
|
|
273
|
-
No sensitive values were displayed.
|
|
274
|
-
```
|
|
275
|
-
|
|
276
|
-
The doctor checks only whether recognized resources are available, including the OpenCode, pi, and GitHub Copilot CLI integrations. It never prints credential values, private paths, endpoint URLs, configuration contents, or raw Codex data. The live check makes the same bounded authenticated read-only usage request as the dashboard; it is reported as `Not checked` when complete authentication is unavailable. Use `codex-limits doctor --json` for the stable machine-readable form documented in [JSON output](docs/readme/json-output.md#doctor-document).
|
|
277
|
-
|
|
278
|
-
### Agent management
|
|
279
|
-
|
|
280
|
-
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.
|
|
281
|
-
|
|
282
|
-
| Command | What it does |
|
|
283
|
-
| --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
284
|
-
| `codex-limits agents` | Prints help for the agent-management command group. |
|
|
285
|
-
| `codex-limits agents install` | Prompts for every supported integration when stdin and stdout are interactive terminals. If no integration is selected, nothing is installed. |
|
|
286
|
-
| `codex-limits agents install <agent...>` | Installs one or more named supported integrations without prompting. |
|
|
287
|
-
| `codex-limits agents install --all` | Installs every supported integration without prompting. |
|
|
288
|
-
| `codex-limits agents install --help` or `-h` | Prints generated installation help without changing any configuration. |
|
|
289
|
-
| `codex-limits init --<agent-name>` or `codex-limits init --all` | Preserves the existing initialization syntax as a compatibility command. |
|
|
290
|
-
|
|
291
|
-
`--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.
|
|
292
|
-
|
|
293
277
|
## Troubleshooting
|
|
294
278
|
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
Make sure Codex has been run and authenticated at least once. If its data is stored outside the standard location, set `CODEX_LIMITS_HOME` or `CODEX_HOME` to the Codex data directory, then run `codex-limits status` again.
|
|
298
|
-
|
|
299
|
-
### Usage information unavailable
|
|
300
|
-
|
|
301
|
-
Run `codex-limits doctor` to check Codex home discovery, authentication presence, local usage, and live endpoint reachability without exposing sensitive values. Run `codex-limits status` to view the safe warning summary. Confirm that Codex authentication is current and that the machine can reach the ChatGPT Codex service. Local session data may still provide a fallback when live usage is unavailable; coupon information requires an internet connection.
|
|
302
|
-
|
|
303
|
-
### Permission errors
|
|
304
|
-
|
|
305
|
-
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`.
|
|
306
|
-
|
|
307
|
-
### Agent command not appearing after installation
|
|
279
|
+
For Codex discovery, authentication, live usage, coupons, permissions, terminal rendering, JSON automation, reset redemption, and agent integration problems, use the complete [Troubleshooting guide](docs/readme/troubleshooting.md).
|
|
308
280
|
|
|
309
|
-
|
|
281
|
+
Start with the read-only `codex-limits doctor` command, then follow the guide for the affected surface.
|
|
310
282
|
|
|
311
283
|
## Documentation
|
|
312
284
|
|
|
313
285
|
The [documentation hub](docs/README.md) routes CLI users, automation authors, agent users, and contributors to the appropriate canonical guide.
|
|
314
286
|
|
|
315
|
-
| Area | Canonical guide
|
|
316
|
-
| ---------------------- |
|
|
317
|
-
| CLI setup and commands | [Quick start](#quick-start) · [Usage](#usage)
|
|
318
|
-
|
|
|
319
|
-
|
|
|
320
|
-
|
|
|
321
|
-
|
|
|
287
|
+
| Area | Canonical guide |
|
|
288
|
+
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
289
|
+
| CLI setup and commands | [Quick start](#quick-start) · [Usage](#usage) |
|
|
290
|
+
| Troubleshooting | [Troubleshooting guide](docs/readme/troubleshooting.md) |
|
|
291
|
+
| Automation | [JSON output](docs/readme/json-output.md) · [Schemas](docs/schema/) · [Examples](docs/examples/) |
|
|
292
|
+
| Agent integrations | [Overview](docs/readme/agent-integrations.md) · [OpenCode](docs/readme/agents/opencode.md) · [pi](docs/readme/agents/pi.md) · [GitHub Copilot CLI](docs/readme/agents/copilot.md) |
|
|
293
|
+
| Runtime support | [Compatibility](docs/readme/compatibility.md) |
|
|
294
|
+
| Development and safety | [Contributing](CONTRIBUTING.md) · [Code of Conduct](CODE_OF_CONDUCT.md) · [Issue forms](https://github.com/simonesiega/codex-limits/issues/new/choose) · [Pull Request template](.github/pull_request_template.md) · [Security](SECURITY.md) · [Changelog](CHANGELOG.md) |
|
|
322
295
|
|
|
323
296
|
## Local development
|
|
324
297
|
|
|
@@ -333,27 +306,30 @@ bun run dev
|
|
|
333
306
|
|
|
334
307
|
Useful development commands:
|
|
335
308
|
|
|
336
|
-
| Command
|
|
337
|
-
|
|
|
338
|
-
| `bun run dev`
|
|
339
|
-
| `bun run check`
|
|
340
|
-
| `bun run docs:link`
|
|
341
|
-
| `bun run docs:schema`
|
|
342
|
-
| `bun run docs:check`
|
|
343
|
-
| `bun
|
|
344
|
-
| `bun run
|
|
345
|
-
| `bun
|
|
346
|
-
| `bun run
|
|
309
|
+
| Command | Description |
|
|
310
|
+
| ----------------------- | ------------------------------------------------------------------------------- |
|
|
311
|
+
| `bun run dev` | Runs the CLI in development mode. |
|
|
312
|
+
| `bun run check` | Runs formatting, documentation, types, tests, builds, and package smoke checks. |
|
|
313
|
+
| `bun run docs:link` | Checks local documentation links and heading anchors. |
|
|
314
|
+
| `bun run docs:schema` | Validates all JSON Schemas and their external and inline examples. |
|
|
315
|
+
| `bun run docs:check` | Runs both documentation checks. |
|
|
316
|
+
| `bun run audit` | Checks the locked dependency graph for known vulnerabilities. |
|
|
317
|
+
| `bun run agents:compat` | Runs one configured real-agent compatibility probe (used by CI). |
|
|
318
|
+
| `bun test` | Runs the test suite. |
|
|
319
|
+
| `bun run build` | Builds the package. |
|
|
320
|
+
| `bun run format` | Formats the repository with Prettier. |
|
|
321
|
+
| `bun run format:check` | Checks formatting without changing files. |
|
|
347
322
|
|
|
348
323
|
## Security
|
|
349
324
|
|
|
350
|
-
| Operation | Reads | Writes
|
|
351
|
-
| ------------------------- | ----------------------------------------------- |
|
|
352
|
-
| `codex-limits` | Recognized Codex state and bounded session data | Nothing
|
|
353
|
-
| `status` / `coupons` | Shared read-only core | Nothing
|
|
354
|
-
| `reset` | Current reset coupon list and Codex credentials | One selected remote coupon
|
|
355
|
-
| `doctor` | Bounded Codex and agent configuration checks | Nothing
|
|
356
|
-
| `agents install` / `init` | Selected agent configuration |
|
|
325
|
+
| Operation | Reads | Writes | Network |
|
|
326
|
+
| ------------------------- | ----------------------------------------------- | ------------------------------------ | -------------------------------------- |
|
|
327
|
+
| `codex-limits` | Recognized Codex state and bounded session data | Nothing | Live usage and coupon endpoints |
|
|
328
|
+
| `status` / `coupons` | Shared read-only core | Nothing | When live data is requested |
|
|
329
|
+
| `reset` | Current reset coupon list and Codex credentials | One selected remote coupon | Confirmed reset-credit consume request |
|
|
330
|
+
| `doctor` | Bounded Codex and agent configuration checks | Nothing | Live usage endpoint when authenticated |
|
|
331
|
+
| `agents install` / `init` | Selected agent configuration | Updates selected agent configuration | Does not send an LLM prompt |
|
|
332
|
+
| `agents uninstall` | Selected agent configuration | Removes recognized integration state | Does not send an LLM prompt |
|
|
357
333
|
|
|
358
334
|
For vulnerability reports and local data safety details, see [`SECURITY.md`](./SECURITY.md).
|
|
359
335
|
|
package/SECURITY.md
CHANGED
|
@@ -13,14 +13,18 @@
|
|
|
13
13
|
<img src="https://img.shields.io/github/license/simonesiega/codex-limits" alt="License" />
|
|
14
14
|
</p>
|
|
15
15
|
|
|
16
|
-
[← Project README](README.md) · [Documentation hub](docs/README.md)
|
|
17
|
-
|
|
18
16
|
## Contents
|
|
19
17
|
|
|
20
18
|
- [Supported versions](#supported-versions)
|
|
21
19
|
- [Reporting a vulnerability](#reporting-a-vulnerability)
|
|
22
20
|
- [What to expect](#what-to-expect)
|
|
23
21
|
- [Local data and network behavior](#local-data-and-network-behavior)
|
|
22
|
+
- [Local data](#local-data)
|
|
23
|
+
- [Network requests](#network-requests)
|
|
24
|
+
- [Reset redemption](#reset-redemption)
|
|
25
|
+
- [Agent integrations and installers](#agent-integrations-and-installers)
|
|
26
|
+
- [Diagnostics](#diagnostics)
|
|
27
|
+
- [Command safety boundaries](#command-safety-boundaries)
|
|
24
28
|
- [What to report](#what-to-report)
|
|
25
29
|
- [Safety expectations](#safety-expectations)
|
|
26
30
|
- [Dependency and release security](#dependency-and-release-security)
|
|
@@ -72,25 +76,37 @@ Please do not publicly disclose the vulnerability until a fix is available or di
|
|
|
72
76
|
|
|
73
77
|
## Local data and network behavior
|
|
74
78
|
|
|
75
|
-
|
|
79
|
+
This section is the canonical reference for deep data-access, network, redaction, installer, diagnostic, and mutation safety behavior. Other guides summarize these guarantees and link here.
|
|
80
|
+
|
|
81
|
+
### Local data
|
|
82
|
+
|
|
83
|
+
`codex-limits` keeps raw local Codex files out of public output and uses discovered credentials only for authenticated requests to recognized ChatGPT Codex endpoints. It sends a reset-credit consume request only after the user invokes and confirms `codex-limits reset`.
|
|
76
84
|
|
|
77
85
|
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, and resolved state files must remain inside the detected Codex home. Filesystem diagnostics are path-free, and fallback reset-duration text is accepted only in a compact normalized form. Raw local files, private paths, and credentials are never returned by the public CLI or JSON contracts.
|
|
78
86
|
|
|
79
|
-
|
|
87
|
+
### Network requests
|
|
88
|
+
|
|
89
|
+
For live usage and coupon information, the project contacts the default ChatGPT Codex endpoints. The only environment endpoint override is `CODEX_LIMITS_USAGE_ENDPOINT`, mainly for testing or advanced setups. Overrides must use HTTPS, except for loopback HTTP during local testing; embedded credentials and other protocols are rejected. Authenticated requests reject redirects, use a 10-second timeout and 1 MB response limit by default, and never include credential headers in diagnostics.
|
|
90
|
+
|
|
91
|
+
### Reset redemption
|
|
80
92
|
|
|
81
93
|
The reset command first refreshes the coupon list and matches either the requested display index or the available coupon with the earliest expiration. Coupon timestamps must be bounded RFC 3339 values before they can reach public output or participate in selection. Redemption requires an exact internal service ID and the recognized `codex_rate_limits` reset type; `--soonest` refuses incomplete or inconsistent availability details rather than selecting a different coupon. It requires an interactive terminal, a displayed recap, and an explicit `y` or `yes` answer. The consume request includes the selected coupon's internal service ID and a fresh UUID idempotency key; transport fallback reuses the same request body. Coupon IDs and reset types remain internal and are not added to text or JSON coupon output. Known no-op service outcomes are reported without claiming that a coupon was used, and malformed or ambiguous responses are reported as unconfirmed.
|
|
82
94
|
|
|
83
|
-
Agent integrations
|
|
95
|
+
### Agent integrations and installers
|
|
96
|
+
|
|
97
|
+
Agent integrations follow the same safety model: they should display a read-only summary by reusing the shared core, not send the request or limit data to the LLM, and not expose sensitive values inside the agent UI. Before combined limits data reaches TUI or agent renderers, the core removes usage endpoint metadata, opaque coupon identifiers, and coupon reset types needed only by the confirmed reset flow. The pi extension runs only its local command handler and does not inject a user or custom message into the model context. The GitHub Copilot CLI extension registers only a local session command, writes its safe result to the host timeline, and does not call the SDK's model-message methods.
|
|
98
|
+
|
|
99
|
+
Agent lifecycle operations use bounded reads, revalidate each mutation target against its bounded source snapshot immediately before changing it, use owner-only atomic replacements for configuration rewrites, refuse symbolic-link or malformed configuration targets, and redact unexpected output paths. Uninstallers fail closed instead of rewriting stale or malformed configuration or deleting changed or unrecognized targets. OpenCode install and uninstall operations limit configurations to 1 MB and change only recognized `@simonesiega/codex-limits` entries in plugin arrays. Pi operations limit settings to 1 MB; installation uses bounded package-filter matching and registers the already installed local package root without downloads or lifecycle scripts, while uninstallation removes only exact recognized local-root or `npm:@simonesiega/codex-limits` package registrations, including registrations added through pi's native package manager. Copilot operations limit extension files to 5 MB; installation copies the bounded bundle already present in the package and refuses unrecognized or competing entry points, while uninstallation refuses competing entry points, removes only an `extension.mjs` carrying the Codex Limits management marker, and preserves other sibling files.
|
|
84
100
|
|
|
85
|
-
|
|
101
|
+
### Diagnostics
|
|
86
102
|
|
|
87
103
|
The `codex-limits doctor` command exposes only package/runtime labels and bounded availability statuses. Its Codex, OpenCode, pi, and GitHub Copilot CLI checks never return credential values, private paths, endpoint URLs, configuration contents, or raw local files. The optional live reachability check uses the same authenticated, bounded, redirect-free usage transport as the dashboard.
|
|
88
104
|
|
|
89
105
|
### Command safety boundaries
|
|
90
106
|
|
|
91
|
-
Every CLI command declares one enforced safety category.
|
|
107
|
+
Every CLI command declares one enforced safety category. Inspection and reporting commands such as the `codex-limits` dashboard, `status`, `coupons`, and `doctor` are read-only and receive no write or account-mutation services. Agent installation and uninstallation are local-write operations scoped to selected, recognized agent configuration. Reset is a `remote-mutation` command with a dedicated consume capability; the router requires an interactive terminal, and the handler requires the recap plus an explicit positive answer before calling that capability.
|
|
92
108
|
|
|
93
|
-
The existing `codex-limits init` compatibility command and the preferred `codex-limits agents install` command share the same local-write implementation.
|
|
109
|
+
The existing `codex-limits init` compatibility command and the preferred `codex-limits agents install` command share the same local-write installation implementation. `codex-limits agents uninstall` provides named, all-agent, and installed-only interactive removal. A selected absent integration is a successful no-op; adapter failures are isolated per agent. None of these agent-management commands modifies Codex data or sends an LLM prompt.
|
|
94
110
|
|
|
95
111
|
## What to report
|
|
96
112
|
|
|
@@ -127,7 +143,7 @@ The project should:
|
|
|
127
143
|
|
|
128
144
|
- Keep `bun.lock` committed and use frozen, script-disabled dependency installation in CI and publishing workflows.
|
|
129
145
|
- Keep third-party GitHub Actions pinned to immutable revisions and review automated updates before merging.
|
|
130
|
-
- Run `bun run check` before publishing;
|
|
146
|
+
- Run `bun run audit` and `bun run check` before publishing. CI and publishing enforce the dependency audit; the project check rebuilds every bundle, validates generated declarations and notices, packs the npm artifact, and smoke-tests supported runtime surfaces.
|
|
131
147
|
- Publish only from a validated release tag whose version matches `package.json` and `src/package/version.ts`.
|
|
132
148
|
- Use npm Trusted Publishing with provenance rather than a long-lived npm token.
|
|
133
149
|
- Keep agent host SDKs external where the host owns them, and keep bundled third-party license notices synchronized with production artifacts.
|
|
@@ -138,5 +154,6 @@ The project should:
|
|
|
138
154
|
- [Documentation hub](docs/README.md) — Task-oriented index for CLI, automation, agent, development, and security guides.
|
|
139
155
|
- [Compatibility](docs/readme/compatibility.md) — Supported runtimes, operating systems, Codex data, networks, terminals, and agent hosts.
|
|
140
156
|
- [JSON output](docs/readme/json-output.md) — Public machine-readable fields and deliberately omitted sensitive data.
|
|
141
|
-
- [
|
|
157
|
+
- [Troubleshooting](docs/readme/troubleshooting.md) — Safe diagnosis for data, network, terminal, reset, and integration problems.
|
|
158
|
+
- [Agent integrations](docs/readme/agent-integrations.md) — Supported-agent index, shared lifecycle modes, and adapter architecture.
|
|
142
159
|
- [Contributing](CONTRIBUTING.md) — Development workflow, safety rules, and review expectations.
|