✨ pi-statusline — Add a Ready-to-Use Powerline Footer to Pi

Add a Powerline-style footer that works without setup and keeps important Pi, workspace, Git, usage, and time context visible as the terminal narrows.

A representative uncolored layout:

░▒▓ 🤖 sonnet-4 🧠 high 📁 pi-extensions 🌿 main ~2 🪟 ctx 42.0%/200k 🕒 16:42

✨ Features

• Works immediately with a balanced default for model, thinking, workspace, Git, context, activity, and time.
• Removes lower-priority segments before important information is clipped.
• Shows when Pi is waiting for an extension UI prompt, streaming, or running tools.
• Adds optional token, prompt-cache, provider usage, and cost details.
• Offers three information levels, seven previewable palettes, and advanced custom layouts.
• Uses ANSI-256 palette colors when Pi's effective terminal capabilities disable true color.
• Loads a generated split runtime to reduce Pi package startup work.

Need more customization? See pi-starship (npm). It uses Starship-inspired TOML and style syntax for deeper control over layout, modules, and colors. Choose pi-statusline for practical defaults and quick setup.

📦 Install

pi install npm:@narumitw/pi-statusline

Try the published package without installing it permanently:

pi -e npm:@narumitw/pi-statusline

Build the generated runtime and try the local package from this repository:

npm --workspace @narumitw/pi-statusline run build
pi -e ./packages/pi-statusline

The package declares dist/index.ts, so build an unbuilt local checkout before Pi loads the package directory. Install only from sources you trust because Pi extensions run with Pi's permissions.

🚀 Quick start

Install the extension and start Pi to use the balanced default immediately. Run /statusline to preview and apply an appearance or information level.

🎛️ Menu and information levels

Appearance (tokyo-night)
Information (balanced)
Advanced
Status
Help

Menu item	What it does
Appearance	Preview palettes with Up/Down; Enter applies and Escape cancels
Information	Preview and apply a curated segment set
Advanced	Open Custom layout or Edit settings JSON
Status	Show the effective source, path, appearance, layout, and diagnostics
Help	Show command and schema guidance

Information levels

Selecting a level replaces only segments and preserves unrelated JSON fields.

Level	Included segments
Minimal	model cwd branch context
Balanced (default)	model thinking cwd branch tools context time
Detailed	provider model thinking cwd branch tools context tokens cache cost time
Custom	Any other segment order, including explicit line breaks

The tools segment takes no space while idle. cache takes no space when Pi has reported no cache reads or writes.

💬 Commands

Command	Purpose
/statusline	Open Appearance, Information, Advanced, Status, and Help
/statusline settings	Open the JSON editor in TUI mode
/statusline status	Show the effective settings and diagnostics
/statusline help	Show command and schema guidance

The direct settings, status, and help routes remain for compatibility. The main menu is TUI-only; Escape returns from Advanced or closes the menu. RPC receives notifications instead of TUI-only controls. Unknown subcommands and trailing arguments are rejected. The standard palette picker owns navigation and cleanup; pi-statusline owns footer previews, settings, and rollback. The width-aware layout editor and JSON editor remain specialized UI.

📐 Runtime behavior

Responsive fitting

Each row keeps its configured segment order. If it is too wide, pi-statusline removes the lowest-priority segment, recomputes the powerline transitions, and repeats until the row fits. Retention priority is highest to lowest:

context model branch tools cwd thinking cost provider cache tokens time turn brand

Explicit line_break entries remain row boundaries. If the last remaining segment is itself wider than the row, that row renders empty rather than emitting an over-width line.

Directory, activity, Git, and PR state

• cwd uses Starship's directory presentation defaults: contract the home directory to ~, contract to the Git repository root when available, then retain at most the last three path components. This changes display only; the configured segment list and Pi working directory are untouched.
• Repository-root discovery is cached with Git status outside footer rendering; a failed root query falls back to home/path-component contraction without hiding the segment.
• During active work, tools shows ⌨ waiting for <kind>, 💭 thinking, or ⚙️ <tool> with parallel counts.
• A sanitized prompt title follows the prompt kind when available.
• Prompt waiting takes precedence without losing the underlying tool or streaming state, which returns when the prompt closes.
• Activity disappears after the agent settles and resets across session replacement or shutdown.
• Clean repositories show no Git counters.
• Dirty counters are ⇡ ahead, ⇣ behind, + staged, ~ modified/deleted, ? untracked, and ! conflicts.
• A linked or plain GitHub PR reference appears with the branch when possible, avoiding a duplicate extension status.
• Context color changes to warning at 70% and error at 90%.
• Git state is cached outside footer rendering and stale session results are ignored.

Usage and context

• context renders one-decimal current usage and the model window, such as 2.4%/272k. After compaction it can temporarily render ?/272k until the next valid assistant response.
• tokens, cache, and cost total every usage-bearing session entry, matching Pi's native footer. This includes assistant messages, nested-LLM tool results, compactions, and branch summaries, including abandoned branches retained in the session.
• Cache tokens are R<read>, W<write>, and CH<rate>. R and W are cumulative; CH uses only the latest assistant prompt: cacheRead / (input + cacheRead + cacheWrite) * 100.
• Subscription-backed OAuth models and kimi-coding append (sub) to cost. The dollar value is usage cost, not proof of an amount billed under a subscription.
• Pi's public extension API does not expose the current auto-compaction toggle, so this footer cannot reliably show the native (auto) marker.

⚙️ Settings

The extension uses one user-level file:

<getAgentDir()>/pi-statusline.json

There are no project or environment overrides. When the file is absent, pi-statusline uses built-in defaults without creating the file or its parent directory. The first successful settings save creates a complete editable document atomically. Malformed or unreadable settings are never overwritten. Settings reload on startup, /reload, and session replacement.

A valid legacy pi-statusline-settings.json remains readable with a warning and is never modified automatically; rename it to pi-statusline.json. If both files exist, pi-statusline.json wins.

Settings reference

Field	Accepted values	Purpose
palettePreset	tokyo-night, ocean, sunset, forest, candy, neon, mono, custom	Select the active color preset
palette	Per-segment fg/bg #RRGGBB colors	Define colors used by custom
density	compact, cozy	Control horizontal padding
separator	none, dot, bar, powerline, round	Separate adjacent segments in one color block
segments	Ordered unique segment names and line_break	Control visibility, order, and rows
segmentText	Per-segment prefix and suffix; model truncation fields	Format Pi-owned dynamic values
extensionStatusIcons	Raw status key or namespace:* to icon string	Customize extension status icons

All fields are optional in an existing document. Missing fields use defaults. Menu saves warn about and preserve unknown fields. Invalid recognized values block saving and leave the file and live footer unchanged.

A compact customization example:

{
  "palettePreset": "ocean",
  "density": "compact",
  "separator": "dot",
  "segments": ["model", "thinking", "cwd", "branch", "context", "cache", "cost"],
  "segmentText": {
    "model": {
      "truncationLength": 40,
      "truncationSymbol": "…",
      "truncationDirection": "middle"
    },
    "context": { "prefix": "ctx ", "suffix": "" }
  },
  "extensionStatusIcons": {
    "goal": "◎",
    "foo:*": "🧪"
  }
}

Use Advanced → Edit settings JSON or /statusline settings to edit, validate, atomically save, and apply the file.

🎨 Appearance

Named palettes provide contrast-checked color ramps. Appearance previews update while the picker moves, but save only when Enter is pressed; Escape restores the saved palette.

When palettePreset is custom, palette maps segment names to foreground/background colors:

{
  "palettePreset": "custom",
  "palette": {
    "model": { "fg": "#090c0c", "bg": "#a3aed2" },
    "context": { "fg": "#c0caf5", "bg": "#1d2230" }
  }
}

• Selecting custom without a palette copies the active named preset as a starting point.
• A manually authored "palettePreset": "custom" without palette uses Tokyo Night colors.
• Named presets ignore but preserve an existing custom palette.
• A palette object without palettePreset selects custom.
• Legacy string palettes such as "palette": "ocean" remain accepted.
• Missing custom colors remain unstyled instead of inheriting Tokyo Night.
• Adjacent segments with identical colors share one block; transitions use .
• Hex palette colors render as ANSI-256 when Pi's effective terminal capabilities disable true color.

segmentText values must be single-line text without terminal control characters. Use line_break for another row rather than inserting a newline into a prefix or suffix.

Model truncation

Long model IDs are truncated out of the box so the balanced footer can retain useful model context:

{
  "segmentText": {
    "model": {
      "truncationLength": 36,
      "truncationSymbol": "…",
      "truncationDirection": "start"
    }
  }
}

truncationLength counts model grapheme clusters retained before the symbol. The built-in value is 36; set it to 0 to display the complete ID. The direction names the removed portion:

• start retains the suffix and is the default, which is useful for long llama.cpp paths and model variants.
• middle retains both ends.
• end retains the prefix.

Truncation runs after the built-in Claude/GPT shortening rules but before the configured model prefix and suffix. It changes display only—the provider model ID is untouched. Terminal control sequences in model IDs are removed at render time, and unsafe configured symbols are rejected. An empty truncationSymbol truncates without a marker. pi-statusline treats model IDs as opaque strings and does not parse paths, repositories, GGUF suffixes, or quantization names. At very narrow widths, the existing responsive priorities may still omit the model rather than overflow the terminal.

🧩 Advanced layout

Open Advanced → Custom layout when the curated levels are not enough.

Key	Action
Up/Down	Navigate
Page Up/Page Down	Move by one viewport
Enter/Space	Show or hide the selected segment
M	Enter or leave Move mode
Up/Down in Move mode	Reorder the selected visible segment
Alt+Up / Alt+Down	Reorder without entering Move mode
B	Add or remove a line break after the selected segment
Configured Back key (Escape by default)	Leave Move mode first, then close the screen
Ctrl+C	Close the screen immediately, including from Move mode

The layout displays the effective Back key and keeps Ctrl+C available when Back is remapped. Every successful change saves and applies immediately. Closing the screen does not roll it back.

Available data segments:

brand provider model thinking cwd branch tools context tokens cache cost time turn

Data segments must be unique. line_break may repeat when data segments separate occurrences, but consecutive breaks are invalid. It has no segmentText entry. The menu cleans up leading, trailing, and newly consecutive breaks after visibility changes. Manually authored leading/trailing breaks represent empty rows.

{
  "segments": ["model", "line_break", "cwd", "branch", "context"]
}

An empty segments array hides the main powerline while extension statuses can still render.

🔌 Extension statuses and icons

Other extension statuses appear below the main powerline, wrap to terminal width, and are limited to five items. Icons use this order:

1. Exact configured raw key, such as goal or foo:server.
2. Longest configured colon wildcard, such as foo:* or foo:server:*.
3. Unambiguous installed-package alias, such as @vendor/pi-foo, pi-foo, or foo.
4. Leading emoji supplied by the status text.
5. Built-in icon.
6. Generic 🔌 fallback.

Set an icon to "" to hide only the icon. Wildcards match colon namespaces, not slash-delimited keys. Configure slash keys exactly. Compatibility fallbacks retain codex-usage, pisync, and unknown-error-retry; an explicit canonical key wins.

For interoperable extensions, prefer one aggregated key or a stable coexistence slot:

<extension-id>
<extension-id>:<stable-slot>

Put transient activity in the value, and clear the exact key that was set.

🚧 Limitations

• The footer needs Powerline glyphs and emoji for its intended appearance.
• Pi does not arbitrate footer ownership, so another footer extension can replace pi-statusline.
• Custom layouts support ordered segments and line breaks, not a variable or format language.

🛠️ Troubleshooting

• Powerline symbols look wrong: use a font with Powerline glyphs and emoji support.
• The footer reports settings warnings: run /statusline status, then /statusline settings to fix invalid recognized fields.
• The footer appears to be replaced: disable pi-starship or another extension that also calls Pi's setFooter().
• A custom segment disappears on a narrow terminal: check the responsive priority above or add an explicit line_break.

🗂️ Package layout

packages/pi-statusline/
├── dist/                  # generated split TypeScript runtime loaded by Jiti
├── scripts/
│   └── build-runtime.mjs  # deterministic runtime bundler and eager-boundary validator
├── src/
│   ├── index.ts          # thin entrypoint forwarding to the source runtime
│   ├── statusline.ts     # authoritative lifecycle implementation
│   ├── command-contract.ts
│   ├── render.ts
│   ├── directory.ts
│   ├── usage.ts
│   ├── powerline.ts
│   ├── information-profiles.ts
│   ├── commands.ts
│   ├── settings.ts
│   ├── extension-status.ts
│   ├── git-status.ts
│   ├── ansi.ts
│   ├── types.ts
│   └── presets/
├── test/
├── README.md
├── LICENSE
├── tsconfig.json
└── package.json

src/ is the authoritative implementation, and src/index.ts remains its thin source forwarder. The package build emits the sole declared Pi entrypoint at dist/index.ts without forwarding back into src.

🔎 Keywords

Pi extension, Pi coding agent, statusline, Tokyo Night, powerline, responsive terminal footer, context usage, prompt cache, cache hit rate, model status.

📄 License

MIT. See LICENSE.