pi-context-map

A Pi extension that visualizes the current session context window and token distribution.

Packages

Package details

extension

Install pi-context-map from npm and Pi will load the resources declared by the package manifest.

npm report
$ pi install npm:pi-context-map
Package
pi-context-map
Version
0.1.4
Published
Jun 13, 2026
Downloads
not available
Author
realvendex
License
MIT
Types
extension
Size
45.7 KB
Dependencies
0 dependencies · 2 peers
Pi manifest JSON
{
  "extensions": [
    "dist/index.js"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

pi-context-map

A visual context window mapping extension for Pi that transforms your abstract token window into a concrete, actionable dashboard.

Pi Package License: MIT npm version

Features

  • Visual Context Budget: Real-time breakdown of tokens used by System, History, Files, and Tool Results.
  • Working Set Analysis: Categorizes files as Active, Stale, or Legacy based on access recency.
  • Token Weighting: Identifies "token hogs" by calculating the approximate size of each file in the window.
  • Operation Tracking: Marks files with their last operation (Read 👁️, Write 📝, Edit ✍️).
  • Temporal Mapping: Visually maps when files entered the context to identify compaction candidates.

Installation

pi install npm:pi-context-map

Quick Start

Run the mapping command to generate your session dashboard:

/context-map

The extension will analyze the session and create an interactive HTML report at: ~/.pi/context-map/report.html

Context Statuses

The extension categorizes files to help you manage context bloat:

Status Criteria Action
Active Accessed in last 3 turns Keep in context
Stale Accessed 4-10 turns ago Monitor for removal
Legacy Accessed > 10 turns ago Prime candidate for compaction

How It Works

  1. Scanning: The analyzer iterates through the session history, identifying all tool_use calls involving file operations.
  2. Weighting: It extracts the content length of tool results and applies a token heuristic (approx. 4 chars/token).
  3. Categorization: It calculates the temporal distance between the current turn and the last file access.
  4. Visualization: It generates a standalone HTML dashboard featuring a token budget bar and a file-weight grid.

Compatibility

  • ✅ Works with any Pi session regardless of model.
  • ✅ Compatible with pi-ultra-compact (use together for a "Scan $\to$ Compress" workflow).
  • ✅ Compatible with gentle-engram and gentle-pi.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'feat: add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

  • Pi - The AI coding agent