@simonesiega/codex-limits 1.1.0 → 1.2.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/CHANGELOG.md +23 -14
- package/CODE_OF_CONDUCT.md +120 -0
- package/CONTRIBUTING.md +44 -41
- package/README.md +119 -143
- package/SECURITY.md +27 -10
- package/dist/cli.js +148 -137
- package/dist/copilot.mjs +3 -3
- package/dist/opencode.js +3 -3
- package/dist/pi.js +3 -3
- package/docs/README.md +36 -29
- package/docs/examples/codex-limits-coupons-output.example.json +25 -0
- package/docs/examples/codex-limits-doctor-output.example.json +14 -0
- package/docs/readme/agent-integrations.md +36 -15
- package/docs/readme/agents/copilot.md +20 -38
- package/docs/readme/agents/opencode.md +23 -29
- package/docs/readme/agents/pi.md +20 -29
- package/docs/readme/compatibility.md +34 -42
- package/docs/readme/json-output.md +70 -35
- package/docs/readme/troubleshooting.md +160 -0
- package/docs/schema/codex-limits-coupons.schema.json +107 -0
- package/docs/schema/codex-limits-doctor.schema.json +50 -0
- package/docs/schema/codex-limits.schema.json +2 -1
- package/package.json +11 -3
package/docs/README.md
CHANGED
|
@@ -2,50 +2,54 @@
|
|
|
2
2
|
|
|
3
3
|
[← Project README](../README.md) · [npm package](https://www.npmjs.com/package/@simonesiega/codex-limits)
|
|
4
4
|
|
|
5
|
-
This documentation is organized by task. The root README is the product overview
|
|
5
|
+
This documentation is organized by task. The root README is the product overview. [Compatibility](readme/compatibility.md) is canonical for support requirements, [`SECURITY.md`](../SECURITY.md) is canonical for deep safety behavior, [Troubleshooting](readme/troubleshooting.md) is the cross-surface diagnosis guide, and each individual agent page is canonical for that integration's setup, removal, and troubleshooting.
|
|
6
6
|
|
|
7
7
|
## Start here
|
|
8
8
|
|
|
9
9
|
- **Installing or using the CLI?** Begin with the [quick start](../README.md#quick-start), then use the [command reference](../README.md#usage).
|
|
10
|
-
- **Writing a script or integration?** Read [JSON output](readme/json-output.md) and use the
|
|
11
|
-
- **Installing an agent command?** Open the [agent integrations guide](readme/agent-integrations.md), then choose [OpenCode](readme/agents/opencode.md), [pi](readme/agents/pi.md), or [GitHub Copilot CLI](readme/agents/copilot.md).
|
|
12
|
-
- **Diagnosing an environment?** Run `codex-limits doctor`, then
|
|
13
|
-
- **Contributing?** Start with [`CONTRIBUTING.md`](../CONTRIBUTING.md) and review the [security policy](../SECURITY.md).
|
|
10
|
+
- **Writing a script or integration?** Read [JSON output](readme/json-output.md) and use the schema for [complete limits](schema/codex-limits.schema.json), [coupons](schema/codex-limits-coupons.schema.json), or [doctor diagnostics](schema/codex-limits-doctor.schema.json).
|
|
11
|
+
- **Installing or removing an agent command?** Open the [agent integrations guide](readme/agent-integrations.md), then choose [OpenCode](readme/agents/opencode.md), [pi](readme/agents/pi.md), or [GitHub Copilot CLI](readme/agents/copilot.md).
|
|
12
|
+
- **Diagnosing an environment?** Run `codex-limits doctor`, then use [Troubleshooting](readme/troubleshooting.md) and check the relevant [compatibility requirements](readme/compatibility.md).
|
|
13
|
+
- **Contributing?** Start with [`CONTRIBUTING.md`](../CONTRIBUTING.md), follow the [Code of Conduct](../CODE_OF_CONDUCT.md), use the [issue chooser](https://github.com/simonesiega/codex-limits/issues/new/choose) for bug reports or feature requests, and review the [security policy](../SECURITY.md).
|
|
14
14
|
|
|
15
15
|
## CLI and automation
|
|
16
16
|
|
|
17
|
-
| Guide
|
|
18
|
-
|
|
|
19
|
-
| [Quick start](../README.md#quick-start)
|
|
20
|
-
| [Command reference](../README.md#usage)
|
|
21
|
-
| [JSON output](readme/json-output.md)
|
|
22
|
-
| [Compatibility](readme/compatibility.md)
|
|
23
|
-
| [Troubleshooting](
|
|
17
|
+
| Guide | Use it when |
|
|
18
|
+
| -------------------------------------------- | ------------------------------------------------------------------------------------------------ |
|
|
19
|
+
| [Quick start](../README.md#quick-start) | Installing the published package and opening the dashboard for the first time. |
|
|
20
|
+
| [Command reference](../README.md#usage) | Using `status`, `coupons`, `reset`, `doctor`, `agents`, or the compatible `init` command. |
|
|
21
|
+
| [JSON output](readme/json-output.md) | Consuming stable machine-readable limits, coupon, or doctor documents. |
|
|
22
|
+
| [Compatibility](readme/compatibility.md) | Checking Node.js, operating-system, terminal, Codex-data, network, or agent requirements. |
|
|
23
|
+
| [Troubleshooting](readme/troubleshooting.md) | Resolving Codex data, authentication, network, coupon, terminal, JSON, reset, or agent problems. |
|
|
24
24
|
|
|
25
25
|
## Agent integrations
|
|
26
26
|
|
|
27
|
-
| Guide | Covers
|
|
28
|
-
| -------------------------------------------------- |
|
|
29
|
-
| [Agent integrations](readme/agent-integrations.md) |
|
|
30
|
-
| [OpenCode](readme/agents/opencode.md) |
|
|
31
|
-
| [pi](readme/agents/pi.md) |
|
|
32
|
-
| [GitHub Copilot CLI](readme/agents/copilot.md) |
|
|
27
|
+
| Guide | Covers |
|
|
28
|
+
| -------------------------------------------------- | -------------------------------------------------------------------------------------------- |
|
|
29
|
+
| [Agent integrations](readme/agent-integrations.md) | Supported-agent index, shared lifecycle modes, adapter architecture, and contribution rules. |
|
|
30
|
+
| [OpenCode](readme/agents/opencode.md) | Canonical OpenCode setup, usage, removal, and troubleshooting. |
|
|
31
|
+
| [pi](readme/agents/pi.md) | Canonical pi setup, usage, removal, and troubleshooting. |
|
|
32
|
+
| [GitHub Copilot CLI](readme/agents/copilot.md) | Canonical Copilot CLI setup, usage, removal, and troubleshooting. |
|
|
33
33
|
|
|
34
34
|
## Development and security
|
|
35
35
|
|
|
36
|
-
| Guide
|
|
37
|
-
|
|
|
38
|
-
| [Contributing](../CONTRIBUTING.md)
|
|
39
|
-
| [
|
|
40
|
-
| [
|
|
36
|
+
| Guide | Covers |
|
|
37
|
+
| ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
|
|
38
|
+
| [Contributing](../CONTRIBUTING.md) | Repository setup, architecture boundaries, tests, documentation rules, and pull-request expectations. |
|
|
39
|
+
| [Code of Conduct](../CODE_OF_CONDUCT.md) | Community behavior, private conduct reporting, and enforcement guidelines. |
|
|
40
|
+
| [Security](../SECURITY.md) | Responsible disclosure, local-data and network boundaries, command safety, and release security. |
|
|
41
|
+
| [Changelog](../CHANGELOG.md) | Released behavior and current unreleased changes. |
|
|
42
|
+
| [Issue forms](https://github.com/simonesiega/codex-limits/issues/new/choose) | Structured bug reports and feature requests. |
|
|
43
|
+
| [Pull Request template](../.github/pull_request_template.md) | Required contribution context, validation, and safety checks. |
|
|
41
44
|
|
|
42
45
|
## Schemas, examples, and visual assets
|
|
43
46
|
|
|
44
|
-
| Resource
|
|
45
|
-
|
|
|
46
|
-
| [Complete
|
|
47
|
-
| [
|
|
48
|
-
| [
|
|
47
|
+
| Resource | Purpose |
|
|
48
|
+
| ------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
|
|
49
|
+
| [Complete limits example](examples/codex-limits-output.example.json) and [schema](schema/codex-limits.schema.json) | Resources for validating `codex-limits --json`. |
|
|
50
|
+
| [Coupon example](examples/codex-limits-coupons-output.example.json) and [schema](schema/codex-limits-coupons.schema.json) | Resources for validating `coupons --json`. |
|
|
51
|
+
| [Doctor example](examples/codex-limits-doctor-output.example.json) and [schema](schema/codex-limits-doctor.schema.json) | Resources for validating `doctor --json`. |
|
|
52
|
+
| [`photos/`](photos/) | README screenshots and project identity assets. |
|
|
49
53
|
|
|
50
54
|
Visual assets are grouped by purpose:
|
|
51
55
|
|
|
@@ -61,7 +65,10 @@ photos/
|
|
|
61
65
|
- Commands are shown from the repository root unless a guide says otherwise.
|
|
62
66
|
- Keep internal repository links relative and route readers through this hub when no more specific canonical guide exists.
|
|
63
67
|
- Treat the root [Usage](../README.md#usage) section and generated `--help` output as the command reference; do not duplicate complete command procedures across guides.
|
|
64
|
-
- Keep
|
|
68
|
+
- Keep deep data-access, network, redaction, installer, and mutation safeguards canonical in [`SECURITY.md`](../SECURITY.md); summarize and link elsewhere.
|
|
69
|
+
- Keep runtime, operating-system, Codex-data, network, terminal, and host support requirements canonical in [Compatibility](readme/compatibility.md).
|
|
70
|
+
- Keep cross-surface diagnosis in [Troubleshooting](readme/troubleshooting.md), while agent-specific installation, configuration, removal, and troubleshooting remain canonical in the matching page under [`readme/agents/`](readme/agents/).
|
|
71
|
+
- Keep JSON field claims synchronized with [JSON output](readme/json-output.md) and each command's schema and sanitized example.
|
|
65
72
|
- Use placeholders in examples. Never include tokens, account IDs, authorization headers, cookies, private paths, raw Codex files, or unredacted environment values.
|
|
66
73
|
- Use repository-relative image paths and descriptive alt text. Screenshots must contain only synthetic or safely redacted data.
|
|
67
74
|
- Run `bun run docs:check` after documentation changes.
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
{
|
|
2
|
+
"available": 2,
|
|
3
|
+
"earnedThisPeriod": 4,
|
|
4
|
+
"nextExpirationDate": "Monday 20 July 2026",
|
|
5
|
+
"nextExpirationIn": "7d 4h 38m",
|
|
6
|
+
"items": [
|
|
7
|
+
{
|
|
8
|
+
"index": 1,
|
|
9
|
+
"status": "available",
|
|
10
|
+
"grantedAt": "2026-06-20T20:38:07Z",
|
|
11
|
+
"expiresAt": "2026-07-20T20:38:07Z",
|
|
12
|
+
"expirationDate": "Monday 20 July 2026",
|
|
13
|
+
"expiresIn": "7d 4h 38m"
|
|
14
|
+
},
|
|
15
|
+
{
|
|
16
|
+
"index": 2,
|
|
17
|
+
"status": "available",
|
|
18
|
+
"grantedAt": "2026-06-27T20:38:07Z",
|
|
19
|
+
"expiresAt": "2026-07-27T20:38:07Z",
|
|
20
|
+
"expirationDate": "Monday 27 July 2026",
|
|
21
|
+
"expiresIn": "14d 4h 38m"
|
|
22
|
+
}
|
|
23
|
+
],
|
|
24
|
+
"warnings": []
|
|
25
|
+
}
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
{
|
|
2
|
+
"packageVersion": "1.2.0",
|
|
3
|
+
"nodeVersion": "22.0.0",
|
|
4
|
+
"operatingSystem": "Windows",
|
|
5
|
+
"codexHomeDetected": true,
|
|
6
|
+
"authenticationFound": true,
|
|
7
|
+
"localUsageFound": true,
|
|
8
|
+
"liveEndpoint": "reachable",
|
|
9
|
+
"agentIntegrations": {
|
|
10
|
+
"opencode": "installed",
|
|
11
|
+
"pi": "installed",
|
|
12
|
+
"copilot": "installed"
|
|
13
|
+
}
|
|
14
|
+
}
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
[← Documentation hub](../README.md) · [Project README](../../README.md)
|
|
4
4
|
|
|
5
|
-
This page is the central index for supported agent integrations. Each agent has a dedicated guide covering installation, usage,
|
|
5
|
+
This page is the central index for supported agent integrations. Each agent has a dedicated guide covering installation, usage, removal, troubleshooting, and links to compatibility requirements.
|
|
6
6
|
|
|
7
7
|
`codex-limits` can expose the shared, read-only limits dashboard inside supported coding agents. Integrations remain thin and load normalized data through the same core as the CLI.
|
|
8
8
|
|
|
@@ -37,21 +37,41 @@ The existing `codex-limits init`, `codex-limits init --<agent-name>`, and `codex
|
|
|
37
37
|
|
|
38
38
|
After a successful installation, restart the target agent terminal so it reloads its configuration.
|
|
39
39
|
|
|
40
|
+
## Uninstalling an integration
|
|
41
|
+
|
|
42
|
+
Removal uses the same target model as installation:
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
# Prompt only for integrations currently recognized as installed
|
|
46
|
+
codex-limits agents uninstall
|
|
47
|
+
|
|
48
|
+
# Uninstall one or more integrations directly
|
|
49
|
+
codex-limits agents uninstall <agent...>
|
|
50
|
+
|
|
51
|
+
# Attempt safe removal for every registered integration
|
|
52
|
+
codex-limits agents uninstall --all
|
|
53
|
+
|
|
54
|
+
# Show removal help
|
|
55
|
+
codex-limits agents uninstall --help
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
Named and `--all` forms work non-interactively. An absent integration reports `not installed` as a successful no-op. With multiple targets, each result is reported even when another adapter fails. Removal is conservative: each adapter changes only configuration it recognizes as Codex Limits-owned, refuses malformed or symbolic-link targets, and preserves unrelated plugins, packages, extension files, and settings. Restart affected agent terminals after removal.
|
|
59
|
+
|
|
40
60
|
## Agents
|
|
41
61
|
|
|
42
|
-
Each agent name links to its dedicated installation, usage, compatibility, and troubleshooting guide.
|
|
62
|
+
Each agent name links to its dedicated installation, usage, removal, compatibility, and troubleshooting guide.
|
|
43
63
|
|
|
44
|
-
| Agent | Official page | Status | Command |
|
|
45
|
-
| --------------------------------------- | ----------------------------------------------------------- | --------- | --------------- |
|
|
46
|
-
| [OpenCode](agents/opencode.md) | [opencode.ai](https://opencode.ai/) | Supported | `/codex-limits` | `
|
|
47
|
-
| [pi](agents/pi.md) | [pi.dev](https://pi.dev/) | Supported | `/codex-limits` | `
|
|
48
|
-
| [GitHub Copilot CLI](agents/copilot.md) | [github/copilot-cli](https://github.com/github/copilot-cli) | Supported | `/codex-limits` | `
|
|
64
|
+
| Agent | Official page | Status | Command | Lifecycle target |
|
|
65
|
+
| --------------------------------------- | ----------------------------------------------------------- | --------- | --------------- | ---------------- |
|
|
66
|
+
| [OpenCode](agents/opencode.md) | [opencode.ai](https://opencode.ai/) | Supported | `/codex-limits` | `opencode` |
|
|
67
|
+
| [pi](agents/pi.md) | [pi.dev](https://pi.dev/) | Supported | `/codex-limits` | `pi` |
|
|
68
|
+
| [GitHub Copilot CLI](agents/copilot.md) | [github/copilot-cli](https://github.com/github/copilot-cli) | Supported | `/codex-limits` | `copilot` |
|
|
49
69
|
|
|
50
70
|
## Data and privacy
|
|
51
71
|
|
|
52
|
-
|
|
72
|
+
Agent integrations are read-only views over the shared local core. The Security policy is canonical for [agent data flow and installer safeguards](../../SECURITY.md#agent-integrations-and-installers) and [command safety boundaries](../../SECURITY.md#command-safety-boundaries).
|
|
53
73
|
|
|
54
|
-
Agent adapters must reuse the shared core rather than independently reading Codex data, resolving credentials, making live requests, or defining
|
|
74
|
+
Agent adapters must reuse the shared core rather than independently reading Codex data, resolving credentials, making live requests, or defining safety rules.
|
|
55
75
|
|
|
56
76
|
## Adding another agent
|
|
57
77
|
|
|
@@ -60,22 +80,23 @@ Agent adapters live under `src/agents/<agent-name>` and use one consistent layou
|
|
|
60
80
|
```text
|
|
61
81
|
src/agents/<agent-name>/
|
|
62
82
|
├── format.ts # Thin host-facing wrapper over shared presentation
|
|
63
|
-
├── install.ts # Bounded configuration install and inspection
|
|
64
|
-
├── integration.ts # Metadata plus
|
|
83
|
+
├── install.ts # Bounded configuration install, uninstall, and inspection
|
|
84
|
+
├── integration.ts # Metadata plus lifecycle/inspection registration contract
|
|
65
85
|
└── plugin.ts # Host API adapter that loads the shared core
|
|
66
86
|
```
|
|
67
87
|
|
|
68
|
-
Register the exported descriptor once in `src/agents/index.ts`. Shared
|
|
88
|
+
Register the exported descriptor once in `src/agents/index.ts`. Shared install and uninstall commands, generated compatibility help, and doctor diagnostics consume that registry automatically. Every registered agent must also use a matching `src/package/<agent-name>.ts` wrapper and expose `@simonesiega/codex-limits/<agent-name>` through the shared package-entry build and declaration flow. Put behavior used by multiple agents in `src/agents/shared` rather than duplicating it.
|
|
69
89
|
|
|
70
|
-
New adapters should remain thin, reuse `src/package/core`, avoid sending limit data to
|
|
90
|
+
New adapters should remain thin, reuse `src/package/core`, avoid sending the request or limit data to the LLM, and include installer, formatter, and host-behavior tests. Each supported integration should also have a dedicated guide under `docs/readme/agents/<agent-name>.md` and an entry in the [Agents](#agents) table.
|
|
71
91
|
|
|
72
92
|
See [Contributing](../../CONTRIBUTING.md#adding-a-new-agent) for the complete contribution checklist.
|
|
73
93
|
|
|
74
94
|
## Related documentation
|
|
75
95
|
|
|
76
|
-
- [Compatibility](compatibility.md) —
|
|
96
|
+
- [Compatibility](compatibility.md) — Canonical runtime, operating-system, terminal, network, and agent support requirements.
|
|
77
97
|
- [JSON output](json-output.md) — Machine-readable output, fields, warnings, and scripting behavior.
|
|
78
98
|
- [Contributing](../../CONTRIBUTING.md#adding-a-new-agent) — Complete checklist for developing and submitting another agent adapter.
|
|
79
99
|
- [Security policy](../../SECURITY.md) — Local-data safeguards, network behavior, and vulnerability reporting.
|
|
100
|
+
- [Troubleshooting](troubleshooting.md) — Cross-surface diagnosis and links to agent-specific problem resolution.
|
|
80
101
|
- [Documentation hub](../README.md) — Task-oriented index for CLI, automation, agent, development, and security guides.
|
|
81
|
-
- [Project README](../../README.md) — Product overview, installation, commands,
|
|
102
|
+
- [Project README](../../README.md) — Product overview, installation, commands, and configuration.
|
|
@@ -2,18 +2,19 @@
|
|
|
2
2
|
|
|
3
3
|
[← Documentation hub](../../README.md) · [Agent integrations](../agent-integrations.md) · [Project README](../../../README.md)
|
|
4
4
|
|
|
5
|
-
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
|
|
5
|
+
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 the request or limit data to the LLM.
|
|
6
6
|
|
|
7
7
|
## Overview
|
|
8
8
|
|
|
9
|
-
| Detail | Value
|
|
10
|
-
| ------------------ |
|
|
11
|
-
| Agent | [GitHub Copilot CLI][copilot-cli]
|
|
12
|
-
| Status | Supported
|
|
13
|
-
| Agent command | `/codex-limits`
|
|
14
|
-
| Install command | `codex-limits agents install copilot`
|
|
15
|
-
|
|
|
16
|
-
|
|
|
9
|
+
| Detail | Value |
|
|
10
|
+
| ------------------ | --------------------------------------- |
|
|
11
|
+
| Agent | [GitHub Copilot CLI][copilot-cli] |
|
|
12
|
+
| Status | Supported |
|
|
13
|
+
| Agent command | `/codex-limits` |
|
|
14
|
+
| Install command | `codex-limits agents install copilot` |
|
|
15
|
+
| Uninstall command | `codex-limits agents uninstall copilot` |
|
|
16
|
+
| Installation scope | Global for the current user |
|
|
17
|
+
| Host API | Experimental Copilot CLI extensions |
|
|
17
18
|
|
|
18
19
|
## Installation
|
|
19
20
|
|
|
@@ -41,18 +42,9 @@ When `COPILOT_HOME` is set, the installer uses `extensions/codex-limits/extensio
|
|
|
41
42
|
|
|
42
43
|
The published package contains the bundled source at `dist/copilot.mjs` and exposes that host module as `@simonesiega/codex-limits/copilot`. The installer copies the same 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 package subpath is a host entry point, not an alternative installation command or a general-purpose JavaScript API.
|
|
43
44
|
|
|
44
|
-
The installer
|
|
45
|
+
The installer creates the dedicated extension directory, updates older bundles managed by `codex-limits`, leaves unrelated files unchanged, and reports `already installed` when the current bundle is present. It refuses to replace an unrecognized or competing extension entry point.
|
|
45
46
|
|
|
46
|
-
-
|
|
47
|
-
- validates the package identity, bounded bundle, and stable extension marker before copying;
|
|
48
|
-
- updates an older extension managed by `codex-limits` and leaves unrelated files in the directory unchanged;
|
|
49
|
-
- reports `already installed` when the installed bundle is current;
|
|
50
|
-
- writes through an owner-only sibling temporary file to avoid a partial entry point;
|
|
51
|
-
- refuses to overwrite an existing entry point that is not marked as the Codex Limits extension;
|
|
52
|
-
- refuses a competing `extension.cjs` or `extension.js` entry point in the dedicated directory;
|
|
53
|
-
- refuses symbolic-link, non-file, unreadable, or oversized entry points.
|
|
54
|
-
|
|
55
|
-
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]`.
|
|
47
|
+
Installer identity checks, file-handling, size, symbolic-link, atomic-write, and path-redaction guarantees are canonical in the [Security policy](../../../SECURITY.md#agent-integrations-and-installers).
|
|
56
48
|
|
|
57
49
|
## Using `/codex-limits`
|
|
58
50
|
|
|
@@ -77,28 +69,19 @@ The slash-command handler calls the shared local core directly. It does not call
|
|
|
77
69
|
|
|
78
70
|
## Compatibility
|
|
79
71
|
|
|
80
|
-
Copilot CLI
|
|
81
|
-
|
|
82
|
-
- it is installed as `extension.mjs` in an immediate child of the user extensions directory;
|
|
83
|
-
- it imports the CLI-provided SDK from `@github/copilot-sdk/extension`;
|
|
84
|
-
- it calls `joinSession()` and registers `codex-limits` through the session `commands` option;
|
|
85
|
-
- it uses `session.log()` for timeline output because extension standard output is reserved for JSON-RPC.
|
|
86
|
-
|
|
87
|
-
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.
|
|
88
|
-
|
|
89
|
-
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.
|
|
72
|
+
See [GitHub Copilot CLI compatibility](../compatibility.md#github-copilot-cli-compatibility) for the canonical experimental host, Node.js, SDK, test coverage, operating-system, terminal, and network support requirements. Keep Copilot CLI current and consult the SDK's [extension documentation][copilot-extension-docs] for its evolving host contract.
|
|
90
73
|
|
|
91
74
|
## Re-running or removing the integration
|
|
92
75
|
|
|
93
76
|
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.
|
|
94
77
|
|
|
95
|
-
|
|
78
|
+
Remove the managed extension with:
|
|
96
79
|
|
|
97
|
-
```
|
|
98
|
-
|
|
80
|
+
```bash
|
|
81
|
+
codex-limits agents uninstall copilot
|
|
99
82
|
```
|
|
100
83
|
|
|
101
|
-
|
|
84
|
+
The uninstaller uses the same `COPILOT_HOME` resolution as installation. It removes only `extensions/codex-limits/extension.mjs` when the bounded file contains the Codex Limits management marker. It removes the dedicated directory only when empty and preserves unrelated sibling files. A missing entry with no competing entry point reports `not installed`; an unrecognized, competing, oversized, unreadable, or symbolic-link entry fails closed and is not deleted. Restart Copilot CLI after successful removal.
|
|
102
85
|
|
|
103
86
|
## Troubleshooting
|
|
104
87
|
|
|
@@ -125,9 +108,7 @@ Run `codex-limits doctor` and `codex-limits status` outside Copilot CLI. If data
|
|
|
125
108
|
|
|
126
109
|
## Data and privacy
|
|
127
110
|
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
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.
|
|
111
|
+
See the [Security policy](../../../SECURITY.md#agent-integrations-and-installers) for the canonical agent, credential, local-data, installer, and output safety guarantees. Copilot CLI extensions execute as separate processes with the current user's system permissions, so install only extensions you trust.
|
|
131
112
|
|
|
132
113
|
## Related documentation
|
|
133
114
|
|
|
@@ -138,8 +119,9 @@ Copilot CLI extensions execute as separate processes with the current user's sys
|
|
|
138
119
|
- [GitHub Copilot CLI][copilot-cli] — Official CLI repository.
|
|
139
120
|
- [Copilot CLI documentation][copilot-docs] — Official concepts and usage documentation.
|
|
140
121
|
- [Copilot SDK extension documentation][copilot-extension-docs] — Current experimental extension lifecycle and API.
|
|
122
|
+
- [Troubleshooting](../troubleshooting.md) — Cross-surface diagnosis and common problem resolution.
|
|
141
123
|
- [Documentation hub](../../README.md) — Task-oriented index for CLI, automation, agent, development, and security guides.
|
|
142
|
-
- [Project README](../../../README.md) — Product overview, installation, commands,
|
|
124
|
+
- [Project README](../../../README.md) — Product overview, installation, commands, and configuration.
|
|
143
125
|
|
|
144
126
|
[copilot-cli]: https://github.com/github/copilot-cli
|
|
145
127
|
[copilot-docs]: https://docs.github.com/en/copilot/concepts/agents/about-copilot-cli
|
|
@@ -2,17 +2,18 @@
|
|
|
2
2
|
|
|
3
3
|
[← Documentation hub](../../README.md) · [Agent integrations](../agent-integrations.md) · [Project README](../../../README.md)
|
|
4
4
|
|
|
5
|
-
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
|
|
5
|
+
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 the request or limit data to the LLM.
|
|
6
6
|
|
|
7
7
|
## Overview
|
|
8
8
|
|
|
9
|
-
| Detail | Value
|
|
10
|
-
| ------------------ |
|
|
11
|
-
| Agent | [OpenCode](https://opencode.ai/)
|
|
12
|
-
| Status | Supported
|
|
13
|
-
| Agent command | `/codex-limits`
|
|
14
|
-
| Install command | `codex-limits agents install opencode`
|
|
15
|
-
|
|
|
9
|
+
| Detail | Value |
|
|
10
|
+
| ------------------ | ---------------------------------------- |
|
|
11
|
+
| Agent | [OpenCode](https://opencode.ai/) |
|
|
12
|
+
| Status | Supported |
|
|
13
|
+
| Agent command | `/codex-limits` |
|
|
14
|
+
| Install command | `codex-limits agents install opencode` |
|
|
15
|
+
| Uninstall command | `codex-limits agents uninstall opencode` |
|
|
16
|
+
| Installation scope | Global for the current user |
|
|
16
17
|
|
|
17
18
|
## Installation
|
|
18
19
|
|
|
@@ -40,18 +41,11 @@ It adds the following package to each file's `plugin` array:
|
|
|
40
41
|
"@simonesiega/codex-limits"
|
|
41
42
|
```
|
|
42
43
|
|
|
43
|
-
The package root
|
|
44
|
+
The package root, the explicit `@simonesiega/codex-limits/opencode` host subpath, and OpenCode's loader-reserved `@simonesiega/codex-limits/tui` subpath resolve to the same bundled plugin. The installer registers the root package name; compatible OpenCode hosts use the `./tui` export automatically during TUI plugin discovery. Neither subpath is a separate installation method.
|
|
44
45
|
|
|
45
|
-
Both files are updated because compatible OpenCode versions discover TUI plugins through different global configuration files. The installer
|
|
46
|
+
Both files are updated because compatible OpenCode versions discover TUI plugins through different global configuration files. The installer creates missing configuration objects, preserves unrelated fields and plugins, recognizes common package version forms, and avoids duplicate registrations. If one file is already configured and the other is not, only the missing plugin registration is added.
|
|
46
47
|
|
|
47
|
-
-
|
|
48
|
-
- preserves existing configuration fields and plugin entries;
|
|
49
|
-
- recognizes unversioned, tagged, pinned, and tuple forms of the package and does not add duplicates;
|
|
50
|
-
- writes changed files through a sibling temporary file to avoid partial JSON;
|
|
51
|
-
- refuses symbolic-link configuration files instead of following or replacing the link;
|
|
52
|
-
- refuses to modify malformed, non-object, oversized, or invalid `plugin` configurations.
|
|
53
|
-
|
|
54
|
-
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]`.
|
|
48
|
+
Installer file-handling, size, symbolic-link, atomic-write, and path-redaction guarantees are canonical in the [Security policy](../../../SECURITY.md#agent-integrations-and-installers).
|
|
55
49
|
|
|
56
50
|
## Using `/codex-limits`
|
|
57
51
|
|
|
@@ -81,20 +75,19 @@ Loading failures are reduced to a static safe error instead of exposing raw file
|
|
|
81
75
|
|
|
82
76
|
## Compatibility
|
|
83
77
|
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
- the current keymap layer registration API; or
|
|
87
|
-
- the legacy command registration API.
|
|
88
|
-
|
|
89
|
-
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.
|
|
90
|
-
|
|
91
|
-
See the general [Compatibility guide](../compatibility.md) for tested runtimes, operating systems, terminals, and network behavior.
|
|
78
|
+
See [OpenCode compatibility](../compatibility.md#opencode-compatibility) for the canonical host API, test coverage, runtime, operating-system, terminal, and network support requirements.
|
|
92
79
|
|
|
93
80
|
## Re-running or removing the integration
|
|
94
81
|
|
|
95
82
|
Running `codex-limits agents install opencode` again is safe. It reports `already installed` when both configuration files already contain the package.
|
|
96
83
|
|
|
97
|
-
|
|
84
|
+
Remove it with:
|
|
85
|
+
|
|
86
|
+
```bash
|
|
87
|
+
codex-limits agents uninstall opencode
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
The uninstaller reads both configuration files before writing either one, removes every recognized unversioned, tagged, pinned, or tuple-form Codex Limits entry from their `plugin` arrays, and preserves every other plugin and unrelated field. If neither file contains a matching entry, it reports `not installed`. If either file is malformed, oversized, symbolic-linked, or has an invalid `plugin` field, removal fails without rewriting the configuration. Restart OpenCode after successful removal.
|
|
98
91
|
|
|
99
92
|
## Troubleshooting
|
|
100
93
|
|
|
@@ -115,7 +108,7 @@ Run `codex-limits status` outside OpenCode. If data is also unavailable there, v
|
|
|
115
108
|
|
|
116
109
|
## Data and privacy
|
|
117
110
|
|
|
118
|
-
|
|
111
|
+
See the [Security policy](../../../SECURITY.md#agent-integrations-and-installers) for the canonical agent, credential, local-data, installer, and output safety guarantees.
|
|
119
112
|
|
|
120
113
|
## Related documentation
|
|
121
114
|
|
|
@@ -124,5 +117,6 @@ The integration follows the safety guarantees defined for [all agent integration
|
|
|
124
117
|
- [JSON output](../json-output.md) — Machine-readable output, fields, warnings, and scripting behavior.
|
|
125
118
|
- [Security policy](../../../SECURITY.md) — Local-data safeguards, network behavior, and vulnerability reporting.
|
|
126
119
|
- [OpenCode](https://opencode.ai/) — Official agent website.
|
|
120
|
+
- [Troubleshooting](../troubleshooting.md) — Cross-surface diagnosis and common problem resolution.
|
|
127
121
|
- [Documentation hub](../../README.md) — Task-oriented index for CLI, automation, agent, development, and security guides.
|
|
128
|
-
- [Project README](../../../README.md) — Product overview, installation, commands,
|
|
122
|
+
- [Project README](../../../README.md) — Product overview, installation, commands, and configuration.
|
package/docs/readme/agents/pi.md
CHANGED
|
@@ -2,17 +2,18 @@
|
|
|
2
2
|
|
|
3
3
|
[← Documentation hub](../../README.md) · [Agent integrations](../agent-integrations.md) · [Project README](../../../README.md)
|
|
4
4
|
|
|
5
|
-
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
|
|
5
|
+
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 the request or limit data to the LLM.
|
|
6
6
|
|
|
7
7
|
## Overview
|
|
8
8
|
|
|
9
|
-
| Detail | Value
|
|
10
|
-
| ------------------ |
|
|
11
|
-
| Agent | [pi](https://pi.dev/)
|
|
12
|
-
| Status | Supported
|
|
13
|
-
| Agent command | `/codex-limits`
|
|
14
|
-
| Install command | `codex-limits agents install pi`
|
|
15
|
-
|
|
|
9
|
+
| Detail | Value |
|
|
10
|
+
| ------------------ | ---------------------------------- |
|
|
11
|
+
| Agent | [pi](https://pi.dev/) |
|
|
12
|
+
| Status | Supported |
|
|
13
|
+
| Agent command | `/codex-limits` |
|
|
14
|
+
| Install command | `codex-limits agents install pi` |
|
|
15
|
+
| Uninstall command | `codex-limits agents uninstall pi` |
|
|
16
|
+
| Installation scope | Global for the current user |
|
|
16
17
|
|
|
17
18
|
## Installation
|
|
18
19
|
|
|
@@ -46,16 +47,9 @@ When `PI_CODING_AGENT_DIR` is set, the installer uses `settings.json` under that
|
|
|
46
47
|
|
|
47
48
|
Registering the local package root avoids another download and keeps the extension synchronized with the globally installed `codex-limits` package. The same host module is exposed explicitly as `@simonesiega/codex-limits/pi`, but pi installation continues to use the package manifest rather than that subpath directly. 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.
|
|
48
49
|
|
|
49
|
-
The installer
|
|
50
|
+
The installer creates missing settings objects, preserves unrelated settings and package registrations, avoids duplicates, and verifies that the package manifest and `dist/pi.js` bundle are available.
|
|
50
51
|
|
|
51
|
-
-
|
|
52
|
-
- preserves unrelated settings and package registrations;
|
|
53
|
-
- avoids duplicate local and npm package registrations;
|
|
54
|
-
- verifies that the package manifest declares the bundled `dist/pi.js` extension and that the bundle is available;
|
|
55
|
-
- writes changes through an owner-only sibling temporary file to avoid partial JSON;
|
|
56
|
-
- refuses symbolic-link, malformed, non-object, oversized, or invalid `packages` settings.
|
|
57
|
-
|
|
58
|
-
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]`.
|
|
52
|
+
Installer file-handling, size, symbolic-link, atomic-write, package-filter, and path-redaction guarantees are canonical in the [Security policy](../../../SECURITY.md#agent-integrations-and-installers).
|
|
59
53
|
|
|
60
54
|
Pi's native package command is also supported because the npm package includes the pi manifest:
|
|
61
55
|
|
|
@@ -87,23 +81,21 @@ The command is interactive-TUI-only. In pi RPC, print, and JSON modes, it perfor
|
|
|
87
81
|
|
|
88
82
|
## Compatibility
|
|
89
83
|
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
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.
|
|
93
|
-
|
|
94
|
-
See the general [Compatibility guide](../compatibility.md) for tested runtimes, operating systems, terminals, and network behavior.
|
|
84
|
+
See [pi compatibility](../compatibility.md#pi-compatibility) for the canonical host version, Node.js, peer dependency, test coverage, operating-system, terminal, and network support requirements.
|
|
95
85
|
|
|
96
86
|
## Re-running or removing the integration
|
|
97
87
|
|
|
98
88
|
Running `codex-limits agents install pi` again is safe. It reports `already installed` when the matching local or npm package registration is already enabled.
|
|
99
89
|
|
|
100
|
-
|
|
90
|
+
Remove recognized registrations with:
|
|
101
91
|
|
|
102
92
|
```bash
|
|
103
|
-
|
|
93
|
+
codex-limits agents uninstall pi
|
|
104
94
|
```
|
|
105
95
|
|
|
106
|
-
|
|
96
|
+
The uninstaller removes only package entries that exactly identify the current local Codex Limits package root or an unversioned, tagged, or pinned `npm:@simonesiega/codex-limits` source. It handles those recognized registrations regardless of whether they were added by `codex-limits` or pi's native package manager, and preserves unrelated packages and settings. It does not invoke pi's package manager or remove any separate package-manager cache. Use `pi remove npm:@simonesiega/codex-limits` instead when you want pi to manage its complete native package lifecycle.
|
|
97
|
+
|
|
98
|
+
An absent registration reports `not installed`. Malformed, oversized, or symbolic-link settings fail without being rewritten. Restart pi or run `/reload` after successful removal.
|
|
107
99
|
|
|
108
100
|
## Troubleshooting
|
|
109
101
|
|
|
@@ -128,9 +120,7 @@ Run `codex-limits doctor` and `codex-limits status` outside pi. If data is also
|
|
|
128
120
|
|
|
129
121
|
## Data and privacy
|
|
130
122
|
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
Pi extensions execute with the current user's system permissions. Install only packages you trust, as described in pi's own extension security guidance.
|
|
123
|
+
See the [Security policy](../../../SECURITY.md#agent-integrations-and-installers) for the canonical agent, credential, local-data, installer, and output safety guarantees. Pi extensions execute with the current user's system permissions, so install only packages you trust.
|
|
134
124
|
|
|
135
125
|
## Related documentation
|
|
136
126
|
|
|
@@ -139,5 +129,6 @@ Pi extensions execute with the current user's system permissions. Install only p
|
|
|
139
129
|
- [JSON output](../json-output.md) — Machine-readable output, fields, warnings, and scripting behavior.
|
|
140
130
|
- [Security policy](../../../SECURITY.md) — Local-data safeguards, network behavior, and vulnerability reporting.
|
|
141
131
|
- [pi](https://pi.dev/) — Official agent website.
|
|
132
|
+
- [Troubleshooting](../troubleshooting.md) — Cross-surface diagnosis and common problem resolution.
|
|
142
133
|
- [Documentation hub](../../README.md) — Task-oriented index for CLI, automation, agent, development, and security guides.
|
|
143
|
-
- [Project README](../../../README.md) — Product overview, installation, commands,
|
|
134
|
+
- [Project README](../../../README.md) — Product overview, installation, commands, and configuration.
|