@nicknisi/pi-statusline

Custom footer for pi's TUI, replacing the default footer with a single-line statusline showing model, session cost, lines changed, Anthropic usage limits, context window usage, and git branch/PR. Also writes tmux status files (working/done/idle) to ~/.cache/pi-status/ so tmux sidebars and other tooling can display per-pane agent state.

Install

pi install /Users/nicknisi/Developer/pi-extensions/packages/statusline

What it adds

• Custom footer — installed via ctx.ui.setFooter(...) on session_start. Single line, segments separated by │:
  • Model icon + name (nerd font icon chosen by name: opus/sonnet/haiku get distinct glyphs, everything else a generic robot icon). Appends the thinking level (e.g. high) when ctx.model.reasoning is true, read live from pi.getThinkingLevel().
  • Session cost ($X.XX), summed from AssistantMessage.usage.cost.total across the current branch. Hidden until cost > $0.001.
  • Lines changed (+N/-M), summed from linesAdded/linesRemoved in toolResult details (i.e. the edit tool). Hidden when zero.
  • Anthropic usage limits (Anthropic models only): remaining-% bars for the 5-hour and 7-day OAuth usage windows, with time-until-reset (↻3h20m).
  • Remaining context: a bar that stretches to fill available terminal width (clamped 5–20 cols), plus N% ctx (tokens used). With Checkpoint loaded, its thresholds control the bar color without changing the fill, width, or labels.
  • Git branch (right-aligned), with a hyperlinked #PR number when gh finds an open PR for the branch.
• Tmux status files — JSON state files at ~/.cache/pi-status/<pane>.status for external consumers (tmux sidebars, fleet monitors).

There are no slash commands, tools, keybindings, widgets, or custom message/entry types.

Events hooked

| Event | Action | | ----------------------- | --------------------------------------------------------------------------------------------- | | session_start | Installs the footer; writes idle status | | agent_start | Writes working status | | tool_execution_start | Writes working status with toolName | | turn_start | Re-writes working to keep the status-file timestamp fresh during long tool-less generations | | agent_end | Writes done status; spawns claude-notify waiting <session> <pane> (detached) | | session_shutdown | Removes the pane's status file | | thinking_level_select | Triggers a footer re-render so the new level shows immediately |

Checkpoint integration

When @nicknisi/pi-checkpoint is loaded, this same context bar uses its policy colors:

• Green (success): below the soft notice threshold.
• Blue (accent, theme-dependent): soft notice.
• Amber (warning): warning threshold.
• Red (error): hard cutoff, invalid settings, or a failed handoff.
• Dim: context usage is temporarily unknown.

The bar still shows remaining model context, not a compaction budget. Model, cost, usage limits, branch, and all other footer segments are unchanged. Checkpoint hides its separate above-editor widget while this footer owns the meter. Either extension can still run alone; removing Checkpoint restores the original remaining-capacity colors.

The optional integration uses Pi's event bus, not a package dependency: self-compact:context-color publishes a theme color (or undefined on shutdown), statusline:context-bar announces whether the footer is active, and statusline:request-context-bar handles late discovery. Subscriptions are removed on shutdown and footer disposal releases the widget fallback.

Tmux status files

Path: ~/.cache/pi-status/<pane>.status where <pane> is TMUX_PANE with the leading % stripped.

{
  "state": "working",
  "pane": "%12",
  "session": "main",
  "tool": "edit",
  "ts": 1717600000
}

• state is one of working, done, idle (the function signature also accepts completed, unused in practice).
• tool is the tool name from tool_execution_start, else "".
• ts is a unix timestamp; external consumers can treat a stale working state as idle (the code comments mention a 180s decay in "fleet").
• The tmux session name is resolved with tmux display-message -p '#{session_name}', falling back to parsing the socket path in $TMUX.
• No-op when TMUX_PANE is unset. All write/remove failures are swallowed so they can't break the agent.

Usage-limit segment (Anthropic only)

Shows remaining capacity for the 5-hour and 7-day rate-limit windows when ctx.model.provider === "anthropic":

󰉁 5h ━━━╌╌ 62% ↻2h10m ╱ 7d ━━╌╌╌ 41% ↻3d4h

Data comes from https://api.anthropic.com/api/oauth/usage (header anthropic-beta: oauth-2025-04-20). The render path never does network or keychain I/O:

• Fresh cache (< 120s) in $TMPDIR/pi-statusline-cache/usage.json is rendered as-is.
• Stale/missing cache renders stale data (or nothing) and kicks a fire-and-forget curl refresh that re-renders the footer on completion.

OAuth token resolution order:

1. ~/.pi/agent/auth.json → anthropic.access
2. macOS Keychain: security find-generic-password -s "Claude Code-credentials" -w → claudeAiOauth.accessToken (Claude Code credentials)

PR lookup

Branch → PR mapping via gh pr view --json number,url --jq '"\(.number)\t\(.url)"', spawned fire-and-forget from the render path. Cached per-branch for 60s, including misses (so non-PR branches don't refetch every render window). The PR number is rendered as an OSC 8 hyperlink (hyperlink() from @earendil-works/pi-tui).

Performance notes

The footer render path is kept synchronous:

• Cost/lines totals require an O(session) walk of ctx.sessionManager.getBranch(); they're cached and recomputed only when the branch entry count changes or every 5s.
• Usage limits and PR data are both cache-reads on render, with async background refresh.
• Re-renders are requested on branch change (footerData.onBranchChange), PR refresh completion, usage refresh completion, and thinking_level_select.

Configuration

Optional global config: ~/.pi/agent/configs/statusline.json. Changes take effect on the next session or after /reload.

{
  "hiddenStatuses": ["mcp"]
}

hiddenStatuses contains stable extension status keys—the first argument passed to ctx.ui.setStatus(key, text). Only matching extension-provided segments are omitted; built-in model, cost, context, usage, and branch segments are unaffected. The default is [], which preserves all extension statuses. Missing or invalid config falls back to the default and invalid config emits a warning.

For example, pi-mcp-adapter publishes its server-count segment under the mcp key, while this repository's subagent fleet uses subagents.

Environment variables read:

| Variable | Use | | ----------- | -------------------------------------------------------- | | TMUX | Detect tmux; parsed as fallback for session name | | TMUX_PANE | Pane id for status files and claude-notify | | HOME | Locates ~/.cache/pi-status and ~/.pi/agent/auth.json | | TMPDIR | Usage cache directory (default /tmp) |

Hardcoded constants you may want to tweak in index.ts:

| Constant | Default | Meaning | | ----------------- | ------------ | -------------------------------------------------- | | USAGE_CACHE_TTL | 120 (s) | How fresh the usage cache must be before a refetch | | PR_CACHE_TTL | 60 (s) | Branch→PR cache lifetime | | Totals recompute | 5000 (ms) | Max age of cached cost/lines totals | | Context bar width | 5..20 cols | Clamp for the stretch-to-fill context bar |

Dependencies

• @nicknisi/pi-shared (workspace) — columns() two-column layout helper (left-truncates to ~45% when the line overflows).
• @earendil-works/pi-coding-agent (peer) — ExtensionAPI, Theme.
• @earendil-works/pi-ai (peer) — AssistantMessage type for usage/cost.
• @earendil-works/pi-tui (peer) — hyperlink(), visibleWidth() for ANSI-aware width math.
• Runtime external commands: tmux, gh, curl, security (macOS), claude-notify.

Caveats

• pi internals: relies on ctx.ui.setFooter, footerData.getGitBranch() / onBranchChange(), ctx.sessionManager.getBranch(), ctx.getContextUsage(), pi.getThinkingLevel(), and toolResult details.linesAdded/linesRemoved (an edit-tool implementation detail). Any of these can change across pi versions.
• Theme colors: assumes theme color names accent, success, warning, error, dim.
• Nerd fonts: icons are private-use-area nerd font codepoints; renders as boxes without a patched font.
• macOS-only paths: the Keychain fallback for OAuth tokens and the security binary are macOS-specific. claude-notify is a personal script expected on PATH.
• Anthropic-only usage segment: the OAuth usage API is called with a bearer token from pi/Claude Code auth; non-Anthropic models skip the segment entirely.
• require in ESM: removeStatus() uses require("node:fs") inside a "type": "module" package — works under pi's loader but would fail under plain Node ESM.
• Duplicate session_start handlers (one for the footer, two for tmux status) — harmless but worth knowing when editing.