@simonesiega/codex-limits 0.1.3 → 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.
Files changed (14) hide show
  1. package/.env.example +10 -13
  2. package/CHANGELOG.md +92 -13
  3. package/LICENSE +21 -21
  4. package/README.md +181 -56
  5. package/SECURITY.md +102 -0
  6. package/dist/THIRD_PARTY_NOTICES.txt +738 -0
  7. package/dist/cli.js +182 -42819
  8. package/dist/index.js +4 -1077
  9. package/docs/photos/logo/title-animation.svg +34 -0
  10. package/docs/photos/terminal/final_result_small.png +0 -0
  11. package/package.json +25 -12
  12. package/scripts/postinstall.cjs +15 -6
  13. package/types/index.d.ts +2 -3
  14. /package/docs/photos/terminal/{final_result.png → final_result_large.png} +0 -0
package/.env.example CHANGED
@@ -1,21 +1,18 @@
1
1
  # Optional: override the local Codex data directory inspected by codex-limits.
2
- # Leave unset to use the default platform-specific candidate paths.
2
+ # Leave unset to use CODEX_HOME and then the default platform-specific candidates.
3
3
  CODEX_LIMITS_HOME=
4
4
 
5
- # Optional fallback: codex-limits reads ~/.codex/auth.json automatically when available.
6
- # The tool calls the live Codex reset-credit endpoint at chatgpt.com only when credentials are found.
5
+ # Optional: Codex's native home override. CODEX_LIMITS_HOME takes precedence.
6
+ CODEX_HOME=
7
7
 
8
- # MacOS/Linux:
9
- # jq -r '.tokens.account_id // empty' ~/.codex/auth.json
10
- # Windows PowerShell:
11
- # (Get-Content "$env:USERPROFILE\.codex\auth.json" -Raw | ConvertFrom-Json).tokens.account_id
8
+ # Optional credential fallback. Prefer automatic auth.json discovery when available.
9
+ # Never commit real values or paste them into issue reports, logs, or screenshots.
12
10
  CODEX_LIMITS_ACCOUNT_ID=
13
-
14
- # MacOS/Linux:
15
- # jq -r '.tokens.access_token // empty' ~/.codex/auth.json
16
- # Windows PowerShell:
17
- # (Get-Content "$env:USERPROFILE\.codex\auth.json" -Raw | ConvertFrom-Json).tokens.access_token
18
11
  CODEX_LIMITS_ACCESS_TOKEN=
19
12
 
20
- # Optional: override the live usage endpoint if ChatGPT changes the Codex usage API path.
13
+ # Optional: override the live usage endpoint for advanced setups or local testing.
14
+ # HTTPS is required except for loopback HTTP (localhost, 127.0.0.1, or ::1).
21
15
  CODEX_LIMITS_USAGE_ENDPOINT=
16
+
17
+ # Optional: suppress global-install guidance from the non-interactive postinstall script.
18
+ CODEX_LIMITS_SKIP_INIT=
package/CHANGELOG.md CHANGED
@@ -1,13 +1,92 @@
1
- # Changelog
2
-
3
- All notable changes to codex-limits are documented in this file.
4
-
5
- ## [0.1.0] - 2026-07-05
6
-
7
- ### Added
8
-
9
- - Added the shared core API for Codex usage limits and reset-credit coupons.
10
- - Added the read-only Ink terminal dashboard with usage limit cards and reset coupon panels.
11
- - Added non-interactive `status`, `coupons`, and JSON command output.
12
- - Added an opencode plugin that registers `/codex-limits` without sending a prompt to the LLM.
13
- - Added `codex-limits init` and npm postinstall setup for optional agent integrations.
1
+ # Changelog
2
+
3
+ All notable changes to codex-limits are documented in this file.
4
+
5
+ ## [Unreleased]
6
+
7
+ ### Breaking Changes
8
+
9
+ ### Added
10
+
11
+ ### Changed
12
+
13
+ ### Fixed
14
+
15
+ ### Removed
16
+
17
+ ### Security
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
+
51
+ ## [0.1.4] - 2026-07-13
52
+
53
+ ### Added
54
+
55
+ - Added responsive dashboard layouts for wide, compact, short, and very small terminals.
56
+ - Added GitHub Actions checks and npm Trusted Publishing workflows.
57
+ - Added consistent Prettier formatting and package-artifact smoke validation.
58
+
59
+ ### Changed
60
+
61
+ - Changed npm artifacts to use self-contained runtime bundles and TypeScript-generated root plugin declarations, reducing installation dependencies while preserving the default and named `tui` exports.
62
+ - Changed `bun run check` to verify formatting, types, tests, production builds, package metadata, and isolated packed artifacts.
63
+ - Changed malformed, duplicate, conflicting, and extra CLI arguments to fail deterministically on stderr.
64
+
65
+ ### Fixed
66
+
67
+ - Fixed partial live usage windows being discarded when local usage data was unavailable.
68
+ - Fixed malformed, oversized, timed-out, aborted, and non-successful live responses to produce stable warnings and safe local fallback behavior.
69
+ - Fixed OpenCode registration and disposal to remain idempotent while supporting both command APIs.
70
+
71
+ ### Security
72
+
73
+ - Bounded local traversal, file sizes, JSONL line sizes, credential files, and live response bodies while skipping nested symbolic links.
74
+ - Prevented authenticated redirects, rejected unsafe endpoint protocols, and removed raw exception details from CLI and OpenCode errors.
75
+ - Strengthened warning and JSON redaction so credentials, private paths, authenticated headers, and internal source metadata do not reach public output.
76
+
77
+ ## [0.1.3] - 2026-07-09
78
+
79
+ ### Fixed
80
+
81
+ - Fixed `codex-limits init --opencode` to install the scoped OpenCode plugin package.
82
+ - Fixed OpenCode command registration to keep `/codex-limits` available with both legacy and current TUI plugin APIs.
83
+
84
+ ## [0.1.0] - 2026-07-05
85
+
86
+ ### Added
87
+
88
+ - Added the shared core API for Codex usage limits and reset-credit coupons.
89
+ - Added the read-only Ink terminal dashboard with usage limit cards and reset coupon panels.
90
+ - Added non-interactive `status`, `coupons`, and JSON command output.
91
+ - Added an opencode plugin that registers `/codex-limits` without sending a prompt to the LLM.
92
+ - Added `codex-limits init` and npm postinstall setup for optional agent integrations.
package/LICENSE CHANGED
@@ -1,21 +1,21 @@
1
- MIT License
2
-
3
- Copyright (c) 2026 Simone Siega
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
11
-
12
- The above copyright notice and this permission notice shall be included in all
13
- copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Simone Siega
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
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">
@@ -19,39 +17,116 @@
19
17
  <p align="center">
20
18
  <img src="https://img.shields.io/npm/v/@simonesiega/codex-limits?label=npm" alt="npm version" />
21
19
  <img src="https://img.shields.io/badge/TypeScript-5-blue?logo=typescript" alt="TypeScript" />
22
- <img src="https://img.shields.io/badge/Bun-runtime-black?logo=bun" alt="Bun" />
20
+ <img src="https://img.shields.io/badge/Bun-toolchain-black?logo=bun" alt="Bun toolchain" />
23
21
  </p>
24
22
 
25
- ## Final result 🚀
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
+
29
+ ## Preview 🚀
26
30
 
27
31
  <p align="center">
28
- <img src="docs/photos/terminal/final_result.png" alt="Final codex-limits terminal dashboard" width="740" />
32
+ <img src="docs/photos/terminal/final_result_large.png" alt="Final codex-limits larger terminal dashboard" width="400" />
33
+ <img src="docs/photos/terminal/final_result_small.png" alt="Final codex-limits smaller terminal dashboard" width="400" />
29
34
  </p>
30
35
 
31
- The screenshot shows the final **`codex-limits`** terminal dashboard: a clean, read-only TUI that summarizes 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.
37
+
38
+ ## Contents
39
+
40
+ - [Quick start](#quick-start)
41
+ - [Requirements](#requirements)
42
+ - [Overview](#overview)
43
+ - [Agent integrations](#agent-integrations)
44
+ - [How it works](#how-it-works)
45
+ - [Environment](#environment)
46
+ - [Usage](#usage)
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)
52
+ - [Local development](#local-development)
53
+ - [Security](#security)
54
+ - [License](#license)
55
+ - [Contributors](#contributors)
56
+
57
+ > Last verified against: `@simonesiega/codex-limits` v0.1.5
58
+ > Verification date: 2026-07-22
59
+
60
+ ## Quick start
61
+
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.
63
+
64
+ Install **`codex-limits`** globally from npm:
65
+
66
+ ```bash
67
+ npm install -g @simonesiega/codex-limits@latest
68
+ ```
69
+
70
+ The `@latest` tag ensures you install the latest published version.
71
+
72
+ Then run it from any terminal:
73
+
74
+ ```bash
75
+ codex-limits
76
+ ```
77
+
78
+ The list of available commands is shown when you run `codex-limits --help` or in the [Usage](#usage) section.
79
+
80
+ Install an optional agent integration by name:
81
+
82
+ ```bash
83
+ codex-limits agents install <agent-name>
84
+ ```
85
+
86
+ For example, install the OpenCode integration:
87
+
88
+ ```bash
89
+ codex-limits agents install opencode
90
+ ```
91
+
92
+ The existing `codex-limits init --<agent-name>` syntax remains supported as a compatibility command.
93
+
94
+ ## Requirements
95
+
96
+ | Requirement | Details |
97
+ | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
98
+ | Node.js | Node.js 20 or newer is required to run the published CLI. Bun is only required for local development. |
99
+ | 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. |
100
+ | 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. |
101
+ | 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. |
32
102
 
33
103
  ## Overview
34
104
 
35
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.
36
106
 
37
- **`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.
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.
38
108
 
39
- 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.
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.
40
110
 
41
111
  ## Agent integrations
42
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
+
43
117
  ### Supported agents
44
118
 
45
- | Agent | Status | Agent command | Init Command | Description |
46
- | --- | --- | --- | --- | --- |
47
- | 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. |
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. |
48
122
 
49
- Agent integrations are not enabled during package installation. The package import export is reserved for the agent plugin entry that supported agents load after you run the matching `codex-limits init` command.
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.
50
124
 
51
125
  ### Selected agent integration screenshots
52
126
 
53
127
  #### OpenCode
54
- 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.
128
+
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.
55
130
 
56
131
  <p align="center">
57
132
  <img src="docs/photos/agents/opencode/opencode_result.png" alt="OpenCode codex-limits integration screenshot" width="740" />
@@ -61,20 +136,20 @@ The OpenCode integration adds a `/codex-limits` command that opens a compact mod
61
136
 
62
137
  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.
63
138
 
64
- See the [Contributing](./CONTRIBUTING.md) section if you want to add support for another agent.
139
+ See the [Contributing](./CONTRIBUTING.md) guide if you want to add support for another agent.
65
140
 
66
141
  ## How it works
67
142
 
68
143
  **`codex-limits`** is built around a shared core with different output surfaces on top of it.
69
144
 
70
- | Area | Path | Purpose |
71
- | --- | --- | --- |
72
- | CLI entry | `src/package/cli.ts` | Starts the `codex-limits` command and routes to the dashboard, plain-text commands, JSON output, and `init`. |
73
- | 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. |
74
- | CLI commands | `src/package/commands` | Handles the dashboard, `status`, `coupons`, `--json`, and `init` commands. |
75
- | Terminal UI | `src/package/tui` | Renders the clean Ink-based dashboard from normalized usage data. |
76
- | Agent integrations | `src/agents` | Contains optional coding-agent adapters that users install with `codex-limits init`. |
77
- | Tests | `tests` | Contains the test suite used to validate core behavior, CLI output, safety rules, and integration logic. |
145
+ | Area | Path | Purpose |
146
+ | ------------------ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
147
+ | CLI entry | `src/package/cli.ts` | Starts the `codex-limits` command and delegates to the shared command registry. |
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. |
149
+ | CLI commands | `src/package/commands` | Defines command metadata, shared parsing and help, scoped runtime services, and focused command handlers. |
150
+ | Terminal UI | `src/package/tui` | Renders the clean Ink-based dashboard from normalized usage data. |
151
+ | Agent integrations | `src/agents` | Contains optional coding-agent adapters used by the `codex-limits agents` command group. |
152
+ | Tests | `tests` | Contains the test suite used to validate core behavior, CLI output, safety rules, and integration logic. |
78
153
 
79
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.
80
155
 
@@ -84,64 +159,114 @@ This structure keeps the project easy to extend: the core decides what the data
84
159
 
85
160
  Environment variables are only used as a fallback when automatic discovery is not enough, or when you want to override the default behavior.
86
161
 
87
- | Variable | Purpose |
88
- | --- | --- |
89
- | `CODEX_LIMITS_HOME` | Manually sets the local Codex data directory when it cannot be detected automatically. |
90
- | `CODEX_LIMITS_ACCESS_TOKEN` | Manually provides an access token for live reset-credit coupon data. |
91
- | `CODEX_LIMITS_ACCOUNT_ID` | Manually provides the account ID used for live reset-credit coupon data. |
92
- | `CODEX_LIMITS_USAGE_ENDPOINT` | Overrides the live usage endpoint, mainly for testing or advanced setups. |
162
+ | Variable | Purpose |
163
+ | ----------------------------- | ---------------------------------------------------------------------------------------- |
164
+ | `CODEX_LIMITS_HOME` | Overrides the local Codex data directory before all other candidates. |
165
+ | `CODEX_HOME` | Uses Codex's native home override when `CODEX_LIMITS_HOME` is not set. |
166
+ | `CODEX_LIMITS_ACCESS_TOKEN` | Provides an access token for authenticated live usage and reset-credit requests. |
167
+ | `CODEX_LIMITS_ACCOUNT_ID` | Provides the account ID paired with `CODEX_LIMITS_ACCESS_TOKEN`. |
168
+ | `CODEX_LIMITS_USAGE_ENDPOINT` | Overrides the live usage endpoint with HTTPS or loopback HTTP for advanced setups/tests. |
169
+ | `CODEX_LIMITS_SKIP_INIT` | Suppresses optional global-install setup guidance from the non-interactive postinstall. |
93
170
 
94
- ## Installation
171
+ ### Data access and safety
95
172
 
96
- Install **`codex-limits`** globally from npm:
173
+ Local Codex data is 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. See [`SECURITY.md`](./SECURITY.md#local-data-and-network-behavior) for the complete data-access and network-safety model.
97
174
 
98
- ```bash
99
- npm install -g @simonesiega/codex-limits
100
- ```
175
+ ## Usage
101
176
 
102
- Then run it from any terminal:
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. |
103
188
 
104
- ```bash
105
- codex-limits
106
- ```
189
+ ### Agent management
107
190
 
108
- ## Usage
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.
109
192
 
110
- | Command | Description |
111
- | --- | --- |
112
- | `codex-limits` | Opens the interactive terminal dashboard. |
113
- | `codex-limits status` | Prints a plain usage summary. |
114
- | `codex-limits coupons` | Prints reset-credit coupon information. |
115
- | `codex-limits --json` | Prints machine-readable usage data for scripts and automation. |
116
- | `codex-limits init` | Installs optional agent integrations. |
117
- | `codex-limits init --opencode` | Installs the OpenCode integration directly. |
118
- | `codex-limits --help` | Prints the help text. |
119
- | `codex-limits --version` | Prints the installed package version. |
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.
203
+
204
+ ## Troubleshooting
205
+
206
+ ### No Codex data found
207
+
208
+ 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.
209
+
210
+ ### Usage information unavailable
211
+
212
+ 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.
213
+
214
+ ### Permission errors
215
+
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`.
217
+
218
+ ### Agent command not appearing after installation
219
+
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.
120
229
 
121
230
  ## Local development
122
231
 
123
232
  Clone the repository, install dependencies, and run the CLI locally:
124
233
 
125
234
  ```bash
235
+ git clone https://github.com/simonesiega/codex-limits.git
236
+ cd codex-limits
126
237
  bun install
127
238
  bun run dev
128
239
  ```
129
240
 
130
241
  Useful development commands:
131
242
 
132
- | Command | Description |
133
- | --- | --- |
134
- | `bun run dev` | Runs the CLI in development mode. |
135
- | `bun run check` | Runs type checking, tests, and build validation. |
136
- | `bun test` | Runs the test suite. |
137
- | `bun run build` | Builds the package. |
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. |
254
+
255
+ ## Security
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 |
138
262
 
263
+ For vulnerability reports and local data safety details, see [`SECURITY.md`](./SECURITY.md).
139
264
 
140
265
  ## License
141
266
 
142
267
  This project is licensed under the MIT License. See [`LICENSE`](LICENSE).
143
268
 
144
- ## Contributors 🧑‍💻
269
+ ## Contributors
145
270
 
146
271
  <p align="center">
147
272
  <a href="https://github.com/simonesiega/codex-limits/graphs/contributors">
package/SECURITY.md ADDED
@@ -0,0 +1,102 @@
1
+ <h1 align="center">
2
+ Security Policy
3
+ </h1>
4
+
5
+ <p align="center">
6
+ Responsible disclosure guidelines for <strong>codex-limits</strong>.
7
+ </p>
8
+
9
+ <p align="center">
10
+ <img src="https://img.shields.io/badge/Security-private%20reporting-red" alt="Private security reporting" />
11
+ <img src="https://img.shields.io/badge/Data%20access-read--only-blue" alt="Read-only data access" />
12
+ <img src="https://img.shields.io/badge/Supported-latest%20release%20%7C%20main-brightgreen" alt="Supported versions: latest release and main" />
13
+ <img src="https://img.shields.io/github/license/simonesiega/codex-limits" alt="License" />
14
+ </p>
15
+
16
+ ## Supported versions
17
+
18
+ Security fixes are handled for the latest published version of `@simonesiega/codex-limits` and for the current `main` branch.
19
+
20
+ | Version | Support |
21
+ | ------------------ | ------------------------------ |
22
+ | Latest npm release | Supported |
23
+ | `main` branch | Supported for unreleased fixes |
24
+ | Older releases | Best effort only |
25
+
26
+ ## Reporting a vulnerability
27
+
28
+ If you discover a vulnerability, a way to expose private Codex data, or a behavior that could leak sensitive information, do not open a public issue.
29
+
30
+ Report it privately using one of the following methods:
31
+
32
+ | Contact | Value |
33
+ | ----------------------------------- | ------------------------------------------------------------------------------------------ |
34
+ | GitHub private vulnerability report | [Submit a private report](https://github.com/simonesiega/codex-limits/security/advisories) |
35
+ | Email | [simonesiega1@gmail.com](mailto:simonesiega1@gmail.com) |
36
+
37
+ Do not include real access tokens, credentials, or unredacted private Codex files in the report. Use redacted examples whenever possible.
38
+
39
+ Please include:
40
+
41
+ | Field | Why it matters |
42
+ | -------------------- | ------------------------------------------------------------------------- |
43
+ | Short description | Explains what the issue is. |
44
+ | Impact | Explains what data, command, output, or integration is affected. |
45
+ | Reproduction steps | Makes the issue easier to verify and fix. |
46
+ | Environment | Helps isolate OS, Bun, Node, Codex, terminal, or agent-specific behavior. |
47
+ | Suggested mitigation | Optional, but useful if you already found a safe fix. |
48
+
49
+ ## What to expect
50
+
51
+ After receiving a report, the maintainer will:
52
+
53
+ 1. Confirm receipt of the report.
54
+ 2. Investigate and reproduce the issue.
55
+ 3. Share relevant progress when possible.
56
+ 4. Coordinate a fix and disclosure before publishing details.
57
+
58
+ Please do not publicly disclose the vulnerability until a fix is available or disclosure has been coordinated. No specific response time is promised, but reports will be handled as promptly as reasonably possible.
59
+
60
+ ## Local data and network behavior
61
+
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
+
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
+
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
+
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
+
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
+
76
+ ## What to report
77
+
78
+ Please report any issue that could expose private data or break the read-only safety model of the project.
79
+
80
+ Relevant examples include:
81
+
82
+ - access tokens printed in terminal output, JSON output, logs, tests, or screenshots;
83
+ - account IDs exposed without redaction;
84
+ - auth headers, cookies, or private environment values reaching user-visible output;
85
+ - raw local Codex files being printed, logged, snapshotted, or committed;
86
+ - agent integrations exposing private Codex data inside the agent UI;
87
+ - unexpected writes to local Codex data;
88
+ - unexpected network behavior related to usage or coupon discovery;
89
+ - unsafe handling of `CODEX_LIMITS_HOME`, `CODEX_LIMITS_ACCESS_TOKEN`, `CODEX_LIMITS_ACCOUNT_ID`, or `CODEX_LIMITS_USAGE_ENDPOINT`.
90
+
91
+ ## Safety expectations
92
+
93
+ `codex-limits` is intended to be safe by default.
94
+
95
+ The project should:
96
+
97
+ - remain read-only for local Codex data;
98
+ - keep sensitive values out of CLI output, TUI output, JSON output, tests, logs, and screenshots;
99
+ - centralize data discovery, parsing, normalization, warnings, and redaction in the shared core;
100
+ - keep agent integrations thin and reuse the shared core instead of reimplementing security-sensitive parsing;
101
+ - use placeholders or redacted values in documentation, examples, and test fixtures;
102
+ - convert network, payload, authentication, and filesystem failures into deterministic safe warnings rather than raw exception messages.