@hank-warren/pi-statusline 0.7.2 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @hank-warren/pi-statusline
 
+## 0.8.0
+
+### Minor Changes
+
+- 1035138: Add custom items: user-defined command segments rendered after the usage meters.
+
+  Each entry in the new `customItems` setting runs a shell command, hands it JSON
+  about the session on stdin, and renders the first line of its stdout as a
+  statusline segment — the same contract Claude Code's `statusLine` uses, so a
+  script written for it ports over. Items refresh at session start, at each turn
+  end, and on an optional `refreshInterval` timer; one run per item at a time,
+  with a timeout, a failure grace period before a stale value is dropped, and
+  output sanitized to SGR colors so a command cannot corrupt the frame.
+
+  `/statusline` gains a **Custom items** toggle and a **Custom item list** submenu
+  that enables or disables each item and shows why one is not rendering. Commands
+  stay in the settings file, and entries this version cannot parse — an unknown
+  `type`, an unrecognised key — are preserved verbatim on write rather than
+  dropped, so toggling an unrelated setting can never delete a configured item.
+
+## 0.7.3
+
+### Patch Changes
+
+- d0c46a5: Resolve `auth.json`, the usage cache and `statusline-settings.json` through Pi's agent directory (`PI_CODING_AGENT_DIR`) instead of a hardcoded `~/.pi/agent`. Behaviour is unchanged for a normal install; a session started with a scratch agent dir no longer reads the real credentials or writes the real usage cache. `engines.node` now states Pi's own floor, `>=22.19.0`.
+
 ## 0.7.2
 
 ### Patch Changes

package/README.md

@@ -10,7 +10,7 @@ gpt-5.6-sol | pi-extensions:main* ⇣1 | 40k/1.0m |  97·54  80
 
 ## What it shows
 
-- **Line 1** — active model ID, optionally the provider of that model, current directory basename and Git branch, current context usage/window, and subscription usage headroom (see below). A yellow `*` marks a dirty checkout and `⇣N` shows how many commits it is behind its locally known upstream ref. Unknown context usage is rendered as `?/<window>` until Pi can provide an estimate. Exceptional prompt-cache hits trigger the celebration described below.
+- **Line 1** — active model ID, optionally the provider of that model, current directory basename and Git branch, current context usage/window, subscription usage headroom (see below), and any [custom items](#custom-items) you configure. A yellow `*` marks a dirty checkout and `⇣N` shows how many commits it is behind its locally known upstream ref. Unknown context usage is rendered as `?/<window>` until Pi can provide an estimate. Exceptional prompt-cache hits trigger the celebration described below.
 - **Worktree lines** — when the session works in or sends tool calls into linked worktrees, one line shows the same branch/dirty/behind state for each worktree plus its associated PR number.
 - **Final line** — the full Pi session ID.
 
@@ -22,6 +22,7 @@ Colors come from a selectable [theme](#themes), with context warning thresholds.
 
 - **Theme** — the color palette, cycled with Enter or Space. See [Themes](#themes).
 - **Cache celebration** — `off` or one of five badge animations, cycled with Enter or Space and previewed live in the statusline below. See [Animation styles](#animation-styles).
+- **Custom item list** — below the alias row: enables or disables each configured item, shows what it is currently doing, and **Add custom item…** hands the job to the agent. A **Custom items** `on`/`off` row for the whole segment appears once at least one item is configured. See [Custom items](#custom-items).
 - **Model**, **Provider**, **Directory & git**, **Context**, **Subscription usage**, **Worktree line**, **Session ID line** — `on`/`off`, cycled with Enter or Space. **Provider** is the only one that starts `off`; it shows the provider id exactly as Pi reports it, so a [pi-multi-login](../pi-multi-login) alias renders as `anthropic-team` and names the login actually spending — something a model id like `claude-opus-5` never carries. With no model, or a model reporting no provider, the segment is simply absent. Disabled segments are dropped from line 1 without leaving a stray ` | ` separator; hiding the worktree line also stops its `git`/`gh` polling, and hiding usage stops the usage poller. With every element off the footer collapses to a single blank row.
 - **Worktree root** — the directory whose immediate children are tracked as session worktrees (default `~/repos/worktrees`). `~` and `$HOME` are expanded; a relative path is rejected and the previous value kept.
 - **Repo aliases** — short display names for repositories on the worktree line. Enter edits the selected `repo → alias` pair, `d` deletes it, and `Add alias…` creates one from a `repo=alias` line.
@@ -101,6 +102,166 @@ An account answering `429` is parked for fifteen minutes (tracked per account, s
 
 Requires a Nerd Font new enough to include the codicon brand glyphs (v3.5.0+); older fonts render them as replacement boxes.
 
+## Custom items
+
+Everything above is built in. **Custom items** are the escape hatch: each one runs a shell command, and its output becomes a segment on line 1, after the usage meters and before the worktree line. This is how a personal metric — a self-hosted quota pool, a deploy status, an on-call flag — gets onto the statusline without being packaged for everybody else.
+
+The contract is deliberately [Claude Code's status line](https://docs.claude.com/en/docs/claude-code/statusline) contract: a command, JSON about the session on **stdin**, one line on **stdout**, ANSI colors passed through. A script written for Claude Code runs here mostly unchanged (see [differences](#differences-from-claude-codes-status-line)).
+
+There is no default item, and with an empty list the feature costs nothing: no process is spawned and no timer runs.
+
+### Adding one
+
+The quickest way is `/statusline` → **Custom item list** → **Add custom item…**. Type one line describing what the item should show (or press Enter and let the agent ask), and the menu closes and sends the agent a message carrying the whole contract below plus the settings path. The agent writes the script, tests it the way the statusline will run it, adds the entry, and tells you to reopen `/statusline`. That message is the only place the contract is injected — it costs nothing until you ask for an item, which is why this package ships no skill for it.
+
+By hand, items live under `customItems` in `~/.pi/agent/statusline-settings.json`. The file is not created for you until a setting is changed, so write it if it is absent:
+
+```json
+{
+  "customItems": [
+    {
+      "id": "cpa",
+      "command": "~/bin/cpa-quota --statusline",
+      "refreshInterval": 60,
+      "timeout": 5
+    }
+  ]
+}
+```
+
+| Field | Required | Meaning |
+|---|---|---|
+| `command` | yes | Shell command line. Run through `sh -c` (`cmd /d /s /c` on Windows), so pipes, `$VARS`, and `~` work. |
+| `id` | no | Stable name, used by the `/statusline` submenu and in error messages. Defaults to `item-1`, `item-2`, …; duplicates get a `#2` suffix. |
+| `refreshInterval` | no | Seconds between forced re-runs, on top of the event-driven ones. Omit for event-driven only. |
+| `timeout` | no | Seconds before the command is killed. Default `5`, capped at `30`. |
+| `enabled` | no | `false` hides the item and stops it running. This is the one field `/statusline` writes. |
+| `type` | no | Accepted for entries pasted from Claude Code, where it is `"command"`. Any other value is preserved but not run. |
+
+Items render in configuration order, each as its own ` | `-separated segment.
+
+**The file is read when a session starts and whenever `/statusline` opens.** After editing it by hand, open `/statusline` and press Esc to load the change into the running session; nothing watches the file.
+
+### When a command runs
+
+- at session start,
+- at the end of every turn,
+- every `refreshInterval` seconds, if set.
+
+A run is skipped while that item's previous run is still going, so a slow command degrades to a lower refresh rate instead of piling up processes. Two runs of the same item are never closer than one second, whatever triggers them. The timer only exists if some enabled item asked for one, ticks at the shortest interval among them, and is `unref`ed and stopped with the footer — turning **Custom items** off in `/statusline` stops all of it.
+
+Use `refreshInterval` for anything whose value moves on a wall clock rather than on your turns: a quota pool refills while you are reading a diff, and an idle session would otherwise show the number from your last turn.
+
+### What the command receives
+
+One JSON object on stdin, and `COLUMNS` in the environment (the footer's current width, exactly as Claude Code provides it):
+
+```json
+{
+  "version": 1,
+  "session_id": "019fafa7-29c0-7e99-9f82-5794d5721848",
+  "cwd": "/home/hank/repos/pi-extensions",
+  "model": { "id": "gpt-5.6-sol", "provider": "openai-codex" },
+  "git": { "branch": "main", "dirty": false, "behind": 0 },
+  "context_window": { "used_tokens": 40000, "context_window_size": 1000000, "used_percentage": 4 },
+  "usage_remaining": {
+    "claude": { "five_hour": 97, "seven_day": 54, "scoped_weekly": 24 },
+    "codex": { "five_hour": 92, "weekly": 99 }
+  }
+}
+```
+
+`git` is `null` outside a repository, `usage_remaining.claude` / `.codex` are `null` without credentials for that provider, and `context_window.used_tokens` is `null` before Pi can estimate it. Handle absence rather than assuming a field.
+
+### What the command should print
+
+The **first line of stdout** becomes the segment. Anything after it is ignored — this is a segment on a shared line, not a row the item owns.
+
+- **Colors work.** SGR escapes (`\033[32m`) pass through. Every other escape sequence is stripped, because a cursor move or an erase-line would corrupt the frame the footer is drawn into. Control characters go too, and tabs become spaces.
+- **Print nothing to hide.** Empty output is a valid answer, not a failure: it is how an item shows itself only when it has something to say.
+- **Output is capped** at 120 characters before the statusline's own truncation.
+- **Exit non-zero to signal failure.** The first line of stderr is kept and shown in `/statusline`.
+
+### When a command fails
+
+Failures never reach the agent — the statusline is best-effort and stays silent. A failing item keeps its last good value for up to three consecutive failures, then drops it. That grace is deliberate in both directions: one blip (a laptop between networks) should not blank a working display, and a value that has quietly gone stale is worse than an empty slot, because the number stays plausible while describing a world that has moved on.
+
+To see what an item is doing, open `/statusline` → **Custom item list**. Each row shows its current value, or why there isn't one: `disabled`, `missing command`, `exit 3: …`, `timed out after 5s`, `empty output`, or `no value yet`. Enter toggles an item on or off; commands themselves are edited in the file.
+
+### Keep it fast
+
+The command runs on the footer's schedule, so treat it like a prompt segment. Do slow work elsewhere — a systemd timer, a cron job, a background daemon — and let the item read the result:
+
+```json
+{ "id": "quota", "command": "cat /run/user/1000/quota.txt 2>/dev/null", "refreshInterval": 30 }
+```
+
+If the item must do the work itself, cache it keyed by `session_id` from the payload (a PID changes every run and defeats the cache).
+
+### Examples
+
+A clock, the smallest possible item:
+
+```json
+{ "id": "clock", "command": "date +%H:%M", "refreshInterval": 30 }
+```
+
+Kubernetes context, colored, hidden when unset:
+
+```json
+{ "id": "k8s", "command": "kubectl config current-context 2>/dev/null | sed 's/.*/\\x1b[35m&\\x1b[0m/'", "refreshInterval": 300 }
+```
+
+Pooled subscription headroom across several accounts behind a self-hosted gateway — the case this feature was built for, where the built-in meters cannot help because they read *this* session's credential, not a round-robin pool:
+
+```bash
+#!/usr/bin/env bash
+# ~/bin/cpa-quota --statusline
+curl -sf -m 3 -H "Authorization: Bearer $CPAMP_ADMIN_KEY" \
+  "$CPAMP_URL/v0/management/auth-files" |
+  jq -r '[.files[] | select(.disabled != true) | .quota.signals]
+         | map(select(."X-Codex-Primary-Used-Percent"))
+         | if length == 0 then empty else
+             "\u001b[36mcpa\u001b[0m " +
+             (map(100 - (."X-Codex-Primary-Used-Percent"|tonumber)) | add / length | floor | tostring) + "/" +
+             (map(100 - (."X-Codex-Secondary-Used-Percent"|tonumber)) | add / length | floor | tostring)
+           end'
+```
+
+Using the session payload — warn only when this session's model is on a nearly exhausted account:
+
+```json
+{ "id": "low", "command": "jq -r '.usage_remaining.codex.five_hour // 100 | if . < 15 then \"\\u001b[31mLOW \\(.)%\\u001b[0m\" else empty end'" }
+```
+
+### Testing an item
+
+The command is an ordinary program, so run it the way the statusline does:
+
+```bash
+echo '{"model":{"id":"gpt-5.6-sol"},"usage_remaining":{"codex":{"five_hour":22,"weekly":55}}}' \
+  | COLUMNS=120 sh -c '~/bin/cpa-quota --statusline'
+```
+
+If that prints one short line, the item will render.
+
+### Differences from Claude Code's status line
+
+| | Claude Code | pi-statusline |
+|---|---|---|
+| Scope | one command owns the whole status line | many items, each a segment after the built-in ones |
+| Config | `statusLine` object in `settings.json` | `customItems` array in `statusline-settings.json` |
+| Multi-line output | each line becomes a row | only the first line is used |
+| Rate-limit fields | `rate_limits.*.used_percentage` | `usage_remaining.*` — **remaining**, the inverse |
+| Refresh | every assistant message, 300 ms debounce | session start, turn end, optional `refreshInterval` |
+| Width | `COLUMNS` and `LINES` | `COLUMNS` |
+
+The naming of `usage_remaining` is the one difference worth checking when porting: reading a *remaining* percentage as a *used* one silently inverts the meaning, and a green bar that means "nearly out" is worse than no bar.
+
+### A note on trust
+
+An item is a command that runs automatically in every TUI session, so `customItems` is executable configuration, exactly like Claude Code's `statusLine` or a shell rc file. Write there is code execution: keep `~/.pi/agent/statusline-settings.json` under your own account (Pi writes it `0600`), and treat an item copied from the internet with the same suspicion as a shell script from the internet.
+
 ## Cache-hit celebration
 
 Whenever one assistant response reaches a prompt-cache hit rate of at least 96%, a temporary module is appended after context usage for about two seconds:
@@ -168,6 +329,10 @@ Both repair layers are skipped entirely in regular TUI mode, which reprints its
 pi install npm:@hank-warren/pi-statusline
 ```
 
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for release history.
+
 ## License
 
 MIT — see [LICENSE](LICENSE).

package/cache-celebration.ts

@@ -2,7 +2,7 @@ export const CACHE_HIT_THRESHOLD = 0.96;
 export const CACHE_CELEBRATION_FRAME_INTERVAL_MS = 60;
 export const CACHE_CELEBRATION_DURATION_MS = 2_000;
 
-export interface CacheUsage {
+interface CacheUsage {
 	input: number;
 	cacheRead: number;
 	cacheWrite: number;
@@ -13,11 +13,11 @@ export interface CacheCelebrationSnapshot {
 	frame: number;
 }
 
-export interface CacheCelebrationTarget {
+interface CacheCelebrationTarget {
 	start(percent: number): void;
 }
 
-export interface CacheCelebrationControllerOptions {
+interface CacheCelebrationControllerOptions {
 	frameIntervalMs?: number;
 	durationMs?: number;
 	now?: () => number;

package/celebration-preview.ts

@@ -7,7 +7,7 @@ import type { SettingsListTheme } from "@earendil-works/pi-tui";
 /** Percentage shown by the settings-menu preview badge. */
 export const PREVIEW_PERCENT = 96;
 
-export interface CelebrationPreviewOptions {
+interface CelebrationPreviewOptions {
 	frameIntervalMs?: number;
 	schedule?: (callback: () => void, intervalMs: number) => unknown;
 	cancel?: (handle: unknown) => void;

package/celebration-styles.ts

@@ -11,13 +11,13 @@ import type { StatuslinePalette } from "./themes.ts";
 const RESET = "\x1b[0m";
 const BOLD = "\x1b[1m";
 
-export interface Rgb {
+interface Rgb {
 	r: number;
 	g: number;
 	b: number;
 }
 
-export const fgCode = ({ r, g, b }: Rgb): string =>
+const fgCode = ({ r, g, b }: Rgb): string =>
 	`\x1b[38;2;${Math.round(r)};${Math.round(g)};${Math.round(b)}m`;
 
 /** Parse an SGR true-colour prefix back into channels; anything else reads as white. */
@@ -68,7 +68,7 @@ function hue(degrees: number): Rgb {
 }
 
 /** Colour every character of `badge` for one frame. */
-export type CelebrationStyle = (badge: string, frame: number, palette: StatuslinePalette) => string;
+type CelebrationStyle = (badge: string, frame: number, palette: StatuslinePalette) => string;
 
 const uniform = (badge: string, colour: Rgb): string => `${BOLD}${fgCode(colour)}${badge}${RESET}`;
 

package/custom-setup.ts

@@ -0,0 +1,41 @@
+import { DEFAULT_TIMEOUT_MS, MAX_OUTPUT_WIDTH, MAX_TIMEOUT_MS } from "./custom.ts";
+
+/**
+ * The message `/statusline` → Custom item list → "Add custom item…" sends on the
+ * user's behalf.
+ *
+ * This is how the contract reaches the agent. It is not a skill on purpose: a
+ * skill's description line sits in every system prompt of every session with
+ * the statusline loaded, to serve a task most users do once. Injecting the
+ * contract from the menu costs nothing until someone asks for an item, and it
+ * is discoverable where the feature is — the same shape Claude Code's own
+ * `/statusline` takes.
+ *
+ * Everything the agent needs is in the message, because the README's install
+ * path is not guessable from inside a session (`~/.pi/agent/npm/node_modules/…`
+ * for an npm install, a git checkout for a git one).
+ */
+export function buildCustomItemSetupPrompt(settingsPath: string, request: string): string {
+	const want = request.trim();
+	const ask =
+		want.length > 0
+			? `I want a custom statusline item that shows: ${want}`
+			: "I want to add a custom statusline item. Ask me what it should show, then set it up.";
+	return [
+		ask,
+		"",
+		"Set it up for pi-statusline. The contract is Claude Code's `statusLine` contract, per item:",
+		"",
+		// An instruction, not a fact: given "items live in <path>", a weaker model
+		// in a canary treated the path as a hint and went looking for the "real"
+		// file with `find /`. The path is the one this session is actually using.
+		`- Write the entry to exactly \`${settingsPath}\` under \`customItems\` (an array). That is the file this session reads; do not search for or edit any other settings file. Create the file or the key if absent, and preserve everything else in it.`,
+		"- Each entry: `{ \"id\": \"<short-name>\", \"command\": \"<shell line>\", \"refreshInterval\": <seconds, optional>, \"timeout\": <seconds, optional> }`. The command runs through `sh -c`, so pipes, `$VARS`, and `~` work.",
+		"- The command receives one JSON object on **stdin** and `COLUMNS` in its environment. Fields: `session_id`, `cwd`, `model.id`, `model.provider`, `git` (`{branch, dirty, behind}` or `null`), `context_window` (`{used_tokens, context_window_size, used_percentage}`, `used_tokens` may be `null`), `usage_remaining.claude` (`{five_hour, seven_day, scoped_weekly}` or `null`) and `usage_remaining.codex` (`{five_hour, weekly}` or `null`). Those percentages are **remaining** headroom, not used.",
+		`- The **first line of stdout** becomes the segment, capped at ${MAX_OUTPUT_WIDTH} characters. SGR colour escapes pass through; every other escape sequence is stripped. **Empty output hides the item** — it is a valid answer, not a failure. Exit non-zero to report a failure; the first line of stderr is shown in \`/statusline\`.`,
+		"- It runs at session start, at the end of every turn, and every `refreshInterval` seconds if set. Use `refreshInterval` for values that move on a wall clock rather than on turns. One run per item at a time; a slow command degrades to a lower refresh rate.",
+		`- Default timeout ${DEFAULT_TIMEOUT_MS / 1000}s, maximum ${MAX_TIMEOUT_MS / 1000}s. Keep it fast: do slow work in a cron job or daemon and have the item read the result; if the item must do the work itself, cache keyed by \`session_id\`.`,
+		"",
+		"Steps: write the script if one is needed (make it executable), test it exactly as the statusline runs it — `echo '{\"model\":{\"id\":\"x\"},\"usage_remaining\":{\"codex\":{\"five_hour\":22,\"weekly\":55}}}' | COLUMNS=120 sh -c '<command>'` — and confirm it prints one short line. Then add the entry to the settings file. When done, tell me to run `/statusline` to reload it; the file is read when that menu opens, and the **Custom item list** submenu shows each item's value or why it is not rendering.",
+	].join("\n");
+}