context-bar

A thin, stacked context-window composition bar for pi, rendered directly above the editor.

▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀────────────────────────42%

The real bar uses a harmonious theme-aware color progression and spans the terminal width. Used context renders as upper-half ▀ blocks, while free capacity renders as a thin ─ line matching the editor's current border color. Whenever width permits, every visible section is separated by a one-cell terminal-background delimiter; wider sections contribute the space so one-cell sections remain intact. This leaves balanced spacing around the input cursor. While enabled, context-bar removes Pi's separate top-border row; disabling the bar restores it. Its only inline text is the integer percentage at the far right showing total context used.

Install

Context Bar requires Pi 0.84.1 or later. Do not add it to a Pithos environment still pinned to Pi 0.83.0; Atlas will report that combination as incompatible.

pi install npm:@pithos-kit/context-bar

For local development:

pi install -l ./pithos.context-bar

Pithos .pithos config

pi:
  extensions:
    "@pithos-kit/context-bar": "npm:0.1.1"

Commands

| Command | Action | |---|---| | /context-bar | Toggle the bar | | /context-bar on | Enable it | | /context-bar off | Disable it | | /context-bar status | Show the legend, estimated counts, model/window, and estimation basis | | /context-bar --help | Show command usage without changing bar state |

-h is also accepted.

New sessions start enabled. Explicit changes are stored as non-context entries on the active session branch, so they survive reload, resume, and fork without creating project or global configuration.

Segments

Segments always appear in this order:

| Segment | Includes | Color identity | |---|---|---| | Prompt | Pi's base prompt, custom/append prompts, working directory, and extension prompt changes | Violet | | Project context | Loaded AGENTS.md, CLAUDE.md, and related project instruction context | Blue | | Skills | Skill catalogue metadata, explicit /skill:* expansions, and recognized skill-file read results | Teal | | Tools | Active definitions/schemas, prompt guidance, calls, arguments, results, and context-visible shell output | Green | | Conversation | User content, prompt templates, images, assistant text/thinking, summaries, and custom context messages | Amber | | Other | Provider framing, serialization differences, extension rewrites, and estimation residual | Gray | | Free | Remaining context capacity | Thin line matching the current editor border (borderMuted fallback) |

The original violet → blue → teal → green → amber progression remains stable across themes. Context Bar selects darker or brighter variants from the active theme's foreground contrast instead of relying on semantic theme tokens whose hues may vary. Free capacity still follows the editor border as its mode/thinking color changes. The percentage uses the same dim theme color as Pi's footer path; it does not change color at thresholds.

Accuracy

Pi exposes aggregate context usage, but not exact additive token counts by source. The colored composition is therefore an estimate:

• Text uses Pi-compatible conservative character-based token estimation.
• Images use Pi's fixed image estimate.
• A current provider aggregate is preferred only when it belongs to the selected model and matches the effective prompt/tool fingerprint; changed requests fall back to the safer local estimate.
• Positive unexplained residual is assigned to Other; overestimates are proportionally reconciled.
• Startup, model-switch, and post-compaction states use a complete local estimate until correlated provider usage is available.

/context-bar status identifies the current basis as provider-backed total or local estimate. The extension persists only the enabled/disabled boolean. While enabled, it reads Pi's in-memory prompt, context, and schema objects to recompute the bar; it clears its references when disabled or shut down and never writes or logs those inputs or provider payloads.

Tiny categories may occupy less than one terminal cell and disappear from the passive bar rather than being visually exaggerated. They remain visible in /context-bar status.

Development

Requires Node.js 22.19 or later and Pi 0.84.1 or later. This minimum includes upstream fixes for the dependency advisories affecting Pi 0.83.0.

npm install
npm test
npm run audit
npm run typecheck
npm pack --dry-run