kaishin-pi-bar

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# 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

Pi Bar

An elegant, information-rich status and menu bar for Pi.

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

◆ 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

pi install npm:pi-bar

Try a checkout without installing it permanently:

pi -e ./pi-bar

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

Local development

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.

Footer anatomy

◆ 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.

Configuration

User configuration:

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

Trusted project configuration:

<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:

{
  "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:

npm run check
npm pack --dry-run
npm pack

Inspect the tarball before running npm publish.

License

MIT