@hank-warren/pi-statusline 0.7.3 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @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

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/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");
+}

package/custom.ts

@@ -0,0 +1,486 @@
+import { spawn as nodeSpawn } from "node:child_process";
+import { platform } from "node:process";
+
+/**
+ * User-defined statusline segments, modelled on Claude Code's `statusLine`.
+ *
+ * Each item is a shell command that receives a JSON snapshot of the session on
+ * stdin and prints one line to stdout. That contract is deliberately the same
+ * one Claude Code uses, so an existing statusline script mostly ports over; the
+ * differences are that pi renders each item as one *segment* of line 1 rather
+ * than owning the whole row, and that the payload's usage numbers are remaining
+ * percentages (see `custom-items.md` in the README).
+ */
+
+/** How long a command may run before it is killed, when it names no timeout. */
+export const DEFAULT_TIMEOUT_MS = 5_000;
+/** Ceiling for a configured timeout: a statusline must never block on a hang. */
+export const MAX_TIMEOUT_MS = 30_000;
+/**
+ * Floor between two event-driven runs of the same item. Turn ends are the main
+ * trigger and are already coarse, but a session can end several turns in a
+ * second, and an item that shells out to `curl` should not follow it there.
+ */
+export const EVENT_MIN_INTERVAL_MS = 1_000;
+/**
+ * Consecutive failures tolerated before an item's last good value is dropped.
+ *
+ * A statusline value that quietly goes stale is worse than an empty slot: the
+ * number stays plausible while it describes a world that has moved on. One
+ * blip (a laptop between networks) keeps the value; a command that is simply
+ * broken loses it.
+ */
+export const FAILURE_GRACE = 3;
+/** Longest rendered value kept from a command, before the line is truncated. */
+export const MAX_OUTPUT_WIDTH = 120;
+
+/**
+ * One configured item.
+ *
+ * `source` is the entry exactly as it appeared on disk. Serialization writes it
+ * back verbatim apart from the one field the menu owns (`enabled`), so an entry
+ * this version cannot parse — a `type` from a newer release, a key added by a
+ * future feature — survives a settings write instead of being silently deleted
+ * by the first person who toggles an unrelated row.
+ */
+export interface CustomItem {
+	id: string;
+	enabled: boolean;
+	/** Absent when the entry is not runnable; `error` then says why. */
+	command?: string;
+	/** Seconds between forced re-runs. Absent means event-driven only. */
+	refreshInterval?: number;
+	timeoutMs: number;
+	/** Why this entry cannot run, shown in the `/statusline` submenu. */
+	error?: string;
+	/** The on-disk entry, preserved for round-tripping. */
+	source: unknown;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Positive finite seconds, or undefined for anything unusable. */
+function positiveSeconds(value: unknown): number | undefined {
+	if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) return undefined;
+	return value;
+}
+
+function uniqueId(candidate: string, taken: Set<string>): string {
+	if (!taken.has(candidate)) return candidate;
+	for (let suffix = 2; ; suffix += 1) {
+		const next = `${candidate}#${suffix}`;
+		if (!taken.has(next)) return next;
+	}
+}
+
+/**
+ * Parse the `customItems` array.
+ *
+ * Every entry becomes an item, including the ones that cannot run: an invalid
+ * entry is reported through `error` rather than dropped, because dropping it
+ * would erase it from the file on the next write. Validation failures are
+ * per-entry, so one bad command never costs the user their other items.
+ */
+export function normalizeCustomItems(value: unknown): CustomItem[] {
+	if (!Array.isArray(value)) return [];
+	const items: CustomItem[] = [];
+	const taken = new Set<string>();
+	value.forEach((entry, index) => {
+		const fallbackId = `item-${index + 1}`;
+		if (!isPlainObject(entry)) {
+			const id = uniqueId(fallbackId, taken);
+			taken.add(id);
+			items.push({ id, enabled: false, timeoutMs: DEFAULT_TIMEOUT_MS, error: "not an object", source: entry });
+			return;
+		}
+		const rawId = entry.id;
+		const id = uniqueId(typeof rawId === "string" && rawId.length > 0 ? rawId : fallbackId, taken);
+		taken.add(id);
+		// `enabled` is the menu's field; everything else is the user's.
+		const enabled = entry.enabled !== false;
+		const timeoutSeconds = positiveSeconds(entry.timeout);
+		const timeoutMs = Math.min(
+			timeoutSeconds === undefined ? DEFAULT_TIMEOUT_MS : timeoutSeconds * 1000,
+			MAX_TIMEOUT_MS,
+		);
+		const refreshInterval = positiveSeconds(entry.refreshInterval);
+		const base = { id, enabled, timeoutMs, source: entry, ...(refreshInterval ? { refreshInterval } : {}) };
+		// Claude Code's `statusLine` carries `type: "command"`, so a pasted entry
+		// may too. That value is accepted; any other is not a mistake this version
+		// can judge, so the entry is kept and flagged rather than run or dropped.
+		const type = entry.type ?? "command";
+		if (type !== "command") {
+			items.push({ ...base, enabled: false, error: `unsupported type: ${String(type)}` });
+			return;
+		}
+		if (typeof entry.command !== "string" || entry.command.trim().length === 0) {
+			items.push({ ...base, enabled: false, error: "missing command" });
+			return;
+		}
+		items.push({ ...base, command: entry.command });
+	});
+	return items;
+}
+
+/**
+ * Write items back to their on-disk form.
+ *
+ * The source entry wins for every field except `enabled`, which the menu owns:
+ * it is written only when false, so toggling an item on again leaves the file
+ * as the user wrote it rather than accumulating defaults.
+ */
+export function serializeCustomItems(items: readonly CustomItem[]): unknown[] {
+	return items.map((item) => {
+		if (!isPlainObject(item.source)) return item.source;
+		const entry = { ...item.source };
+		if (item.enabled) delete entry.enabled;
+		else entry.enabled = false;
+		return entry;
+	});
+}
+
+/** Whether two item lists are the same for save-diffing purposes. */
+export function sameCustomItems(a: readonly CustomItem[], b: readonly CustomItem[]): boolean {
+	if (a.length !== b.length) return false;
+	return a.every((item, index) => {
+		const other = b[index];
+		return (
+			other !== undefined &&
+			item.id === other.id &&
+			item.enabled === other.enabled &&
+			JSON.stringify(item.source) === JSON.stringify(other.source)
+		);
+	});
+}
+
+/**
+ * Strip anything that could damage the footer, keeping SGR colour sequences.
+ *
+ * Scripts are encouraged to colour their output, so `\x1b[32m` has to survive.
+ * Every other escape sequence does not: a cursor move or an erase-line writes
+ * outside the row the statusline owns and corrupts the frame around it.
+ */
+export function sanitizeOutput(raw: string): string {
+	const firstLine = raw.split(/\r?\n/, 1)[0] ?? "";
+	let out = "";
+	for (let index = 0; index < firstLine.length; index += 1) {
+		const char = firstLine[index] as string;
+		if (char === "\x1b") {
+			const sgr = /^\x1b\[[0-9;:]*m/.exec(firstLine.slice(index));
+			if (sgr) {
+				out += sgr[0];
+				index += sgr[0].length - 1;
+				continue;
+			}
+			// Any other escape sequence: skip the introducer and its final byte.
+			const other = /^\x1b(?:\[[0-9;:?]*[ -/]*[@-~]|\][^\x07\x1b]*(?:\x07|\x1b\\)?|[@-Z\\-_])/.exec(
+				firstLine.slice(index),
+			);
+			if (other) index += other[0].length - 1;
+			continue;
+		}
+		// eslint-disable-next-line no-control-regex
+		if (char === "\t") {
+			out += " ";
+			continue;
+		}
+		const code = char.charCodeAt(0);
+		if (code < 0x20 || code === 0x7f) continue;
+		out += char;
+	}
+	return out.trim().slice(0, MAX_OUTPUT_WIDTH);
+}
+
+/** The last thing an item did, for rendering and for the settings submenu. */
+export interface CustomItemState {
+	id: string;
+	enabled: boolean;
+	/** Sanitized first line of stdout; absent when there is nothing to show. */
+	value?: string;
+	/** Configuration or run failure, whichever applies. */
+	error?: string;
+	/** When the value was produced, as epoch ms. */
+	updatedAt?: number;
+	running: boolean;
+}
+
+export type SpawnFn = typeof nodeSpawn;
+
+export interface CustomItemsTrackerOptions {
+	spawn?: SpawnFn;
+	now?: () => number;
+	onChange?: () => void;
+	cwd?: string;
+	schedule?: (callback: () => void, intervalMs: number) => unknown;
+	cancel?: (handle: unknown) => void;
+}
+
+interface RunRecord {
+	value?: string;
+	error?: string;
+	updatedAt?: number;
+	lastAttempt: number;
+	failures: number;
+	running: boolean;
+	abort?: () => void;
+}
+
+function defaultSchedule(callback: () => void, intervalMs: number): unknown {
+	const handle = setInterval(callback, intervalMs);
+	if (typeof handle.unref === "function") handle.unref();
+	return handle;
+}
+
+function defaultCancel(handle: unknown): void {
+	clearInterval(handle as ReturnType<typeof setInterval>);
+}
+
+/** Smallest configured refresh interval, which sets the tick rate. */
+const TICK_FLOOR_MS = 1_000;
+
+/**
+ * Runs the configured items and holds their latest values.
+ *
+ * Each item runs at most once at a time: a trigger that arrives while a command
+ * is still going is dropped rather than queued, so a slow command degrades to a
+ * lower refresh rate instead of a pile of processes.
+ */
+export class CustomItemsTracker {
+	private items: CustomItem[] = [];
+	private readonly records = new Map<string, RunRecord>();
+	private readonly spawnFn: SpawnFn;
+	private readonly now: () => number;
+	private readonly onChange?: () => void;
+	private readonly schedule: (callback: () => void, intervalMs: number) => unknown;
+	private readonly cancel: (handle: unknown) => void;
+	private cwd: string | undefined;
+	private columns = 80;
+	private payloadFactory: () => Record<string, unknown> = () => ({});
+	private tickHandle: unknown;
+
+	constructor(options: CustomItemsTrackerOptions = {}) {
+		this.spawnFn = options.spawn ?? nodeSpawn;
+		this.now = options.now ?? Date.now;
+		this.onChange = options.onChange;
+		this.cwd = options.cwd;
+		this.schedule = options.schedule ?? defaultSchedule;
+		this.cancel = options.cancel ?? defaultCancel;
+	}
+
+	/**
+	 * Adopt a new configuration, keeping the state of items that survived it.
+	 *
+	 * Identity is the item id, so editing a command's text keeps its slot filled
+	 * with the previous value until the new command first answers — the footer
+	 * does not blink on every settings save.
+	 */
+	setItems(items: readonly CustomItem[]): void {
+		this.items = [...items];
+		const live = new Set(items.map((item) => item.id));
+		for (const [id, record] of this.records) {
+			if (live.has(id)) continue;
+			record.abort?.();
+			this.records.delete(id);
+		}
+	}
+
+	setContext(context: { cwd?: string; columns?: number }): void {
+		if (context.cwd !== undefined) this.cwd = context.cwd;
+		if (context.columns !== undefined && context.columns > 0) this.columns = context.columns;
+	}
+
+	/**
+	 * Supply the stdin payload lazily.
+	 *
+	 * A factory rather than a value because the timer fires between turns: a
+	 * snapshot captured at configuration time would hand a script the context
+	 * usage and quota numbers of whenever the session last had an event.
+	 */
+	setPayloadFactory(factory: () => Record<string, unknown>): void {
+		this.payloadFactory = factory;
+	}
+
+	/** Current state of every configured item, in configuration order. */
+	states(): CustomItemState[] {
+		return this.items.map((item) => {
+			const record = this.records.get(item.id);
+			return {
+				id: item.id,
+				enabled: item.enabled,
+				...(record?.value !== undefined ? { value: record.value } : {}),
+				...(item.error !== undefined
+					? { error: item.error }
+					: record?.error !== undefined
+						? { error: record.error }
+						: {}),
+				...(record?.updatedAt !== undefined ? { updatedAt: record.updatedAt } : {}),
+				running: record?.running ?? false,
+			};
+		});
+	}
+
+	/** Rendered values, in order, for the items that currently have one. */
+	values(): string[] {
+		return this.items
+			.filter((item) => item.enabled)
+			.map((item) => this.records.get(item.id)?.value)
+			.filter((value): value is string => value !== undefined && value.length > 0);
+	}
+
+	/** Begin ticking, if any item asked for a timer. Idempotent. */
+	start(): void {
+		if (this.tickHandle !== undefined) return;
+		const intervals = this.items
+			.filter((item) => item.enabled && item.refreshInterval !== undefined)
+			.map((item) => (item.refreshInterval as number) * 1000);
+		if (intervals.length === 0) return;
+		const tick = Math.max(TICK_FLOOR_MS, Math.min(...intervals));
+		this.tickHandle = this.schedule(() => this.refresh(), tick);
+	}
+
+	stop(): void {
+		if (this.tickHandle === undefined) return;
+		this.cancel(this.tickHandle);
+		this.tickHandle = undefined;
+	}
+
+	/** Stop everything and abandon in-flight commands. */
+	dispose(): void {
+		this.stop();
+		for (const record of this.records.values()) record.abort?.();
+		this.records.clear();
+	}
+
+	/**
+	 * Restart the timer after a configuration change, since the tick rate is
+	 * derived from the items themselves.
+	 */
+	restartTimer(): void {
+		const wasRunning = this.tickHandle !== undefined;
+		this.stop();
+		if (wasRunning) this.start();
+	}
+
+	/** Run every item whose throttle has elapsed. Never rejects. */
+	refresh(): void {
+		const now = this.now();
+		for (const item of this.items) {
+			if (!item.enabled || item.command === undefined) continue;
+			const record = this.records.get(item.id);
+			if (record?.running) continue;
+			const minimum =
+				item.refreshInterval !== undefined
+					? Math.max(EVENT_MIN_INTERVAL_MS, item.refreshInterval * 1000)
+					: EVENT_MIN_INTERVAL_MS;
+			if (record !== undefined && now - record.lastAttempt < minimum) continue;
+			this.run(item);
+		}
+	}
+
+	private record(id: string): RunRecord {
+		const existing = this.records.get(id);
+		if (existing) return existing;
+		const created: RunRecord = { lastAttempt: 0, failures: 0, running: false };
+		this.records.set(id, created);
+		return created;
+	}
+
+	private run(item: CustomItem): void {
+		const command = item.command;
+		if (command === undefined) return;
+		const record = this.record(item.id);
+		record.lastAttempt = this.now();
+		record.running = true;
+
+		const shell = platform === "win32" ? (process.env.ComSpec ?? "cmd.exe") : "sh";
+		const args = platform === "win32" ? ["/d", "/s", "/c", command] : ["-c", command];
+
+		let child: ReturnType<SpawnFn>;
+		try {
+			child = this.spawnFn(shell, args, {
+				cwd: this.cwd,
+				// COLUMNS is how Claude Code tells a script the width it may use;
+				// keeping the name means a ported script sizes itself correctly.
+				env: { ...process.env, COLUMNS: String(this.columns) },
+				stdio: ["pipe", "pipe", "pipe"],
+			});
+		} catch (error) {
+			this.settle(item, record, { error: error instanceof Error ? error.message : String(error) });
+			return;
+		}
+
+		let stdout = "";
+		let stderr = "";
+		let settled = false;
+		const finish = (outcome: { value?: string; error?: string }): void => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			record.abort = undefined;
+			this.settle(item, record, outcome);
+		};
+
+		const timer = setTimeout(() => {
+			child.kill("SIGTERM");
+			// A command ignoring SIGTERM must not outlive the session either.
+			setTimeout(() => child.kill("SIGKILL"), 500).unref?.();
+			finish({ error: `timed out after ${Math.round(item.timeoutMs / 100) / 10}s` });
+		}, item.timeoutMs);
+		timer.unref?.();
+
+		record.abort = () => {
+			clearTimeout(timer);
+			settled = true;
+			record.running = false;
+			child.kill("SIGKILL");
+		};
+
+		child.stdout?.on("data", (chunk: Buffer | string) => {
+			// One line is all that is rendered; stop accumulating well before a
+			// runaway command can fill memory with output nobody will read.
+			if (stdout.length < 64_000) stdout += String(chunk);
+		});
+		child.stderr?.on("data", (chunk: Buffer | string) => {
+			if (stderr.length < 4_000) stderr += String(chunk);
+		});
+		child.on("error", (error: Error) => finish({ error: error.message }));
+		child.on("close", (code: number | null) => {
+			if (code === 0) {
+				finish({ value: sanitizeOutput(stdout) });
+				return;
+			}
+			const detail = sanitizeOutput(stderr);
+			finish({ error: detail.length > 0 ? `exit ${code ?? "?"}: ${detail}` : `exit ${code ?? "?"}` });
+		});
+
+		try {
+			child.stdin?.on("error", () => {
+				// A command that never reads stdin (`date`, a shell one-liner) closes
+				// the pipe under us; that is not a failure of the item.
+			});
+			child.stdin?.end(`${JSON.stringify(this.payloadFactory())}\n`);
+		} catch {
+			// Same case, raised synchronously.
+		}
+	}
+
+	private settle(item: CustomItem, record: RunRecord, outcome: { value?: string; error?: string }): void {
+		record.running = false;
+		const previous = record.value;
+		if (outcome.error === undefined) {
+			record.failures = 0;
+			delete record.error;
+			// Empty output is a deliberate "nothing to show right now", not a
+			// failure: it is how a script hides itself when its subject is idle.
+			record.value = outcome.value ?? "";
+			record.updatedAt = this.now();
+		} else {
+			record.failures += 1;
+			record.error = outcome.error;
+			if (record.failures >= FAILURE_GRACE) delete record.value;
+		}
+		if (record.value !== previous) this.onChange?.();
+	}
+}

package/index.ts

@@ -14,16 +14,20 @@ import {
 } from "./cache-celebration.ts";
 import { CelebrationPreview, trackSelectedLabel } from "./celebration-preview.ts";
 import { DEFAULT_CELEBRATION_STYLE, renderCacheBadge } from "./celebration-styles.ts";
+import { CustomItemsTracker } from "./custom.ts";
+import { buildCustomItemSetupPrompt } from "./custom-setup.ts";
 import { FullRedrawScheduler } from "./redraw.ts";
 import {
 	applySettingChange,
 	buildSettingItems,
 	CACHE_CELEBRATION_LABEL,
 	createAliasSubmenu,
+	createCustomItemsSubmenu,
 	createWorktreeRootSubmenu,
 } from "./settings-menu.ts";
 import {
 	changedSettingKeys,
+	collapseHome,
 	defaultSettings,
 	repoAlias,
 	SettingsStore,
@@ -50,6 +54,8 @@ export interface StatuslineData {
 	sessionId: string;
 	cacheCelebration?: CacheCelebrationSnapshot;
 	usage?: UsageSnapshot;
+	/** Rendered output of each enabled custom item, in configuration order. */
+	customValues?: string[];
 }
 
 const RESET = "\x1b[0m";
@@ -177,6 +183,10 @@ export function renderStatusline(
 					formatTokenCount(data.contextTokens),
 				);
 	const usageSegment = settings.showUsage && data.usage ? renderUsageSegment(data.usage, palette) : undefined;
+	// Custom items own their own colours, so they are passed through unstyled;
+	// they sit after the usage meters, which is where the built-in segments stop
+	// and anything the user added begins.
+	const customSegments = settings.showCustomItems ? (data.customValues ?? []).filter((value) => value.length > 0) : [];
 	const segments = [
 		settings.showModel ? styled(palette.model, data.model) : undefined,
 		// No provider is a missing segment, not a placeholder: the model id already
@@ -191,6 +201,7 @@ export function renderStatusline(
 			? `${used}${styled(palette.dim, "/")}${styled(palette.text, formatTokenCount(data.contextWindow))}`
 			: undefined,
 		usageSegment,
+		...customSegments,
 	].filter((segment): segment is string => segment !== undefined);
 
 	const showWorktreeLine = settings.showWorktrees && data.worktrees.length > 0;
@@ -227,6 +238,7 @@ export default function statuslineExtension(pi: ExtensionAPI): void {
 	const cacheCelebration = new CacheCelebrationController(() => requestRender?.());
 	let tracker: SessionWorktreeTracker | undefined;
 	const usageTracker = new UsageTracker({ onChange: () => requestRender?.() });
+	const customItems = new CustomItemsTracker({ onChange: () => requestRender?.() });
 	let cwdGit: GitRepositoryStatus | null = null;
 	let cwdStatusAbort: AbortController | undefined;
 	let cwdStatusInFlight: Promise<void> | undefined;
@@ -267,6 +279,48 @@ export default function statuslineExtension(pi: ExtensionAPI): void {
 		return refresh;
 	};
 
+	/**
+	 * The JSON handed to every custom command on stdin.
+	 *
+	 * Field names follow Claude Code's statusline payload where the two agents
+	 * describe the same thing, so a script written for it needs no rewrite. The
+	 * exception is deliberate: pi's meters are *remaining* headroom, the inverse
+	 * of Claude Code's `rate_limits.*.used_percentage`, so those fields live
+	 * under `usage_remaining` where a ported script cannot read them by accident.
+	 */
+	const customPayload = (ctx: ExtensionContext): Record<string, unknown> => {
+		const context = ctx.getContextUsage();
+		const window = context?.contextWindow ?? ctx.model?.contextWindow ?? 0;
+		const tokens = context?.tokens ?? null;
+		const usage = usageTracker.snapshot();
+		return {
+			version: 1,
+			session_id: ctx.sessionManager.getSessionId(),
+			cwd: ctx.cwd,
+			model: { id: ctx.model?.id ?? null, provider: ctx.model?.provider ?? null },
+			git: cwdGit
+				? { branch: cwdGit.branch, dirty: cwdGit.dirty, behind: cwdGit.behind }
+				: null,
+			context_window: {
+				used_tokens: tokens,
+				context_window_size: window,
+				used_percentage: tokens !== null && window > 0 ? Math.round((tokens * 100) / window) : null,
+			},
+			usage_remaining: {
+				claude: usage.claude
+					? {
+							five_hour: usage.claude.fiveHour,
+							seven_day: usage.claude.sevenDay,
+							scoped_weekly: usage.claude.scopedWeekly ?? null,
+						}
+					: null,
+				codex: usage.codex
+					? { five_hour: usage.codex.fiveHour ?? null, weekly: usage.codex.weekly ?? null }
+					: null,
+			},
+		};
+	};
+
 	const resetTracker = (ctx: ExtensionContext): void => {
 		tracker?.dispose();
 		tracker = undefined;
@@ -279,6 +333,9 @@ export default function statuslineExtension(pi: ExtensionAPI): void {
 			usageTracker.setActiveProvider(ctx.model?.provider);
 			runInBackground(usageTracker.refresh());
 		}
+		customItems.setContext({ cwd: ctx.cwd });
+		customItems.setPayloadFactory(() => customPayload(ctx));
+		if (settings.showCustomItems) customItems.refresh();
 		// A hidden worktree line must not pay for git/gh polling.
 		if (!settings.showWorktrees) return;
 		const next = new SessionWorktreeTracker({
@@ -298,6 +355,18 @@ export default function statuslineExtension(pi: ExtensionAPI): void {
 		settings = next;
 		settingsStore.set(next);
 
+		// Items are adopted before the visibility check so a disabled segment
+		// still shows current config in the submenu; nothing runs while it is off.
+		customItems.setItems(next.customItems);
+		if (next.showCustomItems) {
+			customItems.restartTimer();
+			customItems.start();
+			customItems.refresh();
+		} else if (previous.showCustomItems) {
+			// A hidden segment must not keep spawning commands, matching usage above.
+			customItems.stop();
+		}
+
 		if (!next.showWorktrees) {
 			tracker?.dispose();
 			tracker = undefined;
@@ -347,6 +416,16 @@ export default function statuslineExtension(pi: ExtensionAPI): void {
 				const settingsTheme = tracked.theme;
 				const submenuHost = {
 					getSettings: () => settings,
+					customItemStates: () => customItems.states(),
+					// The contract reaches the agent as a user message, sent when the
+					// menu asks for it. This is the whole reason there is no skill: the
+					// text costs nothing until someone wants an item, and a message from
+					// the menu is discoverable exactly where the feature is.
+					requestCustomItem: (request: string) => {
+						const prompt = buildCustomItemSetupPrompt(collapseHome(settingsStore.getPath(), home), request);
+						if (ctx.isIdle()) pi.sendUserMessage(prompt);
+						else pi.sendUserMessage(prompt, { deliverAs: "followUp" });
+					},
 					commit: (next: StatuslineSettings) => applySettings(ctx, next),
 					notify: (message: string) => ctx.ui.notify(message, "warning"),
 					requestRender: () => tui.requestRender(),
@@ -360,6 +439,7 @@ export default function statuslineExtension(pi: ExtensionAPI): void {
 						{
 							worktreeRoot: createWorktreeRootSubmenu(submenuHost),
 							repoAliases: createAliasSubmenu(submenuHost),
+							customItems: createCustomItemsSubmenu(submenuHost),
 						},
 						home,
 					),
@@ -416,6 +496,7 @@ export default function statuslineExtension(pi: ExtensionAPI): void {
 			// still needs them to move, and a sibling process's poll is worth adopting
 			// before the next turn ends.
 			if (settings.showUsage) usageTracker.start();
+			if (settings.showCustomItems) customItems.start();
 			const stopBranchUpdates = footerData.onBranchChange(() => {
 				runInBackground(refreshCwdStatus(ctx));
 				tui.requestRender();
@@ -428,6 +509,7 @@ export default function statuslineExtension(pi: ExtensionAPI): void {
 					celebrationPreview.dispose();
 					fullRedraw.detach();
 					usageTracker.stop();
+					customItems.dispose();
 					requestRender = undefined;
 				},
 				invalidate(): void {},
@@ -435,6 +517,9 @@ export default function statuslineExtension(pi: ExtensionAPI): void {
 					const usage = ctx.getContextUsage();
 					const cwd = basename(ctx.cwd) || ctx.cwd;
 					const model = ctx.model?.id.split("/").pop() || "no-model";
+					// Commands size themselves with COLUMNS, so the tracker needs the
+					// width the footer is actually being drawn at.
+					customItems.setContext({ columns: width });
 
 					return fullRedraw.decorate(
 						renderStatusline(
@@ -449,6 +534,7 @@ export default function statuslineExtension(pi: ExtensionAPI): void {
 								sessionId: ctx.sessionManager.getSessionId(),
 								cacheCelebration: celebrationPreview.snapshot() ?? cacheCelebration.snapshot(),
 								usage: usageTracker.snapshot(),
+								customValues: customItems.values(),
 							},
 							width,
 							settings,
@@ -476,6 +562,9 @@ export default function statuslineExtension(pi: ExtensionAPI): void {
 			usageTracker.setActiveProvider(ctx.model?.provider);
 			runInBackground(usageTracker.refresh());
 		}
+		// Turn end is the event-driven trigger, mirroring how Claude Code re-runs a
+		// statusline command when a new assistant message arrives.
+		if (settings.showCustomItems) customItems.refresh();
 	});
 	// The meters follow the main model's account, so a switch between two logins
 	// of the same provider family has to re-point the tracker before it repaints.
@@ -491,6 +580,7 @@ export default function statuslineExtension(pi: ExtensionAPI): void {
 		cacheCelebration.dispose();
 		fullRedraw.detach();
 		usageTracker.stop();
+		customItems.dispose();
 		tracker?.dispose();
 		tracker = undefined;
 		cwdStatusAbort?.abort();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hank-warren/pi-statusline",
-  "version": "0.7.3",
+  "version": "0.8.0",
   "description": "Compact Pi footer statusline with Git/worktree context, token usage, and neon celebrations for exceptional prompt-cache hits.",
   "type": "module",
   "keywords": [
@@ -35,6 +35,8 @@
     "cache-celebration.ts",
     "celebration-preview.ts",
     "celebration-styles.ts",
+    "custom.ts",
+    "custom-setup.ts",
     "redraw.ts",
     "settings.ts",
     "settings-menu.ts",

package/settings-menu.ts

@@ -10,6 +10,7 @@ import {
 	truncateToWidth,
 } from "@earendil-works/pi-tui";
 import { type BooleanSettingKey, collapseHome, resolveWorktreeRoot, type StatuslineSettings } from "./settings.ts";
+import type { CustomItemState } from "./custom.ts";
 import { CELEBRATION_STYLE_NAMES, isCelebrationStyleName } from "./celebration-styles.ts";
 import { isThemeName, THEME_NAMES } from "./themes.ts";
 
@@ -17,7 +18,9 @@ export const THEME_ID = "theme";
 export const CACHE_CELEBRATION_ID = "showCacheCelebration";
 export const WORKTREE_ROOT_ID = "worktreeRoot";
 export const REPO_ALIASES_ID = "repoAliases";
+export const CUSTOM_ITEMS_ID = "customItems";
 export const ADD_ALIAS_VALUE = "\u0000add";
+export const ADD_CUSTOM_ITEM_VALUE = "\u0000add-item";
 
 export const ON = "on";
 export const OFF = "off";
@@ -36,6 +39,7 @@ export const BOOLEAN_ROWS: readonly BooleanRow[] = [
 	{ id: "showDirectory", label: "Directory & git", description: "Show the working directory and its git branch." },
 	{ id: "showContext", label: "Context", description: "Show context tokens used against the window." },
 	{ id: "showUsage", label: "Subscription usage", description: "Show Claude/Codex remaining-headroom meters." },
+	{ id: "showCustomItems", label: "Custom items", description: "Run your configured commands and show their output." },
 	{ id: "showWorktrees", label: "Worktree line", description: "Show touched worktrees and their pull requests." },
 	{ id: "showSessionId", label: "Session ID line", description: "Show the full Pi session id on its own line." },
 ];
@@ -57,9 +61,67 @@ export function aliasSummary(settings: StatuslineSettings): string {
 	return `${count} alias${count === 1 ? "" : "es"}`;
 }
 
+/** Row value for the custom-items submenu: how many items are switched on. */
+export function customItemsSummary(settings: StatuslineSettings): string {
+	const total = settings.customItems.length;
+	if (total === 0) return "none configured";
+	return `${settings.customItems.filter((item) => item.enabled).length}/${total} on`;
+}
+
+/**
+ * Rows in the custom-items submenu: each item, what it shows and why, then the
+ * one action that creates an item. Adding hands the job to the agent rather
+ * than opening a form: a statusline command is a script plus a JSON entry plus
+ * a test run, which is a conversation, not a field.
+ */
+export function customItemRows(
+	settings: StatuslineSettings,
+	states: readonly CustomItemState[] = [],
+): SelectItem[] {
+	return [
+		...customItemStateRows(settings, states),
+		{
+			value: ADD_CUSTOM_ITEM_VALUE,
+			label: "Add custom item…",
+			description: "Ask the agent to write one; it gets the contract and the settings path.",
+		},
+	];
+}
+
+function customItemStateRows(settings: StatuslineSettings, states: readonly CustomItemState[]): SelectItem[] {
+	const byId = new Map(states.map((state) => [state.id, state]));
+	return settings.customItems.map((item) => {
+		const state = byId.get(item.id);
+		// Configuration errors outrank run errors: an item that cannot be parsed
+		// never ran, so a stale run error from a previous config would mislead.
+		const error = item.error ?? state?.error;
+		// A broken entry reads as "disabled" unless its reason wins here: it is off
+		// *because* it cannot run, and "disabled" would suggest the user chose that.
+		const detail = item.error !== undefined
+			? item.error
+			: !item.enabled
+				? "disabled"
+				: error !== undefined
+				? error
+				: state?.running === true && state.value === undefined
+					? "running…"
+					: state?.value !== undefined && state.value.length > 0
+						? state.value
+						: state?.value !== undefined
+							? "empty output"
+							: "no value yet";
+		return {
+			value: item.id,
+			label: `${item.enabled ? toggleValue(true) : toggleValue(false)}  ${item.id}`,
+			description: detail,
+		};
+	});
+}
+
 export interface SettingSubmenus {
 	worktreeRoot?: SettingItem["submenu"];
 	repoAliases?: SettingItem["submenu"];
+	customItems?: SettingItem["submenu"];
 }
 
 /** Build the `/statusline` rows for a settings snapshot. */
@@ -81,6 +143,10 @@ export function buildSettingItems(
 	// Rows follow the order their elements render in, so the celebration sits
 	// after the usage meters it is appended to on line 1.
 	for (const row of BOOLEAN_ROWS) {
+		// A toggle for a segment with nothing in it is a row that does nothing;
+		// the list row below is where an item gets created, and the toggle
+		// appears once there is something to switch off.
+		if (row.id === "showCustomItems" && settings.customItems.length === 0) continue;
 		items.push({
 			id: row.id,
 			label: row.label,
@@ -113,6 +179,13 @@ export function buildSettingItems(
 		currentValue: aliasSummary(settings),
 		...(submenus.repoAliases ? { submenu: submenus.repoAliases } : {}),
 	});
+	items.push({
+		id: CUSTOM_ITEMS_ID,
+		label: "Custom item list",
+		description: "Enable or disable configured items; edit commands in statusline-settings.json.",
+		currentValue: customItemsSummary(settings),
+		...(submenus.customItems ? { submenu: submenus.customItems } : {}),
+	});
 
 	return items;
 }
@@ -183,6 +256,13 @@ export function aliasItems(settings: StatuslineSettings): SelectItem[] {
 export interface SubmenuHost {
 	/** Read the live settings; the menu edits a single shared snapshot. */
 	getSettings(): StatuslineSettings;
+	/** Live per-item run state, for the custom-items submenu. */
+	customItemStates?(): CustomItemState[];
+	/**
+	 * Hand "add an item" to the agent with the user's one-line description of
+	 * what it should show. Closes the menu; absent when no agent can be reached.
+	 */
+	requestCustomItem?(request: string): void;
 	/** Commit an edit: persists, applies live, and repaints. */
 	commit(settings: StatuslineSettings): void;
 	notify(message: string): void;
@@ -348,3 +428,99 @@ class AliasSubmenu implements Component {
 export function createAliasSubmenu(host: SubmenuHost): NonNullable<SettingItem["submenu"]> {
 	return (_currentValue, done) => new AliasSubmenu(host, done);
 }
+
+/**
+ * Custom item list: enable/disable each item and read why it is not showing.
+ *
+ * Commands are edited in the settings file, not here. A statusline command is a
+ * shell line with quoting and pipes in it, which a single-line TUI prompt edits
+ * badly, and keeping the field out of the menu means a toggle writes only the
+ * `enabled` flag over whatever the file currently holds.
+ */
+class CustomItemsSubmenu implements Component {
+	private list: SelectList;
+	private prompt: PromptComponent | undefined;
+
+	constructor(
+		private readonly host: SubmenuHost,
+		private readonly done: (value?: string) => void,
+	) {
+		this.list = this.buildList();
+	}
+
+	private buildList(selectedIndex = 0): SelectList {
+		const rows = customItemRows(this.host.getSettings(), this.host.customItemStates?.() ?? []);
+		const list = new SelectList(rows, 10, this.host.selectTheme);
+		list.setSelectedIndex(selectedIndex);
+		list.onCancel = () => this.done(customItemsSummary(this.host.getSettings()));
+		list.onSelect = (item) => (item.value === ADD_CUSTOM_ITEM_VALUE ? this.add() : this.toggle(item.value));
+		return list;
+	}
+
+	private add(): void {
+		if (!this.host.requestCustomItem) {
+			this.host.notify("Add items to statusline-settings.json; see the pi-statusline README");
+			return;
+		}
+		this.prompt = new PromptComponent(
+			"What should the item show? (Enter for the agent to ask)",
+			"",
+			this.host.settingsTheme.hint,
+			(value) => {
+				this.prompt = undefined;
+				// Close the whole menu before the message lands: the agent's reply
+				// renders in the transcript, which the menu is drawn over.
+				this.done(customItemsSummary(this.host.getSettings()));
+				this.host.requestCustomItem?.(value);
+			},
+			() => {
+				this.prompt = undefined;
+				this.host.requestRender();
+			},
+		);
+		this.host.requestRender();
+	}
+
+	private toggle(id: string): void {
+		if (id.startsWith("\u0000")) return;
+		const settings = this.host.getSettings();
+		const index = settings.customItems.findIndex((item) => item.id === id);
+		const target = settings.customItems[index];
+		if (!target) return;
+		if (target.error !== undefined && !target.enabled) {
+			// Enabling an unparseable entry would only fail again on the next tick.
+			this.host.notify(`${id} cannot run: ${target.error}`);
+			return;
+		}
+		const customItems = [...settings.customItems];
+		customItems[index] = { ...target, enabled: !target.enabled };
+		this.host.commit({ ...settings, customItems });
+		this.list = this.buildList(index);
+		this.host.requestRender();
+	}
+
+	invalidate(): void {
+		this.prompt?.invalidate();
+		this.list.invalidate();
+	}
+
+	render(width: number): string[] {
+		if (this.prompt) return this.prompt.render(width);
+		return [
+			truncateToWidth(this.host.settingsTheme.hint("  Custom items"), width),
+			"",
+			...this.list.render(width),
+			"",
+			truncateToWidth(this.host.settingsTheme.hint("  Enter to enable/disable or add · Esc to go back"), width),
+		];
+	}
+
+	handleInput(data: string): void {
+		if (this.prompt) this.prompt.handleInput(data);
+		else this.list.handleInput(data);
+	}
+}
+
+export function createCustomItemsSubmenu(host: SubmenuHost): NonNullable<SettingItem["submenu"]> {
+	return (_currentValue, done) => new CustomItemsSubmenu(host, done);
+}

package/settings.ts

@@ -8,6 +8,12 @@ import {
 	DEFAULT_CELEBRATION_STYLE,
 	isCelebrationStyleName,
 } from "./celebration-styles.ts";
+import {
+	type CustomItem,
+	normalizeCustomItems,
+	sameCustomItems,
+	serializeCustomItems,
+} from "./custom.ts";
 import { DEFAULT_THEME, isThemeName, type StatuslineThemeName } from "./themes.ts";
 
 /** Toggle keys, in the order the `/statusline` menu lists them. */
@@ -17,6 +23,7 @@ export const BOOLEAN_SETTING_KEYS = [
 	"showDirectory",
 	"showContext",
 	"showUsage",
+	"showCustomItems",
 	"showWorktrees",
 	"showSessionId",
 	"showCacheCelebration",
@@ -33,6 +40,8 @@ export interface StatuslineSettings extends Record<BooleanSettingKey, boolean> {
 	worktreeRoot: string;
 	/** `repository name -> display alias` overrides for the worktree line. */
 	repoAliases: Record<string, string>;
+	/** User-defined command segments rendered after the usage meters. */
+	customItems: CustomItem[];
 }
 
 function defaultWorktreeRoot(home: string = homedir()): string {
@@ -47,6 +56,9 @@ export function defaultSettings(home: string = homedir()): StatuslineSettings {
 		showDirectory: true,
 		showContext: true,
 		showUsage: true,
+		// On by default and free until the user configures an item: with an empty
+		// list nothing renders, nothing is spawned, and no timer runs.
+		showCustomItems: true,
 		showWorktrees: true,
 		showSessionId: true,
 		showCacheCelebration: true,
@@ -54,6 +66,7 @@ export function defaultSettings(home: string = homedir()): StatuslineSettings {
 		cacheCelebrationStyle: DEFAULT_CELEBRATION_STYLE,
 		worktreeRoot: defaultWorktreeRoot(home),
 		repoAliases: {},
+		customItems: [],
 	};
 }
 
@@ -140,6 +153,7 @@ export function normalizeSettings(value: unknown, home: string = homedir()): Nor
 		"cacheCelebrationStyle",
 		"worktreeRoot",
 		"repoAliases",
+		"customItems",
 	]);
 	for (const [key, raw] of Object.entries(value)) {
 		if (!known.has(key)) {
@@ -158,6 +172,12 @@ export function normalizeSettings(value: unknown, home: string = homedir()): Nor
 			if (aliases) settings.repoAliases = aliases;
 			continue;
 		}
+		if (key === "customItems") {
+			// Unusable entries come back as items carrying their parse error rather
+			// than being dropped, so a write cannot delete what it failed to read.
+			settings.customItems = normalizeCustomItems(raw);
+			continue;
+		}
 		if (key === "theme") {
 			if (isThemeName(raw)) settings.theme = raw;
 			continue;
@@ -185,6 +205,7 @@ export const SETTING_KEYS = [
 	"cacheCelebrationStyle",
 	"worktreeRoot",
 	"repoAliases",
+	"customItems",
 ] as const satisfies readonly (keyof StatuslineSettings)[];
 
 export type SettingKey = (typeof SETTING_KEYS)[number];
@@ -205,11 +226,11 @@ export function changedSettingKeys(
 	previous: StatuslineSettings,
 	next: StatuslineSettings,
 ): SettingKey[] {
-	return SETTING_KEYS.filter((key) =>
-		key === "repoAliases"
-			? !sameAliases(previous.repoAliases, next.repoAliases)
-			: previous[key] !== next[key],
-	);
+	return SETTING_KEYS.filter((key) => {
+		if (key === "repoAliases") return !sameAliases(previous.repoAliases, next.repoAliases);
+		if (key === "customItems") return !sameCustomItems(previous.customItems, next.customItems);
+		return previous[key] !== next[key];
+	});
 }
 
 /**
@@ -232,6 +253,9 @@ export function serializeSettings(
 	}
 	if (settings.worktreeRoot !== defaults.worktreeRoot) out.worktreeRoot = settings.worktreeRoot;
 	if (!sameAliases(settings.repoAliases, defaults.repoAliases)) out.repoAliases = { ...settings.repoAliases };
+	// An empty list is the default and stays out of the file; a configured one is
+	// written back from each entry's original source object.
+	if (settings.customItems.length > 0) out.customItems = serializeCustomItems(settings.customItems);
 	return out;
 }