Custom Terminal UI for pi Coding Agent
Beautiful themes, smart status bar, and enhanced message rendering
---
## π Features
- ποΈ **Editor user zone** β the prompt area becomes a styled zone with 4 presets (`droid`, `gemini`, `cli-dock`, `nvim`): model, thinking level, context meter, git branch with +/- LOC, response speed, and token usage rendered right around your input β ported from [pi-droid-styling](https://github.com/sting8k/pi-droid-styling)
- π§° **Tool badges** β boxed call/result badges for bash, read, write, edit, grep, find, and ls, with elapsed time, output size, collapsed previews, and a side-by-side split diff for edits; `reasonix` compact-row mode optional
- π¬ **Message styling** β `β’` assistant prefix, muted thinking with a live collapsed-tail view, boxed compaction/skill/branch blocks, and a `β`-railed codeblock renderer; user messages stay plain (optional `β―` prefix and turn dividers in config)
- π **Gradient startup** β 9-row gradient "pi" logo derived from your theme accent, key hints, ready indicator, and OSC 11 terminal background sync so the whole window matches the theme
- π₯οΈ **Custom Status Bar** β real-time footer showing model, thinking level, cwd, git branch, context usage (%), and API cost (used when the custom editor is off)
- π¨ **Catppuccin Dark Theme** β Dark theme based on [Catppuccin Mocha](https://github.com/catppuccin/catppuccin) with 64+ color mappings
- β³ **State-aware Working Loader** β braille spinner with labels that follow the work (Working / Thinking / Answering / Running), elapsed time, and adaptive greenβyellowβred tone when the stream stalls
- π **Compact Startup** β Gradient pi logo with key hints and a one-line `β Resources β¦` summary (expandable into System & Context / Available Tools tables) instead of pi's full resource listing
- βοΈ **Zero-config** β sensible defaults, optional config at `~/.pi/agent/pi-ui.json`
- π **Zero Dependencies** β Pure peer-dependency package; no additional npm packages required
- β‘ **TypeScript Native** β Loaded directly via [jiti](https://github.com/unjs/jiti) β no build step needed
## π¦ Installation
```bash
pi install npm:@mightguy/pi-ui
```
Or from GitHub:
```bash
pi install git:github.com/might-guy106/pi-ui
```
## π Usage
Once installed, pi-ui works **automatically** β no configuration required. On session start the editor zone, footer, spinner, welcome screen, and message renderer are all registered.
Pick an editor style in `~/.pi/agent/pi-ui.json`:
```json
{ "userZoneStyle": "gemini" }
```
### Editor styles
| Style | Look |
|---|---|
| `gemini` *(default)* | One-line divider, status row, half-block framed input, one-line footer |
| `droid` | Host rule `[user@host] ==`, metadata rows, bold divider |
| `cli-dock` | Outlined input box with placeholder + single aligned status line |
| `nvim` | Lined input with branch label in the rule + reverse-video statusline bar |
See [docs/editor-styles.md](./docs/editor-styles.md) for previews and [docs/configuration.md](./docs/configuration.md) for every option.
### Working Loader
Braille spinner (β£·β£―β£β‘Ώβ’Ώβ£»β£½β£Ύ) with a state label and elapsed time:
```
Answering... σ°
12.4s
```
## π¨ Themes
```
/theme catppuccin-dark
```
## ποΈ Project Structure
```
pi-ui/
βββ src/
β βββ index.ts # Extension entry
β βββ ui.ts # Session setup β header, editor, footer, loader, events
β βββ config.ts # ~/.pi/agent/pi-ui.json config
β βββ loader.ts # Working loader (spinner + state labels + tone)
β βββ footer.ts # Legacy standalone footer (fallback)
β βββ footer-patch.ts # Footer data capture for the editor zone
β βββ startup.ts # Gradient logo header + compact resource summary
β βββ editor/ # BoxEditor + style presets + cluster helper
β βββ tools/ # Tool badges, split diff, presentation styles
β βββ messages/ # Prefixes, boxed blocks, codeblock rail, streaming seam
β βββ startup.ts # Gradient pi logo header + clean startup
β βββ core/ # git status, response speed
β βββ theme/ # ANSI toolkit, theme extras, OSC 11 background sync
β βββ perf/ # Profiler (PI_UI_PROFILE=1)
βββ themes/
β βββ catppuccin-dark.json
βββ scripts/ # Smoke tests (npm test)
βββ docs/ # Docs β start at docs/index.md
βββ .github/
βββ workflows/
βββ release.yml
```
## π οΈ Development
See [docs/index.md](./docs/index.md) for the documentation map, [docs/development.md](./docs/development.md) for the dev and publishing workflow.
## Credits
This project is a fork of [DragonYH/pi-ui](https://github.com/DragonYH/pi-ui), originally published as [`@rokiy/pi-ui`](https://www.npmjs.com/package/@rokiy/pi-ui).
The welcome screen is ported from [pi-kaush/pi-welcome-screen](https://github.com/might-guy106/pi-kaush) by the same author.
The editor user zone, working loader, and theme tooling are ported from [sting8k/pi-droid-styling](https://github.com/sting8k/pi-droid-styling) β see [docs/porting-notes.md](./docs/porting-notes.md).
## π License
[MIT](./LICENSE)
---
Built for the pi coding agent ecosystem