pi-statusline

A beautified, Nerd-Font-iconified status line (footer) for the pi coding agent, tuned for the aurora-dark theme.

pi's built-in footer is functional but plain. This extension replaces it with a color-rich status line that keeps every piece of information the original shows — working directory, git branch, session name, cumulative token usage (including cache and cost), context usage with a progress bar, model, thinking level, and extension statuses — but renders it with real color and icons.

---

Preview

Wide terminal (everything on one line):

 ~/src/myapp   feature/login • building-feature   ↑ 42.3k  ↓ 3.1k  ⚡ 150k  87%  $0.42  35% █████░   glm-5.2  ✦ medium

Narrow terminal (wraps to two lines, plus an extension-status line):

 ~/src/myapp   feature/login • building-feature
 ↑ 42.3k  ↓ 3.1k  ⚡ 150k  87%  $0.42  35% █████░        (zai_glm)   glm-5.2  ✦ medium
 ssh-remote: 2 sessions

The colors come from your active theme. Install aurora-dark for the intended look. The icons require a Nerd Font.

---

Features

The status line shows, grouped left → right:

Icon	Meaning	Notes
	Working directory	Shortened to ~ relative to $HOME.
	Git branch	Only when inside a git repo.
•	Session name	When a session name is set.
↑	Cumulative input tokens	Sums across the whole session (handles compaction).
↓	Cumulative output tokens	Sums across the whole session.
⚡	Cache-read tokens	Prompt-cache hits.
%	Cache hit rate	Latest assistant turn.
$	Running cost	$0.420 total; sub suffix for subscription providers (e.g. Kimi Coding).
█░	Context usage bar	5-cell bar + percentage; color goes green → yellow → red.
	Model	Current model id; (provider) prefix when multiple providers are available.
✦	Thinking level	off / minimal / low / medium / high / xhigh / max, each with its own color.

A third line shows extension statuses (e.g. ssh-remote: 2 sessions) when any registered extension reports status.

---

Prerequisites

• pi — the pi coding agent.
• A Nerd Font in your terminal, for the folder / branch / bolt / chip glyphs. Plain Unicode (↑ ↓ ✦ █ ░) is used everywhere else, so the line degrades gracefully if a glyph is missing.

---

Install

Pick one source. All three install the extension and register it with pi.

Option A — npm (recommended)

pi install npm:@gagapony/pi-statusline

pi install runs npm install under the hood, so the package lands in ~/.pi/agent/npm/. To pin a version:

pi install npm:@gagapony/pi-statusline@1.0.0

Option B — git (latest from main)

pi install git:github.com/gagapony/pi-statusline
# or, equivalently:
pi install https://github.com/gagapony/pi-statusline

To pin a tag/commit:

pi install git:github.com/gagapony/pi-statusline@v1.0.0

Option C — manual npm

If you prefer to manage the npm install yourself:

npm install -g @gagapony/pi-statusline
pi install npm:@gagapony/pi-statusline

---

Configure

pi install writes the package into your user settings automatically. You can also add it by hand to ~/.pi/agent/settings.json:

{
  // ...
  "packages": [
    "npm:@gagapony/pi-statusline"
  ]
}

For a single project instead, use project settings (.pi/settings.json) — pi loads it after the project is trusted:

{
  "packages": [
    "npm:@gagapony/pi-statusline"
  ]
}

Reload pi (or run /reload in a running session) and the new footer takes over.

With the aurora-dark theme

This status line was designed for aurora-dark. Add it alongside:

{
  "theme": "aurora-dark",
  "packages": [
    "npm:@gagapony/pi-statusline"
  ]
}

The extension only reads standard theme tokens (accent, success, warning, error, dim, text, mdLink), so it renders correctly under any theme that defines them — it just looks best on aurora-dark.

---

Customize

Everything lives in extensions/statusline.ts. Common tweaks:

• Icons — edit the ICON table near the top.
• Thinking-level colors — edit the THINK_COLOR table.
• Context bar width — change barSegs (default 5).
• Token formatting — edit fmtTok().

After editing, run /reload to apply live.

---

Uninstall

pi remove npm:@gagapony/pi-statusline

Then reload pi; the built-in footer returns.

---

How it works

The extension hooks session_start, checks ctx.mode === "tui", and registers a footer renderer via ctx.ui.setFooter(...). On every render it walks the session entries to compute cumulative token usage (so totals survive compaction / branching), reads git branch and context-usage from the footer data API, and lays out 1–3 lines depending on terminal width.

@earendil-works/pi-coding-agent (the ExtensionAPI types) and @earendil-works/pi-tui (truncateToWidth, visibleWidth) are declared as peerDependencies — pi bundles them, so they are never installed separately.

---

License

MIT © gagapony