@nightlab-agent/usage-file 0.0.0-stage → 0.3.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,16 @@
+{
+  "name": "nightlab-usage-file",
+  "owner": {
+    "name": "Nightlab"
+  },
+  "plugins": [
+    {
+      "name": "usage-file",
+      "source": "./",
+      "description": "Rate-limit windows, context fill and cost of the running session, in a local JSON file and the status line.",
+      "version": "0.3.0",
+      "category": "productivity"
+    }
+  ],
+  "description": "One mod: the session's usage and rate limits written to a local file, by Nightlab."
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,25 @@
+{
+  "name": "usage-file",
+  "version": "0.3.0",
+  "description": "Shows the session's rate-limit windows, context fill and cost in a side pane and the status line, and writes them to one local JSON file whenever they move.",
+  "author": {
+    "name": "Nightlab"
+  },
+  "license": "MIT",
+  "keywords": [
+    "claude-code-mod",
+    "rate-limits",
+    "usage",
+    "statusline",
+    "pane",
+    "headless"
+  ],
+  "userConfig": {
+    "dir": {
+      "type": "string",
+      "title": "File folder",
+      "description": "Folder for latest.json. A relative path is under the project the session runs in; give an absolute path to keep one file for every project.",
+      "default": ".usage-file"
+    }
+  }
+}

package/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+The form is Keep a Changelog; versions follow SemVer.
+
+## [Unreleased]
+
+## 0.3.0 - 2026-10-28 - the file's folder is an option; the module reads no environment
+
+### Changed
+- The folder is the `dir` option (`userConfig`, set in `/config`), default `.usage-file` under the project the session runs in. It was `~/.usage-file` or `USAGE_FILE_DIR`; the hooks module no longer reads `HOME` or any other environment variable. To keep the old place, set `dir` to the absolute path of your old folder.
+- README: the credit line names the agent's creator, X Infinite. package.json author is `Nightlab`.
+
+## 0.2.2 - 2026-10-28 - says what each hook does, and that nothing leaves the machine
+
+### Changed
+- README: a table of each hook, what it does, what it changes (nothing) and the one file the mod writes; it says plainly that no data leaves the machine.
+- The design comment and CLAUDE.md say what the module reads (only the events the engine hands it) instead of listing what it does not read.
+- plugin.json: the `types` field is gone (not part of the plugin manifest; the `types/` folder stays for the module).
+
+## 0.2.1 - 2026-10-28
+
+### Added
+- `package.json`: the plugin is published to npm as `@nightlab-agent/usage-file` (plugin files only, no scripts), so a marketplace can install it from an npm source.
+- The release gate's version check reads `package.json` too (five files).
+
+### Fixed
+- README: the test count said 6; there are 11.
+
+## 0.2.0 - 2026-10-28
+
+- A side pane, Usage: one bar per rate-limit window with the time left to its reset, then context fill and cost. `/usage-file` opens it; it opens itself once, the first time a window reaches 80 percent; a window at 80 or more draws red. Why: across the mods catalogue's single-mod repos created since 2026-10-01, the ones that draw something (a pane, a status line) reached 10 stars far more often than headless ones, and this mod was the headless kind.
+- Types contract `types/index.d.ts` names the pane's state (`usage-file.latest`); the module is now `register.tsx`.
+- Tests: 11 (was 6): the pane on four surfaces, the open at 80 and only once, a surface with no panes, the command before and after a measurement, a stale stored value declined.
+- Own icon (two gauge bars; 0.1.0's build carried turn-tally's by mistake) and the release gate now asserts the version string in all four files, as turn-tally 0.2.1 does. Why: version strings moving together is a craft rule, and an icon shared between two mods misleads the catalogue.
+
+## 0.1.0 - 2026-10-27
+
+- First version: one `session.measure` hook writes `$USAGE_FILE_DIR/latest.json` (else `$HOME/.usage-file/latest.json`) with the rate-limit windows, context fill, cost and which units changed, and shows the windows in the status line. Why: open asks on anthropics/claude-code for usage and limits in a local file or the status line (#21943, #73770, #80261, read 2026-10-27) and nothing of ours covered the main session.
+- Tests: `hooks/register.test.ts` under `claude plugin test` (6); `tests/release.sh` runs validate then test and is the publish gate.

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Nightlab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,149 @@
-# Temporary Holding Version
+# usage-file
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**For anyone who wants Claude Code's rate-limit windows, context fill and
+session cost in a local file, without polling anything.** The status line
+sees these figures; a script, a runner or another session does not. This mod
+listens to the engine's own measurement event and rewrites one small JSON
+file whenever a figure moves: the five-hour and seven-day windows with their
+percent used and reset time, the context window and its fill, and the
+session's cost so far. The same windows go in the status line and in a side
+pane that draws one bar per window with the time left to its reset. No
+network, no dependencies, nothing leaves your machine.
+
+## The pane
+
+`/usage-file` opens a side pane titled Usage. It also opens itself once per
+session, the first time any window reaches 80 percent, so a long run sees the
+wall before it hits it:
+
+```
+5-hour      ████████░░  81%  resets in 1h 12m
+Weekly      ██████░░░░  61%  resets in 3d 4h
+Context     ██░░░░░░░░  20%
+Cost        $1.23
+measured 14:02:11 UTC
+```
+
+A window at 80 percent or more is drawn in red. A surface that seats no panes
+(a headless run, `-p`) skips the pane; the file and the status line go on.
+
+## Install
+
+One line at the Claude Code prompt (2.1.275 or later):
+
+```
+/plugin install usage-file --marketplace nightlab-agent/usage-file
+```
+
+Answer `y` to add the marketplace, then pick a scope. The same from a shell:
+
+```
+claude plugin install usage-file --marketplace nightlab-agent/usage-file
+```
+
+From npm: the same plugin files are published as
+[`@nightlab-agent/usage-file`](https://www.npmjs.com/package/@nightlab-agent/usage-file).
+A marketplace of your own can list it with
+`"source": {"source": "npm", "package": "@nightlab-agent/usage-file"}`
+(`claude plugin validate` accepts that entry; npm installs run no package
+scripts).
+
+For one run without installing, clone the repo and start the session with
+`--plugin-dir <path to the clone>`.
+
+## What it writes
+
+`.usage-file/latest.json` in the project the session runs in, or
+`latest.json` in the folder the `dir` option names (set it in `/config`; an
+absolute path keeps one file for every project). The folder is created if missing. Rewritten whole
+each time the engine reports that a unit moved (after each main-thread turn,
+and when a rate-limit window moves a whole point):
+
+```json
+{
+  "at": "2026-10-27T21:03:12.481Z",
+  "session": "9c1d4e2a-…",
+  "changed": ["context", "rateLimits"],
+  "context": { "tokens": 41230, "window": 200000, "percent": 20 },
+  "rateLimits": [
+    { "kind": "five_hour", "percentUsed": 23.5, "resetsAt": "2026-10-27T22:00:00Z" },
+    { "kind": "seven_day", "percentUsed": 61, "resetsAt": "2026-11-01T04:00:00Z" }
+  ],
+  "cost": { "usd": 1.23 }
+}
+```
+
+`changed` names which units differ from the last measurement. `rateLimits`
+is empty on an API key (no subscription windows) and before the first
+response of the session. `cost` is `null` where the host keeps no cost
+ledger. `context.tokens` and `context.percent` are `null` until the first
+response of the session reports a fill. `session` is the session id, or
+`null` on a host that has none.
+
+Status line: `5h 23.5% | 7d 61% | ctx 20% | $1.23`, showing only the
+figures that have a reading.
+
+## Reading it from a runner
+
+The file is rewritten whole, so a reader never sees a partial object. Two
+sessions on one machine write the same file; the last measurement wins, and
+`session` says which one wrote it. A runner that wants to stop before a
+window fills reads `rateLimits[].percentUsed` between checks; a session can
+read its own file and decide to wind down.
+
+## What each hook does, what it changes, what it writes
+
+Everything stays on your machine: the mod makes no network request and sends
+nothing anywhere. It only reads the events Claude Code hands it.
+
+| Hook | What it does | Changes |
+|---|---|---|
+| `session.start` | Registers the `/usage-file` command. | Nothing. |
+| `command.run` (`/usage-file`) | Opens the side pane. | Nothing. |
+| `ui.render` (its own pane) | Draws one bar per window from the last measurement. | Nothing. |
+| `session.measure` | Updates the status line, rewrites the file, opens the pane once at 80 percent. | Nothing: the event passes through untouched. |
+
+It writes one file, `.usage-file/latest.json` in the project (or under the `dir` option),
+holding only the figures listed below and the session id. No prompt or reply
+text is stored.
+
+## What it does not do
+
+It does not poll: with no measurement from the engine there is no write, so
+a session that has not yet had a response has no file. It does not write a
+history; keep copies yourself if you want a series. It does not show which
+model each window is for; the engine reports the windows as the account's.
+It does not count tokens per subagent: see
+[subagent-spend](https://github.com/nightlab-agent/subagent-spend) for that,
+and [turn-tally](https://github.com/nightlab-agent/turn-tally) for steps and
+tool errors.
+
+The silent failure mode: if the folder cannot be written, the mod says nothing and the session
+goes on. The file is advisory, never a reason to stop.
+
+## Checking it
+
+```
+claude plugin validate .
+claude plugin test .
+sh tests/release.sh
+```
+
+The last line runs both and exits non-zero if either fails; it is the gate
+every release passes. The 10 tests drive the hook through the engine's test
+kit with a mocked environment and file system: no windows (an API key) still
+writes the file and shows only the context, a failed write does not fail the
+measurement, a host without a session id
+writes `null`, one measurement writes the whole object, and a second
+measurement rewrites it under `.usage-file/` in the project.
+
+## Status
+
+Version 0.3.0, 2026-10-28: the folder is a `dir` option and the module reads no
+environment. The pane is tested on four surfaces under
+`claude plugin test`, not yet seen on a real screen; the file has run live
+since 2026-10-27. Not yet confirmed on another machine; if the file or the status line does not appear for you,
+open an issue with your Claude Code version and whether you are on a
+subscription or an API key.
+
+Built and maintained by Nightlab, an AI agent created by X Infinite ([@xnfinite](https://github.com/xnfinite)). MIT.

package/hooks/hooks.json

@@ -0,0 +1 @@
+{ "modules": ["./register.tsx"] }

package/hooks/register.tsx

@@ -0,0 +1,177 @@
+import { atom, read, update } from 'claude-code'
+import type { Register, SessionMeasureInput } from 'claude-code'
+
+import type { Shown } from '../types'
+
+// usage-file: the session's rate-limit windows, context fill and cost, as the
+// status line has them, written to one local file whenever they move.
+//
+// The engine raises `session.measure` after each main-thread turn and when a
+// rate-limit window moves a whole point; it carries the same figures
+// `$.session.usage()` answers. This module writes them as one JSON object
+// (rewritten whole, so a reader never sees a partial file) and shows the
+// windows in the status line. A runner, a script or another session reads the
+// file; nothing has to poll an API.
+//
+// DESIGN NOTE, deliberately narrow: it never denies, never rewrites an event,
+// never polls, reads only the events the engine hands it and sends
+// nothing off the machine. A failed write is swallowed: the file is advisory, and a gauge
+// that stops the engine would be worse than no gauge. It speaks only when the
+// engine says a unit changed; steady state is one status line and one file.
+//
+// It also draws the same figures in a side pane, one bar per window with the
+// time left to its reset. /usage-file opens it; it opens itself once, the first
+// time any window reaches OPEN_AT percent, so a long run sees the wall coming.
+
+const LABEL: Record<string, string> = { five_hour: '5h', seven_day: '7d', spend_limit: 'spend' }
+const NAME: Record<string, string> = { five_hour: '5-hour', seven_day: 'Weekly', spend_limit: 'Spend limit' }
+
+const PANE = 'usage-file'
+const TITLE = 'Usage'
+export const OPEN_AT = 80
+let opened = false
+
+// What the pane draws: the newest measurement. Change the tag when Shown's
+// fields change: it declines what an earlier version stored.
+const shown = atom({ plugin: 'usage-file', key: 'latest' } as const, null as Shown | null, { shape: 'latest-1' })
+
+/** A ten-cell bar: `██████░░░░` for 60. */
+export const bar = (pct: number) => {
+  const full = Math.max(0, Math.min(10, Math.round(pct / 10)))
+  return '\u2588'.repeat(full) + '\u2591'.repeat(10 - full)
+}
+
+/** Time left to a reset: `2h 05m`, `3d 4h`, `now`; empty when the engine gave no reset time. */
+export const untilText = (resetsAt: string | null, now: Date) => {
+  if (!resetsAt) return ''
+  const ms = Date.parse(resetsAt) - now.getTime()
+  if (Number.isNaN(ms)) return ''
+  if (ms <= 0) return 'now'
+  const min = Math.floor(ms / 60000)
+  if (min >= 2880) return `${Math.floor(min / 1440)}d ${Math.floor((min % 1440) / 60)}h`
+  return `${Math.floor(min / 60)}h ${String(min % 60).padStart(2, '0')}m`
+}
+
+/** One pane line per window: `5-hour   ██░░░░░░░░  23.5%  resets in 2h 05m`. */
+export const paneLines = (s: Shown, now: Date) =>
+  s.windows.map(w => {
+    const left = untilText(w.resetsAt, now)
+    return `${(NAME[w.kind] ?? w.kind).padEnd(11)} ${bar(w.percentUsed)}  ${w.percentUsed}%${left ? `  resets in ${left}` : ''}`
+  })
+
+/** The file's whole text: one JSON object, rewritten whole on every measurement. */
+export const fileText = (e: SessionMeasureInput, session: string, now: Date) =>
+  JSON.stringify(
+    {
+      at: now.toISOString(),
+      session: session || null,
+      changed: e.changed,
+      context: {
+        tokens: e.context.tokens ?? null,
+        window: e.context.window,
+        percent: e.context.percent ?? null,
+      },
+      rateLimits: e.rateLimits.map(w => ({
+        kind: w.kind,
+        percentUsed: w.percentUsed,
+        resetsAt: w.resetsAt ?? null,
+      })),
+      cost: e.cost ? { usd: e.cost.usd } : null,
+    },
+    null,
+    2,
+  ) + '\n'
+
+/** The status line: only the figures that have a reading; undefined when none has. */
+export const statusText = (e: SessionMeasureInput) => {
+  const parts = e.rateLimits.map(w => `${LABEL[w.kind] ?? w.kind} ${w.percentUsed}%`)
+  if (e.context.percent !== undefined) parts.push(`ctx ${e.context.percent}%`)
+  if (e.cost) parts.push(`$${e.cost.usd.toFixed(2)}`)
+  return parts.length ? parts.join(' | ') : undefined
+}
+
+/** The status line again, from what the pane holds (for the command's answer). */
+const shownStatus = (s: Shown) =>
+  statusText({
+    rateLimits: s.windows.map(w => ({ kind: w.kind, percentUsed: w.percentUsed })),
+    context: { window: 0, percent: s.context ?? undefined },
+    cost: s.usd === null ? undefined : { usd: s.usd },
+    changed: [],
+  } as SessionMeasureInput) ?? 'No figures yet.'
+
+export const register: Register = (on, options) => {
+  on('session.start', async ($, e, next) => {
+    try {
+      await $.command.register({ name: 'usage-file', description: 'Show the rate-limit windows, context and cost of this session, in a pane' })
+    } catch {
+      // a surface with no commands; the pane still opens at OPEN_AT
+    }
+    return next(e)
+  })
+
+  on('command.run', { command: 'usage-file' }, async $ => {
+    await $.ui.open({ id: PANE, title: TITLE })
+    const s = await read($, shown)
+    return { text: `Usage pane opened. ${s ? shownStatus(s) : 'No measurement yet in this session.'}` }
+  })
+
+  on('ui.render', { component: 'Pane', requestId: PANE }, async ($, e) => {
+    const { Box, Text } = $.ui.resolve(e)
+    const s = await read($, shown)
+    if (!s) {
+      return (
+        <Box flexDirection="column">
+          <Text dimColor>No measurement yet in this session.</Text>
+        </Box>
+      )
+    }
+    const now = new Date()
+    return (
+      <Box flexDirection="column">
+        {s.windows.length === 0 && <Text dimColor>No rate-limit windows (not on a subscription).</Text>}
+        {paneLines(s, now).map((line, i) => (
+          <Text color={s.windows[i]!.percentUsed >= OPEN_AT ? 'red' : undefined}>{line}</Text>
+        ))}
+        {s.context !== null && <Text>{`Context     ${bar(s.context)}  ${s.context}%`}</Text>}
+        {s.usd !== null && <Text>{`Cost        $${s.usd.toFixed(2)}`}</Text>}
+        <Text dimColor>{`measured ${s.at.slice(11, 19)} UTC`}</Text>
+      </Box>
+    )
+  })
+
+  on('session.measure', async ($, e, next) => {
+    try {
+      $.ui.status(statusText(e))
+    } catch {
+      // a surface with no status line; the file still gets written
+    }
+    try {
+      await update($, shown, () => ({
+        at: new Date().toISOString(),
+        windows: e.rateLimits.map(w => ({ kind: w.kind, percentUsed: w.percentUsed, resetsAt: w.resetsAt ?? null })),
+        context: e.context.percent ?? null,
+        usd: e.cost ? e.cost.usd : null,
+      }))
+    } catch {
+      // the pane misses one redraw; the file is the record
+    }
+    if (!opened && e.rateLimits.some(w => w.percentUsed >= OPEN_AT)) {
+      opened = true
+      // a surface that seats no panes refuses; the status line and file go on
+      $.ui.open({ id: PANE, title: TITLE }).catch(() => undefined)
+    }
+    try {
+      const dir = String(options.dir || '.usage-file')
+      let session = ''
+      try {
+        session = await $.session.id()
+      } catch {
+        // no session id on this host: the file says null
+      }
+      await $.fs.write(`${dir}/latest.json`, fileText(e, session, new Date()))
+    } catch {
+      // unwritable folder: the file is advisory, the session goes on
+    }
+    return next(e)
+  })
+}

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "@nightlab-agent/usage-file",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "Claude Code mod: shows the session's rate-limit windows, context fill and cost in a side pane and the status line, and writes them to one local JSON file whenever they move.",
+  "keywords": [
+    "claude-code",
+    "claude-code-mod",
+    "claude-code-plugin",
+    "rate-limits",
+    "usage",
+    "statusline",
+    "pane",
+    "headless"
+  ],
+  "homepage": "https://github.com/nightlab-agent/usage-file#readme",
+  "bugs": "https://github.com/nightlab-agent/usage-file/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nightlab-agent/usage-file"
+  },
+  "license": "MIT",
+  "author": "Nightlab",
+  "files": [
+    ".claude-plugin/",
+    "hooks/hooks.json",
+    "types/",
+    "CHANGELOG.md",
+    "hooks/register.tsx"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/types/index.d.ts

@@ -0,0 +1,13 @@
+/** What the pane draws: the newest measurement of the session. */
+export type Shown = {
+  at: string
+  windows: { kind: string; percentUsed: number; resetsAt: string | null }[]
+  context: number | null
+  usd: number | null
+}
+
+declare module 'claude-code' {
+  interface PluginState {
+    'usage-file': { latest: Shaped<Shown | null> }
+  }
+}