pi-neat-ui

English | 中文

A local pi UI polish package: extension + themes.

pi-neat-ui provides a polished powerline-style statusline, custom header, hint widget, working indicator, compact tool rendering, and theme presets.

Features

• Built-in powerline/emoji statusline with the same visual style as @narumitw/pi-statusline.
• Cache-aware token segment:
  • R shows cache-read tokens, displayed even when zero;
  • W shows cache-write tokens, displayed even when zero;
  • ⚡ shows approximate cache hit rate, displayed even when 0%.
• Session duration segment (⏱).
• Custom startup Header.
• Lightweight editor hint Widget.
• Custom working indicator.
• Compact tool rendering:
  • collapsed mode shows short summaries such as bash: done (3 lines) or grep: 12 matches;
  • expanded/verbose mode falls back to pi's built-in renderers to keep syntax/diff highlighting;
  • edit calls use pi's built-in renderer so the dynamic diff preview and add/remove line counts stay accurate;
  • press Ctrl+O to expand details when needed.
• Slash commands:
  • /neat-ui — toggle the extension UI polish.
  • /neat-statusline — toggle the built-in statusline.
  • /neat-tools — switch tool rendering between compact and verbose.
  • /neat-style — switch layout density between compact and spacious.
  • /neat-theme — list or switch available themes.
• Default theme: Pi's built-in dark theme.
• Included themes:
  • neon-aurora — dark neon theme.
  • paper-dawn — light paper-like theme.

Install / Load

Option 1: Install from npm

Install the published package through pi's package manager:

pi install npm:pi-neat-ui@0.3.3

For a project-local install that is written to .pi/settings.json, add -l:

pi install -l npm:pi-neat-ui@0.3.3

Then start pi. The extension applies Pi's built-in dark theme by default:

pi

You can also try it for one run without changing settings:

pi -e npm:pi-neat-ui@0.3.3

Option 2: Install from GitHub

pi install github:MorseWayne/pi-neat-ui

Option 3: Local project package

Put this folder in your project and configure .pi/settings.json:

{
  "packages": ["./pi-neat-ui"]
}

Option 4: Direct development loading

pi -e ./pi-neat-ui/extensions/beautify-ui.ts

Switch themes at runtime with /neat-theme neon-aurora or /neat-theme paper-dawn.

Usage

The extension is enabled by default after loading.

/neat-ui                 # Toggle UI polish
/neat-statusline         # Toggle built-in statusline
/neat-statusline off     # Restore Pi built-in default footer
/neat-statusline on      # Enable pi-neat-ui statusline
/neat-tools              # Toggle compact/verbose tool rendering
/neat-tools verbose      # Show full tool output
/neat-tools compact      # Show compact summaries
/neat-style              # Toggle compact/spacious layout
/neat-theme              # List available themes
/neat-theme dark         # Switch to Pi's built-in dark theme
/neat-theme neon-aurora  # Switch to dark neon theme
/neat-theme paper-dawn   # Switch to light theme

Statusline cache display

When the provider reports prompt-cache usage, the token segment shows cache data:

🔢 ↑423k ↓27k R19.6m W0 ⚡94%

• ↑ normal input tokens
• ↓ output tokens
• R cache-read tokens, always shown
• W cache-write tokens, always shown
• ⚡ approximate cache hit rate, always shown: cacheRead / (input + cacheRead + cacheWrite)
• ⏱ current pi UI session duration, minute-level display

If you also have @narumitw/pi-statusline or another statusline/footer extension installed, disable one of them to avoid footer override races. /neat-statusline off clears pi-neat-ui's footer and restores Pi's built-in default footer; it cannot restore another extension's previous footer.

/neat-tools vs Ctrl+O

• Ctrl+O is pi's built-in UI-level expand/collapse toggle.
• /neat-tools changes this extension's rendering mode.

Recommended workflow:

/neat-tools compact + Ctrl+O when details are needed

Publishing

The repository includes a GitHub Actions workflow for npm publishing.

1. Add an npm automation token as a GitHub repository secret named NPM_TOKEN.
2. Bump package.json version.
3. Create and push a matching tag, for example:

npm version patch
git push --follow-tags

The workflow validates package contents with npm pack --dry-run and publishes tagged versions with npm provenance.

You can also run the workflow manually from GitHub Actions with publish=true.

Notes

/neat-tools compact does not affect tool execution. It only changes how tool results are rendered in the TUI.

The statusline renderer is inspired by @narumitw/pi-statusline; see NOTICE.md.