pi-statusline — quiet text footer for Pi

@signalridge/pi-statusline is a theme-native footer for the Pi coding agent. Its default Signalridge profile is a restrained, text-first two-line hierarchy: model and thinking state, workspace and branch metadata, active work, and context usage. Context is placed at the right edge when the terminal is wide enough.

Typical output is similar to:

gpt-5.6-sol · think max · main                         ctx 42%

There are no persistent branch icons, emoji, powerline blocks, hard-coded backgrounds, or ornamental per-segment symbols in the default profile. A single dim · separator is used between text fields. Normal metadata is muted; accent and warning/error colors are reserved for current or abnormal state.

Install

pi install npm:@signalridge/pi-statusline

Use from this checkout

From the repository root:

pi -e ./packages/pi-statusline

The package is publishable and stable.

Profiles and settings

The canonical settings file is:

${PI_CODING_AGENT_DIR:-~/.pi/agent}/pi-statusline.json

When it exists, the canonical file always wins. Older installations using pi-statusline-settings.json remain readable and are never rewritten or deleted. If only the legacy file exists, statusline reads it and writes future changes to the canonical filename.

With neither file present, PI_STATUSLINE_PRESET=classic selects the Signalridge default (as does an unset or unknown value):

PI_STATUSLINE_PRESET=classic pi

PI_STATUSLINE_PRESET=tokyo-night remains an explicit opt-in to the richer powerline renderer. Existing canonical or legacy JSON settings always take precedence over the environment. The settings editor and /statusline menu can choose the optional named palettes, information profiles, custom layout, and foreground/background palette values.

Settings writes validate recognized fields, preserve unknown fields, publish through a same-directory temporary file and atomic rename, and fail closed on malformed input or publication errors. Existing files are not replaced when a save fails.

Useful commands:

/statusline          open the interactive menu in TUI mode
/statusline settings edit and apply the canonical JSON document
/statusline status   show the effective source and diagnostics
/statusline help     show configuration help

Default information hierarchy

The balanced Signalridge profile shows, in order:

• current model;
• active thinking level, only when it is not off;
• compact cwd/repository location;
• branch and semantic Git state;
• active tool or streaming activity, only while active;
• context percentage, right-aligned where possible.

Narrow terminals progressively drop lower-priority fields and truncate long model names without emitting partial ANSI sequences. Extension statuses appear on a separate wrapped line. They are text-only by default; explicit extensionStatusIcons entries can add a badge for a selected active state, and an empty string suppresses one.

Model ids, provider ids, active tool names, directory names, and Git branch names are sanitized before display. Escape sequences are removed with their DCS/OSC/PM/APC/SOS payloads, and control characters and bidirectional overrides are dropped rather than replaced, so spoofed text can neither reverse the footer nor shift its layout. An introducer with no terminator drops only itself: consuming the rest of the string would let one byte in a branch name erase the tail of the footer. The branch is sanitized before the optional GitHub PR context is composed in, so the PR hyperlink stays clickable.

Lifecycle behavior

The footer is installed only for TUI sessions. Git status is collected asynchronously and cached outside rendering, with stale cwd/branch results discarded. Usage totals are maintained by a runtime-owned incremental snapshot: rendering does not rescan session history; session replacement, branch/compaction boundaries rebuild it and message/turn events update it. Standalone usage entries (including cache warming) count toward historical tokens, cache, and cost. When tokens, cache, or cost is configured, the footer checks the session leaf every five seconds (including while idle), copying history only after the leaf changes and inspecting only entries appended since its last check. Presets without those segments skip the usage check. Context percentage still comes from ctx.getContextUsage(). Footer timers, branch listeners, pending Git work, command menus, and session ownership are cleaned up on footer disposal, session replacement, compaction, and shutdown. Context usage refreshes after session_compact.

Retained footer callbacks also check the live mode and UI eligibility before work: a headless rebind retires both clocks, branch subscriptions, and pending Git requests even while an earlier session handler is awaited. This resource-only cleanup neither clears a replacement footer nor renders or emits status/settings notifications through the retained UI.

The JSON editor honors Pi's configured external editor. Session replacement or reload retires the dialog without killing that program or restoring its obsolete draft; when the program exits, the surviving terminal may resume. Quit suppression requires statusline to remain loaded in the replacement session. If a reload removes the extension, no replacement instance can observe later quit, so the pending editor retains the host's native restart behavior.

Package layout

packages/pi-statusline/
├── src/
│   ├── statusline.ts          # thin Pi lifecycle entrypoint
│   ├── commands.ts            # settings and menu workflows
│   ├── render.ts              # data-to-segment projection
│   ├── powerline.ts           # restrained text and optional powerline renderers
│   ├── settings.ts            # canonical/legacy loading and atomic saves
│   ├── git-status.ts          # argv-based asynchronous Git status
│   ├── extension-status.ts    # text-only extension status projection
│   └── presets/               # optional palette ramps
├── test/
├── README.md
├── LICENSE
└── package.json

Local divergence

Signalridge maintains the modular port, canonical/legacy settings behavior, session-safe refresh cleanup, and the restrained text-first default appearance described above.

License

MIT. See LICENSE.