@d3ara1n/pi-usage-block

Usage quota status bar block for Pi Coding Agent — displays quota for the currently active pi provider in the powerline.

Only shows usage when the active model's provider has a matching usage provider registered. Switching models automatically updates the display.

Install

pi install npm:@d3ara1n/pi-usage-block

Requires at least one usage provider plugin (e.g. @d3ara1n/pi-provider-zhipu-coding-plan).

Configuration

Powerline item

Add to your settings.json under powerline.customItems:

{
  "powerline": {
    "customItems": [{
      "id": "usage",
      "statusKey": "usage-block",
      "position": "right",
      "prefix": "⚡",
      "color": "accent"
    }]
  }
}

Refresh interval (api-source providers only)

Optionally set the poll interval (default: 60 seconds):

{
  "usageBlock": {
    "refreshIntervalMs": 30000
  }
}

Display format

ProviderName 🟢53% ↺3h34m

| Part | Meaning | |------|---------| | 🟢/🟡/🔴 | Usage threshold: < 70% / 70–90% / ≥ 90% | | 53% | Quota consumed | | ↺3h34m | Time until reset (only if provider supplies resetAt) |

Multiple quota windows from the same provider are shown side by side.

How it works

1. Tracks the active provider via ctx.model.provider (from session_start and model_select events)
2. Looks up a registered UsageProvider whose id matches the active provider key
3. Queries usage based on the provider's source type:
   • api: timer-based polling via fetchUsage()
   • headers: event-driven via after_provider_response + headerMapping
4. If no matching usage provider exists, the status bar is cleared

Building a Usage Provider

A usage provider is a plugin that registers itself with the shared usageRegistry from @d3ara1n/pi-usage-block-core.

This package is an npm dependency, not a pi extension. Add it to your provider plugin's package.json:

{
  "dependencies": {
    "@d3ara1n/pi-usage-block-core": "^1.0.0"
  }
}

Key convention

The usage provider's id must match the pi provider key (the first argument to pi.registerProvider()):

// pi provider registration — this key is the shared identity
pi.registerProvider("zhipu-coding", { ... });

// usage provider registration — same key
usageRegistry.register({ id: "zhipu-coding", ... });

This is how pi-usage-block knows which usage data belongs to the active provider.

Two data source types

api — Poll an external quota API

For providers whose usage quota lives behind a separate API endpoint (e.g. Zhipu, which doesn't include quota in response headers). pi-usage-block calls fetchUsage() on a timer.

import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
import { usageRegistry } from "@d3ara1n/pi-usage-block-core";

export default function (pi: ExtensionAPI) {
  pi.registerProvider("my-provider", {
    name: "My Provider",
    baseUrl: "https://api.example.com/v1",
    apiKey: "$MY_API_KEY",
    api: "openai-completions",
    models: [ ... ],
  });

  usageRegistry.register({
    id: "my-provider",           // must match pi.registerProvider key
    name: "My Provider",
    source: "api",
    async fetchUsage() {
      // Call your provider's quota API
      const res = await fetch("https://api.example.com/quota", {
        headers: { Authorization: `Bearer ${process.env.MY_API_KEY}` },
      });
      const data = await res.json();

      // Return one UsageWindow per quota window
      return [{
        period: "5h",
        used: data.percentage,     // amount consumed
        limit: 100,                // set to 100 if used is already a percentage
        unit: "tokens",
        resetAt: data.resetsAt     // optional Date
      }];
    },
  });
}

headers — Read usage from response headers

For providers that include rate-limit / usage info in HTTP response headers (e.g. OpenAI-style x-ratelimit-* headers). No code needed — just declare the mapping. pi-usage-block extracts data from each after_provider_response event automatically.

import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
import { usageRegistry } from "@d3ara1n/pi-usage-block-core";

export default function (pi: ExtensionAPI) {
  pi.registerProvider("openai-compatible", {
    name: "OpenAI Compatible",
    baseUrl: "https://api.example.com/v1",
    apiKey: "$MY_API_KEY",
    api: "openai-completions",
    models: [ ... ],
  });

  usageRegistry.register({
    id: "openai-compatible",      // must match pi.registerProvider key
    name: "My Provider",
    source: "headers",
    headerMapping: {
      // header name          → UsageWindow field
      "x-ratelimit-remaining-tokens": "used",
      "x-ratelimit-limit-tokens":     "limit",
      "x-ratelimit-reset-requests":   "resetAt",
    },
  });
}

Supported field keys in headerMapping:

| Key | Parsed as | |-----|-----------| | "used" | Number | | "limit" | Number | | "period" | Free-text label (string) | | "unit" | "requests" | "tokens" | "dollars" | | "resetAt" | Epoch seconds or milliseconds (auto-detected) |

Header lookup is case-insensitive.

UsageWindow fields

interface UsageWindow {
  period: string;                     // Label, e.g. "5h", "daily"
  used: number;                       // Amount consumed (or percentage if limit=100)
  limit: number;                      // Maximum (use 100 for percentage-only)
  unit: "requests" | "tokens" | "dollars";
  resetAt?: Date;                     // When quota resets
}

Return an empty array [] from fetchUsage() when data is unavailable (the provider is treated as offline).

Full API: @d3ara1n/pi-usage-block-core

import { usageRegistry, parseHeaderUsage } from "@d3ara1n/pi-usage-block-core";

// Register a provider
usageRegistry.register(provider: UsageProvider): void;

// Unregister
usageRegistry.unregister(id: string): void;

// Get a specific provider by id
usageRegistry.get(id: string): UsageProvider | undefined;

// Get all registered providers
usageRegistry.getAll(): UsageProvider[];

See @d3ara1n/pi-usage-block-core for the full type definitions.