pi-context-map

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

Features

• Visual Context Budget: Real-time breakdown of tokens used by System, Tools, History, Files, and Summaries.
• Accurate Token Count: Uses Pi's actual token count from ctx.getContextUsage(), not heuristic estimation — matches the terminal display.
• Working Set Analysis: Categorizes files as Active, Stale, or Legacy based on position in the conversation.
• 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).
• Compaction Detection: Tracks compaction summaries and branch summaries as a separate slice.
• Auto-Open Browser: Report automatically opens in your default browser on first invocation.
• Dark Mode: Toggle between light and dark themes. Preference persists across sessions via localStorage.
• Live Server: SSE-powered localhost server with auto-refresh after each assistant message.

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

Files are categorized by their position in the conversation (more reliable than turn-based calculation):

| Status | Position in Messages | Action | |--------|---------------------|--------| | Active | Last 30% of messages | Keep in context | | Stale | Middle 40% of messages | Monitor for removal | | Legacy | First 30% of messages | Prime candidate for compaction |

How It Works

1. Scanning: The analyzer iterates through session messages, detecting toolCall blocks, toolResult messages, compactionSummary entries, and image attachments.
2. Weighting: It calculates token counts for each message type using a code-aware heuristic (multipliers for code blocks, strings, etc.).
3. Accuracy: When available, Pi's actual token count from ctx.getContextUsage() overrides the heuristic for the usage percentage.
4. Categorization: Files are classified by their position in the message array (last 30% = active, middle 40% = stale, first 30% = legacy).
5. Visualization: Generates a self-contained HTML dashboard with stacked composition bar, file cards with search/filter, dark mode toggle, and interactive insights.

Live Localhost Server

When the extension loads, it automatically starts a local HTTP server on 127.0.0.1 (a random free port). The server:

• Serves the current report at http://127.0.0.1:<port>/.
• Pushes live updates via Server-Sent Events at /events?token=<sessionToken>.
• Authenticates the SSE connection with a per-session token (injected into the HTML as a <meta> tag).
• Auto-refreshes after each assistant message, so the browser view stays in sync.

Commands:

• /context-map — Generate a fresh report and broadcast it to the browser.
• /context-map stop — Stop the live server.

Endpoints:

• GET / or /report.html — The current report HTML.
• GET /events?token=... — Server-Sent Events stream of updates.
• GET /health — Returns { "status": "ok", "port": <number> }.
• POST /stop — Gracefully stops the server.

Design

The report uses the Linear design system (canvas #010102, accent #5e6ad2) with shadcn/ui card patterns. See docs/design.md for the full specification. The output is a single self-contained HTML file with no external dependencies.

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.

Audit Report

This package has been audited by the pi-audit-master extension for code quality, security, and reliability. The full audit report is available in AUDIT-REPORT-UPDATED.md.

Audit Summary

| Category | Issues Found | Issues Fixed | |----------|--------------|--------------| | 🔴 Critical | 2 | 2 ✅ | | 🟠 High | 4 | 4 ✅ | | 🟡 Medium | 4 | 4 ✅ | | 🟢 Low | 2 | 2 ✅ | | Total | 12 | 12 ✅ |

Key Improvements

• Security: Fixed dangerous signal listener removal, added XSS protection
• Reliability: Added error logging, fixed heartbeat cleanup
• Performance: Optimized file writes, no regression detected
• Maintainability: Removed dead code, extracted constants, improved documentation

Performance Metrics

| Metric | Result | |--------|--------| | Token Counter | 0.0005ms/call | | Context Analyzer | 0.08ms/analysis | | Report Generator | 0.10ms/report | | Live Server | 0.14ms/update |

For detailed findings and recommendations, see the full audit report.

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