---
slug: "pi-powerline"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/jwu/pi-powerline@main/README.md"
repo: "https://github.com/jwu/pi-powerline"
source_file: "README.md"
branch: "main"
---
# pi-powerline

Powerline-style UI extensions for [pi](https://github.com/badlogic/pi-mono): custom editor, breadcrumb, footer, and header.

Highly inspired by [pi-powerline-footer](https://github.com/nicobailon/pi-powerline-footer).

![screenshot](https://raw.githubusercontent.com/jwu/pi-powerline/refs/heads/main/assets/pi-powerline.png)

## Install

```bash
pi install npm:pi-powerline
```

## Settings

Settings are read from both global and project files. Project settings override global settings.

| Location | Scope |
|----------|-------|
| `~/.pi/agent/settings.json` | Global |
| `.pi/settings.json` | Current project |

```json
// .pi/settings.json
{
  "powerline": true,
  "breadcrumb": "inner",
  "footer": true,
  "header": true,
  "header-info": true
}
```

| Setting | Values | Default | Effect |
|---------|--------|---------|--------|
| `powerline` | `true` / `false` | `true` | Master switch for all pi-powerline UI extensions |
| `breadcrumb` | `"hide"` / `"top"` / `"inner"` | `"inner"` | Breadcrumb placement |
| `footer` | `true` / `false` | `true` | Enable custom footer |
| `header` | `true` / `false` | `true` | Enable custom gradient-logo header |
| `header-info` | `true` / `false` | `true` | Show header diagnostic info on startup/reload |

### Nerd Font icons

pi-powerline uses Nerd Font icons when it can infer that the terminal supports them.

Detection order:

1. `PI_NERD_FONTS=1` forces icons on
2. `PI_NERD_FONTS=0` forces icons off
3. `GHOSTTY_RESOURCES_DIR` enables icons for Ghostty
4. `TERM_PROGRAM` or `TERM` containing `iterm`, `wezterm`, `kitty`, `ghostty`, or `alacritty` enables icons
5. Otherwise icons are disabled and plain text fallbacks are used

For SSH or terminals that cannot be detected reliably, set it explicitly:

```bash
export PI_NERD_FONTS=1
```

### Header info

`header-info` adds diagnostic sections under the header:

- `Context` — loaded system prompt context files, such as `AGENTS.md` and `.pi/APPEND_SYSTEM.md`
- `Skills` — loaded skills
- `Prompts` — loaded prompt commands
- `Extensions` — loaded extension packages or paths

It is only rendered for `startup` and `reload`, never for new sessions. It also requires Pi's `quietStartup` setting to be `true`:

```json
{
  "quietStartup": true,
  "header-info": true
}
```

## Commands

| Command | Effect |
|---------|--------|
| `/powerline` | Toggle all extensions on/off |
| `/powerline info` | Show current settings |
| `/powerline breadcrumb:top\|inner\|hide` | Set breadcrumb mode |
| `/powerline footer:on\|off` | Toggle footer |
| `/powerline header:on\|off` | Toggle header |
| `/powerline header-info:on\|off` | Toggle header diagnostic info |

## License

MIT