@simonesiega/codex-limits 0.1.4 → 0.1.6

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.
Files changed (12) hide show
  1. package/.env.example +3 -0
  2. package/CHANGELOG.md +49 -0
  3. package/README.md +130 -50
  4. package/SECURITY.md +13 -3
  5. package/dist/THIRD_PARTY_NOTICES.txt +738 -0
  6. package/dist/cli.js +171 -156
  7. package/dist/index.js +5 -3
  8. package/dist/pi.js +5 -0
  9. package/docs/photos/agents/pi/pi_result.png +0 -0
  10. package/docs/photos/logo/title-animation.svg +34 -0
  11. package/package.json +40 -11
  12. package/scripts/postinstall.cjs +1 -1
package/.env.example CHANGED
@@ -16,3 +16,6 @@ CODEX_LIMITS_USAGE_ENDPOINT=
16
16
 
17
17
  # Optional: suppress global-install guidance from the non-interactive postinstall script.
18
18
  CODEX_LIMITS_SKIP_INIT=
19
+
20
+ # Optional: override pi's global agent configuration directory for integration setup.
21
+ PI_CODING_AGENT_DIR=
package/CHANGELOG.md CHANGED
@@ -16,6 +16,55 @@ All notable changes to codex-limits are documented in this file.
16
16
 
17
17
  ### Security
18
18
 
19
+ ## [0.1.6] - 2026-07-22
20
+
21
+ ### Breaking Changes
22
+
23
+ ### Added
24
+
25
+ - Added `codex-limits doctor` and `codex-limits doctor --json` for safe environment, connectivity, local usage, authentication, OpenCode, and pi integration diagnostics.
26
+ - Added the pi agent integration with `codex-limits agents install pi` and a read-only `/codex-limits` overlay that does not send limit data to the LLM.
27
+
28
+ ### Changed
29
+
30
+ ### Fixed
31
+
32
+ ### Removed
33
+
34
+ ### Security
35
+
36
+ ## [0.1.5] - 2026-07-22
37
+
38
+ ### Breaking Changes
39
+
40
+ ### Added
41
+
42
+ - Added bundled third-party license notices to published package artifacts.
43
+ - Added the `codex-limits agents` command group with named, interactive, and all-agent integration installation while keeping the existing `init` syntax supported.
44
+
45
+ ### Changed
46
+
47
+ - Changed CI to run source checks once and validate packed artifacts across Node.js 20, 22, and 24 on Linux and Windows.
48
+ - Changed CLI parsing and help to use one command definition source, with generated nested help and order-independent supported options.
49
+
50
+ ### Fixed
51
+
52
+ - Fixed authenticated request cancellation when a caller abort coincided with request startup.
53
+ - Fixed CLI help to describe credential overrides for both live usage and reset-credit requests.
54
+ - Fixed very small text dashboards to stay within the available terminal rows when coupon entries are truncated.
55
+ - Fixed Windows checkouts to preserve LF line endings so local formatting checks remain stable.
56
+ - 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.
57
+ - Fixed clean production builds and kept terminal rendering compatible with Node.js 20.
58
+
59
+ ### Removed
60
+
61
+ ### Security
62
+
63
+ - Refused symbolic-link files and path-replacement races when reading bounded local files, including agent configurations.
64
+ - Disabled dependency lifecycle scripts during CI installs, pinned workflow actions to immutable commits, and explicitly requested npm provenance for published packages.
65
+ - Shortened agent configuration paths under the user home to `~/...` and redacted paths outside it before printing installation results.
66
+ - Sanitized and bounded command and agent errors, and rejected control characters in command metadata before terminal output.
67
+
19
68
  ## [0.1.4] - 2026-07-13
20
69
 
21
70
  ### Added
package/README.md CHANGED
@@ -1,7 +1,5 @@
1
1
  <h1 align="center">
2
- <img src="docs/photos/logo/logo.png" alt="codex-limits logo" width="180" />
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">
@@ -18,8 +16,14 @@
18
16
 
19
17
  <p align="center">
20
18
  <img src="https://img.shields.io/npm/v/@simonesiega/codex-limits?label=npm" alt="npm version" />
21
- <img src="https://img.shields.io/badge/TypeScript-5-blue?logo=typescript" alt="TypeScript" />
22
- <img src="https://img.shields.io/badge/Bun-toolchain-black?logo=bun" alt="Bun toolchain" />
19
+ <img src="https://img.shields.io/badge/test_coverage-96.3%25_lines-brightgreen" alt="Test coverage: 96.3% lines" />
20
+ </p>
21
+
22
+ <p align="center">
23
+ <a href="#local-development">
24
+ <img src="https://img.shields.io/badge/TypeScript-5-blue?logo=typescript" alt="TypeScript" />
25
+ <img src="https://img.shields.io/badge/Bun-toolchain-black?logo=bun" alt="Bun toolchain" />
26
+ </a>
23
27
  </p>
24
28
 
25
29
  ## Preview 🚀
@@ -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 current 5-hour and weekly usage windows 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.
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.6
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,21 @@ 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 integrations with their named flag:
80
+ Install an optional agent integration by name:
70
81
 
71
82
  ```bash
72
- codex-limits init --<agent-name>
83
+ codex-limits agents install <agent-name>
73
84
  ```
74
85
 
75
- For example, install the OpenCode integration:
86
+ For example, install the OpenCode or pi integration:
76
87
 
77
88
  ```bash
78
- codex-limits init --opencode
89
+ codex-limits agents install opencode
90
+ codex-limits agents install pi
79
91
  ```
80
92
 
93
+ The existing `codex-limits init --<agent-name>` syntax remains supported as a compatibility command.
94
+
81
95
  ## Requirements
82
96
 
83
97
  | Requirement | Details |
@@ -87,37 +101,52 @@ codex-limits init --opencode
87
101
  | 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. |
88
102
  | 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. |
89
103
 
104
+ The standalone CLI supports Node.js 20 and newer. The optional pi integration runs inside the pi host; pi 0.81.x requires Node.js 22.19 or newer.
105
+
90
106
  ## Overview
91
107
 
92
108
  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
109
 
94
- **`codex-limits`** gives you that information in one clean terminal view. It shows your current 5-hour and weekly usage windows, remaining percentages, progress bars, reset times, and reset-credit coupons when available, so you can quickly check your status and continue coding without leaving the terminal.
110
+ **`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
111
 
96
- It also includes plain-text commands for quick checks, JSON output for scripts and automation, optional agent integrations through `codex-limits init`, and safe output that never prints tokens, account IDs, auth headers, cookies, or raw local files.
112
+ It also includes plain-text commands for quick checks, 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.
97
113
 
98
114
  ## Agent integrations
99
115
 
116
+ 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.
117
+
118
+ For installation details, adapter behavior, architecture, and contribution guidance, see the detailed [Agent integrations guide](docs/readme/agent-integrations.md).
119
+
100
120
  ### Supported agents
101
121
 
102
- | Agent | Status | Agent command | Init command | Description |
103
- | -------- | --------- | --------------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------- |
104
- | OpenCode | Supported | `/codex-limits` | `codex-limits init --opencode` | Opens a fast, read-only Codex limits dashboard directly inside OpenCode without sending the request to the LLM. |
122
+ | Agent | Status | Agent command | Guide | Description |
123
+ | -------- | --------- | --------------- | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
124
+ | 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. |
125
+ | pi | Supported | `/codex-limits` | [Installation and usage](docs/readme/agents/pi.md) | Opens a themed, read-only Codex limits overlay directly inside pi without sending the request to the LLM. |
105
126
 
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.
127
+ 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
128
 
108
129
  ### Selected agent integration screenshots
109
130
 
110
131
  #### OpenCode
111
132
 
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 current 5-hour limit, weekly limit, and reset-credit coupons, then lets you close the view and return immediately to the conversation.
133
+ 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
134
 
114
135
  <p align="center">
115
136
  <img src="docs/photos/agents/opencode/opencode_result.png" alt="OpenCode codex-limits integration screenshot" width="740" />
116
137
  </p>
117
138
 
139
+ #### pi
140
+
141
+ The pi integration adds a `/codex-limits` command that opens a themed overlay inside the agent interface. It shows the same read-only usage windows and reset-credit summary without sending the request or limit data to the LLM.
142
+
143
+ <p align="center">
144
+ <img src="docs/photos/agents/pi/pi_result.png" alt="pi codex-limits integration screenshot" width="740" />
145
+ </p>
146
+
118
147
  ### Adding new agents
119
148
 
120
- New agents can be added by creating a dedicated adapter under `src/agents/<agent-name>` and registering it in `src/agents/index.ts`. Each integration should keep the same goal: show Codex limit information quickly, safely, and without exposing tokens, account IDs, cookies, auth headers, or raw local files.
149
+ 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, installer, and read-only diagnostic check; registering that descriptor in `src/agents/index.ts` automatically connects shared installation, compatibility help, and doctor diagnostics. Each integration should show Codex limit information quickly and safely without exposing tokens, account IDs, cookies, auth headers, or raw local files.
121
150
 
122
151
  See the [Contributing](./CONTRIBUTING.md) guide if you want to add support for another agent.
123
152
 
@@ -127,11 +156,11 @@ See the [Contributing](./CONTRIBUTING.md) guide if you want to add support for a
127
156
 
128
157
  | Area | Path | Purpose |
129
158
  | ------------------ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
130
- | CLI entry | `src/package/cli.ts` | Starts the `codex-limits` command and routes to the dashboard, plain-text commands, JSON output, and `init`. |
159
+ | CLI entry | `src/package/cli.ts` | Starts the `codex-limits` command and delegates to the shared command registry. |
131
160
  | 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` | Handles the dashboard, `status`, `coupons`, `--json`, and `init` commands. |
161
+ | CLI commands | `src/package/commands` | Defines command metadata, shared parsing and help, scoped runtime services, and focused command handlers. |
133
162
  | 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 that users install with `codex-limits init`. |
163
+ | Agent integrations | `src/agents` | Contains optional coding-agent adapters used by the `codex-limits agents` command group. |
135
164
  | Tests | `tests` | Contains the test suite used to validate core behavior, CLI output, safety rules, and integration logic. |
136
165
 
137
166
  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.
@@ -150,6 +179,7 @@ Environment variables are only used as a fallback when automatic discovery is no
150
179
  | `CODEX_LIMITS_ACCOUNT_ID` | Provides the account ID paired with `CODEX_LIMITS_ACCESS_TOKEN`. |
151
180
  | `CODEX_LIMITS_USAGE_ENDPOINT` | Overrides the live usage endpoint with HTTPS or loopback HTTP for advanced setups/tests. |
152
181
  | `CODEX_LIMITS_SKIP_INIT` | Suppresses optional global-install setup guidance from the non-interactive postinstall. |
182
+ | `PI_CODING_AGENT_DIR` | Overrides pi's global agent configuration directory for integration setup and checks. |
153
183
 
154
184
  ### Data access and safety
155
185
 
@@ -157,28 +187,60 @@ Local Codex data is inspected read-only with bounded file, directory, JSONL, and
157
187
 
158
188
  ## Usage
159
189
 
160
- | Command | Description |
161
- | ----------------------------- | -------------------------------------------------------------- |
162
- | `codex-limits` | Opens the interactive terminal dashboard. |
163
- | `codex-limits status` | Prints a plain usage summary. |
164
- | `codex-limits coupons` | Prints reset-credit coupon information. |
165
- | `codex-limits coupons --json` | Prints machine-readable reset-credit coupon data only. |
166
- | `codex-limits --json` | Prints machine-readable usage and coupon data. |
167
- | `codex-limits init` | Prompts for optional agent integrations in an interactive TTY. |
190
+ | Command | Description |
191
+ | ---------------------------------------- | ------------------------------------------------------ |
192
+ | `codex-limits` | Opens the interactive terminal dashboard. |
193
+ | `codex-limits status` | Prints a plain usage summary. |
194
+ | `codex-limits coupons` | Prints reset-credit coupon information. |
195
+ | `codex-limits coupons --json` | Prints machine-readable reset-credit coupon data only. |
196
+ | `codex-limits --json` | Prints machine-readable usage and coupon data. |
197
+ | `codex-limits doctor` | Prints safe environment and connectivity diagnostics. |
198
+ | `codex-limits doctor --json` | Prints machine-readable diagnostics only. |
199
+ | `codex-limits agents` | Lists the available agent-management subcommands. |
200
+ | `codex-limits agents install <agent...>` | Installs one or more named agent integrations. |
201
+ | `codex-limits agents install --all` | Installs every supported agent integration. |
202
+ | `codex-limits init` | Runs the compatible interactive installation flow. |
168
203
 
169
- ### `init` options
204
+ ### Diagnostics
170
205
 
171
- Use `codex-limits init` to install optional agent integrations. Installation only updates the selected agent configuration; it does not send a prompt to an LLM or modify Codex data.
206
+ Run the read-only doctor command when Codex data, live usage, or an agent integration is unavailable:
172
207
 
173
- | Command | What it does |
174
- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
175
- | `codex-limits init` | Prompts for every supported integration when stdin and stdout are interactive terminals. If no integration is selected, nothing is installed. |
176
- | `codex-limits init --help` or `codex-limits init -h` | Prints the `init` command help without changing any configuration. |
177
- | `codex-limits init --all` | Installs every supported integration without prompting. |
178
- | `codex-limits init --opencode` | Installs only the OpenCode integration, which adds `/codex-limits` to OpenCode. |
179
- | `codex-limits init --<agent-name>` | Installs only the named supported integration. Replace `<agent-name>` with an integration listed in [Supported agents](#supported-agents). |
208
+ ```bash
209
+ codex-limits doctor
210
+ ```
211
+
212
+ ```text
213
+ Codex Limits diagnostics
214
+
215
+ Package version: 0.1.6
216
+ Node.js version: 22.0.0
217
+ Operating system: Windows
218
+ Codex home detected: Yes
219
+ Authentication found: Yes
220
+ Local usage found: Yes
221
+ Live endpoint: Reachable
222
+ OpenCode integration: Installed
223
+ pi integration: Installed
224
+
225
+ No sensitive values were displayed.
226
+ ```
227
+
228
+ The doctor checks only whether recognized resources are available, including the OpenCode and pi 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).
180
229
 
181
- `--all` cannot be combined with a named integration flag. Duplicate, unknown, and positional arguments are rejected. In a non-interactive terminal, use `--all` or a named integration flag instead of running `codex-limits init` without options.
230
+ ### Agent management
231
+
232
+ 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.
233
+
234
+ | Command | What it does |
235
+ | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
236
+ | `codex-limits agents` | Prints help for the agent-management command group. |
237
+ | `codex-limits agents install` | Prompts for every supported integration when stdin and stdout are interactive terminals. If no integration is selected, nothing is installed. |
238
+ | `codex-limits agents install <agent...>` | Installs one or more named supported integrations without prompting. |
239
+ | `codex-limits agents install --all` | Installs every supported integration without prompting. |
240
+ | `codex-limits agents install --help` or `-h` | Prints generated installation help without changing any configuration. |
241
+ | `codex-limits init --<agent-name>` or `codex-limits init --all` | Preserves the existing initialization syntax as a compatibility command. |
242
+
243
+ `--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
244
 
183
245
  ## Troubleshooting
184
246
 
@@ -188,15 +250,23 @@ Make sure Codex has been run and authenticated at least once. If its data is sto
188
250
 
189
251
  ### Usage information unavailable
190
252
 
191
- 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.
253
+ 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.
192
254
 
193
255
  ### Permission errors
194
256
 
195
257
  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
258
 
197
- ### Agent command not appearing after initialization
259
+ ### Agent command not appearing after installation
260
+
261
+ Run the named installer again, for example `codex-limits agents install opencode` or `codex-limits agents install pi`, 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.
198
262
 
199
- Run the named initializer again, for example `codex-limits init --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.
263
+ ## Documentation
264
+
265
+ The README provides an overview of the main features, commands, and configuration options. For more detailed technical information, see the following guides:
266
+
267
+ - [JSON output](docs/readme/json-output.md) — Learn about the machine-readable output format, available fields, warnings, examples, and scripting behavior.
268
+ - [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.
269
+ - [Compatibility](docs/readme/compatibility.md) — View the supported operating systems, Node.js versions, terminals, Codex environments, and agent versions.
200
270
 
201
271
  ## Local development
202
272
 
@@ -211,17 +281,27 @@ bun run dev
211
281
 
212
282
  Useful development commands:
213
283
 
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 test` | Runs the test suite. |
219
- | `bun run build` | Builds the package. |
220
- | `bun run format` | Formats the repository with Prettier. |
221
- | `bun run format:check` | Checks formatting without changing files. |
284
+ | Command | Description |
285
+ | ---------------------- | ------------------------------------------------------------------------------- |
286
+ | `bun run dev` | Runs the CLI in development mode. |
287
+ | `bun run check` | Runs formatting, documentation, types, tests, builds, and package smoke checks. |
288
+ | `bun run docs:link` | Checks local documentation links and heading anchors. |
289
+ | `bun run docs:schema` | Validates the JSON Schema and its example output. |
290
+ | `bun run docs:check` | Runs both documentation checks. |
291
+ | `bun test` | Runs the test suite. |
292
+ | `bun run build` | Builds the package. |
293
+ | `bun run format` | Formats the repository with Prettier. |
294
+ | `bun run format:check` | Checks formatting without changing files. |
222
295
 
223
296
  ## Security
224
297
 
298
+ | Operation | Reads | Writes | Network |
299
+ | ------------------------- | ----------------------------------------------- | --------------------------------- | -------------------------------------- |
300
+ | `codex-limits` | Recognized Codex state and bounded session data | Nothing | Live usage and coupon endpoints |
301
+ | `status` / `coupons` | Shared read-only core | Nothing | When live data is requested |
302
+ | `doctor` | Bounded Codex and agent configuration checks | Nothing | Live usage endpoint when authenticated |
303
+ | `agents install` / `init` | Selected agent configuration | Adds the integration registration | Does not send an LLM prompt |
304
+
225
305
  For vulnerability reports and local data safety details, see [`SECURITY.md`](./SECURITY.md).
226
306
 
227
307
  ## License
package/SECURITY.md CHANGED
@@ -59,13 +59,23 @@ 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 data on your machine.
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
 
66
66
  For live usage and coupon information, the project contacts the default ChatGPT Codex endpoints. The only endpoint override is `CODEX_LIMITS_USAGE_ENDPOINT`, mainly for testing or advanced setups. Overrides must use HTTPS, except for loopback HTTP during local testing. Authenticated requests reject redirects, use bounded timeouts and responses, and never include credential headers in diagnostics.
67
67
 
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.
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. The pi extension runs only its local command handler and does not inject a user or custom message into the model context.
69
+
70
+ Agent installers use bounded JSON reads and owner-only atomic replacements. The pi installer registers the already installed local package root and does not download a package or execute dependency lifecycle scripts.
71
+
72
+ The `codex-limits doctor` command exposes only package/runtime labels and bounded availability statuses. Its Codex, OpenCode, and pi 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.
73
+
74
+ ### Command safety boundaries
75
+
76
+ Every CLI command declares one enforced safety category. Dashboard, status, coupon, doctor, 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.
77
+
78
+ 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.
69
79
 
70
80
  ## What to report
71
81
 
@@ -80,7 +90,7 @@ Relevant examples include:
80
90
  - agent integrations exposing private Codex data inside the agent UI;
81
91
  - unexpected writes to local Codex data;
82
92
  - unexpected network behavior related to usage or coupon discovery;
83
- - unsafe handling of `CODEX_LIMITS_HOME`, `CODEX_LIMITS_ACCESS_TOKEN`, `CODEX_LIMITS_ACCOUNT_ID`, or `CODEX_LIMITS_USAGE_ENDPOINT`.
93
+ - unsafe handling of `CODEX_LIMITS_HOME`, `CODEX_LIMITS_ACCESS_TOKEN`, `CODEX_LIMITS_ACCOUNT_ID`, `CODEX_LIMITS_USAGE_ENDPOINT`, or `PI_CODING_AGENT_DIR`.
84
94
 
85
95
  ## Safety expectations
86
96