@simonesiega/codex-limits 0.1.6 → 1.0.0

package/docs/readme/agents/copilot.md

@@ -0,0 +1,147 @@
+# GitHub Copilot CLI integration
+
+[← Documentation hub](../../README.md) · [Agent integrations](../agent-integrations.md) · [Project README](../../../README.md)
+
+The GitHub Copilot CLI integration adds a read-only `/codex-limits` extension command that loads the shared core locally and displays Codex usage windows, reset times, reset credits, and safe warnings without sending a prompt or limit data to the LLM.
+
+## Overview
+
+| Detail             | Value                                 |
+| ------------------ | ------------------------------------- |
+| Agent              | [GitHub Copilot CLI][copilot-cli]     |
+| Status             | Supported                             |
+| Agent command      | `/codex-limits`                       |
+| Install command    | `codex-limits agents install copilot` |
+| Installation scope | Global for the current user           |
+| Host API           | Experimental Copilot CLI extensions   |
+
+## Installation
+
+Install GitHub Copilot CLI and `codex-limits`, then run the named installer:
+
+```bash
+npm install -g @github/copilot@latest
+npm install -g @simonesiega/codex-limits@latest
+codex-limits agents install copilot
+```
+
+Other official Copilot CLI installation methods are documented in [Installing GitHub Copilot CLI][copilot-install]. The explicit agent name works in interactive and non-interactive terminals. The compatible `codex-limits init --copilot` form is also supported.
+
+Restart GitHub Copilot CLI after installation so it discovers the extension. Use Copilot CLI's `/extensions` command to review or re-enable extensions when extension loading is disabled in the host.
+
+### Extension file
+
+The installer writes one user-scoped extension entry point:
+
+```text
+~/.copilot/extensions/codex-limits/extension.mjs
+```
+
+When `COPILOT_HOME` is set, the installer uses `extensions/codex-limits/extension.mjs` under that directory instead. The `codex-limits` subdirectory gives the extension its host-visible name.
+
+The published package contains the bundled source at `dist/copilot.mjs`. The installer copies that bundle to the ESM `extension.mjs` entry point. GitHub Copilot CLI starts it as a separate Node.js process and supplies `@github/copilot-sdk/extension` through its extension module resolver; users do not install the SDK separately.
+
+The installer:
+
+- creates the dedicated extension directory when it is missing;
+- validates the package identity, bounded bundle, and stable extension marker before copying;
+- updates an older extension managed by `codex-limits` and leaves unrelated files in the directory unchanged;
+- reports `already installed` when the installed bundle is current;
+- writes through an owner-only sibling temporary file to avoid a partial entry point;
+- refuses to overwrite an existing entry point that is not marked as the Codex Limits extension;
+- refuses a competing `extension.cjs` or `extension.js` entry point in the dedicated directory;
+- refuses symbolic-link, non-file, unreadable, or oversized entry points.
+
+Extension and package manifest reads are bounded. Extension files larger than 5 MB are not modified. Installation output shortens paths under the user home to `~/...` and displays unexpected paths outside it as `[path]`.
+
+## Using `/codex-limits`
+
+Start a new interactive Copilot CLI session, then invoke:
+
+```text
+/codex-limits
+```
+
+> [!IMPORTANT]
+> Run the command only inside Copilot CLI's interactive interface. Do not use `copilot -p "/codex-limits"`; prompt mode can treat that text as an LLM prompt instead of dispatching the extension command.
+
+The extension logs a compact limits summary directly to the Copilot CLI timeline, including:
+
+- remaining capacity and status for the weekly window;
+- the 5-hour window when supplied by Codex;
+- compact progress bars and reset durations;
+- available reset credits and the next expiration;
+- safe warnings when some data is unavailable.
+
+The slash-command handler calls the shared local core directly. It does not call `session.send()`, create a user message, or ask the model to process the request. Loading and timeline failures are reduced to static safe messages instead of exposing raw filesystem, credential, or network details.
+
+## Compatibility
+
+Copilot CLI extensions are an experimental host feature and may change. The bundled ESM entry point follows the current extension contract:
+
+- it is installed as `extension.mjs` in an immediate child of the user extensions directory;
+- it imports the CLI-provided SDK from `@github/copilot-sdk/extension`;
+- it calls `joinSession()` and registers `codex-limits` through the session `commands` option;
+- it uses `session.log()` for timeline output because extension standard output is reserved for JSON-RPC.
+
+The adapter is type-checked against `@github/copilot-sdk` 1.0.8. Automated tests mock command registration, timeline output, safe failures, and installation behavior, while packed-package validation confirms that the bundled artifact is shipped and copied to the correct user extension path. The repository does not currently claim terminal-level validation against an exact Copilot CLI release.
+
+Keep GitHub Copilot CLI current when using the integration. See the general [Compatibility guide](../compatibility.md) and the SDK's [extension documentation][copilot-extension-docs] for the evolving host contract.
+
+## Re-running or removing the integration
+
+Running `codex-limits agents install copilot` again is safe. It reports `already installed` when the installed entry point matches the current package and replaces only a previously managed older bundle.
+
+There is no `codex-limits` uninstall command. To remove the integration, delete only this dedicated directory, then restart Copilot CLI:
+
+```text
+~/.copilot/extensions/codex-limits
+```
+
+Use the equivalent path under `COPILOT_HOME` when that variable is set. Do not remove unrelated Copilot configuration or extension directories.
+
+## Troubleshooting
+
+### The command does not appear
+
+1. Run `codex-limits agents install copilot` again.
+2. Confirm that it reports `extension.mjs` as installed or already installed.
+3. Restart GitHub Copilot CLI completely.
+4. Run `/extensions` and confirm that `codex-limits` is discovered and enabled.
+5. Check that a project-local `.github/extensions/codex-limits/extension.mjs` is not shadowing the user extension with the same name.
+6. Update Copilot CLI if the installed release does not support experimental extensions and session commands.
+
+### The extension path is already in use
+
+The installer found an `extension.mjs` that is not marked as a bundle managed by `codex-limits`, or it found a competing `extension.cjs` or `extension.js`, so it left the directory unchanged. Review the dedicated `codex-limits` extension directory manually. Move or remove only the conflicting entry point if you are certain it is unrelated, then run the installer again.
+
+### The integration bundle is unavailable
+
+Reinstall or rebuild `@simonesiega/codex-limits`, then run the installer again. Published packages include `dist/copilot.mjs`; source checkouts create it with `bun run build`.
+
+### Limits cannot be loaded
+
+Run `codex-limits doctor` and `codex-limits status` outside Copilot CLI. If data is also unavailable there, verify Codex authentication, local data discovery, and network access.
+
+## Data and privacy
+
+The integration follows the safety guarantees defined for [all agent integrations](../agent-integrations.md#data-and-privacy). It does not send a prompt or Codex limit data to the LLM, and displayed output excludes sensitive credentials, private paths, and raw local data.
+
+Copilot CLI extensions execute as separate processes with the current user's system permissions. Install only extensions you trust. The Codex Limits extension registers one read-only slash command and does not register tools, hooks, or account-mutation behavior.
+
+## Related documentation
+
+- [Agent integrations](../agent-integrations.md) — Supported-agent index and behavior shared by every adapter.
+- [Compatibility](../compatibility.md) — Runtime, operating-system, terminal, network, and agent compatibility.
+- [JSON output](../json-output.md) — Machine-readable output, fields, warnings, and scripting behavior.
+- [Security policy](../../../SECURITY.md) — Local-data safeguards, network behavior, and vulnerability reporting.
+- [GitHub Copilot CLI][copilot-cli] — Official CLI repository.
+- [Copilot CLI documentation][copilot-docs] — Official concepts and usage documentation.
+- [Copilot SDK extension documentation][copilot-extension-docs] — Current experimental extension lifecycle and API.
+- [Documentation hub](../../README.md) — Task-oriented index for CLI, automation, agent, development, and security guides.
+- [Project README](../../../README.md) — Product overview, installation, commands, configuration, and troubleshooting.
+
+[copilot-cli]: https://github.com/github/copilot-cli
+[copilot-docs]: https://docs.github.com/en/copilot/concepts/agents/about-copilot-cli
+[copilot-install]: https://docs.github.com/en/copilot/how-tos/copilot-cli/set-up-copilot-cli/install-copilot-cli
+[copilot-extension-docs]: https://github.com/github/copilot-sdk/blob/main/nodejs/docs/extensions.md

package/docs/readme/agents/opencode.md

@@ -0,0 +1,126 @@
+# OpenCode integration
+
+[← Documentation hub](../../README.md) · [Agent integrations](../agent-integrations.md) · [Project README](../../../README.md)
+
+The OpenCode integration adds a read-only `/codex-limits` command that loads the shared core locally and displays Codex usage windows, reset times, reset credits, and safe warnings without sending a prompt to an LLM.
+
+## Overview
+
+| Detail             | Value                                  |
+| ------------------ | -------------------------------------- |
+| Agent              | [OpenCode](https://opencode.ai/)       |
+| Status             | Supported                              |
+| Agent command      | `/codex-limits`                        |
+| Install command    | `codex-limits agents install opencode` |
+| Installation scope | Global for the current user            |
+
+## Installation
+
+Install the CLI globally, then run the named installer:
+
+```bash
+npm install -g @simonesiega/codex-limits@latest
+codex-limits agents install opencode
+```
+
+The explicit agent name works in interactive and non-interactive terminals. The compatible `codex-limits init --opencode` form remains supported. Restart OpenCode after installation so it reloads its configuration.
+
+### Configuration files
+
+The installer updates both of these global configuration files for the current user:
+
+```text
+~/.config/opencode/opencode.json
+~/.config/opencode/tui.json
+```
+
+It adds the following package to each file's `plugin` array:
+
+```json
+"@simonesiega/codex-limits"
+```
+
+Both files are updated because compatible OpenCode versions discover TUI plugins through different global configuration files. The installer:
+
+- creates a missing configuration as a JSON object with the appropriate OpenCode schema;
+- preserves existing configuration fields and plugin entries;
+- recognizes unversioned, tagged, pinned, and tuple forms of the package and does not add duplicates;
+- writes changed files through a sibling temporary file to avoid partial JSON;
+- refuses symbolic-link configuration files instead of following or replacing the link;
+- refuses to modify malformed, non-object, oversized, or invalid `plugin` configurations.
+
+Configuration files larger than 1 MB are not modified. If one file is already configured and the other is not, only the missing plugin registration is added. Installation results shorten paths under the user home to `~/...`; unexpected paths outside the home are displayed as `[path]`.
+
+## Using `/codex-limits`
+
+Restart OpenCode after installation, then run:
+
+```text
+/codex-limits
+```
+
+<p align="center">
+  <img
+    src="../../photos/agents/opencode/opencode_result.png"
+    alt="Codex Limits modal running inside OpenCode"
+    width="740"
+  />
+</p>
+
+OpenCode opens a modal dialog, loads the shared core directly, and displays:
+
+- remaining capacity and status for the weekly window;
+- the 5-hour window when it is supplied by the usage service;
+- reset durations;
+- available reset credits and the next expiration;
+- safe warnings when some data is unavailable.
+
+Loading failures are reduced to a static safe error instead of exposing raw filesystem, credential, or network details.
+
+## Compatibility
+
+The adapter supports OpenCode hosts that expose either:
+
+- the current keymap layer registration API; or
+- the legacy command registration API.
+
+Compatibility is determined from the API shape available at runtime rather than from a list of exact OpenCode versions. Automated adapter tests use host mocks for both supported API shapes; the repository does not currently claim end-to-end validation against named OpenCode releases.
+
+See the general [Compatibility guide](../compatibility.md) for tested runtimes, operating systems, terminals, and network behavior.
+
+## Re-running or removing the integration
+
+Running `codex-limits agents install opencode` again is safe. It reports `already installed` when both configuration files already contain the package.
+
+There is no uninstall command. To remove the integration, delete every `@simonesiega/codex-limits` entry from the `plugin` arrays in both OpenCode configuration files, then restart OpenCode. Do not remove unrelated plugins or configuration fields.
+
+## Troubleshooting
+
+### The command does not appear
+
+1. Run `codex-limits agents install opencode` again.
+2. Confirm that the reported paths are the OpenCode configuration files used by your installation.
+3. Restart OpenCode completely.
+4. Check that both files contain a JSON `plugin` array with `@simonesiega/codex-limits`.
+
+### Setup reports invalid JSON
+
+Correct the affected OpenCode configuration before running the installer again. The installer intentionally does not overwrite malformed JSON or replace a non-array `plugin` field.
+
+### Limits cannot be loaded
+
+Run `codex-limits status` outside OpenCode. If data is also unavailable there, verify Codex authentication, local data discovery, and network access.
+
+## Data and privacy
+
+The integration follows the safety guarantees defined for [all agent integrations](../agent-integrations.md#data-and-privacy). It does not send a prompt or Codex limit data to an LLM, and displayed output excludes sensitive credentials and raw local data.
+
+## Related documentation
+
+- [Agent integrations](../agent-integrations.md) — Supported-agent index and behavior shared by every adapter.
+- [Compatibility](../compatibility.md) — Runtime, operating-system, terminal, network, and agent compatibility.
+- [JSON output](../json-output.md) — Machine-readable output, fields, warnings, and scripting behavior.
+- [Security policy](../../../SECURITY.md) — Local-data safeguards, network behavior, and vulnerability reporting.
+- [OpenCode](https://opencode.ai/) — Official agent website.
+- [Documentation hub](../../README.md) — Task-oriented index for CLI, automation, agent, development, and security guides.
+- [Project README](../../../README.md) — Product overview, installation, commands, configuration, and troubleshooting.

package/docs/readme/agents/pi.md

@@ -0,0 +1,143 @@
+# pi integration
+
+[← Documentation hub](../../README.md) · [Agent integrations](../agent-integrations.md) · [Project README](../../../README.md)
+
+The pi integration adds a read-only `/codex-limits` extension command that loads the shared core locally and displays Codex usage windows, reset times, reset credits, and safe warnings without sending a prompt to an LLM.
+
+## Overview
+
+| Detail             | Value                            |
+| ------------------ | -------------------------------- |
+| Agent              | [pi](https://pi.dev/)            |
+| Status             | Supported                        |
+| Agent command      | `/codex-limits`                  |
+| Install command    | `codex-limits agents install pi` |
+| Installation scope | Global for the current user      |
+
+## Installation
+
+Install the CLI and pi, then run the named installer:
+
+```bash
+npm install -g @simonesiega/codex-limits@latest
+npm install -g @earendil-works/pi-coding-agent@latest
+codex-limits agents install pi
+```
+
+The explicit agent name works in interactive and non-interactive terminals. The compatible `codex-limits init --pi` form is also supported. Restart pi after installation so it reloads its extensions. An already-running pi session can use `/reload` instead.
+
+### Configuration
+
+The installer updates pi's global settings file:
+
+```text
+~/.pi/agent/settings.json
+```
+
+When `PI_CODING_AGENT_DIR` is set, the installer uses `settings.json` under that directory instead. It adds the current Codex Limits package root to the `packages` array. The published package declares this pi manifest:
+
+```json
+{
+  "pi": {
+    "extensions": ["./dist/pi.js"]
+  }
+}
+```
+
+Registering the local package root avoids another download and keeps the extension synchronized with the globally installed `codex-limits` package. The installer also recognizes existing unversioned, tagged, or pinned `npm:@simonesiega/codex-limits` pi package registrations. If a matching object registration filters out the bundled extension, the named installer force-enables only `dist/pi.js` while preserving unrelated resource filters.
+
+The installer:
+
+- creates a missing settings file as a JSON object;
+- preserves unrelated settings and package registrations;
+- avoids duplicate local and npm package registrations;
+- verifies that the package manifest declares the bundled `dist/pi.js` extension and that the bundle is available;
+- writes changes through an owner-only sibling temporary file to avoid partial JSON;
+- refuses symbolic-link, malformed, non-object, oversized, or invalid `packages` settings.
+
+Settings files larger than 1 MB are not modified. Installation output shortens paths under the user home to `~/...` and displays unexpected paths outside it as `[path]`.
+
+Pi's native package command is also supported because the npm package includes the pi manifest:
+
+```bash
+pi install npm:@simonesiega/codex-limits
+```
+
+Use either installation method rather than registering the package twice.
+
+## Using `/codex-limits`
+
+Restart pi or run `/reload`, then invoke:
+
+```text
+/codex-limits
+```
+
+The extension loads the shared core directly and opens a themed overlay containing:
+
+- remaining capacity and status for the weekly window;
+- the 5-hour window when supplied by Codex;
+- compact progress bars and reset durations;
+- available reset credits and the next expiration;
+- safe warnings when some data is unavailable.
+
+Press Enter, Escape, or Ctrl+C to close the overlay. While data loads, the extension shows a temporary footer status. Loading and display failures are reduced to static safe messages instead of exposing raw filesystem, credential, or network details.
+
+The command is interactive-TUI-only. In pi RPC, print, and JSON modes, it performs no lookup and sends no message to the model.
+
+## Compatibility
+
+The adapter uses pi's extension APIs for command registration, footer status, notifications, and custom overlays. It is developed against `@earendil-works/pi-coding-agent` and `@earendil-works/pi-tui` 0.81.x. Those host packages are optional peers and are not bundled into `codex-limits`.
+
+Pi 0.81.x requires Node.js 22.19 or newer. This requirement applies to the pi host; the standalone `codex-limits` CLI continues to support Node.js 20 or newer. Automated tests use extension-host mocks and the real pi TUI component classes. Local validation also confirmed package discovery and command interception with pi 0.81.1 in print mode, without invoking the model; the interactive overlay is not terminal-tested against every pi release.
+
+See the general [Compatibility guide](../compatibility.md) for tested runtimes, operating systems, terminals, and network behavior.
+
+## Re-running or removing the integration
+
+Running `codex-limits agents install pi` again is safe. It reports `already installed` when the matching local or npm package registration is already enabled.
+
+There is no `codex-limits` uninstall command. To remove an integration installed by the named installer, delete only the Codex Limits package entry from the global pi `packages` array, then restart pi or run `/reload`. If it was installed with pi's native package manager, use:
+
+```bash
+pi remove npm:@simonesiega/codex-limits
+```
+
+Do not remove unrelated pi packages or settings.
+
+## Troubleshooting
+
+### The command does not appear
+
+1. Run `codex-limits agents install pi` again.
+2. Confirm that it reports the pi settings file as installed or already installed.
+3. Restart pi or run `/reload`.
+4. Check that the global `packages` array contains the Codex Limits local package path or `npm:@simonesiega/codex-limits`.
+
+### Setup reports invalid JSON
+
+Correct the affected pi settings before running the installer again. The installer intentionally does not overwrite malformed JSON or replace an invalid `packages` field.
+
+### The integration bundle is unavailable
+
+Reinstall or rebuild `@simonesiega/codex-limits`, then run the installer again. Published packages include `dist/pi.js`; source checkouts create it with `bun run build`.
+
+### Limits cannot be loaded
+
+Run `codex-limits doctor` and `codex-limits status` outside pi. If data is also unavailable there, verify Codex authentication, local data discovery, and network access.
+
+## Data and privacy
+
+The integration follows the safety guarantees defined for [all agent integrations](../agent-integrations.md#data-and-privacy). It does not send a prompt or Codex limit data to an LLM, and displayed output excludes sensitive credentials, private paths, and raw local data.
+
+Pi extensions execute with the current user's system permissions. Install only packages you trust, as described in pi's own extension security guidance.
+
+## Related documentation
+
+- [Agent integrations](../agent-integrations.md) — Supported-agent index and behavior shared by every adapter.
+- [Compatibility](../compatibility.md) — Runtime, operating-system, terminal, network, and agent compatibility.
+- [JSON output](../json-output.md) — Machine-readable output, fields, warnings, and scripting behavior.
+- [Security policy](../../../SECURITY.md) — Local-data safeguards, network behavior, and vulnerability reporting.
+- [pi](https://pi.dev/) — Official agent website.
+- [Documentation hub](../../README.md) — Task-oriented index for CLI, automation, agent, development, and security guides.
+- [Project README](../../../README.md) — Product overview, installation, commands, configuration, and troubleshooting.

package/docs/readme/compatibility.md

@@ -0,0 +1,143 @@
+# Compatibility
+
+[← Documentation hub](../README.md) · [Project README](../../README.md)
+
+This page describes the runtime, operating-system, Codex data, network, terminal, and agent compatibility implemented by the current codebase.
+
+## Runtime and installation
+
+| Environment         | Support                                                 |
+| ------------------- | ------------------------------------------------------- |
+| Published CLI       | Node.js 20 or newer                                     |
+| Package format      | ESM, bundled for Node.js                                |
+| Global installation | npm (`npm install -g @simonesiega/codex-limits@latest`) |
+| Source development  | Bun 1.3.14, as declared in `package.json`               |
+| TypeScript target   | ES2022                                                  |
+
+Bun is used for dependency management, tests, development commands, and production builds. It is not required to run the published CLI. Runtime dependencies are bundled into `dist`, so the published package does not declare separate production dependencies.
+
+The root package module resolves to the agent-specific `dist/opencode.js` bundle for the OpenCode plugin loader. Its public module contract consists of a default plugin export and the named `tui` export; the internal core modules are not public package exports. Pi loads the separate `dist/pi.js` extension declared in the package's `pi.extensions` manifest. The GitHub Copilot CLI installer copies the separate `dist/copilot.mjs` bundle to a recognized user extension entry point.
+
+## Tested environments
+
+The following environments are covered by the repository's automated checks or current local validation. Other compatible environments may also work, but they are not tested for every release.
+
+| Area                   | Tested environments                                                                                                |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| Automated packaged CLI | GitHub Actions on `ubuntu-latest` with Node.js 20, 22, and 24, plus `windows-latest` with Node.js 20               |
+| Current local checks   | Windows build `10.0.26200.8875` with Node.js 22.20.0 and Bun 1.3.14 (verified 2026-07-23)                          |
+| Terminal rendering     | Automated Ink rendering and layout tests; no named terminal application is included in the per-release test matrix |
+| OpenCode agent adapter | Mocked current keymap and legacy command API shapes; no exact OpenCode host release is tested end-to-end           |
+| pi agent adapter       | Mocked command/UI APIs with real TUI components; package discovery validated in pi 0.81.1 print mode               |
+| Copilot CLI adapter    | Mocked SDK command/timeline APIs and packed installation; typed against `@github/copilot-sdk` 1.0.8                |
+
+The supported runtime and operating-system ranges are broader than this test matrix. In particular, macOS compatibility follows the cross-platform implementation but is not currently covered by the repository's automated workflow.
+
+## Operating systems
+
+The CLI supports Windows, macOS, and Linux through Node's cross-platform filesystem and path APIs.
+
+Codex home candidates are checked in this order, skipping missing or unreadable directories and removing duplicates:
+
+1. `CODEX_LIMITS_HOME`
+2. `CODEX_HOME`
+3. `~/.codex`
+4. `~/.config/codex`
+5. `~/Library/Application Support/Codex`
+6. `~/Library/Application Support/Parall/Codex/.codex`
+7. `%APPDATA%/Codex`, when `APPDATA` is available
+8. `%LOCALAPPDATA%/Codex`, when `LOCALAPPDATA` is available
+
+The `Parall` spelling in candidate 6 matches the constant in `src/package/core/codex/paths.ts` and is covered by the path-generation test. This verifies that the documentation matches the current implementation; it does not claim that every macOS Codex installation uses that directory.
+
+`CODEX_LIMITS_HOME` has the highest priority. `CODEX_HOME` is Codex's native override and is used next. Override values must identify readable directories; files and unreadable paths are ignored.
+
+The default home directory is resolved from `HOME`, then `USERPROFILE`, then the operating system's home-directory API.
+
+## Codex data compatibility
+
+For normal use, Codex must have been installed, run, and authenticated at least once. The CLI can use:
+
+- live weekly usage and, when supplied, 5-hour usage from the ChatGPT Codex usage endpoint;
+- bounded local `sessions/**/rollout-*.jsonl` data as a usage fallback;
+- recognized bounded JSON state files as an additional local fallback;
+- `auth.json` in the detected Codex home for live request credentials;
+- the paired `CODEX_LIMITS_ACCESS_TOKEN` and `CODEX_LIMITS_ACCOUNT_ID` variables when automatic credential discovery is unavailable.
+
+Both credential environment variables are required together. Supplying only one produces an incomplete-authentication warning and does not initiate an authenticated request.
+
+Local Codex data is inspected read-only. File traversal, file counts, file sizes, JSONL line sizes, search depth, and response sizes are bounded. Nested symbolic links are skipped. Filesystem warnings do not include relative or absolute Codex paths, and fallback reset-duration strings must use compact duration units before they are normalized. Raw local files, tokens, account IDs, authorization headers, and private paths are excluded from public output.
+
+Local state layouts can vary between Codex versions. The parser recognizes common primary/five-hour and secondary/weekly window names and can return partial data when only some fields are understood. For live responses, declared window durations such as `limit_window_seconds` take precedence over legacy primary/secondary slot names, because the usage service can now return weekly usage in `primary_window` without a 5-hour window.
+
+## Network compatibility
+
+Live data uses these defaults:
+
+| Data                 | Endpoint                                                                | Offline behavior                    |
+| -------------------- | ----------------------------------------------------------------------- | ----------------------------------- |
+| Usage windows        | `https://chatgpt.com/backend-api/codex/usage`                           | Falls back to recognized local data |
+| Reset-credit coupons | `https://chatgpt.com/backend-api/wham/rate-limit-reset-credits`         | Reported as unavailable             |
+| Coupon redemption    | `https://chatgpt.com/backend-api/wham/rate-limit-reset-credits/consume` | Never attempted automatically       |
+
+These endpoints are implementation details rather than a public API contract and may change when Codex changes its service behavior. A response containing only a recognized weekly window is treated as valid live usage; local discovery is used only when the live response contains no recognized usage window.
+
+Requests are authenticated from Codex credentials, reject redirects, time out after 10 seconds by default, and limit JSON responses to 1 MB. Independent usage and coupon lookups start concurrently. The transport uses the runtime's `fetch` implementation and can fall back to native Node HTTP/HTTPS transport for supported failures. Coupon timestamps must be bounded RFC 3339 values. Coupon redemption accepts only an exact coupon ID with the recognized `codex_rate_limits` type. `--soonest` refuses partial or count-inconsistent coupon data and any available coupon whose expiration cannot be verified. Its bounded JSON `POST` uses a fresh idempotency key for each confirmed redemption and reuses that key for any transport fallback.
+
+`CODEX_LIMITS_USAGE_ENDPOINT` can override only the live usage endpoint. Overrides must use HTTPS. Plain HTTP is accepted only for loopback testing on `localhost`, `127.0.0.1`, or `::1`. URLs containing embedded usernames or passwords and all other protocols are rejected.
+
+An internet connection is therefore recommended for current usage and required for coupon data. The CLI remains usable offline when compatible local usage snapshots exist.
+
+## Terminal and automation compatibility
+
+| Surface                        | Requirement                                                |
+| ------------------------------ | ---------------------------------------------------------- |
+| Interactive dashboard          | A terminal capable of running the Ink UI                   |
+| `status` and `coupons`         | Any environment that can capture standard output           |
+| JSON output                    | Any environment that can capture and parse standard output |
+| Reset coupon redemption        | Both standard input and standard output must be TTYs       |
+| Interactive agent installation | Both standard input and standard output must be TTYs       |
+| Explicit agent installation    | Works non-interactively with an agent name or `--all`      |
+
+Use [`codex-limits --json`](json-output.md) or `codex-limits coupons --json` in scripts. Errors use a non-zero exit code and are written to standard error; successful machine-readable output is written to standard output. `codex-limits reset` is intentionally interactive and has no JSON or unattended confirmation mode.
+
+## OpenCode compatibility
+
+Install the OpenCode integration with `codex-limits agents install opencode` (or the compatible `codex-limits init --opencode` form). The integration writes to both `~/.config/opencode/opencode.json` and `~/.config/opencode/tui.json`. It supports OpenCode hosts that expose either:
+
+- the current keymap layer registration API; or
+- the legacy command registration API.
+
+Compatibility is determined from the API shape available at runtime rather than from a list of exact OpenCode versions. Automated adapter tests use host mocks for both supported API shapes; the repository does not currently claim end-to-end validation against named OpenCode releases.
+
+The command is `/codex-limits`. It loads the shared core locally and does not send an LLM prompt. See [Agent integrations](agent-integrations.md) for installation and troubleshooting.
+
+## pi compatibility
+
+Install the pi integration with `codex-limits agents install pi` (or the compatible `codex-limits init --pi` form). The installer registers the current package root in `~/.pi/agent/settings.json`, or in the directory selected by `PI_CODING_AGENT_DIR`. The npm package also supports pi's native `pi install npm:@simonesiega/codex-limits` flow through its extension manifest.
+
+The extension uses pi's command registration and custom overlay APIs. It is developed against `@earendil-works/pi-coding-agent` and `@earendil-works/pi-tui` 0.81.x, which require Node.js 22.19 or newer. These packages are optional peers and are supplied by the pi host rather than bundled into the extension. This does not change the standalone CLI's Node.js 20 requirement. Local validation confirmed that pi 0.81.1 discovers the installed package and handles `/codex-limits` without invoking the model in print mode; the interactive overlay is covered with host mocks and real TUI components rather than a terminal-level end-to-end test.
+
+The `/codex-limits` command loads the shared core locally, opens a themed read-only overlay, and never sends a prompt or limit data to the LLM. Outside pi's interactive TUI it skips loading and sends no message to the model. See the dedicated [pi integration guide](agents/pi.md) for installation, removal, and troubleshooting.
+
+## GitHub Copilot CLI compatibility
+
+Install the GitHub Copilot CLI integration with `codex-limits agents install copilot` (or the compatible `codex-limits init --copilot` form). The installer copies the bundled ESM extension to `~/.copilot/extensions/codex-limits/extension.mjs`, or beneath the directory selected by `COPILOT_HOME`.
+
+The integration uses Copilot CLI's experimental extension mechanism. Copilot starts the extension in a separate Node.js process, supplies `@github/copilot-sdk/extension` through its module resolver, and communicates over JSON-RPC on standard input and output. The bundle calls `joinSession()`, registers `/codex-limits` through session commands, and uses `session.log()` for the compact timeline output. It does not call `session.send()` or add the request or result to the model conversation.
+
+The adapter is type-checked against `@github/copilot-sdk` 1.0.8. Automated tests use host mocks for registration, timeline output, static safe failures, and installer behavior. Package validation confirms that `dist/copilot.mjs` retains only the CLI-provided SDK as an external host import and is copied to the expected user extension path. No exact Copilot CLI release is currently tested end-to-end, and the experimental API may change. The current npm installation of Copilot CLI requires Node.js 22 or newer; other official installation methods package the host separately.
+
+See the dedicated [GitHub Copilot CLI integration guide](agents/copilot.md) for installation, removal, host details, and troubleshooting.
+
+## Support policy
+
+The latest npm release is supported. The current `main` branch is supported for unreleased fixes, while older releases receive best-effort support. See the [Security policy](../../SECURITY.md#supported-versions) for security support details.
+
+## Related documentation
+
+- [JSON output](json-output.md) — Machine-readable output, fields, warnings, and scripting behavior.
+- [Agent integrations](agent-integrations.md) — Installation, architecture, compatibility, and troubleshooting for agent adapters.
+- [Security policy](../../SECURITY.md) — Data-access safeguards, network behavior, and vulnerability reporting.
+- [Documentation hub](../README.md) — Task-oriented index for CLI, automation, agent, development, and security guides.
+- [Project README](../../README.md) — Product overview, installation, commands, configuration, and troubleshooting.