coding-usage-bar 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DuYing
+
+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

@@ -0,0 +1,220 @@
+# Coding Usage Bar
+
+[English](README.md) · [简体中文](README.zh-CN.md)
+
+**Claude Code and Codex usage monitoring in your macOS menu bar.** Track rolling plan limits across Claude Code, OpenAI Codex, GLM (Zhipu AI), DeepSeek, and MiniMax before a coding session hits the wall.
+
+[![npm](https://img.shields.io/npm/v/coding-usage-bar.svg)](https://www.npmjs.com/package/coding-usage-bar)
+[![CI](https://github.com/hanzhangzzz/coding-usage-bar/actions/workflows/test.yml/badge.svg)](https://github.com/hanzhangzzz/coding-usage-bar/actions/workflows/test.yml)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![platform](https://img.shields.io/badge/platform-macOS-lightgrey.svg?logo=apple)](#requirements)
+
+![Coding Usage Bar showing Claude Code, Codex, GLM, DeepSeek, and MiniMax plan usage in the macOS menu bar](docs/assets/hero.png)
+
+Coding Usage Bar does more than display quota percentages. It compares short rolling windows with the weekly budget and labels your pace as learning, under-burning, on track, over-burning, or close to a limit.
+
+Claude Code and Codex data stays local and is read from files those tools already produce. Provider API keys for GLM, DeepSeek, and MiniMax are stored only in `~/.coding-usage-bar/config.json` and sent directly to their respective quota APIs.
+
+## Quick Start
+
+```bash
+npx coding-usage-bar install
+coding-usage-bar doctor
+coding-usage-bar status
+```
+
+`install` creates a local runtime at `~/.coding-usage-bar/app`, a user-level CLI shim at `~/.local/bin/coding-usage-bar`, a launchd agent, a default config file, and a SwiftBar menu bar plugin. Make sure `~/.local/bin` is in your `PATH`.
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `coding-usage-bar install` | Install runtime, launchd checker, SwiftBar host/plugin, and Claude ingest when safe |
+| `coding-usage-bar uninstall` | Remove Coding Usage Bar managed launchd/status line/plugin config |
+| `coding-usage-bar doctor` | Check local Codex/Claude/GLM usage sources and notification backend |
+| `coding-usage-bar status` | Print the rolling windows reported by each account and their pacing state from `~/.coding-usage-bar/status.json` |
+| `coding-usage-bar status --json` | Print the same status snapshot written to `~/.coding-usage-bar/status.json` |
+| `coding-usage-bar status --refresh` | Re-collect local usage before printing status |
+| `coding-usage-bar menubar render` | Print SwiftBar-compatible menu text from `~/.coding-usage-bar/status.json` |
+| `coding-usage-bar menubar install` | Install the SwiftBar plugin wrapper |
+| `coding-usage-bar menubar uninstall` | Remove the Coding Usage Bar managed SwiftBar plugin |
+| `coding-usage-bar ingest claude-statusline` | Read Claude Code status line JSON from stdin and cache usage |
+
+## Install Behavior
+
+`coding-usage-bar install` is designed to be repeatable.
+
+- From `npx coding-usage-bar install` or `npx --no-install coding-usage-bar install`, it copies the current package into `~/.coding-usage-bar/app` through a temporary directory, then restarts launchd.
+- From a source checkout, `npm run build && npx --no-install coding-usage-bar install` installs the current local build.
+- From the installed shim `coding-usage-bar install`, it detects that it is already running from `~/.coding-usage-bar/app`, skips runtime self-copy, and still refreshes the CLI shim, SwiftBar plugin, and launchd agent.
+- The launchd job runs `~/.coding-usage-bar/app/dist/cli.js daemon --once` every 300 seconds.
+- The installer does not overwrite user-managed Claude Code status line scripts. If one already exists, it asks before installing a Coding Usage Bar wrapper around it.
+- Long-lived launchd, SwiftBar, and Claude wrapper commands prefer the stable `node` found in `PATH` (for example `/opt/homebrew/bin/node`) instead of a versioned Homebrew Cellar path. Set `CODING_USAGE_BAR_NODE=/absolute/path/to/node` before installing to override it, and rerun `coding-usage-bar install` after moving or replacing Node.
+
+## Claude Code Status Line
+
+If you do not have a Claude Code status line, `coding-usage-bar install` can create a minimal one.
+
+If you already have one, Coding Usage Bar will ask before changing Claude settings. When you answer `y`, it writes a Coding Usage Bar wrapper at `~/.coding-usage-bar/claude/statusline.sh`, saves the original command metadata, and updates `statusLine.command` so the wrapper runs first. The wrapper ingests Claude usage, then forwards the same input to your existing status line command. `coding-usage-bar uninstall` restores the original command.
+
+If you answer `n` or run in a non-interactive shell, Coding Usage Bar skips the status line update and prints manual setup instructions. Add this near the top of your own script:
+
+```bash
+input="$(cat)"
+printf "%s" "$input" | node "$HOME/.coding-usage-bar/app/dist/cli.js" ingest claude-statusline >/dev/null
+
+# Make the rest of your script read from "$input" instead of stdin.
+```
+
+Without this integration, Claude usage stays unavailable in Coding Usage Bar. Claude burn-rate analysis, Claude notifications, and Claude menu bar data will report `CLAUDE_INGEST_MISSING`; Codex usage is unaffected.
+
+## Codex
+
+Coding Usage Bar reads Codex `payload.rate_limits` from local `~/.codex` JSONL session data. It displays the windows the current account actually reports; some accounts expose both 5h and 7d windows, while others currently expose only 7d. If no rate-limit data exists, run Codex CLI or Codex App once and complete a normal interaction.
+
+## GLM (Zhipu AI)
+
+Coding Usage Bar calls the Zhipu AI quota API (`GET /api/monitor/usage/quota/limit`) to read 5h and 7d usage windows. You need to set `glm.apiKey` in `~/.coding-usage-bar/config.json`:
+
+```json
+{
+  "providers": ["codex", "claude", "glm"],
+  "glm": {
+    "baseUrl": "https://open.bigmodel.cn",
+    "apiKey": "your-api-key"
+  }
+}
+```
+
+Get your API key from the [Zhipu AI console](https://open.bigmodel.cn). Without this key, GLM monitoring will report `GLM_API_KEY_MISSING`.
+
+## DeepSeek
+
+Coding Usage Bar calls `GET https://api.deepseek.com/user/balance` to read your account balance. DeepSeek exposes balance rather than 5h/7d usage windows, so the menu bar shows `Available` or `Depleted` plus the currency amount. Set `deepseek.apiKey` in `~/.coding-usage-bar/config.json`:
+
+```json
+{
+  "providers": ["codex", "claude", "glm", "deepseek"],
+  "deepseek": {
+    "apiKey": "your-deepseek-api-key"
+  }
+}
+```
+
+Without this key, DeepSeek monitoring will report `DEEPSEEK_API_KEY_MISSING`.
+
+## MiniMax (M3)
+
+Coding Usage Bar calls `GET https://api.minimaxi.com/v1/token_plan/remains` to read 5h and 7d usage windows. MiniMax returns two signals per model: a count-based ratio (`current_*_usage_count` / `current_*_total_count`) for tiered models like `video`, and a credit-based `current_*_remaining_percent` (0-100) for the `general` model where the count stays at 0. Coding Usage Bar prefers the count ratio when total > 0 and otherwise derives used% as `100 - remaining_percent`. Set `minimax.apiKey` and (optionally) `minimax.region` in `~/.coding-usage-bar/config.json`:
+
+```json
+{
+  "providers": ["codex", "claude", "glm", "minimax"],
+  "minimax": {
+    "region": "cn",
+    "apiKey": "your-minimax-api-key"
+  }
+}
+```
+
+`region` defaults to `cn` (api.minimaxi.com); set it to `global` to use api.minimax.io. Without this key, MiniMax monitoring will report `MINIMAX_API_KEY_MISSING`.
+
+## Profiles
+
+Set `CODING_USAGE_BAR_PROFILE=high` for the more aggressive profile. The default is `low`.
+
+```bash
+CODING_USAGE_BAR_PROFILE=high coding-usage-bar status
+```
+
+Both profiles are constrained by the weekly budget. When a short window is reported, Coding Usage Bar does not treat filling every short window as the goal.
+
+## Provider Config
+
+`coding-usage-bar install` creates `~/.coding-usage-bar/config.json`:
+
+```json
+{
+  "providers": ["codex", "claude", "glm", "deepseek", "minimax"]
+}
+```
+
+Remove a provider from this list if you do not want Coding Usage Bar to monitor it. For one-off runs, `CODING_USAGE_BAR_PROVIDERS=codex coding-usage-bar status --refresh` also works.
+
+## Menu Bar
+
+The first menu bar implementation uses SwiftBar as a thin host. Coding Usage Bar still owns collection and state; the SwiftBar plugin only runs `coding-usage-bar menubar render` and reads `~/.coding-usage-bar/status.json`.
+
+`coding-usage-bar install` checks for SwiftBar and installs it with Homebrew cask when it is missing. It installs the Coding Usage Bar plugin into SwiftBar's configured `PluginDirectory`, not blindly into a hardcoded default directory, then opens SwiftBar.
+
+```bash
+coding-usage-bar menubar install
+```
+
+If SwiftBar is not installed, `coding-usage-bar doctor` will report it. If SwiftBar already has a custom plugin folder, Coding Usage Bar uses that folder.
+
+The compact menu bar title and dropdown use recognizable Provider marks for Codex, Claude Code, Zhipu AI, DeepSeek, and MiniMax alongside the rolling-window data (DeepSeek shows balance instead of windows):
+
+```text
+{Codex icon} 5H:14%,7D:67% │ {Claude icon} 5H:24%,7D:74% │ {GLM icon} 5H:36%,7D:7%
+```
+
+SwiftBar only supports one bitmap image on a single stable title item, so Coding Usage Bar renders the full title into one transparent PNG at render time. That bitmap keeps each provider marker next to its own usage segment while avoiding SwiftBar's multi-title rotation behavior. The dropdown stays read-only and uses SwiftBar-native symbols, badges, progress meters, reset time, target range, data age, and warnings. SwiftBar is a host dependency; `coding-usage-bar uninstall` removes the Coding Usage Bar plugin but does not uninstall SwiftBar itself.
+
+## Runtime Files
+
+| Path | Purpose |
+|------|---------|
+| `~/.coding-usage-bar/app/` | Stable runtime copy used by launchd, Claude ingest hints, and SwiftBar |
+| `~/.coding-usage-bar/config.json` | Provider selection, default `["codex", "claude", "glm", "deepseek", "minimax"]` |
+| `~/.coding-usage-bar/status.json` | Stable display-layer entry point |
+| `~/.coding-usage-bar/codex/latest.json` | Latest normalized Codex usage |
+| `~/.coding-usage-bar/claude/latest.json` | Latest normalized Claude usage after status line ingest |
+| `~/.coding-usage-bar/glm/latest.json` | Latest normalized GLM usage from Zhipu AI quota API |
+| `~/.coding-usage-bar/deepseek/latest.json` | Latest normalized DeepSeek balance from DeepSeek API |
+| `~/.coding-usage-bar/minimax/latest.json` | Latest normalized MiniMax 5h/7d usage from MiniMax API |
+| `~/.local/bin/coding-usage-bar` | CLI shim pointing at the stable runtime |
+| `~/Library/LaunchAgents/com.duying.coding-usage-bar.plist` | macOS launchd agent |
+| SwiftBar `PluginDirectory` / `coding-usage-bar.1m.js` | Menu bar plugin wrapper |
+
+## Notifications
+
+On macOS, Coding Usage Bar uses `terminal-notifier` when available and attaches a dynamic data card as the notification content image.
+
+The card shows provider, the available rolling-window usage, state label, target range, and reset countdown. This avoids asking users to infer meaning from a red/yellow icon.
+
+After an interactive install, Coding Usage Bar may ask whether you want to star the repository. The prompt defaults to **No** (`[y/N]`) and only uses an already authenticated GitHub CLI after explicit `y`/`yes` consent.
+
+If `terminal-notifier` is unavailable, Coding Usage Bar falls back to `osascript display notification`, which uses the system default notification appearance.
+
+See the [product and technical baseline](https://github.com/hanzhangzzz/coding-usage-bar/blob/main/plan.md) for the current design.
+
+## Why Coding Usage Bar?
+
+- **One menu bar for multiple coding providers:** Claude Code, Codex, GLM, DeepSeek, and MiniMax.
+- **Pacing, not just percentages:** short-window usage is evaluated against the weekly budget.
+- **Local-first:** Claude Code and Codex usage is read from local tool output, without a separate account or telemetry service.
+- **Visible but lightweight:** SwiftBar is only the host; collection and display state remain separated and auditable.
+- **Actionable warnings:** limit risk and burn-rate notifications include reset timing and current usage.
+
+## Requirements
+
+- macOS
+- Node.js 20 or newer
+- SwiftBar (the installer can install it through Homebrew)
+- Claude Code or Codex for local usage monitoring
+
+## Development
+
+```bash
+npm ci
+npm test
+npm run build
+npm pack
+```
+
+## License
+
+[MIT](LICENSE)
+
+Provider names and trademarks belong to their respective owners. Coding Usage Bar is an independent project and is not affiliated with or endorsed by Anthropic, OpenAI, Zhipu AI, DeepSeek, or MiniMax. Provider marks are used only for identification, are excluded from the MIT License, and are documented in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

package/README.zh-CN.md

@@ -0,0 +1,53 @@
+# Coding Usage Bar
+
+[English](README.md) · [简体中文](README.zh-CN.md)
+
+**在 macOS 菜单栏监控 Claude Code、Codex 和其他 AI 编程套餐用量。**
+
+![Coding Usage Bar 在 macOS 菜单栏展示多个 AI 编程 Provider 的套餐用量](docs/assets/hero.png)
+
+Coding Usage Bar 同时支持 Claude Code、OpenAI Codex、GLM（智谱 AI）、DeepSeek 和 MiniMax。它不只展示百分比，还会结合短周期和周额度判断当前节奏是偏慢、正常、偏快，还是已经接近限额。
+
+Claude Code 与 Codex 的数据直接读取它们在本机产生的文件，不需要额外登录，也不会上传使用记录。GLM、DeepSeek 和 MiniMax 的 API Key 只保存在 `~/.coding-usage-bar/config.json`，并直接请求对应 Provider 的额度接口。
+
+## 快速开始
+
+```bash
+npx coding-usage-bar install
+coding-usage-bar doctor
+coding-usage-bar status
+```
+
+安装器会创建：
+
+- `~/.coding-usage-bar/app` 稳定运行副本
+- `~/.local/bin/coding-usage-bar` 命令入口
+- 每 5 分钟采集一次用量的 launchd 任务
+- 写入 SwiftBar 当前插件目录的菜单栏插件
+
+## 核心特点
+
+- 一个菜单栏同时查看多个 AI 编程 Provider
+- 按账户实际下发的滚动窗口分析使用节奏；部分 Codex 账户当前只提供 7d
+- Claude Code、Codex 本地优先，不依赖额外遥测服务
+- 展示层只读稳定的 `status.json`，不会在打开菜单时临时访问数据源
+- 接近限额或燃烧节奏异常时发送系统通知
+
+完整命令、Provider 配置和实现边界请查看[英文 README](README.md)。
+
+交互式安装结束后，工具可能询问是否为 GitHub 仓库加 Star。该提示默认选择 No（`[y/N]`），只有用户明确输入 `y`/`yes` 且本机 GitHub CLI 已登录时才会修改远端账户状态。
+
+## 开发验证
+
+```bash
+npm ci
+npm test
+npm run build
+npm pack
+```
+
+## License
+
+[MIT](LICENSE)
+
+各 Provider 名称与商标归其权利人所有。本项目独立开发，与 Anthropic、OpenAI、智谱 AI、DeepSeek、MiniMax 无隶属或背书关系。Provider 标识仅用于识别，不适用项目 MIT License，详见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,16 @@
+# Third-Party Marks
+
+Coding Usage Bar includes the following provider marks solely to identify the services whose local usage data is being displayed:
+
+| Files | Provider |
+|---|---|
+| `assets/provider-claude.png` | Anthropic / Claude |
+| `assets/provider-codex.png` | OpenAI / Codex |
+| `assets/provider-glm.png`, `assets/provider-glm-dark.png` | Zhipu AI / GLM |
+| `assets/provider-deepseek.png` | DeepSeek |
+| `assets/provider-minimax.png` | MiniMax |
+| `assets/provider-marks.png` | Composite of the marks listed above |
+
+These marks and their associated names are owned by their respective holders. They are **not** licensed under this repository's MIT License. Their inclusion identifies the Provider whose usage is displayed and does not imply affiliation, sponsorship, or endorsement. No rights to the marks are granted by this project. Use of a mark remains subject to its owner's applicable brand rules, including the [OpenAI Design Guidelines](https://openai.com/brand/).
+
+All other Coding Usage Bar artwork named `coding-usage-bar-*` is project-owned and covered by the repository license.

package/dist/burn.d.ts

@@ -0,0 +1,3 @@
+import { BurnAnalysis, BurnProfile, ProviderUsage } from "./types.js";
+export declare function estimateConversionRate(samples: ProviderUsage[]): number | null;
+export declare function analyzeUsage(usage: ProviderUsage, samples: ProviderUsage[], profile?: BurnProfile, now?: Date): BurnAnalysis;

package/dist/burn.js

@@ -0,0 +1,164 @@
+import { findWindow } from "./usage.js";
+const PROFILE_FACTORS = {
+    low: { min: 0.8, max: 1.1 },
+    high: { min: 0.9, max: 1.35 },
+};
+function round(value) {
+    return Math.round(value * 10) / 10;
+}
+function minutesUntil(iso, nowMs) {
+    return Math.max(0, (Date.parse(iso) - nowMs) / 60_000);
+}
+const MIN_TOTAL_FIVE_DELTA = 5;
+export function estimateConversionRate(samples) {
+    const usable = [...samples]
+        .sort((left, right) => Date.parse(left.observedAt) - Date.parse(right.observedAt))
+        .map((sample) => ({
+        five: findWindow(sample, "five_hour")?.usedPercent,
+        seven: findWindow(sample, "seven_day")?.usedPercent,
+    }))
+        .filter((item) => {
+        return typeof item.five === "number" && typeof item.seven === "number";
+    });
+    // Trim to the longest tail where the 7d window is monotonically non-decreasing.
+    // Cross-session anomalies (Codex picking a different rollout file with stale
+    // rate_limits) show up as sharp drops in 7d; using only the most recent
+    // stable tail avoids contaminating the rate with the recovery ramp-up.
+    let startIdx = usable.length - 1;
+    while (startIdx > 0 && usable[startIdx - 1].seven <= usable[startIdx].seven) {
+        startIdx -= 1;
+    }
+    // If we stopped because of a drop, the sample we landed on is the anomalous
+    // low reading itself; skip it so its artificially low 7d baseline doesn't
+    // inflate the first delta of the tail.
+    if (startIdx > 0) {
+        startIdx += 1;
+    }
+    const recent = usable.slice(startIdx);
+    // Aggregate cumulative deltas across positive 5h advances. Using totals
+    // (not the median of per-pair rates) averages out integer-rounding noise:
+    // a single 5h tick is often 1% while 7d may not bump until several 5h ticks
+    // accumulate, so per-pair rates are dominated by zeros and over-estimates.
+    let totalFive = 0;
+    let totalSeven = 0;
+    for (let i = 1; i < recent.length; i += 1) {
+        const deltaFive = recent[i].five - recent[i - 1].five;
+        const deltaSeven = recent[i].seven - recent[i - 1].seven;
+        if (deltaFive > 0 && deltaSeven >= 0) {
+            totalFive += deltaFive;
+            totalSeven += deltaSeven;
+        }
+    }
+    if (totalFive < MIN_TOTAL_FIVE_DELTA) {
+        return null;
+    }
+    const value = totalSeven / totalFive;
+    return Number.isFinite(value) && value > 0 ? value : null;
+}
+function providerLabel(provider) {
+    return provider === "claude" ? "Claude" : provider === "glm" ? "GLM" : provider === "deepseek" ? "DeepSeek" : provider === "minimax" ? "MiniMax" : "Codex";
+}
+function messageForState(provider, state, fiveUsed, target) {
+    const label = providerLabel(provider);
+    if (state === "LIMIT_RISK") {
+        return `${label} usage is close to a plan limit. Consider switching provider or lowering intensity.`;
+    }
+    if (!target || fiveUsed === undefined) {
+        return `${label} usage is visible, but more samples are needed before dynamic burn advice is available.`;
+    }
+    if (state === "UNDER_BURN") {
+        return `${label} 5h usage is below target (${round(fiveUsed)}%, target ${round(target.min)}%-${round(target.max)}%).`;
+    }
+    if (state === "OVER_BURN") {
+        return `${label} 5h usage is above target (${round(fiveUsed)}%, target ${round(target.min)}%-${round(target.max)}%).`;
+    }
+    return `${label} burn pace is on track (${round(fiveUsed)}%, target ${round(target.min)}%-${round(target.max)}%).`;
+}
+export function analyzeUsage(usage, samples, profile = "low", now = new Date()) {
+    const fiveHour = findWindow(usage, "five_hour");
+    const sevenDay = findWindow(usage, "seven_day");
+    if (usage.balance && usage.windows.length === 0) {
+        const currency = usage.balance.currency === "CNY" ? "¥" : "$";
+        const balanceText = `${currency}${usage.balance.total}`;
+        return {
+            provider: usage.provider,
+            state: "RAW",
+            profile,
+            observedAt: usage.observedAt,
+            message: usage.balance.isAvailable
+                ? `${messageForState(usage.provider, "RAW")} balance: ${balanceText}`
+                : `${messageForState(usage.provider, "LIMIT_RISK")} balance depleted`,
+        };
+    }
+    if ((fiveHour?.usedPercent ?? 0) >= 90 || (sevenDay?.usedPercent ?? 0) >= 90) {
+        return {
+            provider: usage.provider,
+            state: "LIMIT_RISK",
+            profile,
+            observedAt: usage.observedAt,
+            fiveHour,
+            sevenDay,
+            message: messageForState(usage.provider, "LIMIT_RISK"),
+        };
+    }
+    if (!fiveHour || !sevenDay) {
+        const label = providerLabel(usage.provider);
+        const message = !fiveHour && sevenDay
+            ? `${label} 5h usage unavailable; showing 7d only.`
+            : fiveHour && !sevenDay
+                ? `${label} 7d usage unavailable; showing 5h only.`
+                : `${label} usage windows unavailable.`;
+        return {
+            provider: usage.provider,
+            state: "RAW",
+            profile,
+            observedAt: usage.observedAt,
+            fiveHour,
+            sevenDay,
+            message,
+        };
+    }
+    const conversionRate = estimateConversionRate(samples);
+    if (conversionRate === null) {
+        return {
+            provider: usage.provider,
+            state: "RAW",
+            profile,
+            observedAt: usage.observedAt,
+            fiveHour,
+            sevenDay,
+            message: messageForState(usage.provider, "RAW"),
+        };
+    }
+    const remainingSeven = Math.max(0, 100 - sevenDay.usedPercent);
+    const remainingSlots = Math.max(1, minutesUntil(sevenDay.resetsAt, now.getTime()) / 300);
+    const weeklyBudgetPerSlot = remainingSeven / remainingSlots;
+    const recommendedPercent = Math.min(100, weeklyBudgetPerSlot / conversionRate);
+    const factors = PROFILE_FACTORS[profile];
+    const target = {
+        minPercent: Math.min(100, recommendedPercent * factors.min),
+        maxPercent: Math.min(100, recommendedPercent * factors.max),
+        recommendedPercent,
+        conversionRate,
+    };
+    let state = "ON_TRACK";
+    if (fiveHour.usedPercent < target.minPercent) {
+        state = "UNDER_BURN";
+    }
+    else if (fiveHour.usedPercent > target.maxPercent) {
+        state = "OVER_BURN";
+    }
+    return {
+        provider: usage.provider,
+        state,
+        profile,
+        observedAt: usage.observedAt,
+        fiveHour,
+        sevenDay,
+        target,
+        message: messageForState(usage.provider, state, fiveHour.usedPercent, {
+            min: target.minPercent,
+            max: target.maxPercent,
+        }),
+    };
+}

package/dist/card.d.ts

@@ -0,0 +1,4 @@
+import { BurnAnalysis, RuntimePaths } from "./types.js";
+export declare function notificationCardSvg(analysis: BurnAnalysis): string;
+export declare function cardPathForAnalysis(analysis: BurnAnalysis, paths?: RuntimePaths): string;
+export declare function writeNotificationCard(analysis: BurnAnalysis, paths?: RuntimePaths): string;

package/dist/card.js

@@ -0,0 +1,79 @@
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { ensureDir } from "./fs-util.js";
+import { formatDurationUntil } from "./format.js";
+import { buildPaths } from "./paths.js";
+function escapeXml(value) {
+    return value
+        .replaceAll("&", "&")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;");
+}
+function providerLabel(provider) {
+    if (provider === "claude")
+        return "Claude";
+    if (provider === "glm")
+        return "GLM";
+    if (provider === "deepseek")
+        return "DeepSeek";
+    return "Codex";
+}
+function cardTheme(state) {
+    if (state === "UNDER_BURN") {
+        return { accent: "#f59e0b", label: "BURN LOW" };
+    }
+    if (state === "OVER_BURN") {
+        return { accent: "#7c3aed", label: "TOO FAST" };
+    }
+    if (state === "LIMIT_RISK") {
+        return { accent: "#dc2626", label: "LIMIT RISK" };
+    }
+    return { accent: "#16a34a", label: "ON TRACK" };
+}
+function targetLine(analysis) {
+    if (analysis.state === "LIMIT_RISK") {
+        return "near plan limit";
+    }
+    if (!analysis.target) {
+        return "learning baseline";
+    }
+    return `target ${Math.round(analysis.target.minPercent)}-${Math.round(analysis.target.maxPercent)}%`;
+}
+export function notificationCardSvg(analysis) {
+    const theme = cardTheme(analysis.state);
+    const used = analysis.fiveHour ? `${Math.round(analysis.fiveHour.usedPercent)}%` : "--";
+    const reset = analysis.fiveHour ? `${formatDurationUntil(analysis.fiveHour.resetsAt)} left` : "no reset data";
+    const title = `${providerLabel(analysis.provider)} 5h`;
+    const target = targetLine(analysis);
+    return `<svg xmlns="http://www.w3.org/2000/svg" width="420" height="180" viewBox="0 0 420 180">
+  <rect width="420" height="180" rx="28" fill="#111827"/>
+  <rect x="0" y="0" width="12" height="180" fill="${theme.accent}"/>
+  <text x="30" y="45" fill="#f9fafb" font-family="Arial, Helvetica, sans-serif" font-size="28" font-weight="700">${escapeXml(title)}</text>
+  <text x="30" y="116" fill="${theme.accent}" font-family="Arial, Helvetica, sans-serif" font-size="62" font-weight="800">${escapeXml(used)}</text>
+  <text x="214" y="64" fill="#f9fafb" font-family="Arial, Helvetica, sans-serif" font-size="24" font-weight="700">${escapeXml(theme.label)}</text>
+  <text x="214" y="104" fill="#d1d5db" font-family="Arial, Helvetica, sans-serif" font-size="22">${escapeXml(target)}</text>
+  <text x="214" y="138" fill="#9ca3af" font-family="Arial, Helvetica, sans-serif" font-size="21">${escapeXml(reset)}</text>
+</svg>
+`;
+}
+export function cardPathForAnalysis(analysis, paths = buildPaths()) {
+    const fileName = `${analysis.provider}-${analysis.state.toLowerCase()}.png`;
+    return path.join(paths.stateDir, "cards", fileName);
+}
+export function writeNotificationCard(analysis, paths = buildPaths()) {
+    const pngPath = cardPathForAnalysis(analysis, paths);
+    const svgPath = pngPath.replace(/\.png$/, ".svg");
+    ensureDir(path.dirname(pngPath));
+    fs.writeFileSync(svgPath, notificationCardSvg(analysis), "utf8");
+    try {
+        execFileSync("sips", ["-s", "format", "png", svgPath, "--out", pngPath], {
+            stdio: "ignore",
+        });
+        return pngPath;
+    }
+    catch {
+        return svgPath;
+    }
+}

package/dist/claude.d.ts

@@ -0,0 +1,9 @@
+import { ProviderUsage } from "./types.js";
+export declare function usageFromClaudeStatusLine(input: unknown): ProviderUsage;
+export declare function readStdin(): Promise<string>;
+export declare function readClaudeSettings(file: string): Record<string, unknown> | null;
+export declare function getClaudeStatusLineCommand(settings: Record<string, unknown> | null): string | null;
+export declare function claudeStatusLineHasIngest(command: string | null, options: {
+    appCliPath: string;
+    managedScriptPath?: string;
+}): boolean;