Custom Terminal UI for pi Coding Agent Beautiful themes, smart status bar, and enhanced message rendering
---
## ๐ Features
pi-ui is a **pi-package** extension for the [pi coding agent](https://github.com/earendil-works/pi-coding-agent) that enhances your terminal with a custom status bar, rich theming, and improved editing experience.
- ๐ฅ๏ธ **Custom Status Bar** โ Real-time footer display showing model name, thinking level, current working directory, git branch, context usage (%), token usage (โinput โoutput), and API cost โ all in one glance
- ๐จ **Catppuccin Dark Theme** โ A meticulously crafted dark theme based on [Catppuccin Mocha](https://github.com/catppuccin/catppuccin) with 64+ color mappings covering syntax highlighting, markdown rendering, thinking levels, UI components, and export backgrounds
- โจ **Boxed Editor** โ Unicode border editor (`โญโโฎ` style) replacing the default editor with elegant rounded corners
- โณ **Adaptive Working Indicator** โ Animated spinner (๓ฐชโ๓ฐชฅ) at 120ms with **3-tone adaptive coloring** (greenโyellowโred based on token recency). Now also shows **real-time elapsed time** (`Working... ๓ฐ 12.3s`) refreshed every 100ms โ at-a-glance awareness of agent status and how long it's been thinking.
- ๐ **Per-Message Usage Stats** โ After each assistant reply, a **token/cost/duration summary** is displayed inline (`โ271 โ50 ยท $0.0017 ยท ๓ฐ 4.1s`) with a matching-width separator line. Stats are displayed only โ **automatically stripped from LLM context** to avoid polluting the conversation.
- ๐ฌ **Enhanced Message Rendering** โ Custom assistant message renderer with optional expanded JSON details display; usage stats injected via `message_end` event and filtered via `context` event
- ๐ **Zero Dependencies** โ Pure peer-dependency package; no additional npm packages required
- โก **TypeScript Native** โ Source code loaded directly via [jiti](https://github.com/unjs/jiti) โ no build step needed
- ๐งฉ **Modular Architecture** โ Code split into 4 focused modules: `index.ts` (entry), `ui.ts` (UI setup), `footer.ts` (status bar rendering), `editor.ts` (BoxedEditor component)
## ๐ฆ Installation
### Option 1: Install from npm (Recommended)
```bash
pi install npm:@rokiy/pi-ui
```
### Option 2: Install from GitHub
```bash
pi install git:github.com/DragonYH/pi-ui
```
### Option 3: Local Development
```bash
git clone https://github.com/DragonYH/pi-ui.git
cd pi-ui
pi install ./
```
### Verify Installation
Restart pi. You should see the custom footer appear at the bottom of your terminal, with the Catppuccin dark theme applied automatically.
## ๐ Usage
Once installed, pi-ui works **completely automatically** โ no configuration required:
1. **On session start** โ the custom UI initializes: footer, editor, spinner, message renderer
2. **On agent activity** (`agent_start` โ `message_update` โ `agent_end`) โ the working indicator adapts its color in real-time, and the footer stats refresh
3. **On thinking level change** (`thinking_level_select`) โ the thinking level indicator in the footer updates
4. **On session shutdown** (`session_shutdown`) โ all working timers are cleaned up gracefully
### Status Bar Layout
The two-line footer displays at the bottom of your terminal:
```
๓ฐฟ | ๓ฐฉ provider/model ๓ฐง thinking_level ๏ป cwd ๎ฅ branch ๓ฐจ context% ๓ฐก โinput โoutput ๓ฐ cost
๎ซฆ | ๓ฐฒ extension-status-1 ๓ฐฒข extension-status-2 ...
```
Each section uses Nerd Font icons and adaptive color theming. The footer gracefully **shrinks** to fit your terminal width โ non-critical sections are dropped first, ensuring the most important info (cwd, branch) always stays visible.
### Editor
The default message editor is replaced with a **BoxedEditor** that uses Unicode box-drawing characters:
```
โญโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
โ Your message content goes here... โ
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
```
### Working Indicator
The default "Working..." indicator is replaced with an animated **spinner sequence** (๓ฐช ๓ฐช ๓ฐช ๓ฐชก ๓ฐชข ๓ฐชฃ ๓ฐชค ๓ฐชฅ) cycling every 120ms. The spinner features **3-tone adaptive coloring**:
| Tone | Condition | Meaning |
|-------|----------------------------------|-----------------|
| ๐ข Green | Last token received < 10s ago | Active streaming |
| ๐ก Yellow | 10โ30s since last token | Thinking / idle |
| ๐ด Red | > 30s since last token | Possible stall |
The indicator starts on `agent_start`, resets on each incoming token (`message_update`), and stops on `agent_end`, giving you real-time awareness of agent activity.
## ๐จ Themes
| Theme | Description |
|-------|-------------|
| `catppuccin-dark` | Full Catppuccin Mocha dark theme โ 64+ color mappings for syntax highlighting, markdown, UI components, thinking levels, and export backgrounds |
### Color Palette
The Catppuccin Dark theme maps 24 distinct palette variables across every visual layer:
| Category | Colors |
|----------|--------|
| **UI** | `primary` `secondary` `accent` `surface` `overlay` `text` `subtext0` `subtext1` |
| **Semantic** | `green` `red` `yellow` `blue` `mauve` `teal` `sky` `pink` `peach` `maroon` `lavender` `flamingo` |
| **Thinking Levels** | Each level gets a distinct color: `off`โsubtext0, `minimal`โaccent, `low`โblue, `medium`โteal, `high`โmauve, `xhigh`โred |
| **Export** | Page/card/info export backgrounds for sharing conversations (light `#11111b`, `#1e1e2e`, `#313244`) |
### Using Themes
pi-ui themes are automatically registered when installed. You can switch themes in pi:
```
/theme catppuccin-dark
```
See the [pi themes documentation](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/themes.md) for more details.
## ๐๏ธ Project Structure
```
pi-ui/
โโโ src/
โ โโโ index.ts # Extension entry โ registers events
โ โโโ ui.ts # UI setup โ footer, BoxedEditor, working indicator, message renderer
โ โโโ footer.ts # Footer rendering โ model, usage, context, git branch
โ โโโ editor.ts # BoxedEditor component โ Unicode border decoration
โโโ themes/
โ โโโ catppuccin-dark.json # Catppuccin Mocha dark theme (64+ color mappings)
โโโ .github/
โ โโโ workflows/
โ โโโ release.yml # CI/CD โ auto-publishes to npm on version tag
โโโ LICENSE # MIT license
โโโ README.md # English documentation
โโโ README.zh-CN.md # Chinese documentation
โโโ package.json # Node.js and pi package manifest
```
## ๐ง How It Works
```
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ pi Coding Agent โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ โ โ
โ โ โญโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ โ โ
โ โ โ [Chat Interface with BoxedEditor] โ โ โ
โ โ โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ โ โ
โ โ โ โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค โ
โ โ ๓ฐฟ | ๓ฐฉ deepseek/deepseek-chat ๓ฐง medium ๏ป my-project โ โ
โ โ ๎ฅ main ๓ฐจ 45% ๓ฐก โ1.2k โ3.4k ๓ฐ 0.0012 โ โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ
โ โโโ Extension: pi-ui โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ session_start โโโบ setupCustomUI() โโโบ footer โ โ
โ โ editor โ โ
โ โ spinner โ โ
โ โ messageRenderer โ โ
โ โ agent_start โโโบ startWorkingTimer() โ โ
โ โ message_update โโโบ reset token timestamp โ โ
โ โ agent_end โโโบ stopWorkingTimer() โ โ
โ โ โโโบ rerenderFooter() โ โ
โ โ thinking_level_select โโโบ rerenderFooter() โ โ
โ โ session_shutdown โโโบ clearWorkingIndicatorTimer() โ โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
```
### Events Handled
| Event | Handler | Description |
|-------|---------|-------------|
| `session_start` | `setupCustomUI()` | Registers footer, BoxedEditor, working indicator, and message renderer |
| `session_shutdown` | `clearWorkingIndicatorTimer()` | Cleans up timers on session end |
| `agent_start` | `startWorkingTimer()` | Begins the adaptive working indicator (green) with elapsed time counter; re-renders footer |
| `message_update` | reset `lastTokenTime` | Updates token timestamp; the 100ms interval timer adjusts the spinner color and elapsed time accordingly |
| `message_end` | append usage stats | Injects per-message token/cost/duration stats into assistant message content for display |
| `agent_end` | `stopWorkingTimer()` | Stops the working indicator, clears the working message after 2s, and re-renders footer |
| `thinking_level_select` | `rerenderFooter()` | Updates the thinking level label in the footer |
| `context` | strip usage stats | Filters out the usage stats text blocks before messages are sent to the LLM, keeping context clean |
## ๐ ๏ธ For Developers
### Development
Since pi-ui uses **zero dependencies** and TypeScript is loaded via pi's built-in jiti transformer, there's nothing to build. Just clone and install:
```bash
git clone https://github.com/DragonYH/pi-ui.git
cd pi-ui
pi install ./
```
### Publish Checklist
This project publishes through GitHub Actions when a version tag is pushed.
Before publishing, verify the package contents:
```bash
npm pack --dry-run
```
Then create and push a tag that matches `package.json`:
```bash
git tag vX.Y.Z
git push origin vX.Y.Z
```
Before pushing the tag, configure npm Trusted Publishing for this package:
- Publisher: GitHub Actions
- Owner: `DragonYH`
- Repository: `pi-ui`
- Workflow: `release.yml`
- Environment: leave empty
### Adding a New Theme
Create a JSON theme file in `themes/` following the [pi theme schema](https://raw.githubusercontent.com/earendil-works/pi/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json). It will be automatically discovered by pi at startup.
### Compatibility
- Node.js >= 20
- pi runtime loads TypeScript directly via jiti โ no build step required
- Works with any model provider supported by pi
## ๐ License
[MIT](https://github.com/DragonYH/pi-ui/tree/HEAD/LICENSE)
---
