Info Screen

See what your session costs, what fills its context and what compaction saved you.

@pi-unipi/info-screen · part of UniPi

What it does

• Startup splash. Unicrab says hello when Pi starts. The splash shows how fast Pi got ready, the session you came back to, today's spend and any update. It does not take your keys. It closes after bootTimeoutMs.
• Dashboard. /unipi:info opens a set of pages. The first page is about this session.
• Scope tags. A small letter before a number gives its scope: g is all projects on this machine, p is this project and s is this session.
• Fast open. The dashboard opens at once on cached numbers. Then it updates the page that you look at.

Quick start

UniPi installs this package:

pi install npm:@pi-unipi/unipi

To install this package alone:

pi install npm:@pi-unipi/info-screen

Run /unipi:info to open the dashboard.

Commands

Dashboard keys

In auto-close mode the splash does not take keyboard input. You can type your first prompt while it shows. If another overlay opens on top of it, the splash waits for that overlay to close.

Pages

The context bucket

The bucket shows what Pi sends with the next request. Each part has its own colour:

The page counts characters and divides by 4 to get tokens. Then it scales the parts to the token count from Pi. Before the first reply, Pi has no count. The page then shows its own estimate and marks it with ~.

The bottom edge of the bucket shows how full the window is. It is green up to 70%, amber up to 90% and red after that.

How the Compactor page counts savings

1. Each compaction makes the context smaller. The page takes the tokens before and after.
2. Each reply after a compaction sends the smaller context. The page multiplies the removed tokens by the number of these replies.
3. The page prices those tokens at the rate that you paid for context in the same replies. This rate includes cache discounts.

A free model saves tokens but no money. The p and g numbers come from the session files in ~/.pi/agent/sessions/. The page counts a compaction one time, also when a forked session file copies it.

Settings

Open /unipi:settings → Info Screen. The file is ~/.unipi/config/info-screen/config.json.

The splash opens only when Pi starts. It does not open when you resume or start a session. The start-screen header from the hints module is a separate feature.

Add a page from a package

A package can add its own page. Use the registry on globalThis.__unipi_info_registry, or import infoRegistry from @pi-unipi/info-screen.

globalThis.__unipi_info_registry?.registerGroup({
  id: "my-module",
  name: "My Module",
  icon: "",
  priority: 60,          // lower numbers come first
  config: {
    showByDefault: true,
    stats: [
      { id: "status", label: "Status", show: true },
      { id: "count", label: "Count", show: true },
    ],
  },
  dataProvider: async () => ({
    status: { value: "running" },
    count: { value: "42", detail: "items processed" },
  }),
});

A page with no renderer shows its stats as a list. A package that imports @pi-unipi/info-screen can give a render(pc) function. It can draw with the page kit (tiles, section, meterRow, rankBars, legend, tag) and the core viz kit (bigText, spark, columns, brailleArea, gauge, shareBar, grid).

Keep the data JSON-safe. The registry writes it to disk, so the next session opens with numbers at once.

To see each page and the splash without Pi:

npx tsx scripts/info-preview/index.ts all 60,100
INFO_PREVIEW_EXTRA=scripts/info-preview/demo.ts npx tsx scripts/info-preview/index.ts session 112

How it works

Each UniPi module emits MODULE_READY on the event bus when it loads. The Info Screen collects these events for 150 ms. Then it marks the Tools and Modules pages as out of date.

The registry keeps data in three places, from fast to slow:

1. Memory. Page data stays in memory for 5 seconds. The dashboard keeps each drawn page until the data or the size changes.
2. Snapshot on disk. ~/.unipi/cache/info-screen.json holds the pages for all projects. ~/.unipi/cache/info-screen/<workspace>.json holds the Memory, MCP and Compactor pages for one project. The registry does not write the session page.
3. The provider. The page runs its data provider.

The usage parser keeps a cache for each session file. It reads a file again only when the file changes. It writes the cache to disk at most one time in 30 seconds, and at shutdown.

The session page reads the transcript one time for each new entry. The splash reads only memory and the snapshot.

The Footer reads the cached Memory page from this registry.

See also

• Footer
• Compactor
• Event bus
• Settings reference