# Status line reference

The custom status line is enabled by default in Pi's terminal UI. It displays session information in colour and includes status text from other plugins. It does not install a footer in RPC or print mode.

## Commands

| Command | Behavior |
| --- | --- |
| `/statusline` | Opens an editor with a preview, module selection, and module ordering. |
| `/statusline on` | Enables the custom footer. |
| `/statusline off` | Restores Pi's built-in footer. |
| `/statusline reset` | Restores the default configuration. |
| `/statusline status` | Shows the current settings and settings file path. |
| `/statusline colorful` | Selects the colourful mode. `colourful` is also accepted. |
| `/statusline theme` | Selects the restrained theme mode. |
| `/statusline mono` | Selects monochrome. |

`/statusline color <mode>` and `/statusline colour <mode>` also select a colour mode. Outside the terminal UI, `/statusline` reports the configuration instead of opening the editor.

The `color` and `colour` forms require a mode. Other actions, such as `on` and `reset`, use the direct commands in the table.

## Editor keys

The editor has a live preview and a sample preview. Long previews show a window of lines that follows the selected row so the controls remain visible. Changes remain in the draft until saved. The right side of the header shows `Saved` or `Unsaved changes`. The first three settings control the custom footer, colour mode, and visibility of newly discovered plugin statuses.

If saved settings change while the editor is open, the save reports a conflict and leaves the file unchanged. Reopening the editor loads the latest settings.

| Key | Behavior |
| --- | --- |
| Up or Down, `j` or `k` | Moves the selection. |
| Home or End | Selects the first or last item. |
| Page Up or Page Down | Moves the selection by one page. |
| Space | Toggles a module or changes the selected setting. |
| Shift+Up or Shift+Down, Alt+Up or Alt+Down, `[` or `]` | Moves the selected module earlier or later within its side. Crossing a row boundary moves it to the previous or next row on the same side. |
| Left or Right | Assigns the selected module to the left or right side. |
| `1` through `9` | Assigns the selected module to that row. |
| `+` or `-` | Moves the selected module to the next or previous row, including rows above 9. `=` also moves to the next row. |
| `s` | Adds a separator item after the selected item, on the same row and side. |
| Delete or Backspace | Removes the selected separator item. |
| `c` | Cycles the colour mode. |
| `t` or `T` | Cycles the selected external module's colour forward or backward, including its original styling. |
| `p` | Switches between live and sample previews. |
| `r` | Restores defaults in the draft. |
| Enter or Ctrl+S | Saves the draft and closes the editor. |
| Escape | Closes the editor. Unsaved changes require a second Escape to discard. |
| Ctrl+C | Discards changes and closes the editor immediately. |

## Modules

Each module can be enabled, disabled, reordered, or assigned to either side of any positive-numbered row. The editor groups modules by row and side. Within each side, list order determines display order from left to right. A right group ends at the terminal's right edge, with empty space between the two groups.

Empty values do not occupy space. Rows have no fixed count limit and appear in numeric order. Empty row numbers add no blank lines. Each side wraps between modules onto as many terminal lines as needed, with no overflow cutoff. When both sides have content, the renderer divides the available width between them. A short group leaves more room for the other side. Continuation lines use the full width after the opposite side runs out of content. Every line fits the terminal width. A one-column terminal stacks the two sides.

By default, row 1 contains ready or working, model, thinking level, working directory, branch, and session name. Row 2 contains context remaining, token usage, cache usage, cost, and external statuses. Modules start on the left. Existing settings retain their layout until a module moves to the right.

Modules use spaces between values. There are no automatic dot separators. The optional separator item displays `·` and can be added more than once. Each separator can be moved, hidden, or removed independently. A separator appears only between populated modules on the same side and terminal line, so empty modules and wrapping do not leave a dot at the edge.

| Module | Value |
| --- | --- |
| Ready / working | Whether Pi is idle or running. |
| Model | The current model. |
| Thinking level | The current reasoning effort, shown for models that support reasoning. |
| Working directory | The session's working directory, relative to the home directory when possible. Long paths retain their last characters. |
| Git branch | The branch supplied by Pi's footer data provider. |
| Session name | The current thread name, when present. |
| Context remaining | Remaining context based on Pi's context usage report, with warnings above 70% and 90% used. Unknown usage displays `?`. |
| Token usage | Cumulative session input and output tokens. |
| Cache reads/writes | Cumulative session cache usage. |
| Cost | Cumulative session cost from Pi's usage records, with `(sub)` when Pi reports OAuth authentication. |

Token and cache counts use `k` for thousands, `M` for millions, and `B` for billions. For example, 1,200,000,000 cache-read tokens display as `R1.2B`.

Account quotas and permission settings are not available as built-in modules. A plugin can publish those values as external status text.

## Colour modes

| Mode | Behavior |
| --- | --- |
| `colorful` | Uses varied colours from the active theme, including reasoning effort colours. This is the default. |
| `theme` | Uses a restrained palette from the active theme, with accents and warning colours. |
| `mono` | Removes colour, including ANSI colours from external statuses. |

## External plugin modules

Pi's public `ctx.ui.setStatus(key, text)` API publishes a status value under a key. The editor discovers these keys through the footer data provider. It includes new keys by default and allows each key to be hidden or reordered. Saved preferences remain available when a plugin clears its status or is temporarily absent.

An external module appears when its plugin publishes a status. A plugin can publish several keys, or combine several values into one key. The editor controls each published key as one module. It cannot split values within a key or extract modules from a plugin's custom footer.

Discovery runs while the pi-qol footer is mounted, including while the editor is open. With the custom footer off, the editor retains saved keys but cannot discover new ones.

The new-status visibility setting applies to all keys not yet listed in saved settings, including keys present when the editor opens. Explicitly toggling a key overrides that policy for the key. Previously saved visibility choices stay unchanged.

Each external module has a separate colour choice. The editor shows the choice beside the module and previews changes immediately. The choices are original, red, green, yellow, blue, magenta, cyan, white, and gray. Named colours use the terminal's palette. Colours remain saved when a plugin clears its status.

Original preserves the extension's ANSI styling. A chosen colour replaces that styling, including dim text and background colours, across the whole module. Monochrome suppresses all colours while retaining saved choices. The renderer removes terminal control sequences and flattens multiline text to fit the footer.

Pi has one custom footer slot. If another plugin calls `setFooter`, the latest call determines which footer appears. `/statusline on` installs the pi-qol footer again. `/statusline off` restores Pi's built-in footer when pi-qol owns the footer. It leaves a footer installed by another plugin in place.

If the saved layout only appears after running `/statusline`, another plugin may be replacing the footer at startup. For `pi-subagents`, set `"indicatorPosition": "status"` in `~/.pi/agent/subagents/settings.json`, preserving any other settings, then run `/reload`. This keeps the pi-qol layout active at startup and shows subagent status through the `extension:pi-subagents` module. The default `"footer-right"` mode replaces the whole footer.

## Settings

Settings apply across chats and are stored in `<agent directory>/pi-qol/status-line.json`, normally `~/.pi/agent/pi-qol/status-line.json`.

Each command re-reads saved settings, including manual repairs and changes saved by another Pi process.

The JSON fields are `version`, `enabled`, `colorMode`, `showNewExtensionStatuses`, and `items`. Version is `1`. Each item contains an `id`, an `enabled` boolean, and `row` set to a positive safe integer. The optional `side` field is `left` or `right` and defaults to `left`. Array order determines module order within each row and side.

Built-in IDs are `state`, `model`, `thinking`, `cwd`, `git`, `session`, `context`, `tokens`, `cache`, and `cost`. External status IDs use `extension:<key>`. Missing built-in entries receive their default settings. Disabling a built-in module requires an entry with `enabled` set to `false`.

External items accept an optional `color` field with one of the named colours above, for example `{"id":"extension:pi-subagents","enabled":true,"row":1,"color":"cyan"}`. Omitting `color` preserves the extension's original styling.

Separator items use unique IDs such as `separator:1` and `separator:2`. They have the same `enabled`, `row`, and optional `side` fields as modules. No separators are added to default or existing settings.

The configuration supports at most 200 modules including built-ins. External keys can contain at most 200 characters. Empty keys are ignored. New keys start in row 2, sorted alphabetically, with visibility determined by `showNewExtensionStatuses`.

Malformed settings produce a warning and defaults apply in memory. The original file stays unchanged until a save or reset. Before replacing an invalid file, the extension copies it to `<settings path>.invalid-<timestamp>`. Saves create missing directories and replace the settings file atomically.