pi-footer

A configurable, Ultimate multi-line footer/statusline extension for pi.

pi-footer is built for people who live in the terminal and want their agent UI to expose useful state at a glance: model, provider, context, tokens, cost, git state, session activity, extension statuses, and custom values published by other extensions.

Why use it?

• Make pi feel like your editor. Pick a compact, plain, or powerline-style footer and tune every segment.
• See important agent state without opening menus. Model, reasoning level, verbosity, context usage, token counts, cost, git info, session stats, and more.
• Give other extensions a place to speak. Extensions can publish values through pi.events or ctx.ui.setStatus(...), and users decide where those values appear.
• Experiment safely. The config UI gives a live preview, but only writes to disk when you explicitly save.

Complete demo video

Install

Install extension from npm:

pi install npm:pi-footer

Try it for one run without installing:

pi -e npm:pi-footer

Local development checkout:

npm install
pi -e ./src/index.ts

Quick start

Open the configuration UI:

/footer

Try a preset:

/footer preset powerline
/footer preset powerline-bright
/footer preset powerline-blocks
/footer preset powerline-mono
/footer preset pi-footer
/footer preset compact

Other quick commands:

/footer on
/footer off
/footer reset

Settings are persisted to:

~/.pi/agent/extensions/pi-footer.json

Override with PI_FOOTER_CONFIG=/path/to/settings.json.

Presets

Presets are starting points. After applying one, you can edit lines, widgets, separators, colors, icons, and terminal behavior in the config UI.

| Preset | Best for | Notes | | --- | --- | --- | | default | Everyday use | Balanced model/context/git/cost/session layout. | | compact | Narrow terminals | Uses full width minus 40 columns and a tighter widget set. | | powerline | A clean colored powerline footer | Uses Nerd Font icons, explicit colored separator widgets, and no global separator. | | powerline-bright | A colorful two-line powerline layout | Inspired by ccstatusline-style bright blocks. | | powerline-blocks | Multi-line blocky powerline layouts | Demonstrates multiline styling, token rows, and context blocks. | | powerline-mono | High-contrast monochrome powerline | Gray/black palette inspired by terminal powerline themes. | | git-heavy | Git-heavy workflows | Emphasizes cwd, branch, sha, status, diff, and upstream info. | | pi-footer | Default pi-like footer | Dimmed with pi theme colors; uses full cwd, bracketed branch, session name, pi-style token/cost/cache formatting, context percentage/window, subscription marker, and right-aligned model/thinking. | | demo | Preset gallery | Demo preset combines pi-footer and powerline presets. | | demo-standard | Standard preset gallery | Demo preset for the standard non-powerline presets. |

demo preset:

demo-standard preset:

The pi-footer preset is intended to look like pi's built-in footer while staying editable. It follows the active pi theme.

Powerline presets look best with a Nerd Font-compatible terminal font.

Configuration UI

/footer

Main menu:

• Edit lines — add, clone, move, delete, and select pi-footer rows.
• Edit colors — choose a line, then configure widget foreground/background/bold.
• Terminal Options — configure terminal width behavior and color level.
• Global Overrides — choose presets, separators, icon mode, minimalist mode, and global separator colors.
• Pi extensions — choose which published extension statuses appear in the extension status row.
• Save & Exit — explicitly save the current configuration.
• Exit without saving — discard changes and restore the last saved config.

Common keys:

| Key | Action | | --- | --- | | ↑ / ↓ | Select item | | page up / page down | Jump through long lists | | enter | Open/select/change | | a | Add line/widget | | c | Clone line/widget | | w / s | Move line/widget up/down | | d | Delete line/widget | | space | Enable/disable widget | | r | Toggle raw value in the widget list | | ctrl+s | Save without closing | | esc | Back/close; dirty exit asks for confirmation |

Save/discard behavior

The UI updates the live preview immediately while you edit. Disk writes only happen when you explicitly save:

• ctrl+s
• Save & Exit
• confirm save from the unsaved-changes dialog

If you exit without saving, the runtime config is restored to the last saved config.

The title shows inline config state: Unsaved, Saving…, Saved.

Widgets

Widgets are instance-based. You can add the same widget multiple times, clone it, disable individual instances, and customize each instance separately.

Every non-layout widget supports common options: Enabled, Raw value only, Hide when empty where relevant, Custom icon, foreground/background/bold colors, and ANSI256 overrides.

The Value example column shows the widget value before labels/icons and colors are applied. In normal mode, pi-footer prefixes non-layout widgets with the selected emoji, Nerd Font icon, text label, or custom icon. Raw value only and minimalist mode render the raw value directly.

Core widgets

| Widget | Shows | Widget-specific options | Value example | | --- | --- | --- | --- | | Model | Active model id. | Show provider. | claude-sonnet-4-5 | | Provider | Active model provider. | — | anthropic | | Provider/Model | Provider and model together. | — | anthropic/claude-sonnet-4-5 | | Thinking Level | Current pi thinking/reasoning level. Hidden when unavailable. | — | high | | Text Verbosity | Text verbosity for providers that expose it. Hidden when unavailable. | — | low | | Context Window | Model context window size. | Token format, hide when zero. | 200k | | Working Dir | Current working directory. | Display style: default, full ~, fish-style; segment count. | ~/…/projects/pi-footer | | Working Dir Name | Basename of current working directory. | — | pi-footer | | Session Name | pi session display name. | Text when empty, hide when empty. | release prep | | Active Tools | Count of active tools. | — | 4 | | Pi Event Value | Value published through pi.events. | Widget ID, text when empty, hide when empty. | on | | Pi Extension Status | Value published by another extension through ctx.ui.setStatus. | Status key, trim value, preserve trim styles, text when empty, hide when empty. | fast |

Tokens, context, and cost widgets

| Widget | Shows | Widget-specific options | Value example | | --- | --- | --- | --- | | Input/Output Tokens | Session input and output token totals. | Token format. | ↑42k ↓8.4k | | Input Tokens | Session input token total. | Token format, hide when zero. | 42k | | Output Tokens | Session output token total. | Token format, hide when zero. | 8.4k | | Total Tokens | Total tokens from usage records. | Token format, hide when zero. | 182.4k | | Cache Read | Cache-read token total. | Token format, hide when zero. | 120k | | Cache Write | Cache-write token total. | Token format, hide when zero. | 12k | | Context Length | Current context token estimate/usage. | Token format, conditional colors, hide when zero. | 50k | | Context % | Used context percentage. | Conditional colors. | 25% | | Context Remaining | Remaining context percentage. | Conditional colors. | 75% | | Context Bar | Progress bar plus context usage. | Display: default, short, short-only, medium; token format; conditional colors. | [████████░░░░░░░░░░░░░░░░░░░░░░░░] 50k/200k (25%) | | Session Cost | Estimated session cost. | Cost format, show subscription marker. | $0.1234 | | Input Speed | Average input tokens per minute across transcript span. | Token format, hide when zero. | 20.1k/min | | Output Speed | Average output tokens per minute across transcript span. | Token format, hide when zero. | 1.1k/min | | Total Speed | Average total tokens per minute across transcript span. | Token format, hide when zero. | 21.2k/min |

Session widgets

| Widget | Shows | Widget-specific options | Value example | | --- | --- | --- | --- | | Message Counts | User/assistant/tool result counts. | — | 7u/6a/12t | | User Messages | User message count. | — | 7 | | Assistant Messages | Assistant message count. | — | 6 | | Tool Results | Tool result count. | — | 12 | | Total Messages | Total user, assistant, and tool messages. | — | 25 | | Transcript Span | Time between first and latest recorded session entry. | — | 1h 12m | | Session Total Time | Live wall-clock time since first session entry. | — | 1h 20m | | Session Start | First session entry time. | — | 09:41 | | Last Activity | Most recent session entry time. | — | 11:06 | | Session ID | Current pi session id. | — | 018f1234 | | Compactions | Number of compaction summaries. | — | 1 |

Git widgets

| Widget | Shows | Widget-specific options | Value example | | --- | --- | --- | --- | | Git Branch | Current Git branch. | Display: plain, round brackets, custom surround; hide when empty. | main or (main) | | Git SHA | Short HEAD commit SHA. | Hide when empty. | a1b2c3d | | Git Root Dir | Repository root directory name. | Hide when empty. | pi-footer | | Git Status | Staged, unstaged, and untracked file counts. | Hide when empty. | +2 ±3 ?1 | | Git Diff | Uncommitted insertion/deletion summary. | Display: plain or compact; hide when empty. | +42/-10 or (+42,-10) | | Git Clean Status | Clean/dirty repository state. | Hide when empty. | clean or dirty | | Git Staged Files | Staged file count. | Hide when empty. | 2 | | Git Unstaged Files | Unstaged file count. | Hide when empty. | 3 | | Git Untracked Files | Untracked file count. | Hide when empty. | 1 | | Git Insertions | Uncommitted insertion count. | Hide when empty. | 42 | | Git Deletions | Uncommitted deletion count. | Hide when empty. | 10 | | Git Ahead/Behind | Ahead/behind counts relative to upstream. | Hide when empty. | ↑1 ↓0 | | Git Remote | origin remote URL. | Hide when empty. | [email protected]:user/repo.git |

Custom and layout widgets

| Widget | Shows | Widget-specific options | Value example | | --- | --- | --- | --- | | Custom Text | Literal user-defined text. | Text. | prod | | Separator | Explicit separator segment. | Separator style; custom text for custom separator. | •, \|, -, , | | Spacer | Fixed blank space. | Width from 1 to 40. | <empty space> | | Flex Separator | Invisible split point that pushes following widgets to the right side. | — | left widgets <---> right widgets |

Styling

Icon modes

Supported icon modes: Emoji, Nerd Font icons, Text labels.

Individual widgets can override their icon with Custom icon.

Colors

Each widget supports:

• foreground
• background
• bold
• custom ANSI256 foreground/background (0-255)

Foreground colors also include pi theme colors such as Pi Dim, Pi Accent, Pi Warning, and Pi Error. These follow the active pi theme and are useful for native-looking presets like pi-footer.

In color editing:

• ← / → cycle/change
• type digits to edit ANSI256 values
• backspace deletes one digit
• values over 255 clamp to 255

Terminal color levels: Truecolor, 256 Color, Basic 16-color, No Color.

Separators

Global separator modes: none, dot, pipe, space, powerline, dash, comma

Global separator foreground/background colors apply only to automatic separators inserted between widgets.

Separator widgets are independent. They have their own separator style and colors and are not affected by global separator colors.

Powerline-oriented separator widget styles include hard transitions, soft transitions, and caps. The powerline presets use explicit separator widgets so transitions can be colored segment-by-segment.

Terminal width modes

• Full width always
• Full width minus 40 - truncates the pi-footer to fit within terminal width - 40 columns.

The compact preset uses Full width minus 40; other presets use full width.

Extension integration

pi-footer exposes two integration paths for extension authors.

1. Event widgets

Add a Pi Event Value widget and set its Widget ID to a stable value, for example fast_mode or service_tier.

Other extensions can update that widget through pi's shared event bus:

pi.events.emit("pi-footer:update-widget", {
  widgetId: "fast_mode",
  value: "on",
});

Clear a previously published value by sending null:

pi.events.emit("pi-footer:update-widget", {
  widgetId: "fast_mode",
  value: null,
});

Values are live/in-memory. After reload or session switch, publisher extensions should emit their current value again.

2. Pi extension statuses

Extensions can publish status text through pi's UI API:

const STATUS_KEY = "my-extension";

ctx.ui.setStatus(STATUS_KEY, "fast");

Users can display that value in two ways:

• add a Pi Extension Status widget and set Status key to my-extension
• show/hide it in the Pi extensions menu for the extension status row

Multiple widgets may point at the same status key. pi-footer does not auto-hide or deduplicate extension statuses; the user controls what appears.

Use Trim value on a Pi Extension Status widget to remove leading visible characters from the published status. For example, trim 2 turns ● On, ● Enabled, or ◌ Disabled into On, Enabled, or Disabled. Preserve trim styles is enabled by default, so whole-status ANSI styling is replayed after the trimmed prefix; turn it off to drop styling that was attached only to the trimmed prefix.

Incoming ANSI styling from extension statuses is preserved by default. If the user sets a custom foreground/background/bold override on the Pi Extension Status widget, incoming ANSI is stripped first so the user override wins cleanly.

Development

npm run lint
npm run fmt
npm run typecheck
npm run test

Credits

• @sirmalloc for ccstatusline inspiration.
• @badlogic for pi and its built-in footer.

License

MIT