46 lines
2.6 KiB
Markdown
46 lines
2.6 KiB
Markdown
# 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:
|
|
|
|
```ts
|
|
{ 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`.
|