---
slug: "kaishin-pi-bar"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/kaishin/pi-bar@main/README.md"
repo: "https://github.com/kaishin/pi-bar"
source_file: "README.md"
branch: "main"
---
# Pi Bar

An elegant, information-rich status and menu bar for [Pi](https://pi.dev).

Pi Bar replaces Pi's default footer with a responsive editorial-luxe bar while preserving the operational metrics that matter during long coding sessions.

## Preview

```text
◆ BAR  ● Pondering…  gpt-5.6-sol · low  main ✦    ↑ 324k ↓ 15k  ↯ 99%  ██░░░░░░ 27%/372k  ⌥A
```

Wide terminals use a dual-zone instrument rail: workspace identity stays left while operational telemetry is right-aligned.

### Midnight Amethyst palette

- **Purple `#B18CFF`:** Bar and output tokens
- **Blue `#6EA8FE`:** Ready, input tokens, healthy context
- **Ice blue `#7DD3FC`:** cache telemetry
- **Orange `#FF9F43`:** active working status, cost, Git dirty, context warning
- **Red `#FF5D73`:** errors and dangerous context only

No green or yellow is used by the normal footer palette. With `NO_COLOR` enabled, Pi Bar falls back to neutral Pi theme colors rather than green/yellow semantic colors.

## Features

- Preserves cumulative input/output, cache-hit, and context information
- Responsive one-line layout that never wraps
- Model and thinking-level controls
- Searchable tool controls
- Editorial, minimal, and classic display presets
- Session details, renaming, and safe compaction controls
- Theme-aware styling with no hard-coded ANSI colors
- Muted `✻ Cooked for 8s` completed-work entries, kept out of model context
- Suppresses Pi's duplicate inline working loader; Bar owns working state
- User and trusted-project configuration
- No telemetry or external network requests

## Requirements

- Pi `0.80.7` or newer
- Node.js `22.19.0` or newer
- Interactive TUI mode

## Install

```bash
pi install npm:pi-bar
```

Try a checkout without installing it permanently:

```bash
pi -e ./pi-bar
```

Pi packages execute with your full system permissions. Review third-party source before installation.

## Local development

```bash
git clone https://github.com/kaishin/pi-bar.git
cd pi-bar
npm install
npm run check
pi -e .
```

Display configuration and host-integration notes are documented in [`docs/design.md`](https://github.com/kaishin/pi-bar/blob/HEAD/docs/design.md).

## Footer anatomy

```text
◆ BAR  ● READY │ SESSION TOKENS │ CONTEXT │ MODEL · THINKING │ GIT │ ⌥A
```

- `↑` cumulative input tokens
- `↓` cumulative output tokens
- `↯` cache-hit percentage for the latest assistant response
- `✦` tracked working-tree changes

`READY` remains fixed when idle. During each work cycle, the working label is selected once from a playful built-in phrase set—such as `KNEADING`, `MOONWALKING`, or `PONDERING`—and remains stable until the cycle ends. In Gallery and Balanced layouts, the active bullet is orange and remains upright, while the stable working phrase and its animated dots are orange and italic; the ellipsis shrinks from `...` to `..` to `.` every 400 ms. Narrower layouts retain the compact static activity bullet.

When both brand and activity segments are hidden, the workspace keeps a two-column inset so the model does not sit against the terminal edge.

At 56 columns or wider, required metrics and context remain visible. Below 56 columns, Pi Bar prioritizes the compact metrics cluster and truncates safely rather than wrapping.

## Menu

Open Pi Bar with:

```text
/bar
```

The default shortcut is `alt+a`. The menu contains:

- **Model** — choose an authenticated model or thinking level
- **Tools** — search and toggle active Pi tools
- **Display** — switch presets and save user defaults
- **Session** — inspect, rename, or compact the current session

Additional commands:

```text
/bar disable
/bar enable
```

## Configuration

User configuration:

```text
~/.pi/agent/pi-bar.json
```

Trusted project configuration:

```text
<project>/.pi/pi-bar.json
```

Project settings override user settings only after Pi trusts the project. Menu changes apply to the current session; **Save as user default** writes user configuration atomically. Pi Bar never modifies project configuration from the menu.

Complete example:

```json
{
  "preset": "editorial",
  "shortcut": "alt+a",
  "segments": [
    "brand",
    "activity",
    "metrics",
    "context",
    "model",
    "git",
    "statuses",
    "menu"
  ],
  "ornament": "restrained",
  "contextWarning": 70,
  "contextDanger": 90,
  "currencyDecimals": 3,
  "showExtensionStatuses": true,
  "showSessionActions": true
}
```

Unknown or invalid values are ignored with one warning. The required `metrics` and `context` segments are restored if omitted.

## Presets

- **editorial** — full Bar identity and balanced workspace information
- **minimal** — compact activity, metrics, context, model, and menu
- **classic** — restrained metrics, context, model, git, and extension status layout

## Responsive behavior

- **Gallery (132+):** complete left-aligned workspace zone and right-aligned telemetry zone
- **Balanced (96–131):** compact brand, model, Git, telemetry, context, and shortcut groups
- **Focus (72–95):** activity, bounded model identity, core telemetry, context, and shortcut when space permits
- **Telemetry (56–71):** complete compact operational metrics and context without decorative workspace data
- **Safe (<56):** metrics-first ANSI-aware truncation with no wrapping

Color remains semantic at every width: input and healthy context are blue, output is purple, cache-hit is ice blue, active work and warnings are orange, and only dangerous context or errors use red.

## Privacy and security

Pi Bar:

- Performs no telemetry, analytics, or network calls
- Does not store prompts, responses, credentials, or session content
- Reads structured usage metadata already available inside Pi
- Executes local `git status --porcelain --untracked-files=no` after relevant events to show tracked dirty state
- Reads project configuration only when Pi reports the project as trusted

## Footer conflicts

Pi supports one custom footer at a time. If multiple extensions call `setFooter`, extension load order determines which footer is visible. Pi Bar does not wrap undocumented footer internals. Disable it with `/bar disable` to restore Pi's built-in footer.

## Troubleshooting

### The menu shortcut does not open

Some terminals or personal keymaps intercept `alt+a`. Use `/bar`, then choose another shortcut in `pi-bar.json` and run `/reload`.

### Metrics differ from the current context percentage

Token and cost metrics are cumulative across the entire session. Context percentage describes only the current model context after compaction.

### The footer is missing

Pi Bar intentionally does not install terminal UI in print, JSON, or RPC modes. In TUI mode, check whether another extension replaced the footer later in load order.

## Publishing

Release verification must include:

```bash
npm run check
npm pack --dry-run
npm pack
```

Inspect the tarball before running `npm publish`.

## License

MIT