pi-status-line

A pi package that provides a natural-language configurable multi-line status line.

Included resource

• extensions/status-line.ts

Install

Local path

pi install /absolute/path/to/pi-status-line

npm

pi install npm:@zhangweiii/pi-status-line

GitHub

pi install git:github.com/zhangweiii/pi-status-line

Features

• Multi-line footer rendering
• Rich status widgets for model, git, tokens, context, session, and environment
• /statusline command for natural-language configuration
• configure_statusline tool for LLM-driven layout updates
• Persistent layout config stored under the pi agent directory

Commands

• /statusline — show help, presets, and available widgets
• /statusline reset — reset to the default layout
• /statusline <natural language request> — update the layout with natural language

Examples:

/statusline 切成双排平衡布局
/statusline 第一排模型、分支、上下文，第二排费用、today、month、时长
/statusline show git branch, cost, and context usage
/statusline reset

Presets

• single-line-balanced
• two-line-balanced
• two-line-compact
• three-line-detailed

Default layout:

• row 1: model, thinking, git-branch, git-files, context-pct, context-left
• row 2: cost, tokens-in, tokens-out, tokens-daily, tokens-monthly, session-clock

Display preview

The status line is rendered in the pi footer area at the bottom of the terminal. It supports one-line, two-line, and three-line layouts.

Notes

• The examples below are plain-text previews. Actual colors follow your current pi theme.
• Real values change with your model, repo state, session usage, context size, and terminal width.
• When the terminal is narrow, the footer is truncated to fit the available width.

Default (two-line-balanced)

Model: claude-sonnet-4 | Think: medium | ⎇ main | Files: 3 | Ctx: 12.4% | Left: 175k
Cost: $0.18 | In: 24.3k | Out: 3.8k | Today: 412.7k | Month: 8.1M | Session: 46m

single-line-balanced

Model: claude-sonnet-4 | Think: medium | ⎇ main | Files: 3 | Ctx: 12.4% | Left: 175k | Cost: $0.18 | In: 24.3k | Out: 3.8k | Today: 412.7k | Month: 8.1M | Session: 46m

two-line-compact

Model: claude-sonnet-4 | ⎇ main | Ctx: 12.4% | Cost: $0.18
In: 24.3k | Out: 3.8k | Today: 412.7k | Month: 8.1M | Session: 46m

three-line-detailed

Model: claude-sonnet-4 | Think: medium | ⎇ main | Files: 3
Ctx: 12.4% | Left: 175k | Cost: $0.18
In: 24.3k | Out: 3.8k | Today: 412.7k | Month: 8.1M | Session: 46m

Other widget examples

Ctx: ███░░░░░░░░░░░░ 28k/200k
(+128,-24) | +128 | -24 | (pi-status-line) | 𖠰 feature-readme
Cache: 37.5% | Total: 52.1k | Turns: 19 | ~/work/pi-status-line | Mem: 18.4G/32.0G | Term: 180

Available widgets

• Core: model, thinking
• Git: git-branch, git-changes, git-files, git-insertions, git-deletions, git-root, git-worktree
• Tokens: tokens-in, tokens-out, tokens-cached, tokens-total, tokens-daily, tokens-monthly, cache-hit
• Token speed: speed-in, speed-out, speed-total
• Context: context-length, context-pct, context-left, context-bar
• Session: cost, session-clock, session-turns, session-name
• Environment: cwd, memory, terminal-width

Token widget semantics:

• tokens-in, tokens-out, tokens-cached, tokens-total, cost, session-turns are based on the current session/branch.
• tokens-daily and tokens-monthly are aggregated across session files under the pi agent directory.
• Daily/monthly token scans are cached briefly to avoid rescanning on every render.

Configuration

The extension saves layout config to:

• $PI_CODING_AGENT_DIR/statusline.json
• default: ~/.pi/agent/statusline.json

It also reads session files from:

• $PI_CODING_AGENT_DIR/sessions
• default: ~/.pi/agent/sessions

Development

Use the package locally first:

pi install /absolute/path/to/pi-status-line

Then inside pi:

/reload
/statusline 第一排模型、分支、上下文，第二排费用、today、month、时长

configure_statusline is primarily intended for LLM/tool-driven updates; human users will usually use /statusline.

Publish

1. Check whether package.json → name is available on npm.
2. Login:

npm login

3. Publish:

npm publish --access public

After publishing, users can install it with:

pi install npm:@zhangweiii/pi-status-line

Notes

• This package ships the TypeScript source directly. pi loads extensions via jiti, so a separate build step is not required.
• pi core packages are declared as peerDependencies, following pi package guidance.
• The extension respects PI_CODING_AGENT_DIR for its status line config and session scans, which makes isolated testing and non-default pi runtimes behave correctly.