# pi-context-viz

Interactive context window visualizer for [pi](https://github.com/earendil-works/pi-mono) — a colored overlay showing token usage breakdown, session stats, and optimization suggestions.

![screenshot](https://img.shields.io/badge/pi-package-blue)

## Features

- **Colored grid** — visual breakdown of context window by category
- **Progress bar** — at-a-glance usage overview
- **3 view modes** — Grid (`default`), Table (`T`), Detail (`Enter`)
- **Interactive navigation** — arrow keys / `jk` to browse categories, `Enter` for details
- **Remaining turns estimate** — how many more turns before compaction needed
- **Cost projection** — current cost + projected cost for full context
- **Session history** — trend of context usage across `/context` invocations
- **Smart warnings** — context >80%, tools >25%, thinking >40%, compaction bloat
- **Compact mode** — auto-adapts for narrow terminals (<60 cols)
- **Save report** — `S` copies a text report to clipboard

## Categories tracked

| Category | Description |
|----------|-------------|
| System Prompt | Estimated system prompt tokens |
| User Messages | All user input tokens |
| Assistant Text | Model output (excluding thinking) |
| Thinking | Hidden reasoning tokens |
| Tool: read/bash/edit/… | Tool result tokens, per tool |
| Compaction | Compaction summary tokens |
| Custom Messages | Injected/custom message tokens |
| Images | Estimated image tokens |
| Free | Available context space |

## Install

```bash
pi install git:github.com/viartemev/pi-context-viz
```

Or try without installing:

```bash
pi -e git:github.com/viartemev/pi-context-viz
```

## Usage

Type `/context` in pi to open the overlay.

### Keybindings

| Key | Action |
|-----|--------|
| `↑` `↓` / `j` `k` | Navigate categories |
| `Enter` | Show category details |
| `T` | Toggle table/grid view |
| `S` | Save report to clipboard |
| `Esc` / `q` | Close overlay |

### Detail mode

Pressing `Enter` on a category shows:
- **Tools**: call count, avg tokens/call, max call size
- **User/Assistant**: message count, text vs thinking split
- **Images**: image count
- **Free**: estimated remaining turns

## How it works

1. Iterates the session branch to extract message types and tool calls
2. Estimates tokens using ~4 chars/token heuristic (consistent with pi's estimator)
3. Uses `ctx.getContextUsage()` for accurate total when available
4. Renders as an interactive TUI overlay via `ctx.ui.custom()`

## License

MIT