@simonesiega/codex-limits 0.1.6 → 1.1.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 +47 -0
- package/CONTRIBUTING.md +226 -0
- package/README.md +92 -39
- package/SECURITY.md +52 -16
- package/dist/cli.js +153 -137
- 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 +128 -0
- package/docs/readme/agents/pi.md +143 -0
- package/docs/readme/compatibility.md +145 -0
- package/docs/readme/json-output.md +295 -0
- package/docs/schema/codex-limits.schema.json +183 -0
- package/package.json +23 -7
- package/types/copilot.d.ts +6 -0
- package/types/opencode.d.ts +10 -0
- package/types/pi.d.ts +4 -0
- package/dist/index.js +0 -5
- package/types/index.d.ts +0 -8
package/.env.example
CHANGED
package/CHANGELOG.md
CHANGED
|
@@ -16,6 +16,53 @@ All notable changes to codex-limits are documented in this file.
|
|
|
16
16
|
|
|
17
17
|
### Security
|
|
18
18
|
|
|
19
|
+
## [1.1.0] - 2026-07-31
|
|
20
|
+
|
|
21
|
+
### Added
|
|
22
|
+
|
|
23
|
+
- Added explicit OpenCode, pi, and GitHub Copilot CLI package subpath exports while keeping the package root dedicated to OpenCode loading and the internal core private.
|
|
24
|
+
|
|
25
|
+
### Changed
|
|
26
|
+
|
|
27
|
+
- Changed package safety messaging to distinguish read-only inspection commands from the explicitly confirmed `reset` remote mutation.
|
|
28
|
+
- Changed packed-runtime checks to validate the packed CLI on macOS with Node.js 22.
|
|
29
|
+
|
|
30
|
+
### Fixed
|
|
31
|
+
|
|
32
|
+
- Fixed packed-package validation for canonical temporary-directory paths on macOS.
|
|
33
|
+
- Fixed inconsistent reset-coupon counts to be reported as partial data instead of complete availability.
|
|
34
|
+
- Fixed agent summaries to label unknown usage percentages as unknown instead of displaying them as 0%.
|
|
35
|
+
|
|
36
|
+
### Security
|
|
37
|
+
|
|
38
|
+
- Kept usage endpoint metadata and coupon redemption identifiers outside the combined limits data supplied to read-only TUI and agent renderers, and enforced resolved-path containment for local state reads.
|
|
39
|
+
- Bounded pi integration filter matching against adversarial configuration patterns and updated the locked `brace-expansion` dependency to a non-vulnerable release.
|
|
40
|
+
|
|
41
|
+
## [1.0.0] - 2026-07-23
|
|
42
|
+
|
|
43
|
+
### Added
|
|
44
|
+
|
|
45
|
+
- Added `codex-limits reset` for consuming a numbered or soonest-expiring reset coupon after an interactive recap and explicit `y` confirmation.
|
|
46
|
+
- 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.
|
|
47
|
+
- Added a task-oriented documentation hub and included the complete guides, JSON Schema, and sanitized example in published npm packages.
|
|
48
|
+
- Added weekly Dependabot updates for the Bun dependency graph.
|
|
49
|
+
|
|
50
|
+
### Changed
|
|
51
|
+
|
|
52
|
+
- Changed the packaged OpenCode runtime entry point to the agent-specific `dist/opencode.js` bundle while preserving the package root plugin exports.
|
|
53
|
+
- Changed `codex-limits doctor` text output to align every diagnostic value with the longest integration label.
|
|
54
|
+
|
|
55
|
+
### Fixed
|
|
56
|
+
|
|
57
|
+
- Fixed local session fallback to select the newest bounded event timestamp when file modification times are misleading.
|
|
58
|
+
- Fixed combined dashboard loading to start independent usage and reset-coupon requests concurrently.
|
|
59
|
+
|
|
60
|
+
### Security
|
|
61
|
+
|
|
62
|
+
- 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.
|
|
63
|
+
- Prevented private Codex paths, free-form local reset text, and malformed coupon timestamp content from reaching public output.
|
|
64
|
+
- Required manual npm publishing runs to use the version tag matching the package metadata.
|
|
65
|
+
|
|
19
66
|
## [0.1.6] - 2026-07-22
|
|
20
67
|
|
|
21
68
|
### 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 | Add `src/package/<agent-name>.ts`, its host-only `./<agent-name>` subpath, and the shared 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
|
@@ -3,7 +3,11 @@
|
|
|
3
3
|
</h1>
|
|
4
4
|
|
|
5
5
|
<p align="center">
|
|
6
|
-
|
|
6
|
+
<strong>Monitor OpenAI Codex usage limits, reset times, and reset-credit coupons directly from your terminal.</strong>
|
|
7
|
+
</p>
|
|
8
|
+
|
|
9
|
+
<p align="center">
|
|
10
|
+
Every inspection command is read-only. Only <code>codex-limits reset</code> can modify remote state, and it always requires explicit interactive confirmation.
|
|
7
11
|
</p>
|
|
8
12
|
|
|
9
13
|
<p align="center">
|
|
@@ -16,7 +20,10 @@
|
|
|
16
20
|
|
|
17
21
|
<p align="center">
|
|
18
22
|
<img src="https://img.shields.io/npm/v/@simonesiega/codex-limits?label=npm" alt="npm version" />
|
|
19
|
-
<
|
|
23
|
+
<a href="https://www.npmjs.com/package/@simonesiega/codex-limits">
|
|
24
|
+
<img src="https://img.shields.io/npm/dm/@simonesiega/codex-limits?label=monthly%20downloads" alt="npm downloads in the last month"/>
|
|
25
|
+
</a>
|
|
26
|
+
<a href="https://github.com/simonesiega/codex-limits/actions/workflows/check.yml?query=branch%3Amain"><img src="https://img.shields.io/github/actions/workflow/status/simonesiega/codex-limits/check.yml?branch=main&label=tests" alt="Automated test status" /></a>
|
|
20
27
|
</p>
|
|
21
28
|
|
|
22
29
|
<p align="center">
|
|
@@ -46,6 +53,7 @@ The screenshots show the **`codex-limits`** terminal dashboards: clean, read-onl
|
|
|
46
53
|
- [Usage](#usage)
|
|
47
54
|
- [Troubleshooting](#troubleshooting)
|
|
48
55
|
- [Documentation](#documentation)
|
|
56
|
+
- [Documentation hub](docs/README.md)
|
|
49
57
|
- [JSON output](docs/readme/json-output.md)
|
|
50
58
|
- [Agent integrations](docs/readme/agent-integrations.md)
|
|
51
59
|
- [Compatibility](docs/readme/compatibility.md)
|
|
@@ -54,9 +62,6 @@ The screenshots show the **`codex-limits`** terminal dashboards: clean, read-onl
|
|
|
54
62
|
- [License](#license)
|
|
55
63
|
- [Contributors](#contributors)
|
|
56
64
|
|
|
57
|
-
> Last verified against: `@simonesiega/codex-limits` v0.1.6
|
|
58
|
-
> Verification date: 2026-07-22
|
|
59
|
-
|
|
60
65
|
## Quick start
|
|
61
66
|
|
|
62
67
|
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 +88,12 @@ Install an optional agent integration by name:
|
|
|
83
88
|
codex-limits agents install <agent-name>
|
|
84
89
|
```
|
|
85
90
|
|
|
86
|
-
For example, install the OpenCode or
|
|
91
|
+
For example, install the OpenCode, pi, or GitHub Copilot CLI integration:
|
|
87
92
|
|
|
88
93
|
```bash
|
|
89
94
|
codex-limits agents install opencode
|
|
90
95
|
codex-limits agents install pi
|
|
96
|
+
codex-limits agents install copilot
|
|
91
97
|
```
|
|
92
98
|
|
|
93
99
|
The existing `codex-limits init --<agent-name>` syntax remains supported as a compatibility command.
|
|
@@ -101,7 +107,7 @@ The existing `codex-limits init --<agent-name>` syntax remains supported as a co
|
|
|
101
107
|
| Operating systems | Windows, macOS, and Linux are supported through their standard Codex data locations. Use `CODEX_LIMITS_HOME` or `CODEX_HOME` if your data is stored elsewhere. |
|
|
102
108
|
| Internet connection | Local usage fallback can work offline. An internet connection is required for current live usage and reset-credit coupon information; unavailable network data is reported safely without breaking the dashboard. |
|
|
103
109
|
|
|
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.
|
|
110
|
+
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
111
|
|
|
106
112
|
## Overview
|
|
107
113
|
|
|
@@ -109,20 +115,21 @@ When you are working with Codex or agent-based coding tools, usage limits can in
|
|
|
109
115
|
|
|
110
116
|
**`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
117
|
|
|
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.
|
|
118
|
+
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
119
|
|
|
114
120
|
## Agent integrations
|
|
115
121
|
|
|
116
|
-
Optional integrations make Codex limit information available directly inside supported coding agents while reusing the same read
|
|
122
|
+
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
123
|
|
|
118
124
|
For installation details, adapter behavior, architecture, and contribution guidance, see the detailed [Agent integrations guide](docs/readme/agent-integrations.md).
|
|
119
125
|
|
|
120
126
|
### Supported agents
|
|
121
127
|
|
|
122
|
-
| Agent
|
|
123
|
-
|
|
|
124
|
-
| OpenCode
|
|
125
|
-
| pi
|
|
128
|
+
| Agent | Status | Agent command | Guide | Description |
|
|
129
|
+
| ------------------ | --------- | --------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
|
|
130
|
+
| 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. |
|
|
131
|
+
| 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. |
|
|
132
|
+
| 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
133
|
|
|
127
134
|
Agent integrations are not enabled automatically during package installation. They must be installed with `codex-limits agents install` (or the compatible `codex-limits init` syntax) and are only available in the agent terminal after a restart. See [Adding new agents](#adding-new-agents) if you want to add support for another agent.
|
|
128
135
|
|
|
@@ -144,9 +151,17 @@ The pi integration adds a `/codex-limits` command that opens a themed overlay in
|
|
|
144
151
|
<img src="docs/photos/agents/pi/pi_result.png" alt="pi codex-limits integration screenshot" width="740" />
|
|
145
152
|
</p>
|
|
146
153
|
|
|
154
|
+
#### GitHub Copilot CLI
|
|
155
|
+
|
|
156
|
+
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.
|
|
157
|
+
|
|
158
|
+
<p align="center">
|
|
159
|
+
<img src="docs/photos/agents/copilot/copilot_result.png" alt="GitHub Copilot CLI codex-limits integration screenshot" width="740" />
|
|
160
|
+
</p>
|
|
161
|
+
|
|
147
162
|
### Adding new agents
|
|
148
163
|
|
|
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.
|
|
164
|
+
New agents use the same four-file adapter layout under `src/agents/<agent-name>`: `format.ts`, `install.ts`, `integration.ts`, and `plugin.ts`. The integration descriptor owns its metadata, environment help, installer, and read-only diagnostic check; registering that descriptor in `src/agents/index.ts` automatically connects shared installation, compatibility help, and doctor diagnostics. Every registered agent must also use a matching `src/package/<agent-name>.ts` host wrapper and expose `@simonesiega/codex-limits/<agent-name>` through the shared package-entry build. Each integration should show Codex limit information quickly and safely without exposing tokens, account IDs, cookies, auth headers, or raw local files.
|
|
150
165
|
|
|
151
166
|
See the [Contributing](./CONTRIBUTING.md) guide if you want to add support for another agent.
|
|
152
167
|
|
|
@@ -154,16 +169,32 @@ See the [Contributing](./CONTRIBUTING.md) guide if you want to add support for a
|
|
|
154
169
|
|
|
155
170
|
**`codex-limits`** is built around a shared core with different output surfaces on top of it.
|
|
156
171
|
|
|
157
|
-
| Area | Path
|
|
158
|
-
| ------------------ |
|
|
159
|
-
| CLI entry | `src/package/cli.ts`
|
|
160
|
-
|
|
|
161
|
-
|
|
|
162
|
-
|
|
|
163
|
-
|
|
|
164
|
-
|
|
|
172
|
+
| Area | Path | Purpose |
|
|
173
|
+
| ------------------ | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
174
|
+
| CLI entry | `src/package/cli.ts` | Starts the `codex-limits` command and delegates to the shared command registry. |
|
|
175
|
+
| Agent host entries | `src/package/<agent-name>.ts` | Publish narrow, agent-specific host contracts through one shared package-entry build. |
|
|
176
|
+
| Core logic | `src/package/core` | Detects Codex data, normalizes live and local information, performs confirmed coupon redemption, and keeps sensitive values out of output. |
|
|
177
|
+
| CLI commands | `src/package/commands` | Defines command metadata, shared parsing and help, scoped runtime services, and focused command handlers. |
|
|
178
|
+
| Terminal UI | `src/package/tui` | Renders the clean Ink-based dashboard from normalized usage data. |
|
|
179
|
+
| Agent integrations | `src/agents` | Contains optional coding-agent adapters used by the `codex-limits agents` command group. |
|
|
180
|
+
| Tests | `tests` | Contains the test suite used to validate core behavior, CLI output, safety rules, and integration logic. |
|
|
181
|
+
|
|
182
|
+
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.
|
|
165
183
|
|
|
166
|
-
|
|
184
|
+
### Supported package interfaces
|
|
185
|
+
|
|
186
|
+
For general use and automation, the supported interfaces are the `codex-limits` CLI and its documented [JSON output](docs/readme/json-output.md). The package does not currently expose a general-purpose JavaScript API.
|
|
187
|
+
|
|
188
|
+
The npm module exports are reserved for supported agent hosts:
|
|
189
|
+
|
|
190
|
+
| Module specifier | Purpose |
|
|
191
|
+
| ------------------------------------ | ----------------------------------------------------------------------------------------- |
|
|
192
|
+
| `@simonesiega/codex-limits` | OpenCode plugin entry point retained at the package root for plugin-loader compatibility. |
|
|
193
|
+
| `@simonesiega/codex-limits/opencode` | Explicit alias for the same OpenCode plugin module. |
|
|
194
|
+
| `@simonesiega/codex-limits/pi` | Host-only entry point for the bundled pi extension. |
|
|
195
|
+
| `@simonesiega/codex-limits/copilot` | Host-only entry point for the bundled GitHub Copilot CLI extension. |
|
|
196
|
+
|
|
197
|
+
There is intentionally no `@simonesiega/codex-limits/core` export. Files under `src/package/core` are shared implementation details and are not covered by the package's public compatibility contract. The presence of an agent module export does not install or enable that integration; use `codex-limits agents install <agent-name>` for setup.
|
|
167
198
|
|
|
168
199
|
## Environment
|
|
169
200
|
|
|
@@ -180,10 +211,11 @@ Environment variables are only used as a fallback when automatic discovery is no
|
|
|
180
211
|
| `CODEX_LIMITS_USAGE_ENDPOINT` | Overrides the live usage endpoint with HTTPS or loopback HTTP for advanced setups/tests. |
|
|
181
212
|
| `CODEX_LIMITS_SKIP_INIT` | Suppresses optional global-install setup guidance from the non-interactive postinstall. |
|
|
182
213
|
| `PI_CODING_AGENT_DIR` | Overrides pi's global agent configuration directory for integration setup and checks. |
|
|
214
|
+
| `COPILOT_HOME` | Overrides GitHub Copilot CLI's user configuration and extension directory. |
|
|
183
215
|
|
|
184
216
|
### Data access and safety
|
|
185
217
|
|
|
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.
|
|
218
|
+
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
219
|
|
|
188
220
|
## Usage
|
|
189
221
|
|
|
@@ -193,6 +225,8 @@ Local Codex data is inspected read-only with bounded file, directory, JSONL, and
|
|
|
193
225
|
| `codex-limits status` | Prints a plain usage summary. |
|
|
194
226
|
| `codex-limits coupons` | Prints reset-credit coupon information. |
|
|
195
227
|
| `codex-limits coupons --json` | Prints machine-readable reset-credit coupon data only. |
|
|
228
|
+
| `codex-limits reset <coupon-index>` | Reviews and uses the numbered available reset coupon. |
|
|
229
|
+
| `codex-limits reset --soonest` | Reviews and uses the coupon that expires first. |
|
|
196
230
|
| `codex-limits --json` | Prints machine-readable usage and coupon data. |
|
|
197
231
|
| `codex-limits doctor` | Prints safe environment and connectivity diagnostics. |
|
|
198
232
|
| `codex-limits doctor --json` | Prints machine-readable diagnostics only. |
|
|
@@ -201,6 +235,19 @@ Local Codex data is inspected read-only with bounded file, directory, JSONL, and
|
|
|
201
235
|
| `codex-limits agents install --all` | Installs every supported agent integration. |
|
|
202
236
|
| `codex-limits init` | Runs the compatible interactive installation flow. |
|
|
203
237
|
|
|
238
|
+
### Resetting usage
|
|
239
|
+
|
|
240
|
+
Use one available reset coupon by the number shown in `codex-limits coupons`, or let the command select the available coupon that expires first:
|
|
241
|
+
|
|
242
|
+
```bash
|
|
243
|
+
codex-limits reset <coupon-index>
|
|
244
|
+
codex-limits reset --soonest
|
|
245
|
+
```
|
|
246
|
+
|
|
247
|
+
Reset is an irreversible remote mutation and works only in an interactive terminal. The command refreshes the coupon list, rejects missing or unavailable indexes, prints a recap with the selected coupon and expiration, and asks `Type y to confirm [y/N]`. Only `y` or `yes` sends the consume request; every other answer cancels without using a coupon. The request carries the coupon's internal service ID and a fresh idempotency key so an internal retry cannot consume a second coupon.
|
|
248
|
+
|
|
249
|
+
If no coupon is available, the command reports that nothing was used. If the selected index is absent, coupon details cannot be verified, or the final service result is ambiguous, it exits without claiming success.
|
|
250
|
+
|
|
204
251
|
### Diagnostics
|
|
205
252
|
|
|
206
253
|
Run the read-only doctor command when Codex data, live usage, or an agent integration is unavailable:
|
|
@@ -212,20 +259,21 @@ codex-limits doctor
|
|
|
212
259
|
```text
|
|
213
260
|
Codex Limits diagnostics
|
|
214
261
|
|
|
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:
|
|
262
|
+
Package version: 1.1.0
|
|
263
|
+
Node.js version: 22.0.0
|
|
264
|
+
Operating system: Windows
|
|
265
|
+
Codex home detected: Yes
|
|
266
|
+
Authentication found: Yes
|
|
267
|
+
Local usage found: Yes
|
|
268
|
+
Live endpoint: Reachable
|
|
269
|
+
OpenCode integration: Installed
|
|
270
|
+
pi integration: Installed
|
|
271
|
+
GitHub Copilot CLI integration: Installed
|
|
224
272
|
|
|
225
273
|
No sensitive values were displayed.
|
|
226
274
|
```
|
|
227
275
|
|
|
228
|
-
The doctor checks only whether recognized resources are available, including the OpenCode and
|
|
276
|
+
The doctor checks only whether recognized resources are available, including the OpenCode, pi, and GitHub Copilot CLI integrations. It never prints credential values, private paths, endpoint URLs, configuration contents, or raw Codex data. The live check makes the same bounded authenticated read-only usage request as the dashboard; it is reported as `Not checked` when complete authentication is unavailable. Use `codex-limits doctor --json` for the stable machine-readable form documented in [JSON output](docs/readme/json-output.md#doctor-document).
|
|
229
277
|
|
|
230
278
|
### Agent management
|
|
231
279
|
|
|
@@ -258,15 +306,19 @@ Confirm that your user can read the selected Codex directory and its session fil
|
|
|
258
306
|
|
|
259
307
|
### Agent command not appearing after installation
|
|
260
308
|
|
|
261
|
-
Run the named installer again, for example `codex-limits agents install opencode` or `codex-limits agents install
|
|
309
|
+
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
310
|
|
|
263
311
|
## Documentation
|
|
264
312
|
|
|
265
|
-
The README
|
|
313
|
+
The [documentation hub](docs/README.md) routes CLI users, automation authors, agent users, and contributors to the appropriate canonical guide.
|
|
266
314
|
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
315
|
+
| Area | Canonical guide |
|
|
316
|
+
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
317
|
+
| CLI setup and commands | [Quick start](#quick-start) · [Usage](#usage) · [Troubleshooting](#troubleshooting) |
|
|
318
|
+
| 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) |
|
|
319
|
+
| 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) |
|
|
320
|
+
| Runtime support | [Compatibility](docs/readme/compatibility.md) |
|
|
321
|
+
| Development and safety | [Contributing](CONTRIBUTING.md) · [Security](SECURITY.md) · [Changelog](CHANGELOG.md) |
|
|
270
322
|
|
|
271
323
|
## Local development
|
|
272
324
|
|
|
@@ -299,6 +351,7 @@ Useful development commands:
|
|
|
299
351
|
| ------------------------- | ----------------------------------------------- | --------------------------------- | -------------------------------------- |
|
|
300
352
|
| `codex-limits` | Recognized Codex state and bounded session data | Nothing | Live usage and coupon endpoints |
|
|
301
353
|
| `status` / `coupons` | Shared read-only core | Nothing | When live data is requested |
|
|
354
|
+
| `reset` | Current reset coupon list and Codex credentials | One selected remote coupon | Confirmed reset-credit consume request |
|
|
302
355
|
| `doctor` | Bounded Codex and agent configuration checks | Nothing | Live usage endpoint when authenticated |
|
|
303
356
|
| `agents install` / `init` | Selected agent configuration | Adds the integration registration | Does not send an LLM prompt |
|
|
304
357
|
|