@latentminds/pi-quotas 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Latent Minds Pty Ltd
+
+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,94 @@
+<p align="center">
+  <img src="docs/latent-minds@2x.png" alt="Latent Minds" width="320" />
+</p>
+
+# @latentminds/pi-quotas
+
+Quota monitoring for the [Pi coding agent](https://github.com/mariozechner/pi). Shows remaining usage and rate limits for Anthropic, OpenAI Codex, and GitHub Copilot — directly in your Pi session.
+
+## Screenshots
+
+| `/quotas` dashboard | Footer status |
+|---|---|
+| ![Quotas dashboard](docs/quotas-dashboard.png) | ![Footer status](docs/footer-status.png) |
+
+## Install
+
+**From npm** (recommended):
+
+```bash
+pi install npm:@latentminds/pi-quotas
+```
+
+**From source:**
+
+```bash
+git clone https://github.com/latentminds-ai/pi-quotas.git
+pi install ./pi-quotas
+```
+
+**Try without installing:**
+
+```bash
+pi -e npm:@latentminds/pi-quotas
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/quotas` | Combined quota dashboard for all providers |
+| `/anthropic:quotas` | Anthropic quotas only |
+| `/codex:quotas` | OpenAI Codex quotas only |
+| `/github:quotas` | GitHub Copilot quotas only |
+| `/quotas:settings` | Toggle individual features on or off |
+
+## Features
+
+### Quota dashboard
+
+Run `/quotas` to open a bordered TUI view showing all providers side by side, with progress bars, used/remaining counts, and reset times. Press `r` to refresh, `q` or `Esc` to close.
+
+### Footer status widget
+
+When your active model is from a supported provider, the Pi footer shows real-time quota headroom — updated every 60 seconds and on each turn. Colours shift from green → amber → red as usage climbs.
+
+### Quota warnings
+
+Automatic notifications when projected usage is on track to exceed limits before the window resets. Warnings escalate from `warning` → `high` → `critical` based on your consumption pace.
+
+### Per-feature toggles
+
+Use `/quotas:settings` to enable or disable:
+- Combined `/quotas` command
+- Per-provider commands (`/anthropic:quotas`, `/codex:quotas`, `/github:quotas`)
+- Footer status widget
+- Quota warning notifications
+
+Settings can be saved globally (`~/.pi/agent/extensions/quotas.json`) or per-project (`.pi/quotas.json`). Run `/reload` after changing command visibility.
+
+## Supported providers
+
+| Provider | Windows | Details |
+|----------|---------|---------|
+| Anthropic | 5h, 7d, per-model 7d, extra usage | Utilization percentages; optional overage budget in local currency |
+| OpenAI Codex | 5h, 7d, credits, spend cap | Rate-limit percentages; credit balance; spend-cap reached/OK |
+| GitHub Copilot | Premium/chat/completions per month | Remaining/entitlement counts with overage indicators |
+
+## Credentials
+
+pi-quotas reads existing Pi auth entries from `~/.pi/agent/auth.json`:
+
+- `anthropic` — Anthropic OAuth token
+- `openai-codex` — Codex access token (also reads `~/.codex/auth.json` for the account ID)
+- `github-copilot` — GitHub Copilot OAuth token (falls back to `gh auth token` if needed)
+
+No additional setup is required — if Pi can use the provider, pi-quotas can check its quotas.
+
+## Requirements
+
+- [Pi](https://github.com/mariozechner/pi) >= 0.61.0
+
+## License
+
+[MIT](LICENSE) © Latent Minds Pty Ltd

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@latentminds/pi-quotas",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "private": false,
+  "author": "Markus Strazds <markus@latentminds.ai>",
+  "keywords": ["pi-package", "pi-extension", "pi"],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/latentminds-ai/pi-quotas"
+  },
+  "pi": {
+    "extensions": [
+      "./src/extensions/core/index.ts",
+      "./src/extensions/command-quotas/index.ts",
+      "./src/extensions/usage-status/index.ts",
+      "./src/extensions/quota-warnings/index.ts"
+    ],
+    "image": "https://raw.githubusercontent.com/latentminds-ai/pi-quotas/main/docs/quotas-dashboard.png"
+  },
+  "files": ["src", "README.md", "LICENSE"],
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*",
+    "@mariozechner/pi-tui": "*"
+  },
+  "peerDependenciesMeta": {
+    "@mariozechner/pi-coding-agent": { "optional": true },
+    "@mariozechner/pi-tui": { "optional": true }
+  },
+  "devDependencies": {
+    "@mariozechner/pi-coding-agent": "0.61.0",
+    "@mariozechner/pi-tui": "0.61.0",
+    "@sinclair/typebox": "^0.34.48",
+    "@types/node": "^25.0.10",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/src/config.ts

@@ -0,0 +1,216 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import pkg from "../package.json" with { type: "json" };
+
+export type QuotasFeatureId =
+  | "quotasCommand"
+  | "providerCommands"
+  | "usageStatus"
+  | "quotaWarnings";
+
+export const QUOTAS_EXTENSIONS_REQUEST_EVENT =
+  "quotas:extensions:request" as const;
+export const QUOTAS_EXTENSIONS_REGISTER_EVENT =
+  "quotas:extensions:register" as const;
+export const QUOTAS_CONFIG_UPDATED_EVENT =
+  "quotas:config:updated" as const;
+
+export interface QuotasExtensionsRegisterPayload {
+  feature: QuotasFeatureId;
+}
+
+export interface QuotasConfig {
+  configVersion?: string;
+  quotasCommand?: boolean;
+  providerCommands?: boolean;
+  usageStatus?: boolean;
+  quotaWarnings?: boolean;
+}
+
+export interface ResolvedQuotasConfig {
+  configVersion: string;
+  quotasCommand: boolean;
+  providerCommands: boolean;
+  usageStatus: boolean;
+  quotaWarnings: boolean;
+}
+
+const DEFAULT_CONFIG: ResolvedQuotasConfig = {
+  configVersion: pkg.version,
+  quotasCommand: true,
+  providerCommands: true,
+  usageStatus: true,
+  quotaWarnings: true,
+};
+
+let pendingMigrationNotice = false;
+
+function markMigrationNoticePending(): void {
+  pendingMigrationNotice = true;
+}
+
+export function hasPendingMigrationNotice(): boolean {
+  return pendingMigrationNotice;
+}
+
+export function clearPendingMigrationNotice(): void {
+  pendingMigrationNotice = false;
+}
+
+class QuotasConfigStore {
+  private config: ResolvedQuotasConfig = DEFAULT_CONFIG;
+  private cwd = process.cwd();
+
+  private globalPath(): string {
+    return join(homedir(), ".pi", "agent", "extensions", "quotas.json");
+  }
+
+  private localPath(): string {
+    return join(this.cwd, ".pi", "quotas.json");
+  }
+
+  private resolve(input?: QuotasConfig): ResolvedQuotasConfig {
+    return {
+      configVersion: input?.configVersion ?? DEFAULT_CONFIG.configVersion,
+      quotasCommand: input?.quotasCommand ?? DEFAULT_CONFIG.quotasCommand,
+      providerCommands: input?.providerCommands ?? DEFAULT_CONFIG.providerCommands,
+      usageStatus: input?.usageStatus ?? DEFAULT_CONFIG.usageStatus,
+      quotaWarnings: input?.quotaWarnings ?? DEFAULT_CONFIG.quotaWarnings,
+    };
+  }
+
+  private async readConfig(path: string): Promise<QuotasConfig | undefined> {
+    try {
+      const data = JSON.parse(await readFile(path, "utf8")) as QuotasConfig;
+      return data;
+    } catch {
+      return undefined;
+    }
+  }
+
+  async load(cwd = process.cwd()): Promise<void> {
+    this.cwd = cwd;
+    const global = await this.readConfig(this.globalPath());
+    const local = await this.readConfig(this.localPath());
+    const merged = { ...global, ...local };
+    if (!global && !local) markMigrationNoticePending();
+    this.config = this.resolve(merged);
+  }
+
+  getConfig(): ResolvedQuotasConfig {
+    return this.config;
+  }
+
+  hasConfig(scope: "global" | "local"): boolean {
+    const path = scope === "global" ? this.globalPath() : this.localPath();
+    return existsSync(path);
+  }
+
+  async save(scope: "global" | "local", config: QuotasConfig): Promise<void> {
+    const path = scope === "global" ? this.globalPath() : this.localPath();
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, JSON.stringify(this.resolve(config), null, 2) + "\n", "utf8");
+    await this.load(this.cwd);
+  }
+}
+
+export const configLoader = new QuotasConfigStore();
+
+export async function seedQuotasConfigIfMissing(): Promise<void> {
+  if (configLoader.hasConfig("global") || configLoader.hasConfig("local")) return;
+  markMigrationNoticePending();
+  try {
+    await configLoader.save("global", DEFAULT_CONFIG);
+  } catch {
+    // ignore
+  }
+}
+
+export interface QuotasConfigUpdatedPayload {
+  config: ResolvedQuotasConfig;
+}
+
+export function emitQuotasConfigUpdated(pi: ExtensionAPI): void {
+  pi.events.emit(QUOTAS_CONFIG_UPDATED_EVENT, {
+    config: configLoader.getConfig(),
+  });
+}
+
+const FEATURE_META: Array<{
+  id: QuotasFeatureId;
+  label: string;
+  description: string;
+}> = [
+  {
+    id: "quotasCommand",
+    label: "Combined quotas command",
+    description: "Toggle the `/quotas` command",
+  },
+  {
+    id: "providerCommands",
+    label: "Provider quota commands",
+    description: "Toggle `/anthropic:quotas`, `/codex:quotas`, and `/github:quotas`",
+  },
+  {
+    id: "usageStatus",
+    label: "Usage status",
+    description: "Toggle footer quota status for the active provider",
+  },
+  {
+    id: "quotaWarnings",
+    label: "Quota warnings",
+    description: "Toggle projected-usage warning notifications",
+  },
+];
+
+export function registerQuotasSettings(
+  pi: ExtensionAPI,
+  getLoadedFeatures: () => Set<QuotasFeatureId>,
+): void {
+  pi.registerCommand("quotas:settings", {
+    description: "Configure quota extension settings",
+    handler: async (_args, ctx) => {
+      await configLoader.load(ctx.cwd);
+      const scopeChoice = await ctx.ui.select("Save settings to", [
+        "global",
+        "local",
+        "cancel",
+      ]);
+      if (!scopeChoice || scopeChoice === "cancel") return;
+      const scope = scopeChoice as "global" | "local";
+      const draft: ResolvedQuotasConfig = { ...configLoader.getConfig() };
+
+      while (true) {
+        const choices = FEATURE_META.map((feature) => {
+          const loaded = getLoadedFeatures().has(feature.id) ? "" : " (not loaded)";
+          const enabled = draft[feature.id] ? "enabled" : "disabled";
+          return `${feature.label}: ${enabled}${loaded}`;
+        });
+        choices.push("Save and exit", "Cancel");
+
+        const selected = await ctx.ui.select("Quotas Settings", choices);
+        if (!selected || selected === "Cancel") return;
+        if (selected === "Save and exit") {
+          await configLoader.save(scope, draft);
+          emitQuotasConfigUpdated(pi);
+          ctx.ui.notify(
+            "Quota settings saved. Run /reload to fully apply command visibility changes.",
+            "info",
+          );
+          return;
+        }
+
+        const feature = FEATURE_META.find((item) => selected.startsWith(item.label));
+        if (!feature) continue;
+        if (!getLoadedFeatures().has(feature.id)) {
+          ctx.ui.notify(`${feature.label} is not loaded by Pi in this session.`, "warning");
+          continue;
+        }
+        draft[feature.id] = !draft[feature.id];
+      }
+    },
+  });
+}

package/src/extensions/command-quotas/command.ts

@@ -0,0 +1,122 @@
+import type { ExtensionAPI, ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
+import {
+  QUOTAS_EXTENSIONS_REGISTER_EVENT,
+  QUOTAS_EXTENSIONS_REQUEST_EVENT,
+  configLoader,
+} from "../../config.js";
+import {
+  fetchAllProviderQuotas,
+  fetchProviderQuotas,
+  SUPPORTED_PROVIDERS,
+} from "../../lib/quotas.js";
+import type { QuotasResult, SupportedQuotaProvider } from "../../types/quotas.js";
+import { QuotasComponent } from "./components/quotas-display.js";
+import { getProviderCommandInfo } from "./provider-commands.js";
+
+type Snapshot = { provider: SupportedQuotaProvider; result: QuotasResult };
+
+async function openQuotaView(
+  title: string,
+  loadSnapshots: (force: boolean, signal?: AbortSignal) => Promise<Snapshot[]>,
+  ctx: ExtensionCommandContext,
+): Promise<void> {
+  const result = await ctx.ui.custom<null>((tui, theme, _kb, done) => {
+    const controller = new AbortController();
+    const component = new QuotasComponent(
+      theme,
+      tui,
+      title,
+      () => {
+        controller.abort();
+        done(null);
+      },
+      () => {
+        component.setState({ type: "loading" });
+        tui.requestRender();
+        void load(true);
+      },
+    );
+
+    async function load(force = false): Promise<void> {
+      const snapshots = await loadSnapshots(force, controller.signal);
+      if (controller.signal.aborted) return;
+      component.setState({ type: "loaded", snapshots });
+      tui.requestRender();
+    }
+
+    void load();
+
+    return {
+      render: (width: number) => component.render(width),
+      invalidate: () => component.invalidate(),
+      handleInput: (data: string) => component.handleInput(data),
+      dispose: () => {
+        controller.abort();
+        component.destroy();
+      },
+    };
+  });
+
+  if (result === undefined) {
+    const snapshots = await loadSnapshots(true);
+    ctx.ui.notify(JSON.stringify(snapshots, null, 2), "info");
+  }
+}
+
+export function registerQuotasCommands(pi: ExtensionAPI): void {
+  pi.registerCommand("quotas", {
+    description: "Display remaining quotas for Anthropic, Codex, and GitHub Copilot",
+    handler: async (_args, ctx) => {
+      if (!configLoader.getConfig().quotasCommand) {
+        ctx.ui.notify("/quotas is disabled. Re-enable it in /quotas:settings.", "warning");
+        return;
+      }
+      await openQuotaView(
+        "Provider Quotas",
+        (force, signal) => fetchAllProviderQuotas(ctx.modelRegistry.authStorage, { force, signal }),
+        ctx,
+      );
+    },
+  });
+
+  for (const provider of SUPPORTED_PROVIDERS) {
+    const info = getProviderCommandInfo(provider);
+    pi.registerCommand(info.commandName, {
+      description: `Display remaining ${info.title.toLowerCase()}`,
+      handler: async (_args, ctx) => {
+        if (!configLoader.getConfig().providerCommands) {
+          ctx.ui.notify(`${info.commandName} is disabled. Re-enable it in /quotas:settings.`, "warning");
+          return;
+        }
+        await openQuotaView(
+          info.title,
+          async (force, signal) => [
+            {
+              provider,
+              result: await fetchProviderQuotas(ctx.modelRegistry.authStorage, provider, { force, signal }),
+            },
+          ],
+          ctx,
+        );
+      },
+    });
+  }
+}
+
+export default async function (pi: ExtensionAPI) {
+  await configLoader.load();
+
+  const config = configLoader.getConfig();
+  if (config.quotasCommand || config.providerCommands) {
+    registerQuotasCommands(pi);
+  }
+
+  pi.events.on(QUOTAS_EXTENSIONS_REQUEST_EVENT, () => {
+    if (configLoader.getConfig().quotasCommand) {
+      pi.events.emit(QUOTAS_EXTENSIONS_REGISTER_EVENT, { feature: "quotasCommand" });
+    }
+    if (configLoader.getConfig().providerCommands) {
+      pi.events.emit(QUOTAS_EXTENSIONS_REGISTER_EVENT, { feature: "providerCommands" });
+    }
+  });
+}