@pi-extensions/pi-statusline

Custom statusline for pi: a rounded editor text box with a prompt and bottom-right session name, plus a footer with model/effort, context, provider remaining, git branch, PR, and diff.

Part of the pi-extensions monorepo.

Highlights

• Rounded text box with ╭─╮, │ │, and ╰─╯ corners plus a › prompt
• Session name on the editor's bottom-right border
• Model · effort from the active model + thinking level
• Context as ctx N% · used/total: green below 50%, yellow at 50%+, red at 70%+
• Session cost $x.xxx from assistant usage.cost.total when non-zero
• Provider remaining for openai-codex, opt-in, off by default (see Provider usage)
• Git ⎇ branch +staged *unstaged ?untracked plus ahead/behind; open PR via gh when present
• Local by default with no network calls or token reads unless you enable provider usage

Quickstart

pi install npm:@pi-extensions/pi-statusline
# or local
pi install /absolute/path/to/pi-extensions/packages/pi-statusline

Restart pi. Name the session so it shows:

/name my task

Example (default, no provider-usage segment until you opt in):

╭─────────────────────────────╮
│ › type here…                │
╰────────────────────── my task ──╯
[gpt-5-codex · high]  [ctx 12% · 24k/200k]  [$0.042]  [⎇ main +1 *2 ?1]  [#12]

After /statusline usage on, a Codex quota segment appears: [5h 80% rem · 4h].

The current branch's open PR is checked on startup, branch changes, /statusline refresh, and at most once every 30 seconds after an agent run. Lookups run in the background and never block the editor. Merged or closed PRs disappear automatically after the next check.

Commands

/statusline            # status + current segments
/statusline on         # enable custom footer (default)
/statusline off        # restore pi’s default footer
/statusline usage on   # opt in to provider quota (reads auth, calls provider)
/statusline usage off  # disable provider quota (default)
/statusline refresh    # re-fetch git (+ provider usage if enabled) now

Both on/off and usage on/off persist to ~/.pi/agent/statusline.json.

Provider usage

Opt-in and off by default. With usage off, the statusline reads no auth files and makes no network calls. Turn it on with /statusline usage on; turn it back off with /statusline usage off.

When on, it reads your provider token and calls that provider's usage API:

| Provider id in pi | Remaining / windows | Reads | Sends token to | |-------------------|---------------------|-------|----------------| | openai-codex | Primary + secondary windows (% rem + reset time) | ~/.pi/agent/auth.json → openai-codex, or ~/.codex/auth.json | chatgpt.com/backend-api |

Only your own credentials are used, and the token goes only to that provider. Other providers (xAI, OpenCode Go, …) have no reliable remaining-% API with pi's credentials, so the segment is omitted for them even when usage is on.

Costs

Yes, pi exposes per-assistant-message usage.cost.total (USD estimate from model pricing). The footer sums those across the session and shows $x.xxx when non-zero. Subscription OAuth turns may still report a computed cost even when you are not billed per-token.

Install methods

| Method | Loads | Command | |--------|-------|---------| | npm (recommended) | This package only | pi install npm:@pi-extensions/pi-statusline | | local | This package only | pi install /absolute/path/to/pi-extensions/packages/pi-statusline | | git (whole monorepo) | All packages in the repo | pi install git:github.com/smarzban/pi-extensions |

See docs/install for one package vs whole monorepo.

License

MIT