ExtensionSession@piex-dev/context

context — See How Much Token a Session Eats

TL;DR

/context shows the current session content distribution at a glance: who holds context, which entries bloat fastest, where your token budget goes.

Overview

As a coding agent runs long, the context window is the biggest hidden cost. You feel "slower", "shallower", but can't pinpoint the cause — bloated tool results? a read that pulled redundant content? or just long history? Pi's built-in /session only lists sessions, lacking per-session content distribution. @piex-dev/context fills the gap: a one-shot structured entry analysis, role share, and token estimate.

How it works

Token estimate: no precise counting (that needs the model tokenizer, too costly) — uses the industry "chars / 3.5" heuristic. Conservative for mixed CJK/Latin but a useful relative comparison. Dimensions: classify by role (user/assistant/system) + type (message/tool_call/tool_result/custom) and count chars; three roles are the main axis — Assistant (model answers, usually the bulk), User (your instructions), Tool Results (most prone to accidental bloat, e.g. read big files, verbose grep).

flow

session entries → by role → by type
→ count chars per role → ASCII bar chart + structured table

Usage

Install

bash

pi install npm:@piex-dev/context

Source: extensions/context

Usage

bash

/context

Outputs an Overview table + Distribution ASCII bar chart + token estimate.

Configuration

No config, works out of the box. Token estimate fixed at chars / 3.5.

Verify

bash

pi -e ./extensions/context/src/context.ts -p "what is 1+1" --no-session

Implementation

~160 lines, single file. Core functions: analyzeEntries() (walk entries, count by role/type), countChars() (handles both string and content-block array), buildReport() (Markdown table + ASCII bar chart), estimateTokens() (chars/3.5), buildBar() (█/░ bars).

report

## Context Usage Report

### Overview
| Metric            | Value |
| Total entries     | 42    |
| Estimated tokens  | ~3.2k |

### Distribution
████████████░░░░░░░░ Assistant     62%
██████░░░░░░░░░░░░░░ User          28%
██░░░░░░░░░░░░░░░░░░ Tool Results  10%

pi /session	context (piex)
lists sessions	shows current session content distribution
no distribution chart	ASCII bar chart
no token estimate	chars → tokens estimate
no entry classification	detailed by role/type

Design notes

Project	Mechanism	piex choice
pi built-in /session	lists sessions, no per-session distribution	Coexist: context adds distribution analysis, token estimate, role/type classification, doesn't replace /session
industry token estimate	chars / 3.5 heuristic	Adopted: relative comparison is enough at zero cost, conservative but good for "who's bloating"

Core trade-off: relative comparison over precise counting (zero cost, enough for locating problems); static snapshot over time-series (solve "who's big now" first).

Changelog

Roadmap

Direction	Plan
Precise token counting	chars/3.5 deviates for mixed CJK; switch to precise once Pi exposes a tokenizer interface
Time-series analysis	currently static snapshot; add "token growth per turn" to find the fastest-bloating turn
Anomaly detection	auto-flag tool results above a threshold (e.g. 50K chars), prompt to check for redundant pulls
Configurable metric	per-project custom coefficient, or external tokenizer

Version history

Version	Date	Changes
0.1.0	2026-07-19	Initial release: `/context` outputs session content distribution report; `analyzeEntries` by role (user/assistant/system) + type (message/tool_call/tool_result/custom); `estimateTokens` (chars/3.5); ASCII bar chart; coexists with pi `/session` (adds distribution + token estimate + classification)

Source Markdown: docs/packages/context.md