pi-statusline/AGENTS.md

pi-statusbar Agent Guide

Purpose

pi-statusbar is a pi extension that replaces the built-in footer with a configurable two-row statusbar. It combines native footer-like modules with account usage modules for providers such as Claude/Anthropic, Codex/ChatGPT, and Z.ai.

Layout

• index.ts — Extension entrypoint, footer registration, refresh timers, debounced rendering, slash command, auth lookup.
• config.ts — User-facing layout/config. Prefer changing this for layout tweaks.
• types.ts — Shared config/module/state types.
• render.ts — Width allocation, ANSI-aware truncation, dim text rendering.
• utils.ts — Shared utility helpers (isRecord, toNumber).
• usage.ts — Provider-agnostic usage type definitions (report, limit, credential, etc.).
• modules/basic.ts — Directory, context, model, thinking, and cost modules.
• modules/usage.ts — Usage bars/text modules and color gradient rendering.
• usage/ — Provider usage fetchers adapted from oh-my-pi: https://github.com/can1357/oh-my-pi/tree/main/packages/ai/src/usage
• providers/openai-codex/constants.ts — OpenAI Codex base URL constant.

Conventions

• Keep user layout changes in config.ts when possible.
• Do NOT modify files in usage/ or providers/ without explicit user approval. These contain copied upstream provider logic. Always ask before changing them.
• Use composable module config instead of subtype strings. For usage, prefer:

{ type: "usage", window: "current", style: "line", grow: 1 }
{ type: "usage", window: "week", style: "text", parts: ["percent", "time"], separator: " | " }

• Usage data is preserved during refresh (no clearing before fetch) to prevent pop-in:
  • Old data stays visible until new data arrives.
  • When no data exists yet: line bars render like 0% usage, percent renders 0%, time renders ∞.
• Usage bar colors are a continuous green → yellow → red gradient derived from usage percentage, not hard thresholds.
• Rendering must remain ANSI-aware. If adding colors, update visibleWidth/truncate behavior as needed.
• Text modules and separators should remain dim; filled usage bars may use gradient color.
• Thinking level comes from pi.getThinkingLevel() and thinking_level_select, not ctx.thinkingLevel.
• rerender() is debounced via queueMicrotask — multiple rapid calls coalesce into a single render pass.
• All providers use the same refresh interval (REFRESH_MS).

Testing

• Reload pi with /reload after changes.
• Test narrow terminal widths after render changes.
• If terminal styling gets stuck during color work, reset with printf '\033[0m' or reset.