@xprnvd/pi-context-view 0.0.0-stage → 0.8.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dmitry Makarov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,115 @@
-# Temporary Holding Version
+# pi-context-view
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<p align="center">
+  <img width="456" src="https://media.githubusercontent.com/media/dimk90/pi-context-view/9a9f9f4fafaa09c77759485d53c42f8694650755/doc/images/pi-context-view.png">
+  <br>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square" alt="License: MIT"></a>
+  <a href="https://www.npmjs.com/package/pi-context-view"><img src="https://img.shields.io/npm/v/pi-context-view?style=flat-square&amp;logoColor=white" alt="npm version"></a>
+  <a href="https://pi.dev/packages/pi-context-view"><img src="https://img.shields.io/badge/Pi-Package-6366F1?style=flat-square" alt="Pi Package"></a>
+  <a href="https://www.npmjs.com/package/pi-context-view"><img src="https://img.shields.io/npm/dm/pi-context-view?label=Downloads&style=flat-square" alt="npm downloads"></a>
+  <a href="https://discord.com/channels/1456806362351669492/1531004733873979532"><img src="https://img.shields.io/static/v1?label=%20&message=Chat&color=5865F2&labelColor=555&style=flat-square&logo=discord&logoColor=white" alt="Discord"></a>
+</p>
+
+<br>
+
+[Pi](https://pi.dev) extension that visualizes context usage and lets you inspect the parts you
+normally can't see: the system prompt, tool definitions, and instructions
+injected by other extensions.
+
+## Features
+
+- **Context usage map** - visualize used and free context space, grouped by
+  category (tools, skills, messages, and more).
+
+- **Context injections** - explore the hidden parts of the context: the
+  system prompt, tool definitions, and extension injections, including
+  changes that extensions make only to the request sent to the model.
+
+## Commands
+
+- `/context` - shorthand for `/context usage`.
+- `/context usage` - open the context usage visualization.
+- `/context injections` - explore the latest request's injections: its system
+  prompt, tool definitions, and extension contributions.
+- `/context config` - create the global configuration file populated with
+  defaults, useful for
+  [customization](https://github.com/dimk90/pi-context-view#customization).
+
+## Demo: `/context`
+
+See what fills your context, for example, what survives compaction:
+
+![Context usage view showing estimated context composition](https://media.githubusercontent.com/media/dimk90/pi-context-view/e9f75e538ada31af0c1ba3517bad0a13f06050e6/doc/images/context-usage.gif)  
+➥ Pi theme in this demo: [`dark-legacy`](https://github.com/dimk90/pi-context-view/blob/master/doc/dark-legacy.json).
+
+
+## Demo: `/context injections`
+
+Inspect hidden parts of the context, such as tool definitions:
+
+![Context injections view and item preview](https://media.githubusercontent.com/media/dimk90/pi-context-view/0ee9a806e9c23bea642edabacfd6830755f3122d/doc/images/context-injections.gif)  
+➥ Pi theme in this demo: [`dark-legacy`](https://github.com/dimk90/pi-context-view/blob/master/doc/dark-legacy.json).
+
+## Demo: Zoom
+
+Zoom in for a more detailed breakdown of large context windows, such as
+1M-token windows:
+
+![Zoom feature](https://media.githubusercontent.com/media/dimk90/pi-context-view/e9f75e538ada31af0c1ba3517bad0a13f06050e6/doc/images/zoom.gif)  
+➥ Pi theme in this demo: [`dark-legacy`](https://github.com/dimk90/pi-context-view/blob/master/doc/dark-legacy.json).
+
+## Install
+
+```bash
+pi install npm:pi-context-view
+```
+
+## Customization
+
+Currently, you can customize only the colors and dimensions of the `Context Usage` map.
+
+To get started, create a configuration file populated with the current defaults:
+
+```text
+/context config
+```
+➥ This creates `~/.pi/agent/extensions/pi-context-view.json`.
+
+See the [configuration reference](https://github.com/dimk90/pi-context-view/blob/master/doc/CONFIG.md)
+for each parameter's meaning and default value.
+
+### Category Colors
+
+You can use theme color names to match your current theme or hex values for
+colors that stay the same across themes. Here are examples of custom
+[terrain](https://github.com/dimk90/pi-context-view/blob/master/doc/palettes/terrain.json) and
+[rainbow](https://github.com/dimk90/pi-context-view/blob/master/doc/palettes/rainbow.json) palettes:
+
+![Terrain and rainbow palettes](https://media.githubusercontent.com/media/dimk90/pi-context-view/e9f75e538ada31af0c1ba3517bad0a13f06050e6/doc/images/palettes.png)  
+➥ Pi theme in this demo: [`dark-legacy`](https://github.com/dimk90/pi-context-view/blob/master/doc/dark-legacy.json).
+
+See the [theme color reference](https://github.com/dimk90/pi-context-view/blob/develop/doc/PI-THEME-COLORS.md)
+for color names that follow the current theme.
+
+### Map Size
+
+You can configure the number of rows and columns in the `Context Usage` map:
+
+![Map size demo](https://media.githubusercontent.com/media/dimk90/pi-context-view/2bc280f758d88fc0ac6396e921c7e697c9016086/doc/images/map-sizes.png)  
+➥ Pi theme in this demo: [`dark-legacy`](https://github.com/dimk90/pi-context-view/blob/master/doc/dark-legacy.json).
+
+
+## Context Footprint
+
+`pi-context-view` adds nothing to the model context. Opening a view before the
+first turn may run one [silent probe](doc/architecture/probe.md)
+that sends no request and leaves only blank entries, omitted from future context.
+Set `"autoProbing": false` in the [config](https://github.com/dimk90/pi-context-view/blob/master/doc/CONFIG.md#silent-probe) to disable it.
+
+## My Other Stuff
+
+📌 [S-VHS](https://github.com/dimk90/s-vhs) - terminal recorder used to create the demo GIFs.
+
+## License
+
+[MIT](https://github.com/dimk90/pi-context-view/blob/master/LICENSE)

package/package.json

@@ -1,6 +1,56 @@
 {
-  "name": "@xprnvd/pi-context-view",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@xprnvd/pi-context-view",
+	"version": "0.8.0",
+	"description": "Pi extension to visualize context usage and inspect the hidden parts: base prompt, tools defs, and extension injections",
+	"type": "module",
+	"license": "MIT",
+	"author": "Dmitry Makarov",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/xprnvd/pi-context-view.git"
+	},
+	"homepage": "https://github.com/xprnvd/pi-context-view",
+	"bugs": {
+		"url": "https://github.com/xprnvd/pi-context-view/issues"
+	},
+	"keywords": [
+		"pi",
+		"pi-extension",
+		"pi-package",
+		"coding-agent",
+		"context",
+		"tokens",
+		"tui"
+	],
+	"engines": {
+		"node": ">=22.19.0"
+	},
+	"files": [
+		"src",
+		"README.md"
+	],
+	"scripts": {
+		"test": "node test/run.ts",
+		"check": "tsc --noEmit && pnpm test"
+	},
+	"pi": {
+		"extensions": [
+			"./src/index.ts"
+		],
+		"image": "https://media.githubusercontent.com/media/dimk90/pi-context-view/9a9f9f4fafaa09c77759485d53c42f8694650755/doc/images/pi-context-view.png"
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-agent-core": "*",
+		"@earendil-works/pi-ai": "*",
+		"@earendil-works/pi-coding-agent": "*",
+		"@earendil-works/pi-tui": "*"
+	},
+	"devDependencies": {
+		"@earendil-works/pi-agent-core": "1.3.0",
+		"@earendil-works/pi-ai": "1.3.0",
+		"@earendil-works/pi-coding-agent": "1.3.0",
+		"@earendil-works/pi-tui": "1.3.0",
+		"@types/node": "^22.20.1",
+		"typescript": "^7.0.2"
+	}
+}