# pi-hud-classic-footer

English | [简体中文](README.md)

## Based on [Hiyori97/pi-hud-footer](https://github.com/Hiyori97/pi-hud-footer) (MIT License)

A Claude HUD style custom footer/statusline extension for [pi coding agent](https://github.com/earendil-works/pi).

It keeps model, context, token, cache, cost, tool-call, and running-state information visible near the bottom of the TUI. Which items appear on each line — and in what order — is fully customizable via `classicLayout`. The cursor supports `bar` / `block` styles, defaulting to a steady, non-blinking vertical bar.

## Highlights

- Shows the current model, thinking level, project name, and git branch
- Shows context usage, cumulative token usage scoped to the session tree or active branch, output rate, cache read/write tokens, and cache hit rate
- Supports aggregate or latest-request cache hit rates
- Shows running / ready state, session elapsed time, estimated cost, and turn duration (the ready state includes the last turn duration)
- Displays costs in USD or CNY, with a customizable USD-to-CNY rate that defaults to `6.8`
- Shows tool-call statistics while keeping footer height stable
- Custom footer layout via `classicLayout`: freely arrange display keys row by row (see [Layout](#layoutclassiclayout) below)
- Can show the previous user question (`lastQuestion`), with a `Ctrl+Shift+I` shortcut to view it quickly
- Supports Chinese and English UI text, selected automatically from the system language by default
- Supports global and project-level JSONC/JSON configuration (with comments)
- Supports bar / block cursor styles via DECSCUSR for a steady hardware-bar cursor experience

## Screenshots

![Classic footer style example](docs/assets/hud-footer-classic.png)

## Installation

Recommended installation from npm:

```bash
pi install npm:pi-hud-classic-footer
```

You can also install from GitHub without specifying a version:

```bash
pi install git:github.com/0717wuwang/pi-hud-classic-footer
```

For local development or debugging, install from a local path:

```bash
pi install /path/to/pi-hud-classic-footer
```

## Commands & shortcuts

| Command | Description |
|---|---|
| `/hud-footer` | Toggle the HUD footer on or off for the current session. |
| `/hud-footer-reload` | Reload configuration and refresh the HUD footer. |

| Shortcut | Description |
|---|---|
| `Ctrl+Shift+I` | Pop up the previous user question (only when one exists). |

## Configuration

Full configuration reference: [docs/CONFIG.en.md](docs/CONFIG.en.md)

Example configuration: [examples/hud-footer.json](examples/hud-footer.json) / annotated JSONC: [examples/hud-footer.jsonc](examples/hud-footer.jsonc)

| Level | Path | Notes |
|---|---|---|
| Global | `~/.pi/agent/hud-footer.jsonc` (or `.json`) | Applies to all sessions.
| Project | `.pi/hud-footer.jsonc` (or `.json`) | Read only when the project is trusted, and overrides global configuration.

### Options

| Option | Description |
|---|---|
| `enabled` | Enable the HUD footer. |
| `language` | UI language: `auto` / `zh` / `en`. |
| `cursorStyle` | Cursor style: `bar` (steady vertical bar) / `block` (default block). Defaults to `bar`. TUI mode only. |
| `modelDisplay` | Model name display mode: `short` / `long` / `full`. Defaults to `short`. |
| `projectNameDepth` | Number of segments kept in the project path. Range `-1..10`, defaults to `3`; `-1` shows the full path. |
| `classicLayout` | Footer layout config. Each element is an array of display keys for one row. Falls back to the built-in default layout when unset (see [Layout](#layoutclassiclayout) below). |
| `cacheRateMode` | Cache hit rate: aggregate (`total`) or latest request (`latest`). Defaults to `total`. |
| `currency` | Cost display currency: `USD` / `CNY`. Defaults to `USD`. |
| `exchangeRate` | USD-to-CNY exchange rate. Defaults to `6.8` (1 USD = 6.8 CNY). |
| `barWidth` | Context progress bar width. Range `6..40`, defaults to `18`. |
| `maxTools` | Maximum number of tools shown in the tool summary. Range `1..20`, defaults to `7`. |
| `usageScope` | Cumulative token and cost scope: active branch (`branch`) or complete session tree (`session`). Defaults to `branch`. |

After changing configuration, run this in pi:

```text
/hud-footer-reload
```

Or:

```text
/reload
```

## Layout (classicLayout)

`classicLayout` controls what each footer line shows. Each line is an array; items render in order, separated by ` | `. Lines with no visible content are not rendered. When unset, the built-in default layout is used:

```jsonc
[
	["project", "git"],
	["model", "context", "state"],
	["tokens", "tokenBreakdown", "tokenRate", "cacheRate", "elapsed", "cost"],
	["toolsLine"]
]
```

Example: model and project on one line, plus the previous question:

```jsonc
{
	"classicLayout": [
		["model", "project", "git"],
		["context", "state"],
		["tokens", "tokenBreakdown", "tokenRate", "cacheRate", "elapsed", "cost"],
		["toolsLine"],
		["lastQuestion"]
	]
}
```

Available display keys:

| Key | Content |
|---|---|
| `model` | Model (includes thinking level and provider). |
| `project` | Project path (depth controlled by `projectNameDepth`). |
| `git` | Git branch. |
| `context` | Context usage: progress bar + percentage + tokens. |
| `tokens` | Total tokens. |
| `tokenBreakdown` | Input / output / cache read/write breakdown. |
| `tokenRate` | Main agent's current streaming output rate. |
| `cacheRate` | Cache hit rate. |
| `elapsed` | Session elapsed time. |
| `cost` | Estimated cost. |
| `state` | running / ready state (includes last turn duration when ready). |
| `turnDuration` | Renders no column of its own; when present on any line it enables the "turn duration" display: the working message shows the current turn's elapsed time while running, and a notification shows "Turn duration X" when the turn ends. |
| `toolsLine` | Tool-call statistics line. |
| `lastQuestion` | The previous user question (truncated to fit width). |

Invalid keys are skipped (with a `console.warn`, no error).

## Metrics

Token metrics use these icons:

| Icon | Meaning |
|---|---|
| `↑` | Input tokens |
| `↓` | Output tokens |
| `R` | Cache read tokens |
| `W` | Cache write tokens |
| `⚡` | Cache hit rate |

`R` / `W` are hidden independently when their value is `0`.

`usageScope` determines whether ↑/↓/R/W and cost accumulate over the complete session tree or the active branch. The `session` mode includes assistant messages, tool results with usage, compactions, and branch summaries. Context usage and tool statistics remain scoped to the effective context and active branch, respectively.

`tokenRate` shows the main agent's current streaming output rate, computed from output-token deltas over the last 0.5-2 seconds.

`cacheRateMode` selects either the latest assistant request on the active branch (`latest`) or aggregate active-branch usage (`total`). Cache hit rate formula:

```txt
cacheRead / (input + cacheRead + cacheWrite)
```

Meaning: cached input tokens / total input-side tokens.

## Cursor style

`cursorStyle` sets the terminal hardware cursor via DECSCUSR. It only applies in TUI mode and is restored when the session ends:

| Value | Description |
|---|---|
| `bar` | Steady vertical bar (default), no blinking. |
| `block` | Restores the terminal's default block cursor. |

## Development / temporary loading

Load without installing:

```bash
pi -e ./pi-hud-classic-footer
```

From inside this repository:

```bash
pi -e .
```

After making changes, run this in pi:

```text
/reload
```

## Publishing

See [docs/PUBLISH.en.md](docs/PUBLISH.en.md).

## Security

pi extensions run with your system permissions. This extension only reads session metadata exposed by the pi extension API and git branch information exposed by the pi footer API. It does not access the network.

## License

MIT