@false00/pi-powerline

@false00/pi-powerline is a maintained fork of jwu/pi-powerline, continuing to provide powerline-style UI extensions for pi: a custom editor, breadcrumb, footer, and header.

The upstream inspiration still comes from pi-powerline-footer.

Differences from upstream

This fork currently includes the following explicit additions:

1. Fixes stale ctx crashes
   • Fixes cases where old UI components kept reading an invalid ExtensionContext after ctx.reload(), ctx.newSession(), ctx.fork(), or ctx.switchSession() and triggered:
     • This extension ctx is stale after session replacement or reload
   • Approach:
     • breadcrumb / widget / editor / header / footer now use snapshot state instead of holding long-lived old ctx references
     • custom UI state is proactively cleaned up during session_shutdown
2. Footer supports subagent-inclusive token totals and cost estimates
   • If @tintinweb/pi-subagents is installed and used, the footer shows extra Σ↑... and Σ↓... segments.
   • Those segments represent the summed input and output tokens used by all subagents in the current session.
   • When subagent cost data is available, the footer also shows Σ$... for summed subagent cost and T$... for the combined main-session + subagent cost.
   • Subscription-auth cost displays are labeled with est so Copilot / OAuth-backed sessions are clearly shown as estimates rather than exact billing.
   • That usage is written into the current session when subagents complete, so it remains available after /resume.
3. More consistent cross-platform path display
   • Header-rendered context, extension, and package paths are normalized to /, reducing Windows/Unix display differences.
4. Development checks use standard Node/npm commands
   • Uses npm test, npm run typecheck, and npm run lint, so local validation no longer depends on bun.

Install

Install from npm

pi install npm:@false00/pi-powerline

Install from GitHub

pi install git:github.com/false00/pi-powerline

Settings

Settings are read from both global and project configuration, with project settings taking precedence.

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

{
  "powerline": true,
  "breadcrumb": "inner",
  "footer": true,
  "header": true,
  "header-info": true
}

| Setting | Values | Default | Description | |---|---|---|---| | powerline | true / false | true | Master switch | | breadcrumb | "hide" / "top" / "inner" | "inner" | Breadcrumb placement | | footer | true / false | true | Enable custom footer | | header | true / false | true | Enable gradient header | | header-info | true / false | true | Show diagnostic info during startup/reload |

Nerd Font icons

If the terminal supports Nerd Font, icons are enabled automatically. Detection order:

1. PI_NERD_FONTS=1 forces icons on
2. PI_NERD_FONTS=0 forces icons off
3. GHOSTTY_RESOURCES_DIR implies support
4. TERM_PROGRAM or TERM contains iterm, wezterm, kitty, ghostty, or alacritty
5. Otherwise it falls back to plain text

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

export PI_NERD_FONTS=1

Header diagnostics

header-info displays the following under the header:

• Context: system-prompt context files such as AGENTS.md and .pi/APPEND_SYSTEM.md
• Packages: configured pi packages
• Tools: currently active tools
• Skills: loaded skills
• Prompts: loaded prompt commands
• Extensions: loaded extension paths

It is rendered only for startup and reload; it is not shown for new, resume, or fork. It also requires Pi's quietStartup setting to be true:

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

Commands

| Command | Description | |---|---| | /powerline | Toggle the master switch | | /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 diagnostics |

Development and verification

npm install --ignore-scripts
npm test
npm run typecheck
npm run lint
npm pack --dry-run

This repository intentionally avoids install-time lifecycle hooks. Dependency installs should use --ignore-scripts. The committed .npmrc also sets ignore-scripts=true, so cloned checkouts stay in no-script mode by default. Current development and validation targets assume Node.js 22.19+.

This repository includes:

• tsconfig.check.json: reproducible TypeScript check configuration
• semantic-release: automated release config for GitHub / npm
• CHANGELOG.md: explicit fork version history
• CONTRIBUTING.md: contributor workflow and release checklist
• SECURITY.md: vulnerability reporting and hardening guidance

Manual publish note

Recommended manual publish flow:

npm run lint && npm pack --dry-run && npm publish --access public

Because this repository commits .npmrc with ignore-scripts=true, npm publish already runs in no-script mode here. Run the validation steps above manually before publishing.

License

MIT