npm package: @juanibiapina/pi-powerbar
Description: Pi extension that renders a persistent powerline status bar with left/right segments updated via events
Author: Juan Ibiapina
Latest version: 0.8.0

# pi-powerbar

A [pi](https://github.com/badlogic/pi) extension that renders a persistent powerline-style status bar with left-aligned and right-aligned segments.

Any other pi extension can update segments by emitting a single `powerbar:update` event — no imports or dependencies required.

## Install

```bash
pi install npm:@juanibiapina/pi-powerbar
```

> **⚠️ Load Order:** `pi-powerbar` must appear **after** `pi-extension-settings` and **before** any segment-emitting extensions in your `packages` array in `~/.pi/settings.json`. It registers settings at load time (requiring `pi-extension-settings` to already be loaded), and segment emitters send events that `pi-powerbar` must be ready to receive.

## Usage

The powerbar renders a widget with two sides, like tmux:

![powerbar screenshot](screenshot.png)

### Producing segments

Any extension can register and update a segment. First, register the segment so it appears in the settings menu:

```typescript
pi.events.emit("powerbar:register-segment", {
  id: "git-branch",
  label: "Git Branch",
});
```

Then update it with data:

```typescript
pi.events.emit("powerbar:update", {
  id: "git-branch",
  text: "main",
  icon: "⎇",
  color: "accent",
});
```

Segments can include a progress bar with an optional block count hint:

```typescript
pi.events.emit("powerbar:update", {
  id: "context-usage",
  text: "",
  suffix: "30%",
  bar: 30,              // progress value 0–100
  barSegments: 10,      // optional: number of discrete blocks in blocks mode
  color: "muted",
});
```

To remove a segment:

```typescript
pi.events.emit("powerbar:update", {
  id: "git-branch",
  text: undefined,
});
```

### Built-in segments

| Segment ID | Description |
|------------|-------------|
| `git-branch` | Current git branch (refreshes after bash commands) |
| `tokens` | Cumulative input/output tokens and session cost (e.g. `↑9 ↓270 $0.11`) |
| `context-usage` | Context window usage as a progress bar with percentage |
| `provider` | Current LLM provider name (e.g. `anthropic`, `openai`) |
| `model` | Current model name and thinking level |
| `sub-hourly` | Hourly subscription usage from [pi-sub-core](https://github.com/marckrenn/pi-sub-core) |
| `sub-weekly` | Weekly subscription usage from pi-sub-core |

### Configuration

Settings are managed through [`pi-extension-settings`](https://github.com/juanibiapina/pi-extension-settings) and can be changed via the `/extension-settings` command in pi.

| Setting | Description | Default |
|---------|-------------|---------|
| **Left segments** | Segments shown on the left side (ordered multi-select menu) | `git-branch,tokens,context-usage` |
| **Right segments** | Segments shown on the right side (ordered multi-select menu) | `provider,model,sub-hourly,sub-weekly` |
| **Separator** | String drawn between segments on the same side | ` │ ` |
| **Placement** | Where the powerbar appears (`belowEditor` or `aboveEditor`) | `belowEditor` |
| **Bar style** | Visual style of progress bars (`continuous` or `blocks`) | `blocks` |
| **Bar width** | Width of progress bars in characters (4–24) | `10` |

The left and right segment settings open an interactive menu where you can toggle segments on/off and reorder them with Shift+↑/↓. All segments registered via `powerbar:register-segment` appear as options. Segments not listed in either side are ignored.

## Development

```bash
npm install
npm run check    # lint + typecheck
npm run build    # compile to dist/
npm run dev      # watch mode
```

## License

MIT