claude-usage-limits 1.6.1 → 1.7.1

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "usage-limits",
   "displayName": "Usage Limits",
-  "version": "1.6.1",
+  "version": "1.7.1",
   "description": "Puts your remaining Claude Code usage limit into Claude's context before every prompt, so it opens with what fits in the budget instead of starting work that gets cut off. Reports headroom as turns rather than percentages, prices a job before you start it, and detects your plan tier.",
   "author": {
     "name": "Ridelink",

package/.codex-plugin/plugin.json

@@ -0,0 +1,40 @@
+{
+  "name": "usage-limits",
+  "version": "1.7.1",
+  "description": "Reports how much of your Codex usage limit is left as turns of work rather than a percentage, prices a job before you start it, and counts the other agents sharing the same budget.",
+  "author": {
+    "name": "Ridelink",
+    "url": "https://github.com/ridelink0"
+  },
+  "homepage": "https://github.com/ridelink0/claude-code-usage-limits",
+  "repository": "https://github.com/ridelink0/claude-code-usage-limits",
+  "license": "MIT",
+  "keywords": [
+    "usage",
+    "limits",
+    "quota",
+    "rate-limit",
+    "budget",
+    "cost",
+    "planning",
+    "effort"
+  ],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Usage Limits",
+    "shortDescription": "How much usage limit is left, in turns of work",
+    "longDescription": "Reads the usage figures Codex already writes to disk and turns them into something you can plan with: which window binds, how many turns of work is left in it, and whether the job in front of you fits before the reset. Prices a job before you start it, notices when several agents are sharing one budget, and says what to land and what to leave when the limit is close. Everything is read locally; nothing is uploaded and no credentials are read.",
+    "developerName": "Ridelink",
+    "category": "Developer Tools",
+    "capabilities": [
+      "Read"
+    ],
+    "websiteURL": "https://github.com/ridelink0/claude-code-usage-limits",
+    "defaultPrompt": [
+      "How much usage do I have left?",
+      "Will this job fit before my limit resets?",
+      "Finish this using as little usage as possible"
+    ],
+    "brandColor": "#0C0A03"
+  }
+}

package/README.md

@@ -392,6 +392,63 @@ own account reports, so it is right on any tier, including ones that did not
 exist when this was written. The plan only decides which line of advice you
 get at the bottom of the report.
 
+## Codex
+
+It reads Codex's limits too, from the same repo and the same commands.
+
+Codex writes its session rollouts to `~/.codex/sessions`, one JSON object per
+line, and every model request appends a record carrying both the account meter
+and what that request cost in tokens. That is the same pair of things this tool
+needs from Claude Code, so the window arithmetic, the turn estimates, the
+forecast and the concurrent-session counting all work unchanged. Nothing is
+uploaded and no credentials are read.
+
+```
+npx claude-usage-limits --host codex
+npx claude-usage-limits --host codex --refresh
+npx claude-usage-limits codex-hook on
+```
+
+The host is detected, so `--host` is only needed on a machine with both
+installed. `--refresh` asks Codex itself for a live reading rather than the
+newest one it happened to write; it starts a short-lived `codex app-server` and
+takes about a second, and it is the Codex equivalent of `/usage`.
+
+As a plugin, Codex installs it from this repo directly:
+
+```
+codex plugin marketplace add https://github.com/ridelink0/claude-code-usage-limits
+codex plugin add usage-limits@usage-limits
+```
+
+### One thing is different, and it is worth being straight about
+
+Under Claude Code the budget line arrives on its own, because a plugin can ship
+hooks. Under Codex it does not, and not for want of trying:
+
+- Codex has the whole hook engine. The binary carries `UserPromptSubmit`,
+  `SessionStart`, `PreToolUse` and the rest, and `codex features list` reports
+  `hooks` as stable and enabled.
+- A plugin cannot ship one: `plugin_hooks` is reported as `removed`.
+- And on `codex-cli 0.151.0-alpha.7.2` nothing fires it. Tested with a hook
+  whose only job was to write a file, from `~/.codex/hooks.json`, from a
+  `[hooks]` table in `config.toml`, and from `~/.codex/hooks/`, in both
+  `codex exec` and the desktop app. The engine is present and inert.
+
+So `codex-hook on` installs two things. A marked block in `~/.codex/AGENTS.md`,
+which Codex reads at the top of every session and which is what actually works
+today; and the hooks themselves, ready for the build that runs them. `status`
+reports both, `off` removes both, and neither touches anything else in those
+files.
+
+The practical difference is that under Codex the budget is read deliberately,
+once at the start of a piece of work, rather than being handed to you before
+every prompt.
+
+Two smaller differences. There is no money column: Codex meters a share of an
+allowance and never quotes a price, so the percentages stand alone. And
+`lowpower` is Claude Code only, because it writes Claude's `settings.json`.
+
 ## Where it works
 
 Every surface of Claude Code on a machine shares one config directory, so
@@ -502,12 +559,17 @@ names, the formulas, and the rest of it.
 ## Layout
 
 ```
-.claude-plugin/plugin.json        plugin manifest
+.claude-plugin/plugin.json        plugin manifest, Claude Code
 .claude-plugin/marketplace.json   lets the repo serve itself
-skills/usage-limits/SKILL.md      what Claude reads
-skills/usage-limits/scripts/      usage.js, lowpower.js, brief.js
+.codex-plugin/plugin.json         plugin manifest, Codex
+agents/openai.yaml                how Codex lists the plugin
+skills/usage-limits/SKILL.md      what the agent reads
+skills/usage-limits/agents/       how Codex lists the skill
+skills/usage-limits/scripts/      usage.js, brief.js, pulse.js, codex.js,
+                                  host.js, lowpower.js, install-codex-hook.js
 skills/usage-limits/references/   the longer notes
-hooks/hooks.json                  runs brief.js before each prompt
+hooks/hooks.json                  runs brief.js before each prompt, and
+                                  pulse.js during long turns
 commands/check.md                 the /usage-limits:check command
 bin/cli.js                        the npx entry point
 tools/sync-version.js             keeps the manifest version in step
@@ -520,9 +582,10 @@ test/                             node --test, no dependencies
 node --test
 ```
 
-190 tests over the pricing, the window arithmetic, plan and credit detection,
-the status line, the before-prompt line, job forecasting, per-project
-attribution, the CLI, packaging, and the settings save/restore.
+248 tests over the pricing, the window arithmetic, plan and credit detection,
+the status line, the before-prompt line, the mid-turn pulse, job forecasting,
+per-project attribution, the Codex reader and its installer, the CLI,
+packaging, and the settings save/restore.
 
 ## Status
 

package/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Usage Limits"
+  short_description: "How much usage limit is left, in turns of work"
+  default_prompt: "Use Usage Limits before starting anything long, when the limit is getting close, when asked how much usage is left or whether a job fits before the reset, and when asked to work cheaply or stretch what is left."

package/bin/cli.js

@@ -5,20 +5,28 @@
 // under skills/usage-limits/scripts directly; this just gives npx users a
 // single command that reaches the same code.
 
-const HELP = `claude-usage-limits - how much Claude Code usage is left, and whether the job fits
+const HELP = `claude-usage-limits - how much agent usage is left, and whether the job fits
 
   claude-usage-limits                     the report
   claude-usage-limits --json              the same numbers, machine readable
   claude-usage-limits --status            one short line, for a status line
   claude-usage-limits --forecast 15       what a 15 turn job would cost
 
+  claude-usage-limits --host codex        read Codex's limits instead
+  claude-usage-limits --host codex --refresh   ask Codex for a live reading
+
   claude-usage-limits lowpower status     show the current effort setting
   claude-usage-limits lowpower on         lower effortLevel, remembering the old value
   claude-usage-limits lowpower on --effort medium --model sonnet
   claude-usage-limits lowpower off        put back exactly what was there
 
-Reads the usage figures Claude Code already caches locally, plus your session
-transcripts, to report the remaining headroom as turns of work. Nothing is
+  claude-usage-limits codex-hook status   is the Codex prompt hook installed
+  claude-usage-limits codex-hook on       install it into ~/.codex/hooks.json
+  claude-usage-limits codex-hook off      remove it
+
+Reads the usage figures the agent already keeps on disk, plus its own session
+history, to report the remaining headroom as turns of work. Works with Claude
+Code and with Codex; the host is detected, or state it with --host. Nothing is
 uploaded and no credentials are read.
 
   https://github.com/ridelink0/claude-code-usage-limits
@@ -42,6 +50,11 @@ function run(argv) {
     return Promise.resolve(lowpower.main(args.slice(1)));
   }
 
+  if (args[0] === 'codex-hook') {
+    const installer = require('../skills/usage-limits/scripts/install-codex-hook.js');
+    return Promise.resolve(installer.main(args.slice(1)));
+  }
+
   const usage = require('../skills/usage-limits/scripts/usage.js');
   return Promise.resolve(usage.main(args));
 }

package/commands/check.md

@@ -1,12 +1,17 @@
 ---
-description: Report how much Claude Code usage limit is left and how many turns of work it buys
+description: Report how much usage limit is left and how many turns of work it buys
 ---
 
 Run the usage report and read it back to me.
 
 1. Run `node "${CLAUDE_PLUGIN_ROOT}/skills/usage-limits/scripts/usage.js"`.
+   Under Codex, add `--host codex`, and add `--refresh` as well if the report
+   says the snapshot is old.
 2. Tell me which window is binding, how many turns of headroom is left, and
-   whether that window resets before the budget runs out.
+   whether that window resets before the budget runs out. If it reports a
+   runway in minutes, lead with that rather than the turn count: a count that
+   looks generous can be minutes away when several sessions are sharing the
+   budget.
 3. If I have already said what I want built, size it against the turns left
    and say whether it fits. If it does not fit, say what to cut rather than
    starting and hoping.

package/hooks/hooks.json

@@ -1,5 +1,5 @@
 {
-  "description": "Tells Claude how much usage budget is left, but only when it is tight enough to change what can be done.",
+  "description": "Tells Claude how much usage budget is left: once before each prompt, and again during long turns so the figure it is working from does not go stale.",
   "hooks": {
     "UserPromptSubmit": [
       {
@@ -11,6 +11,17 @@
           }
         ]
       }
+    ],
+    "PostToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/skills/usage-limits/scripts/pulse.js\"",
+            "timeout": 10
+          }
+        ]
+      }
     ]
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-usage-limits",
-  "version": "1.6.1",
+  "version": "1.7.1",
   "description": "Puts your remaining Claude Code usage limit into Claude's context before every prompt, so it opens with what fits in the budget instead of starting work that gets cut off. Reports headroom as turns rather than percentages, prices a job before you start it, and detects your plan tier.",
   "keywords": [
     "claude",
@@ -32,7 +32,9 @@
     "skills/",
     "commands/",
     "hooks/",
-    ".claude-plugin/"
+    "agents/",
+    ".claude-plugin/",
+    ".codex-plugin/"
   ],
   "engines": {
     "node": ">=18"
@@ -40,6 +42,6 @@
   "scripts": {
     "test": "node --test",
     "usage": "node bin/cli.js",
-    "version": "node tools/sync-version.js && git add .claude-plugin/plugin.json"
+    "version": "node tools/sync-version.js && git add .claude-plugin/plugin.json .codex-plugin/plugin.json"
   }
 }

package/skills/usage-limits/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: usage-limits
-description: Check how much of the Claude Code usage limit is left and plan the work to fit inside it. Use before starting anything long, when the 5-hour or weekly limit is getting close, when asked how much usage is left or whether there is enough left to finish, and when asked to work cheaply, burn fewer credits, or stretch the rest of the limit.
+description: Check how much usage limit is left in this agent (Claude Code or Codex) and plan the work to fit inside it. Use before starting anything long, when the 5-hour or weekly limit is getting close, when asked how much usage or quota is left, whether there is enough left to finish, whether a job fits before the reset, when to stop and hand off, and when asked to work cheaply, burn fewer credits, or stretch the rest of the limit.
 ---
 
 # usage-limits
@@ -18,6 +18,11 @@ node scripts/usage.js
 Paths here are relative to this skill's own directory, not the project you are
 working in. Run them from there, or prefix them with the skill's path.
 
+This works the same in Claude Code and in Codex. The host is detected from the
+environment; add `--host codex` or `--host claude` if a machine has both
+installed and the wrong one is picked. Everything below applies to both unless
+it says otherwise.
+
 It prints the real percentages and reset times from the CLI's own cache, plus
 a pace measured from the local session transcripts:
 
@@ -34,7 +39,13 @@ by what a turn has actually been costing over the last hour, on this account,
 at this effort level. Add `--json` when you want the raw fields.
 
 If it says no snapshot was found, run `/usage` once in Claude Code and try
-again. That populates the cache the script reads.
+again. That populates the cache the script reads. In Codex the equivalent is
+`node scripts/usage.js --refresh`, which asks Codex itself for a live reading
+instead of using the newest one it happened to write.
+
+`Left` is money, so it only appears under Claude Code. Codex meters a share of
+an allowance and never quotes a price, so its report has no money column and
+its percentages are exactly what they say they are.
 
 The last line names the plan (Pro, Max 5x, Max 20x, Team, Enterprise) and what
 it means for spending. Pro has the least room and the 5-hour window usually
@@ -68,12 +79,26 @@ not tight.
 **It fits only if nothing goes wrong.** Say so, switch to low power for the
 run, and reorder the work so the valuable part lands first.
 
-**It does not fit.** Say so before starting, in plain words. State that not
-all of it can be done in what is left, list what you are doing now and what
-you are leaving, and name the wall-clock time the window resets so the user
-knows when the rest can happen. Then do the part that fits, properly. Do not
-start and hope: half a feature, committed and working, beats a whole one
-abandoned mid-edit.
+**It does not fit.** Say so in one line before starting, and name the
+wall-clock time the window resets so the user knows when the rest can happen.
+Then do the whole thing anyway, ordered so that being cut off costs as little
+as possible.
+
+That is the part to get right, because the tempting move is the wrong one.
+Deciding on the user's behalf to do less of what they asked spends their
+request to protect a budget that expires regardless, and they did not ask for
+that trade. Scaling the work down is their call, not yours.
+
+So take the whole request, and make a cutoff cheap instead:
+
+- Order it so the most valuable part lands first.
+- Save at clean boundaries as you go, rather than once at the end.
+- Keep a short running note of what is done, what is next, and which files are
+  mid-change, so stopping at any moment loses nothing.
+
+Half a feature, committed and working, still beats a whole one abandoned
+mid-edit. The difference is that you get there by sequencing the work, not by
+refusing part of it.
 
 **The window resets first.** If the reset lands before the budget runs out,
 the limit is not the constraint. Say that and stop optimising for it.
@@ -222,6 +247,20 @@ to `low` is the largest per-turn saving available without changing model or
 scope. The file change applies to new sessions; for the session already
 running, `/effort low` takes effect immediately.
 
+Do not take that on trust: the report measures it. Under the model table it
+says how much of the output was reasoning and what that cost, for example
+
+```
+    Of that output, 74k was reasoning (40%, about $1.85), the part effort controls.
+```
+
+That share is the ceiling on what lowering effort can save, so read it before
+deciding whether the saving is worth the loss of reasoning. Forty per cent of
+output is worth acting on; four per cent is not, and turning effort down for it
+would cost more in rework than it saves. The same figure covers reasoning asked
+for per prompt, by `ultrathink` or any other means, because it is all the same
+spend on the same meter and the transcript does not separate them.
+
 The behaviour, which applies **even at xhigh or max effort**, because the
 effort setting does not control any of it:
 
@@ -245,16 +284,70 @@ one.
 
 ## 5. Checkpoint before the wall
 
-When the binding window is under roughly 15 percent, or under about ten turns
-of headroom, stop adding work and land what exists:
+When the binding window is under roughly 10 percent, or under about ten turns
+of headroom, keep working and start keeping the work landable:
 
-1. Commit or otherwise save the working state.
-2. Write `HANDOFF.md`: what is done, what is next, which files are mid-change,
-   what the next session should read first.
+1. Commit or otherwise save the working state, at every clean boundary rather
+   than once at the end.
+2. Keep `HANDOFF.md` current as you go: what is done, what is next, which files
+   are mid-change, what the next session should read first.
 3. Say when the window resets, as a clock time and not just a duration, plus
    what to run on the way back in.
 
-A handoff written with ten turns left is worth more than the tenth turn.
+The point of the handoff is that it costs almost nothing and removes the reason
+to stop early. With one in place, being cut off loses a turn instead of an
+afternoon, so there is no longer anything to buy by winding down.
+
+The one thing not to economise on is the handoff itself. Everything else can be
+picked up next session; a session that ends without one cannot.
+
+## Running under Codex
+
+Everything above works the same. The numbers come from a different place and
+one thing about how they arrive is different, and both are worth knowing.
+
+Codex writes its session rollouts to `~/.codex/sessions`, one JSON object per
+line, and every model request appends a record carrying both the account meter
+and what that request cost in tokens. So the two things this skill needs, the
+percentages and the pace, come out of the same files. Nothing is sent anywhere
+and no credentials are read.
+
+```
+node scripts/usage.js --host codex
+node scripts/usage.js --host codex --refresh
+```
+
+`--refresh` asks Codex itself for a live reading instead of the newest one it
+happened to write. It starts a short-lived `codex app-server`, takes about a
+second, and is the Codex equivalent of running `/usage` in Claude Code. Use it
+when the report says the snapshot is old, not routinely.
+
+The difference that matters: **there is no budget line in front of the prompt.**
+Claude Code lets a plugin ship hooks, so it gets one automatically. Codex will
+not load hooks from a plugin, and on current builds it does not run them from
+`~/.codex/hooks.json` or `config.toml` either, so nothing puts the figures in
+front of you before you start.
+
+What replaces it is an instruction, installed by:
+
+```
+node scripts/install-codex-hook.js on
+```
+
+That writes a marked block into `~/.codex/AGENTS.md` saying to run the report at
+the start of a substantial piece of work, and it stages the hooks for the build
+that runs them. `status` says what is installed, `off` removes both, and neither
+touches anything else in those files.
+
+So under Codex, read the budget deliberately rather than waiting to be told it.
+Once at the start of a piece of work, and again if the job grows or starts
+looping. The rest of this skill applies unchanged.
+
+The report has no money column under Codex. Codex meters a share of an
+allowance and never quotes a price, so the percentages are exactly what they
+say and there is no dollar figure to attach. `scripts/lowpower.js` is for Claude
+Code only: it writes Claude's `settings.json`, so it must not be run under
+Codex. Change model or effort through Codex's own controls instead.
 
 ## When to skip this skill
 
@@ -266,8 +359,12 @@ a turn, which is the thing it is trying to save.
 
 | Path | What it is |
 | --- | --- |
-| `scripts/usage.js` | The report. `--json` for raw fields, `--status` for a one-line readout that skips the transcript scan, `--forecast N` for what an N turn job would cost. |
+| `scripts/usage.js` | The report. `--json` for raw fields, `--status` for a one-line readout that skips the transcript scan, `--forecast N` for what an N turn job would cost, `--host codex` to read Codex's limits, `--refresh` to ask Codex for a live figure. |
 | `scripts/brief.js` | What the hook runs before each prompt. Not meant to be called by hand. |
-| `scripts/lowpower.js` | `status`, `on`, `off`. Restores what it replaced. |
+| `scripts/pulse.js` | What runs after tool calls, to re-check the budget during a long turn. Not meant to be called by hand. |
+| `scripts/host.js` | Works out which agent this is running inside, so one host's percentages are never reported against the other's turns. |
+| `scripts/codex.js` | The Codex reader: the meter and the pace out of `~/.codex/sessions`, plus the live `--refresh` call. |
+| `scripts/install-codex-hook.js` | `status`, `on`, `off`. Installs the Codex-side instruction, which Claude Code does not need. |
+| `scripts/lowpower.js` | `status`, `on`, `off`. Restores what it replaced. Claude Code only. |
 | `references/tactics.md` | Every lever that lowers cost, and why it works. |
 | `references/how-it-works.md` | Where the numbers come from and where they are soft. |

package/skills/usage-limits/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Usage Limits"
+  short_description: "Read the remaining usage limit and size the work to fit inside it"
+  default_prompt: "Use $usage-limits whenever the size of a job matters against the budget: before starting anything long, when asked how much usage is left, whether the work fits before the reset, when to stop, or how to finish using less. Run it once at the start of a piece of work rather than on every reply."