pi-statusline

A pi extension that replaces the built-in footer with a colorful, segment-based status line.

Install

pi install npm:@liuovo/pi-statusline

Or try it without installing, for the current run only:

pi -e npm:@liuovo/pi-statusline

Segments

Segment	Content
model	Active model id + thinking level
cwd	Current directory (basename)
branch	Git branch; * marks uncommitted changes
context	Context window usage percent (tokens/window); color shifts green → yellow (>70%) → red (>90%, with a warning icon). An autorenew icon appears while auto-compaction is enabled
cost	Cumulative session cost (adaptive precision: $0.0042 for small amounts)
usage	Cumulative input/output tokens + latest-request cache hit rate (color-coded: ≥90% green, ≥70% yellow, below red)
tps	Output speed in tokens/sec, updated live while streaming; measured over pure LLM streaming time (tool execution excluded)
statuses	Texts from other extensions' ctx.ui.setStatus() (noise like MCP:/Ready/Working filtered out)

Usage totals mirror pi's built-in footer: they accumulate over all session entries, including compaction/branch summaries and nested tool-call usage, so they survive compaction.

When the terminal is too narrow for one line, segments wrap whole to a second line (never cut mid-segment); the second line is truncated as a last resort.

Customize

Run /statusline inside pi to toggle the footer and each segment individually (Enter/Space toggles in place, Esc closes). Choices persist to ~/.pi/agent/pi-statusline.json:

{
  "enabled": true,
  "segments": {
    "model": true,
    "cwd": true,
    "branch": true,
    "context": true,
    "cost": true,
    "usage": true,
    "tps": true,
    "statuses": true
  }
}

Font requirements

Icons are Nerd Font glyphs (private-use-area codepoints). Use a Nerd Font v3+ terminal font, or replace the entries in ICONS in src/statusline.ts with plain text.

Colors use truecolor escape sequences when COLORTERM is truecolor/24bit, and fall back to theme colors otherwise.

Develop

git clone https://github.com/liuc-c/pi-statusline.git
cd pi-statusline
pnpm install

pnpm check        # type-check
pnpm test         # render smoke tests (Node >= 22.6, native type stripping)

pi loads extensions via jiti — no build step. Test changes against your local checkout with:

pi -e ./src/index.ts

Structure

src/
├── index.ts        # Extension entry: event wiring, data collection, /statusline command
└── statusline.ts   # Pure rendering: segments, colors, two-line wrapping
scripts/
└── smoke.ts        # Framework-free render smoke tests

Releasing

Releases are driven by git tags and run entirely in CI (release.yml):

npm version patch   # bumps package.json, commits, creates tag vX.Y.Z
git push --follow-tags

The workflow verifies the tag matches package.json, runs checks, publishes to npm with provenance, and creates a GitHub release with generated notes.

One-time setup on the repo:

• Add an NPM_TOKEN secret (npm granular access token with publish rights on @liuovo), or configure trusted publishing for the package and drop the token from the workflow — provenance works via OIDC either way.

License

MIT