@simonesiega/codex-limits 0.1.6 → 1.0.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/.env.example +3 -0
- package/CHANGELOG.md +25 -0
- package/CONTRIBUTING.md +226 -0
- package/README.md +67 -37
- package/SECURITY.md +52 -16
- package/dist/cli.js +152 -136
- package/dist/copilot.mjs +5 -0
- package/dist/opencode.js +5 -0
- package/dist/pi.js +3 -3
- package/docs/README.md +67 -0
- package/docs/examples/codex-limits-output.example.json +63 -0
- package/docs/photos/agents/copilot/copilot_result.png +0 -0
- package/docs/readme/agent-integrations.md +81 -0
- package/docs/readme/agents/copilot.md +147 -0
- package/docs/readme/agents/opencode.md +126 -0
- package/docs/readme/agents/pi.md +143 -0
- package/docs/readme/compatibility.md +143 -0
- package/docs/readme/json-output.md +295 -0
- package/docs/schema/codex-limits.schema.json +183 -0
- package/package.json +7 -4
- package/dist/index.js +0 -5
package/.env.example
CHANGED
package/CHANGELOG.md
CHANGED
|
@@ -16,6 +16,31 @@ All notable changes to codex-limits are documented in this file.
|
|
|
16
16
|
|
|
17
17
|
### Security
|
|
18
18
|
|
|
19
|
+
## [1.0.0] - 2026-07-23
|
|
20
|
+
|
|
21
|
+
### Added
|
|
22
|
+
|
|
23
|
+
- Added `codex-limits reset` for consuming a numbered or soonest-expiring reset coupon after an interactive recap and explicit `y` confirmation.
|
|
24
|
+
- Added the GitHub Copilot CLI integration with `codex-limits agents install copilot` and a read-only `/codex-limits` extension command that does not send limit data to the LLM.
|
|
25
|
+
- Added a task-oriented documentation hub and included the complete guides, JSON Schema, and sanitized example in published npm packages.
|
|
26
|
+
- Added weekly Dependabot updates for the Bun dependency graph.
|
|
27
|
+
|
|
28
|
+
### Changed
|
|
29
|
+
|
|
30
|
+
- Changed the packaged OpenCode runtime entry point to the agent-specific `dist/opencode.js` bundle while preserving the package root plugin exports.
|
|
31
|
+
- Changed `codex-limits doctor` text output to align every diagnostic value with the longest integration label.
|
|
32
|
+
|
|
33
|
+
### Fixed
|
|
34
|
+
|
|
35
|
+
- Fixed local session fallback to select the newest bounded event timestamp when file modification times are misleading.
|
|
36
|
+
- Fixed combined dashboard loading to start independent usage and reset-coupon requests concurrently.
|
|
37
|
+
|
|
38
|
+
### Security
|
|
39
|
+
|
|
40
|
+
- Hardened bounded session and native HTTP reads against path-replacement races and unbounded error-body draining, and made `reset --soonest` fail closed when coupon expirations cannot be verified.
|
|
41
|
+
- Prevented private Codex paths, free-form local reset text, and malformed coupon timestamp content from reaching public output.
|
|
42
|
+
- Required manual npm publishing runs to use the version tag matching the package metadata.
|
|
43
|
+
|
|
19
44
|
## [0.1.6] - 2026-07-22
|
|
20
45
|
|
|
21
46
|
### Breaking Changes
|
package/CONTRIBUTING.md
ADDED
|
@@ -0,0 +1,226 @@
|
|
|
1
|
+
<p align="center">
|
|
2
|
+
<img src="docs/photos/logo/logo.png" alt="codex-limits logo" width="180" />
|
|
3
|
+
</p>
|
|
4
|
+
|
|
5
|
+
<h1 align="center">
|
|
6
|
+
Contributing to Codex Limits
|
|
7
|
+
</h1>
|
|
8
|
+
|
|
9
|
+
<p align="center">
|
|
10
|
+
Guidelines for contributing to <strong>codex-limits</strong>.
|
|
11
|
+
</p>
|
|
12
|
+
|
|
13
|
+
<p align="center">
|
|
14
|
+
<img src="https://img.shields.io/badge/TypeScript-5-blue?logo=typescript" alt="TypeScript" />
|
|
15
|
+
<img src="https://img.shields.io/badge/PRs-welcome-brightgreen" alt="PRs welcome" />
|
|
16
|
+
<img src="https://img.shields.io/github/license/simonesiega/codex-limits" alt="License" />
|
|
17
|
+
<img src="https://img.shields.io/github/issues-pr/simonesiega/codex-limits" alt="Open pull requests" />
|
|
18
|
+
<img src="https://img.shields.io/github/issues/simonesiega/codex-limits" alt="Open issues" />
|
|
19
|
+
</p>
|
|
20
|
+
|
|
21
|
+
Read [`README.md`](README.md) first, then use the [documentation hub](docs/README.md) to find the canonical guide for the area you plan to change.
|
|
22
|
+
|
|
23
|
+
## Contents
|
|
24
|
+
|
|
25
|
+
- [Quick start](#quick-start)
|
|
26
|
+
- [Branch naming](#branch-naming)
|
|
27
|
+
- [Issues](#issues)
|
|
28
|
+
- [Local development](#local-development)
|
|
29
|
+
- [Code guidelines](#code-guidelines)
|
|
30
|
+
- [Safety rules](#safety-rules)
|
|
31
|
+
- [Adding a new agent](#adding-a-new-agent)
|
|
32
|
+
- [Documentation changes](#documentation-changes)
|
|
33
|
+
- [Pull request checklist](#pull-request-checklist)
|
|
34
|
+
- [Security policy](#security-policy)
|
|
35
|
+
- [Community guidelines](#community-guidelines)
|
|
36
|
+
- [Contact](#contact)
|
|
37
|
+
|
|
38
|
+
## Quick start
|
|
39
|
+
|
|
40
|
+
If you are new to the project, read [`README.md`](README.md) and the [documentation hub](docs/README.md), then choose one focused issue or improvement.
|
|
41
|
+
|
|
42
|
+
| Step | Action |
|
|
43
|
+
| ---- | ----------------------------------------------- |
|
|
44
|
+
| 1 | Fork the repository. |
|
|
45
|
+
| 2 | Create a branch from `main`. |
|
|
46
|
+
| 3 | Make one focused change. |
|
|
47
|
+
| 4 | Run the local checks. |
|
|
48
|
+
| 5 | Open a Pull Request with context and rationale. |
|
|
49
|
+
|
|
50
|
+
## Branch naming
|
|
51
|
+
|
|
52
|
+
| Type | Pattern | Example |
|
|
53
|
+
| ----------- | -------- | --------------------------- |
|
|
54
|
+
| Feature | `feat/` | `feat/add-agent-adapter` |
|
|
55
|
+
| Bug fix | `fix/` | `fix/usage-window-reset` |
|
|
56
|
+
| Docs | `docs/` | `docs/update-agent-guide` |
|
|
57
|
+
| Maintenance | `chore/` | `chore/update-build-config` |
|
|
58
|
+
| Tests | `test/` | `test/add-coupon-coverage` |
|
|
59
|
+
|
|
60
|
+
## Issues
|
|
61
|
+
|
|
62
|
+
Before opening a new issue, check existing [Issues](https://github.com/simonesiega/codex-limits/issues) to avoid duplicates.
|
|
63
|
+
|
|
64
|
+
Please include:
|
|
65
|
+
|
|
66
|
+
| Field | Why it matters |
|
|
67
|
+
| ------------------- | -------------------------------------------------------- |
|
|
68
|
+
| Expected behavior | Explains what should happen. |
|
|
69
|
+
| Actual behavior | Shows what currently happens. |
|
|
70
|
+
| Reproduction steps | Makes the issue easier to verify. |
|
|
71
|
+
| Environment | Helps isolate OS, Node, Bun, or Codex-specific behavior. |
|
|
72
|
+
| Logs or screenshots | Clarifies terminal, CLI, or agent output. |
|
|
73
|
+
|
|
74
|
+
For architecture-level changes, open an issue first so the design can be discussed before implementation.
|
|
75
|
+
|
|
76
|
+
## Local development
|
|
77
|
+
|
|
78
|
+
### Requirements
|
|
79
|
+
|
|
80
|
+
Before starting development, read the project [Requirements](README.md#requirements) and make sure your environment meets them. Development also requires [Bun](https://bun.sh/) using the version declared in `package.json`, because this repository uses Bun for dependency management, scripts, builds, and tests.
|
|
81
|
+
|
|
82
|
+
Install dependencies:
|
|
83
|
+
|
|
84
|
+
```bash
|
|
85
|
+
bun install
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
Run the CLI locally:
|
|
89
|
+
|
|
90
|
+
```bash
|
|
91
|
+
bun run dev
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
Run the full validation pipeline (format verification, documentation checks, types, tests, production builds, and packed-artifact smoke checks):
|
|
95
|
+
|
|
96
|
+
```bash
|
|
97
|
+
bun run check
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
Run all documentation checks:
|
|
101
|
+
|
|
102
|
+
```bash
|
|
103
|
+
bun run docs:check
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
Run the documentation checks individually:
|
|
107
|
+
|
|
108
|
+
```bash
|
|
109
|
+
bun run docs:link
|
|
110
|
+
bun run docs:schema
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
Run tests only:
|
|
114
|
+
|
|
115
|
+
```bash
|
|
116
|
+
bun test
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
Build the package:
|
|
120
|
+
|
|
121
|
+
```bash
|
|
122
|
+
bun run build
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
## Code guidelines
|
|
126
|
+
|
|
127
|
+
Keep changes small, readable, and easy to review.
|
|
128
|
+
|
|
129
|
+
| Area | Guideline |
|
|
130
|
+
| ------------------ | ------------------------------------------------------------------------------------------------- |
|
|
131
|
+
| Core logic | Keep usage detection, normalization, and safety rules inside `src/package/core`. |
|
|
132
|
+
| CLI commands | Add commands through the shared registry and parser; keep handlers focused and capability-scoped. |
|
|
133
|
+
| Terminal UI | Keep Ink rendering inside `src/package/tui`; components should receive display-ready data. |
|
|
134
|
+
| Agent integrations | Keep adapters thin and reuse the shared core instead of reimplementing Codex limit parsing. |
|
|
135
|
+
| Tests | Add or update tests when behavior, safety rules, or output formatting changes. |
|
|
136
|
+
|
|
137
|
+
When adding a CLI command, create a focused command module and register it in `src/package/commands/command-registry.ts`. Put names, descriptions, usage, options, positional arguments, conflicts, and safety classification in that command definition so the shared parser and help generator stay synchronized. Command factories should accept only the runtime capabilities their handlers use.
|
|
138
|
+
|
|
139
|
+
## Safety rules
|
|
140
|
+
|
|
141
|
+
`codex-limits` treats local Codex data as read-only and should remain safe by default.
|
|
142
|
+
|
|
143
|
+
Do not print, log, snapshot, or commit:
|
|
144
|
+
|
|
145
|
+
- access tokens;
|
|
146
|
+
- account IDs;
|
|
147
|
+
- auth headers;
|
|
148
|
+
- cookies;
|
|
149
|
+
- raw local Codex files;
|
|
150
|
+
- private environment values.
|
|
151
|
+
|
|
152
|
+
If a change touches local data discovery, live coupon data, warnings, output formatting, or agent integrations, make sure sensitive values are redacted before they can reach the CLI, TUI, JSON output, tests, or screenshots.
|
|
153
|
+
|
|
154
|
+
Command handlers should let the router replace unexpected exceptions with their fixed command failure message. Use `AgentInstallError` only for bounded, deliberately user-safe adapter messages; never pass through a raw filesystem, network, or credential error.
|
|
155
|
+
|
|
156
|
+
## Adding a new agent
|
|
157
|
+
|
|
158
|
+
New agents should use the same small adapter shape as [`src/agents/opencode`](src/agents/opencode), [`src/agents/pi`](src/agents/pi), and [`src/agents/copilot`](src/agents/copilot): `format.ts`, `install.ts`, `integration.ts`, and `plugin.ts`. Put reusable presentation and safe configuration behavior in `src/agents/shared`.
|
|
159
|
+
|
|
160
|
+
| Step | Action |
|
|
161
|
+
| ---- | ------------------------------------------------------------------------------------------------------------------------------- |
|
|
162
|
+
| 1 | Create `src/agents/<agent-name>` with the standard four-file adapter layout. |
|
|
163
|
+
| 2 | Define metadata, optional environment help, `install`, and `inspect` in `integration.ts`. |
|
|
164
|
+
| 3 | Keep `plugin.ts` focused on the target host API and load Codex data only through the shared package core. |
|
|
165
|
+
| 4 | Register the integration descriptor once in `src/agents/index.ts`; shared install and doctor commands consume it automatically. |
|
|
166
|
+
| 5 | Add installer, formatter, and host-behavior tests. When end-to-end automation is impractical, document the manual validation. |
|
|
167
|
+
| 6 | Add `docs/readme/agents/<agent-name>.md`. |
|
|
168
|
+
| 7 | Add the integration to [Agent Integrations](docs/readme/agent-integrations.md). |
|
|
169
|
+
| 8 | Update the README supported-agent summary and any target-specific package/build metadata. |
|
|
170
|
+
| 9 | Add or update screenshots when the visual output changes. |
|
|
171
|
+
| 10 | Run the documentation link and schema checks. |
|
|
172
|
+
|
|
173
|
+
The goal of every integration is the same: show Codex limit information quickly, safely, and without sending unnecessary work to the LLM.
|
|
174
|
+
|
|
175
|
+
## Documentation changes
|
|
176
|
+
|
|
177
|
+
Task-oriented guides live under [`docs/`](docs/README.md), and visual assets live under [`docs/photos/`](docs/photos/). Update the canonical guide whenever behavior, setup, compatibility, output, or safety guarantees change; avoid copying complete procedures into multiple files.
|
|
178
|
+
|
|
179
|
+
Keep documentation changes consistent with these rules:
|
|
180
|
+
|
|
181
|
+
- use relative links for files in this repository;
|
|
182
|
+
- keep commands executable from their documented working directory;
|
|
183
|
+
- keep heading anchors stable when another file links to them;
|
|
184
|
+
- synchronize JSON examples with `docs/schema/codex-limits.schema.json`;
|
|
185
|
+
- use descriptive image alt text and sanitized screenshots;
|
|
186
|
+
- never include tokens, account IDs, cookies, authorization headers, private paths, environment contents, or raw Codex files.
|
|
187
|
+
|
|
188
|
+
Run:
|
|
189
|
+
|
|
190
|
+
```bash
|
|
191
|
+
bun run docs:check
|
|
192
|
+
git diff --check
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
Documentation-only changes do not require unrelated runtime changes, but the complete `bun run check` remains the final repository gate before release.
|
|
196
|
+
|
|
197
|
+
## Pull request checklist
|
|
198
|
+
|
|
199
|
+
Before requesting review, verify:
|
|
200
|
+
|
|
201
|
+
- [ ] The PR title and description explain what changed and why.
|
|
202
|
+
- [ ] The change is focused and does not include unrelated cleanup.
|
|
203
|
+
- [ ] `bun run format` was run and `bun run check` passes locally.
|
|
204
|
+
- [ ] Tests were added or updated for behavior changes.
|
|
205
|
+
- [ ] Documentation was updated if commands, setup, output, or agent support changed.
|
|
206
|
+
- [ ] No secrets, account data, tokens, cookies, or raw local files were committed.
|
|
207
|
+
- [ ] Screenshots were updated only when the visual output changed.
|
|
208
|
+
|
|
209
|
+
## Security policy
|
|
210
|
+
|
|
211
|
+
If you discover a vulnerability or a way to expose private Codex data, do not open a public issue.
|
|
212
|
+
|
|
213
|
+
Please follow the private reporting process in [`SECURITY.md`](./SECURITY.md).
|
|
214
|
+
|
|
215
|
+
## Community guidelines
|
|
216
|
+
|
|
217
|
+
Be clear, respectful, and constructive in issues, Pull Requests, and reviews. Good contributions are focused, tested, documented, and easy to understand.
|
|
218
|
+
|
|
219
|
+
## Contact
|
|
220
|
+
|
|
221
|
+
For direct contact:
|
|
222
|
+
|
|
223
|
+
- Email: [simonesiega1@gmail.com](mailto:simonesiega1@gmail.com)
|
|
224
|
+
- GitHub: [@simonesiega](https://github.com/simonesiega)
|
|
225
|
+
|
|
226
|
+
Thanks for contributing to **`codex-limits`**.
|
package/README.md
CHANGED
|
@@ -16,7 +16,7 @@
|
|
|
16
16
|
|
|
17
17
|
<p align="center">
|
|
18
18
|
<img src="https://img.shields.io/npm/v/@simonesiega/codex-limits?label=npm" alt="npm version" />
|
|
19
|
-
<img src="https://img.shields.io/badge/test_coverage-96.
|
|
19
|
+
<img src="https://img.shields.io/badge/test_coverage-96.2%25_lines-brightgreen" alt="Test coverage: 96.2% lines" />
|
|
20
20
|
</p>
|
|
21
21
|
|
|
22
22
|
<p align="center">
|
|
@@ -46,6 +46,7 @@ The screenshots show the **`codex-limits`** terminal dashboards: clean, read-onl
|
|
|
46
46
|
- [Usage](#usage)
|
|
47
47
|
- [Troubleshooting](#troubleshooting)
|
|
48
48
|
- [Documentation](#documentation)
|
|
49
|
+
- [Documentation hub](docs/README.md)
|
|
49
50
|
- [JSON output](docs/readme/json-output.md)
|
|
50
51
|
- [Agent integrations](docs/readme/agent-integrations.md)
|
|
51
52
|
- [Compatibility](docs/readme/compatibility.md)
|
|
@@ -54,9 +55,6 @@ The screenshots show the **`codex-limits`** terminal dashboards: clean, read-onl
|
|
|
54
55
|
- [License](#license)
|
|
55
56
|
- [Contributors](#contributors)
|
|
56
57
|
|
|
57
|
-
> Last verified against: `@simonesiega/codex-limits` v0.1.6
|
|
58
|
-
> Verification date: 2026-07-22
|
|
59
|
-
|
|
60
58
|
## Quick start
|
|
61
59
|
|
|
62
60
|
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.
|
|
@@ -83,11 +81,12 @@ Install an optional agent integration by name:
|
|
|
83
81
|
codex-limits agents install <agent-name>
|
|
84
82
|
```
|
|
85
83
|
|
|
86
|
-
For example, install the OpenCode or
|
|
84
|
+
For example, install the OpenCode, pi, or GitHub Copilot CLI integration:
|
|
87
85
|
|
|
88
86
|
```bash
|
|
89
87
|
codex-limits agents install opencode
|
|
90
88
|
codex-limits agents install pi
|
|
89
|
+
codex-limits agents install copilot
|
|
91
90
|
```
|
|
92
91
|
|
|
93
92
|
The existing `codex-limits init --<agent-name>` syntax remains supported as a compatibility command.
|
|
@@ -101,7 +100,7 @@ The existing `codex-limits init --<agent-name>` syntax remains supported as a co
|
|
|
101
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. |
|
|
102
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. |
|
|
103
102
|
|
|
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.
|
|
103
|
+
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. The GitHub Copilot CLI integration uses Copilot's experimental extension host and its CLI-provided SDK.
|
|
105
104
|
|
|
106
105
|
## Overview
|
|
107
106
|
|
|
@@ -109,20 +108,21 @@ When you are working with Codex or agent-based coding tools, usage limits can in
|
|
|
109
108
|
|
|
110
109
|
**`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.
|
|
111
110
|
|
|
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.
|
|
111
|
+
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.
|
|
113
112
|
|
|
114
113
|
## Agent integrations
|
|
115
114
|
|
|
116
|
-
Optional integrations make Codex limit information available directly inside supported coding agents while reusing the same read
|
|
115
|
+
Optional integrations make Codex limit information available directly inside supported coding agents while reusing the same normalized read paths and safety model as the CLI. Agent integrations do not receive the reset command's mutation capability.
|
|
117
116
|
|
|
118
117
|
For installation details, adapter behavior, architecture, and contribution guidance, see the detailed [Agent integrations guide](docs/readme/agent-integrations.md).
|
|
119
118
|
|
|
120
119
|
### Supported agents
|
|
121
120
|
|
|
122
|
-
| Agent
|
|
123
|
-
|
|
|
124
|
-
| OpenCode
|
|
125
|
-
| pi
|
|
121
|
+
| Agent | Status | Agent command | Guide | Description |
|
|
122
|
+
| ------------------ | --------- | --------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
|
|
123
|
+
| 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. |
|
|
124
|
+
| 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. |
|
|
125
|
+
| GitHub Copilot CLI | Supported | `/codex-limits` | [Installation and usage](docs/readme/agents/copilot.md) | Logs a compact, read-only Codex limits summary through a local Copilot CLI extension without sending it to the LLM. |
|
|
126
126
|
|
|
127
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.
|
|
128
128
|
|
|
@@ -144,6 +144,14 @@ The pi integration adds a `/codex-limits` command that opens a themed overlay in
|
|
|
144
144
|
<img src="docs/photos/agents/pi/pi_result.png" alt="pi codex-limits integration screenshot" width="740" />
|
|
145
145
|
</p>
|
|
146
146
|
|
|
147
|
+
#### GitHub Copilot CLI
|
|
148
|
+
|
|
149
|
+
The GitHub Copilot CLI integration adds a `/codex-limits` command that displays a compact, read-only limits summary in the session timeline. It loads the shared core locally without sending the request or limit data to the LLM.
|
|
150
|
+
|
|
151
|
+
<p align="center">
|
|
152
|
+
<img src="docs/photos/agents/copilot/copilot_result.png" alt="GitHub Copilot CLI codex-limits integration screenshot" width="740" />
|
|
153
|
+
</p>
|
|
154
|
+
|
|
147
155
|
### Adding new agents
|
|
148
156
|
|
|
149
157
|
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.
|
|
@@ -154,16 +162,16 @@ See the [Contributing](./CONTRIBUTING.md) guide if you want to add support for a
|
|
|
154
162
|
|
|
155
163
|
**`codex-limits`** is built around a shared core with different output surfaces on top of it.
|
|
156
164
|
|
|
157
|
-
| Area | Path | Purpose
|
|
158
|
-
| ------------------ | ---------------------- |
|
|
159
|
-
| CLI entry | `src/package/cli.ts` | Starts the `codex-limits` command and delegates to the shared command registry.
|
|
160
|
-
| Core logic | `src/package/core` | Detects Codex data,
|
|
161
|
-
| CLI commands | `src/package/commands` | Defines command metadata, shared parsing and help, scoped runtime services, and focused command handlers.
|
|
162
|
-
| Terminal UI | `src/package/tui` | Renders the clean Ink-based dashboard from normalized usage data.
|
|
163
|
-
| Agent integrations | `src/agents` | Contains optional coding-agent adapters used by the `codex-limits agents` command group.
|
|
164
|
-
| Tests | `tests` | Contains the test suite used to validate core behavior, CLI output, safety rules, and integration logic.
|
|
165
|
+
| Area | Path | Purpose |
|
|
166
|
+
| ------------------ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
167
|
+
| CLI entry | `src/package/cli.ts` | Starts the `codex-limits` command and delegates to the shared command registry. |
|
|
168
|
+
| Core logic | `src/package/core` | Detects Codex data, normalizes live and local information, performs confirmed coupon redemption, and keeps sensitive values out of output. |
|
|
169
|
+
| CLI commands | `src/package/commands` | Defines command metadata, shared parsing and help, scoped runtime services, and focused command handlers. |
|
|
170
|
+
| Terminal UI | `src/package/tui` | Renders the clean Ink-based dashboard from normalized usage data. |
|
|
171
|
+
| Agent integrations | `src/agents` | Contains optional coding-agent adapters used by the `codex-limits agents` command group. |
|
|
172
|
+
| Tests | `tests` | Contains the test suite used to validate core behavior, CLI output, safety rules, and integration logic. |
|
|
165
173
|
|
|
166
|
-
This structure keeps the project easy to extend: the core
|
|
174
|
+
This structure keeps the project easy to extend: the core owns data meaning and authenticated network operations, while commands control when capabilities are used and the TUI and agents remain rendering-only surfaces.
|
|
167
175
|
|
|
168
176
|
## Environment
|
|
169
177
|
|
|
@@ -180,10 +188,11 @@ Environment variables are only used as a fallback when automatic discovery is no
|
|
|
180
188
|
| `CODEX_LIMITS_USAGE_ENDPOINT` | Overrides the live usage endpoint with HTTPS or loopback HTTP for advanced setups/tests. |
|
|
181
189
|
| `CODEX_LIMITS_SKIP_INIT` | Suppresses optional global-install setup guidance from the non-interactive postinstall. |
|
|
182
190
|
| `PI_CODING_AGENT_DIR` | Overrides pi's global agent configuration directory for integration setup and checks. |
|
|
191
|
+
| `COPILOT_HOME` | Overrides GitHub Copilot CLI's user configuration and extension directory. |
|
|
183
192
|
|
|
184
193
|
### Data access and safety
|
|
185
194
|
|
|
186
|
-
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.
|
|
195
|
+
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.
|
|
187
196
|
|
|
188
197
|
## Usage
|
|
189
198
|
|
|
@@ -193,6 +202,8 @@ Local Codex data is inspected read-only with bounded file, directory, JSONL, and
|
|
|
193
202
|
| `codex-limits status` | Prints a plain usage summary. |
|
|
194
203
|
| `codex-limits coupons` | Prints reset-credit coupon information. |
|
|
195
204
|
| `codex-limits coupons --json` | Prints machine-readable reset-credit coupon data only. |
|
|
205
|
+
| `codex-limits reset <coupon-index>` | Reviews and uses the numbered available reset coupon. |
|
|
206
|
+
| `codex-limits reset --soonest` | Reviews and uses the coupon that expires first. |
|
|
196
207
|
| `codex-limits --json` | Prints machine-readable usage and coupon data. |
|
|
197
208
|
| `codex-limits doctor` | Prints safe environment and connectivity diagnostics. |
|
|
198
209
|
| `codex-limits doctor --json` | Prints machine-readable diagnostics only. |
|
|
@@ -201,6 +212,19 @@ Local Codex data is inspected read-only with bounded file, directory, JSONL, and
|
|
|
201
212
|
| `codex-limits agents install --all` | Installs every supported agent integration. |
|
|
202
213
|
| `codex-limits init` | Runs the compatible interactive installation flow. |
|
|
203
214
|
|
|
215
|
+
### Resetting usage
|
|
216
|
+
|
|
217
|
+
Use one available reset coupon by the number shown in `codex-limits coupons`, or let the command select the available coupon that expires first:
|
|
218
|
+
|
|
219
|
+
```bash
|
|
220
|
+
codex-limits reset <coupon-index>
|
|
221
|
+
codex-limits reset --soonest
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
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.
|
|
225
|
+
|
|
226
|
+
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.
|
|
227
|
+
|
|
204
228
|
### Diagnostics
|
|
205
229
|
|
|
206
230
|
Run the read-only doctor command when Codex data, live usage, or an agent integration is unavailable:
|
|
@@ -212,20 +236,21 @@ codex-limits doctor
|
|
|
212
236
|
```text
|
|
213
237
|
Codex Limits diagnostics
|
|
214
238
|
|
|
215
|
-
Package version:
|
|
216
|
-
Node.js version:
|
|
217
|
-
Operating system:
|
|
218
|
-
Codex home detected:
|
|
219
|
-
Authentication found:
|
|
220
|
-
Local usage found:
|
|
221
|
-
Live endpoint:
|
|
222
|
-
OpenCode integration:
|
|
223
|
-
pi integration:
|
|
239
|
+
Package version: 1.0.0
|
|
240
|
+
Node.js version: 22.0.0
|
|
241
|
+
Operating system: Windows
|
|
242
|
+
Codex home detected: Yes
|
|
243
|
+
Authentication found: Yes
|
|
244
|
+
Local usage found: Yes
|
|
245
|
+
Live endpoint: Reachable
|
|
246
|
+
OpenCode integration: Installed
|
|
247
|
+
pi integration: Installed
|
|
248
|
+
GitHub Copilot CLI integration: Installed
|
|
224
249
|
|
|
225
250
|
No sensitive values were displayed.
|
|
226
251
|
```
|
|
227
252
|
|
|
228
|
-
The doctor checks only whether recognized resources are available, including the OpenCode and
|
|
253
|
+
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).
|
|
229
254
|
|
|
230
255
|
### Agent management
|
|
231
256
|
|
|
@@ -258,15 +283,19 @@ Confirm that your user can read the selected Codex directory and its session fil
|
|
|
258
283
|
|
|
259
284
|
### Agent command not appearing after installation
|
|
260
285
|
|
|
261
|
-
Run the named installer again, for example `codex-limits agents install opencode` or `codex-limits agents install
|
|
286
|
+
Run the named installer again, for example `codex-limits agents install opencode`, `codex-limits agents install pi`, or `codex-limits agents install copilot`, 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.
|
|
262
287
|
|
|
263
288
|
## Documentation
|
|
264
289
|
|
|
265
|
-
The README
|
|
290
|
+
The [documentation hub](docs/README.md) routes CLI users, automation authors, agent users, and contributors to the appropriate canonical guide.
|
|
266
291
|
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
292
|
+
| Area | Canonical guide |
|
|
293
|
+
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
294
|
+
| CLI setup and commands | [Quick start](#quick-start) · [Usage](#usage) · [Troubleshooting](#troubleshooting) |
|
|
295
|
+
| Automation | [JSON output](docs/readme/json-output.md) · [JSON Schema](docs/schema/codex-limits.schema.json) · [Example document](docs/examples/codex-limits-output.example.json) |
|
|
296
|
+
| 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) |
|
|
297
|
+
| Runtime support | [Compatibility](docs/readme/compatibility.md) |
|
|
298
|
+
| Development and safety | [Contributing](CONTRIBUTING.md) · [Security](SECURITY.md) · [Changelog](CHANGELOG.md) |
|
|
270
299
|
|
|
271
300
|
## Local development
|
|
272
301
|
|
|
@@ -299,6 +328,7 @@ Useful development commands:
|
|
|
299
328
|
| ------------------------- | ----------------------------------------------- | --------------------------------- | -------------------------------------- |
|
|
300
329
|
| `codex-limits` | Recognized Codex state and bounded session data | Nothing | Live usage and coupon endpoints |
|
|
301
330
|
| `status` / `coupons` | Shared read-only core | Nothing | When live data is requested |
|
|
331
|
+
| `reset` | Current reset coupon list and Codex credentials | One selected remote coupon | Confirmed reset-credit consume request |
|
|
302
332
|
| `doctor` | Bounded Codex and agent configuration checks | Nothing | Live usage endpoint when authenticated |
|
|
303
333
|
| `agents install` / `init` | Selected agent configuration | Adds the integration registration | Does not send an LLM prompt |
|
|
304
334
|
|
package/SECURITY.md
CHANGED
|
@@ -8,11 +8,24 @@
|
|
|
8
8
|
|
|
9
9
|
<p align="center">
|
|
10
10
|
<img src="https://img.shields.io/badge/Security-private%20reporting-red" alt="Private security reporting" />
|
|
11
|
-
<img src="https://img.shields.io/badge/
|
|
11
|
+
<img src="https://img.shields.io/badge/Local%20data-read--only-blue" alt="Read-only local data access" />
|
|
12
12
|
<img src="https://img.shields.io/badge/Supported-latest%20release%20%7C%20main-brightgreen" alt="Supported versions: latest release and main" />
|
|
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
|
+
## Contents
|
|
19
|
+
|
|
20
|
+
- [Supported versions](#supported-versions)
|
|
21
|
+
- [Reporting a vulnerability](#reporting-a-vulnerability)
|
|
22
|
+
- [What to expect](#what-to-expect)
|
|
23
|
+
- [Local data and network behavior](#local-data-and-network-behavior)
|
|
24
|
+
- [What to report](#what-to-report)
|
|
25
|
+
- [Safety expectations](#safety-expectations)
|
|
26
|
+
- [Dependency and release security](#dependency-and-release-security)
|
|
27
|
+
- [Related documentation](#related-documentation)
|
|
28
|
+
|
|
16
29
|
## Supported versions
|
|
17
30
|
|
|
18
31
|
Security fixes are handled for the latest published version of `@simonesiega/codex-limits` and for the current `main` branch.
|
|
@@ -29,10 +42,10 @@ If you discover a vulnerability, a way to expose private Codex data, or a behavi
|
|
|
29
42
|
|
|
30
43
|
Report it privately using one of the following methods:
|
|
31
44
|
|
|
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)
|
|
45
|
+
| Contact | Value |
|
|
46
|
+
| ----------------------------------- | ---------------------------------------------------------------------------------------------- |
|
|
47
|
+
| GitHub private vulnerability report | [Submit a private report](https://github.com/simonesiega/codex-limits/security/advisories/new) |
|
|
48
|
+
| Email | [simonesiega1@gmail.com](mailto:simonesiega1@gmail.com) |
|
|
36
49
|
|
|
37
50
|
Do not include real access tokens, credentials, or unredacted private Codex files in the report. Use redacted examples whenever possible.
|
|
38
51
|
|
|
@@ -59,27 +72,29 @@ Please do not publicly disclose the vulnerability until a fix is available or di
|
|
|
59
72
|
|
|
60
73
|
## Local data and network behavior
|
|
61
74
|
|
|
62
|
-
`codex-limits` is designed to keep raw local Codex files and sensitive values on your machine. It makes authenticated requests to the
|
|
75
|
+
`codex-limits` is designed to keep raw local Codex files and sensitive values on your machine. It makes authenticated requests to the recognized ChatGPT Codex endpoints when retrieving live usage or reset-credit information, and only sends a reset-credit consume request after the user invokes and confirms `codex-limits reset`.
|
|
76
|
+
|
|
77
|
+
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. 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.
|
|
63
78
|
|
|
64
|
-
|
|
79
|
+
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. Authenticated requests reject redirects, use bounded timeouts and responses, and never include credential headers in diagnostics.
|
|
65
80
|
|
|
66
|
-
|
|
81
|
+
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.
|
|
67
82
|
|
|
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.
|
|
83
|
+
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. 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.
|
|
69
84
|
|
|
70
|
-
Agent installers use bounded
|
|
85
|
+
Agent installers use bounded 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. The Copilot installer copies the bounded extension bundle already present in the package, refuses to overwrite an unrecognized entry point, and does not install the SDK or another package.
|
|
71
86
|
|
|
72
|
-
The `codex-limits doctor` command exposes only package/runtime labels and bounded availability statuses. Its Codex, OpenCode, and
|
|
87
|
+
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.
|
|
73
88
|
|
|
74
89
|
### Command safety boundaries
|
|
75
90
|
|
|
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.
|
|
91
|
+
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. 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.
|
|
77
92
|
|
|
78
93
|
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.
|
|
79
94
|
|
|
80
95
|
## What to report
|
|
81
96
|
|
|
82
|
-
Please report any issue that could expose private data or
|
|
97
|
+
Please report any issue that could expose private data, write local Codex data, or consume a reset coupon without the documented confirmation flow.
|
|
83
98
|
|
|
84
99
|
Relevant examples include:
|
|
85
100
|
|
|
@@ -89,8 +104,10 @@ Relevant examples include:
|
|
|
89
104
|
- raw local Codex files being printed, logged, snapshotted, or committed;
|
|
90
105
|
- agent integrations exposing private Codex data inside the agent UI;
|
|
91
106
|
- unexpected writes to local Codex data;
|
|
92
|
-
-
|
|
93
|
-
-
|
|
107
|
+
- a reset coupon consumed without a positive interactive answer;
|
|
108
|
+
- duplicate coupon consumption after one confirmed action;
|
|
109
|
+
- unexpected network behavior related to usage, coupon discovery, or coupon redemption;
|
|
110
|
+
- unsafe handling of `CODEX_LIMITS_HOME`, `CODEX_LIMITS_ACCESS_TOKEN`, `CODEX_LIMITS_ACCOUNT_ID`, `CODEX_LIMITS_USAGE_ENDPOINT`, `PI_CODING_AGENT_DIR`, or `COPILOT_HOME`.
|
|
94
111
|
|
|
95
112
|
## Safety expectations
|
|
96
113
|
|
|
@@ -98,9 +115,28 @@ Relevant examples include:
|
|
|
98
115
|
|
|
99
116
|
The project should:
|
|
100
117
|
|
|
101
|
-
- remain read-only for local Codex data;
|
|
118
|
+
- remain read-only for local Codex data and read-only remote commands;
|
|
119
|
+
- isolate reset redemption behind the explicit remote-mutation confirmation flow;
|
|
102
120
|
- keep sensitive values out of CLI output, TUI output, JSON output, tests, logs, and screenshots;
|
|
103
121
|
- centralize data discovery, parsing, normalization, warnings, and redaction in the shared core;
|
|
104
122
|
- keep agent integrations thin and reuse the shared core instead of reimplementing security-sensitive parsing;
|
|
105
123
|
- use placeholders or redacted values in documentation, examples, and test fixtures;
|
|
106
124
|
- convert network, payload, authentication, and filesystem failures into deterministic safe warnings rather than raw exception messages.
|
|
125
|
+
|
|
126
|
+
## Dependency and release security
|
|
127
|
+
|
|
128
|
+
- Keep `bun.lock` committed and use frozen, script-disabled dependency installation in CI and publishing workflows.
|
|
129
|
+
- Keep third-party GitHub Actions pinned to immutable revisions and review automated updates before merging.
|
|
130
|
+
- Run `bun run check` before publishing; it rebuilds every bundle, validates generated declarations and notices, packs the npm artifact, and smoke-tests supported runtime surfaces.
|
|
131
|
+
- Publish only from a validated release tag whose version matches `package.json` and `src/package/version.ts`.
|
|
132
|
+
- Use npm Trusted Publishing with provenance rather than a long-lived npm token.
|
|
133
|
+
- Keep agent host SDKs external where the host owns them, and keep bundled third-party license notices synchronized with production artifacts.
|
|
134
|
+
- Do not publish from a dirty tree or bypass package validation, release-version checks, lifecycle-script restrictions, or provenance.
|
|
135
|
+
|
|
136
|
+
## Related documentation
|
|
137
|
+
|
|
138
|
+
- [Documentation hub](docs/README.md) — Task-oriented index for CLI, automation, agent, development, and security guides.
|
|
139
|
+
- [Compatibility](docs/readme/compatibility.md) — Supported runtimes, operating systems, Codex data, networks, terminals, and agent hosts.
|
|
140
|
+
- [JSON output](docs/readme/json-output.md) — Public machine-readable fields and deliberately omitted sensitive data.
|
|
141
|
+
- [Agent integrations](docs/readme/agent-integrations.md) — Shared adapter architecture, installation, and privacy guarantees.
|
|
142
|
+
- [Contributing](CONTRIBUTING.md) — Development workflow, safety rules, and review expectations.
|