@simonesiega/codex-limits 0.1.5 → 0.1.6

package/.env.example

@@ -16,3 +16,6 @@ CODEX_LIMITS_USAGE_ENDPOINT=
 
 # Optional: suppress global-install guidance from the non-interactive postinstall script.
 CODEX_LIMITS_SKIP_INIT=
+
+# Optional: override pi's global agent configuration directory for integration setup.
+PI_CODING_AGENT_DIR=

package/CHANGELOG.md

@@ -16,6 +16,23 @@ All notable changes to codex-limits are documented in this file.
 
 ### Security
 
+## [0.1.6] - 2026-07-22
+
+### Breaking Changes
+
+### Added
+
+- Added `codex-limits doctor` and `codex-limits doctor --json` for safe environment, connectivity, local usage, authentication, OpenCode, and pi integration diagnostics.
+- Added the pi agent integration with `codex-limits agents install pi` and a read-only `/codex-limits` overlay that does not send limit data to the LLM.
+
+### Changed
+
+### Fixed
+
+### Removed
+
+### Security
+
 ## [0.1.5] - 2026-07-22
 
 ### Breaking Changes

package/README.md

@@ -16,13 +16,13 @@
 
 <p align="center">
   <img src="https://img.shields.io/npm/v/@simonesiega/codex-limits?label=npm" alt="npm version" />
-  <img src="https://img.shields.io/badge/TypeScript-5-blue?logo=typescript" alt="TypeScript" />
-  <img src="https://img.shields.io/badge/Bun-toolchain-black?logo=bun" alt="Bun toolchain" />
+  <img src="https://img.shields.io/badge/test_coverage-96.3%25_lines-brightgreen" alt="Test coverage: 96.3% lines" />
 </p>
 
 <p align="center">
   <a href="#local-development">
-    <img src="https://img.shields.io/badge/test_coverage-95.9%25_lines-brightgreen" alt="Test coverage: 95.9% lines" />
+    <img src="https://img.shields.io/badge/TypeScript-5-blue?logo=typescript" alt="TypeScript" />
+    <img src="https://img.shields.io/badge/Bun-toolchain-black?logo=bun" alt="Bun toolchain" />
   </a>
 </p>
 
@@ -54,7 +54,7 @@ The screenshots show the **`codex-limits`** terminal dashboards: clean, read-onl
 - [License](#license)
 - [Contributors](#contributors)
 
-> Last verified against: `@simonesiega/codex-limits` v0.1.5
+> Last verified against: `@simonesiega/codex-limits` v0.1.6
 > Verification date: 2026-07-22
 
 ## Quick start
@@ -83,10 +83,11 @@ Install an optional agent integration by name:
 codex-limits agents install <agent-name>
 ```
 
-For example, install the OpenCode integration:
+For example, install the OpenCode or pi integration:
 
 ```bash
 codex-limits agents install opencode
+codex-limits agents install pi
 ```
 
 The existing `codex-limits init --<agent-name>` syntax remains supported as a compatibility command.
@@ -100,13 +101,15 @@ The existing `codex-limits init --<agent-name>` syntax remains supported as a co
 | 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.                                                    |
 | 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. |
 
+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.
+
 ## Overview
 
 When you are working with Codex or agent-based coding tools, usage limits can interrupt your flow if you do not know what is left or when the next reset happens.
 
 **`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.
 
-It also includes plain-text commands for quick checks, JSON output for scripts and automation, optional agent integrations through `codex-limits agents`, and safe output that never prints tokens, account IDs, auth headers, cookies, or raw local files.
+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.
 
 ## Agent integrations
 
@@ -119,6 +122,7 @@ For installation details, adapter behavior, architecture, and contribution guida
 | Agent    | Status    | Agent command   | Guide                                                    | Description                                                                                                     |
 | -------- | --------- | --------------- | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
 | 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. |
+| 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.       |
 
 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.
 
@@ -132,9 +136,17 @@ The OpenCode integration adds a `/codex-limits` command that opens a compact mod
   <img src="docs/photos/agents/opencode/opencode_result.png" alt="OpenCode codex-limits integration screenshot" width="740" />
 </p>
 
+#### pi
+
+The pi integration adds a `/codex-limits` command that opens a themed overlay inside the agent interface. It shows the same read-only usage windows and reset-credit summary without sending the request or limit data to the LLM.
+
+<p align="center">
+  <img src="docs/photos/agents/pi/pi_result.png" alt="pi codex-limits integration screenshot" width="740" />
+</p>
+
 ### Adding new agents
 
-New agents can be added by creating a dedicated adapter under `src/agents/<agent-name>` and registering it in `src/agents/index.ts`. Each integration should keep the same goal: show Codex limit information quickly, safely, and without exposing tokens, account IDs, cookies, auth headers, or raw local files.
+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.
 
 See the [Contributing](./CONTRIBUTING.md) guide if you want to add support for another agent.
 
@@ -167,6 +179,7 @@ Environment variables are only used as a fallback when automatic discovery is no
 | `CODEX_LIMITS_ACCOUNT_ID`     | Provides the account ID paired with `CODEX_LIMITS_ACCESS_TOKEN`.                         |
 | `CODEX_LIMITS_USAGE_ENDPOINT` | Overrides the live usage endpoint with HTTPS or loopback HTTP for advanced setups/tests. |
 | `CODEX_LIMITS_SKIP_INIT`      | Suppresses optional global-install setup guidance from the non-interactive postinstall.  |
+| `PI_CODING_AGENT_DIR`         | Overrides pi's global agent configuration directory for integration setup and checks.    |
 
 ### Data access and safety
 
@@ -181,11 +194,39 @@ Local Codex data is inspected read-only with bounded file, directory, JSONL, and
 | `codex-limits coupons`                   | Prints reset-credit coupon information.                |
 | `codex-limits coupons --json`            | Prints machine-readable reset-credit coupon data only. |
 | `codex-limits --json`                    | Prints machine-readable usage and coupon data.         |
+| `codex-limits doctor`                    | Prints safe environment and connectivity diagnostics.  |
+| `codex-limits doctor --json`             | Prints machine-readable diagnostics only.              |
 | `codex-limits agents`                    | Lists the available agent-management subcommands.      |
 | `codex-limits agents install <agent...>` | Installs one or more named agent integrations.         |
 | `codex-limits agents install --all`      | Installs every supported agent integration.            |
 | `codex-limits init`                      | Runs the compatible interactive installation flow.     |
 
+### Diagnostics
+
+Run the read-only doctor command when Codex data, live usage, or an agent integration is unavailable:
+
+```bash
+codex-limits doctor
+```
+
+```text
+Codex Limits diagnostics
+
+Package version:       0.1.6
+Node.js version:       22.0.0
+Operating system:      Windows
+Codex home detected:   Yes
+Authentication found:  Yes
+Local usage found:     Yes
+Live endpoint:         Reachable
+OpenCode integration:  Installed
+pi integration:        Installed
+
+No sensitive values were displayed.
+```
+
+The doctor checks only whether recognized resources are available, including the OpenCode and pi integrations. It never prints credential values, private paths, endpoint URLs, configuration contents, or raw Codex data. The live check makes the same bounded authenticated read-only usage request as the dashboard; it is reported as `Not checked` when complete authentication is unavailable. Use `codex-limits doctor --json` for the stable machine-readable form documented in [JSON output](docs/readme/json-output.md#doctor-document).
+
 ### Agent management
 
 Use `codex-limits agents install` to install optional integrations. Installation only updates the selected agent configuration; it does not send a prompt to an LLM or modify Codex data.
@@ -209,7 +250,7 @@ Make sure Codex has been run and authenticated at least once. If its data is sto
 
 ### Usage information unavailable
 
-Run `codex-limits status` to view the safe warning summary. Confirm that Codex authentication is current and that the machine can reach the ChatGPT Codex service. Local session data may still provide a fallback when live usage is unavailable; coupon information requires an internet connection.
+Run `codex-limits doctor` to check Codex home discovery, authentication presence, local usage, and live endpoint reachability without exposing sensitive values. Run `codex-limits status` to view the safe warning summary. Confirm that Codex authentication is current and that the machine can reach the ChatGPT Codex service. Local session data may still provide a fallback when live usage is unavailable; coupon information requires an internet connection.
 
 ### Permission errors
 
@@ -217,7 +258,7 @@ Confirm that your user can read the selected Codex directory and its session fil
 
 ### Agent command not appearing after installation
 
-Run the named installer again, for example `codex-limits agents install opencode`, and confirm that it reports the integration as installed or already installed. Restart the target agent terminal so it reloads its configuration. If the command is still missing, verify that the displayed configuration paths belong to the agent installation you are using.
+Run the named installer again, for example `codex-limits agents install opencode` or `codex-limits agents install pi`, and confirm that it reports the integration as installed or already installed. Restart the target agent terminal so it reloads its configuration. If the command is still missing, verify that the displayed configuration paths belong to the agent installation you are using.
 
 ## Documentation
 
@@ -254,11 +295,12 @@ Useful development commands:
 
 ## Security
 
-| Operation                 | Reads                                           | Writes                            | Network                         |
-| ------------------------- | ----------------------------------------------- | --------------------------------- | ------------------------------- |
-| `codex-limits`            | Recognized Codex state and bounded session data | Nothing                           | Live usage and coupon endpoints |
-| `status` / `coupons`      | Shared read-only core                           | Nothing                           | When live data is requested     |
-| `agents install` / `init` | Selected agent configuration                    | Adds the integration registration | Does not send an LLM prompt     |
+| Operation                 | Reads                                           | Writes                            | Network                                |
+| ------------------------- | ----------------------------------------------- | --------------------------------- | -------------------------------------- |
+| `codex-limits`            | Recognized Codex state and bounded session data | Nothing                           | Live usage and coupon endpoints        |
+| `status` / `coupons`      | Shared read-only core                           | Nothing                           | When live data is requested            |
+| `doctor`                  | Bounded Codex and agent configuration checks    | Nothing                           | Live usage endpoint when authenticated |
+| `agents install` / `init` | Selected agent configuration                    | Adds the integration registration | Does not send an LLM prompt            |
 
 For vulnerability reports and local data safety details, see [`SECURITY.md`](./SECURITY.md).
 

package/SECURITY.md

@@ -65,11 +65,15 @@ The CLI performs bounded, read-only inspection of recognized Codex home candidat
 
 For live usage and coupon information, the project contacts the default ChatGPT Codex endpoints. The only endpoint override is `CODEX_LIMITS_USAGE_ENDPOINT`, mainly for testing or advanced setups. Overrides must use HTTPS, except for loopback HTTP during local testing. Authenticated requests reject redirects, use bounded timeouts and responses, and never include credential headers in diagnostics.
 
-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.
+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.
+
+Agent installers use bounded JSON reads and owner-only atomic replacements. The pi installer registers the already installed local package root and does not download a package or execute dependency lifecycle scripts.
+
+The `codex-limits doctor` command exposes only package/runtime labels and bounded availability statuses. Its Codex, OpenCode, and pi checks never return credential values, private paths, endpoint URLs, configuration contents, or raw local files. The optional live reachability check uses the same authenticated, bounded, redirect-free usage transport as the dashboard.
 
 ### Command safety boundaries
 
-Every CLI command declares one enforced safety category. Dashboard, status, coupon, and agent-inspection commands are read-only and receive no write or account-mutation services. Agent installation is a local-write operation scoped to the selected agent configuration. Any future remote account mutation must use the separate `remote-mutation` category and declare an explicit boolean confirmation option before the router will execute it.
+Every CLI command declares one enforced safety category. Dashboard, status, coupon, doctor, and agent-inspection commands are read-only and receive no write or account-mutation services. Agent installation is a local-write operation scoped to the selected agent configuration. Any future remote account mutation must use the separate `remote-mutation` category and declare an explicit boolean confirmation option before the router will execute it.
 
 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.
 
@@ -86,7 +90,7 @@ Relevant examples include:
 - agent integrations exposing private Codex data inside the agent UI;
 - unexpected writes to local Codex data;
 - unexpected network behavior related to usage or coupon discovery;
-- unsafe handling of `CODEX_LIMITS_HOME`, `CODEX_LIMITS_ACCESS_TOKEN`, `CODEX_LIMITS_ACCOUNT_ID`, or `CODEX_LIMITS_USAGE_ENDPOINT`.
+- unsafe handling of `CODEX_LIMITS_HOME`, `CODEX_LIMITS_ACCESS_TOKEN`, `CODEX_LIMITS_ACCOUNT_ID`, `CODEX_LIMITS_USAGE_ENDPOINT`, or `PI_CODING_AGENT_DIR`.
 
 ## Safety expectations