@saifymatteo/pi-extensions 0.1.1 → 0.1.3

package/README.md

@@ -2,8 +2,12 @@
 
 Reusable pieces of a personal Pi setup, packaged separately from the setup itself.
 
+![Demo: every extension in this collection loaded into one Pi session](demo.gif)
+
 **Work in progress.** Packages are licensed AGPL-3.0-only ([NOTICE.md](NOTICE.md)) and publish through GitHub Actions when tagged: each extension individually, plus the root as the all-in-one collection [`@saifymatteo/pi-extensions`](https://github.com/saifymatteo/pi-extensions). Git is local for now, with no GitHub repository yet.
 
+Each package README opens with a screenshot of what it adds. The screenshots are real captures, not mockups: stock Pi 1.4.0 driven by a scripted demo model, in an isolated agent home. The catalogue below shows them as thumbnails; click one for the package README.
+
 ## Start here
 
 Use Node.js 24 or newer. From this repository:
@@ -27,6 +31,8 @@ Host-provided Pi packages (`@earendil-works/*`) are declared only as package pee
 - `pack:check`: asks npm to show each standalone package's and the root collection's prospective contents without publishing or creating archives.
 - `smoke`: loads each package through isolated host help/startup. Checks module/factory loading, not session events, interactive rendering, models, external CLIs, or backend compatibility. The host is located automatically (`PI_HOST`, `pi` on PATH, then `pi-bolt` for a Pi-Bolt build, then the local `~/.pi-bolt` install). Pi-Bolt is optional; set `PI_HOST` to another executable to compare hosts. A pass here does not prove compatibility with a different host build.
 - `context`: measures what each package adds to the first-turn context window. Current result: the whole collection costs about **1.7k tokens** on top of stock Pi, and 17 of 22 packages contribute nothing (they register hooks, commands, or UI patches only). Measured by capturing the actual request Pi sends to a local provider, against the pinned stock host, with machine state excluded. First-turn static cost only: runtime injections (tool results, hook-driven messages) are not measured. Not part of the `check` gate.
+- `screenshots`: regenerates each `packages/<name>/screenshot.png` (`npm run screenshots -- pi-bg-bash` for one). Drives the pinned stock host in a pseudo-terminal against a scripted local model and fake service endpoints, in a throwaway `/tmp/demo` home, with a stubbed clipboard. macOS only for now (font path, clipboard stub). Needs `agent-browser` on PATH. One-time setup: `npm ci --prefix scripts/screenshots`, then make node-pty's helper executable (`chmod +x scripts/screenshots/node_modules/node-pty/prebuilds/*/spawn-helper`) if npm skipped its install script. Not part of the `check` gate.
+- `demo`: re-records the root `demo.gif` (also the gallery preview via `pi.image`): one session with the whole root collection loaded, same harness and setup as `screenshots`. `DRY=1` prints each scene's screen without rendering. Not part of the `check` gate.
 
 ## Isolated sessions
 
@@ -50,46 +56,46 @@ Each directory under `packages/` is an independently loadable, independently pub
 
 ### Session and model navigation
 
-| Package | Purpose |
-| --- | --- |
-| [pi-session-id](packages/pi-session-id) | Copy the current session ID |
-| [pi-session-finder](packages/pi-session-finder) | Search saved sessions across projects; open or fork them |
-| [pi-session-nav](packages/pi-session-nav) | Jump between messages in the active context (compaction-aware) |
-| [pi-session-rename](packages/pi-session-rename) | Generate session titles from the first prompt using configured models |
-| [pi-session-retention](packages/pi-session-retention) | Inspect and manage stored sessions; review deletion behavior before use |
-| [pi-model-go](packages/pi-model-go) | `/model-go`: cost-aware model picker with Go-plan pricing and intelligence scores |
+| Package | Purpose | Preview |
+| --- | --- | --- |
+| [pi-session-id](packages/pi-session-id) | Copy the current session ID | <a href="packages/pi-session-id"><img src="packages/pi-session-id/screenshot.png" width="280" alt="pi-session-id screenshot"></a> |
+| [pi-session-finder](packages/pi-session-finder) | Search saved sessions across projects; open or fork them | <a href="packages/pi-session-finder"><img src="packages/pi-session-finder/screenshot.png" width="280" alt="pi-session-finder screenshot"></a> |
+| [pi-session-nav](packages/pi-session-nav) | Jump between messages in the active context (compaction-aware) | <a href="packages/pi-session-nav"><img src="packages/pi-session-nav/screenshot.png" width="280" alt="pi-session-nav screenshot"></a> |
+| [pi-session-rename](packages/pi-session-rename) | Generate session titles from the first prompt using configured models | <a href="packages/pi-session-rename"><img src="packages/pi-session-rename/screenshot.png" width="280" alt="pi-session-rename screenshot"></a> |
+| [pi-session-retention](packages/pi-session-retention) | Inspect and manage stored sessions; review deletion behavior before use | <a href="packages/pi-session-retention"><img src="packages/pi-session-retention/screenshot.png" width="280" alt="pi-session-retention screenshot"></a> |
+| [pi-model-go](packages/pi-model-go) | `/model-go`: cost-aware model picker with Go-plan pricing and intelligence scores | <a href="packages/pi-model-go"><img src="packages/pi-model-go/screenshot.png" width="280" alt="pi-model-go screenshot"></a> |
 
 ### Transcript and terminal UI
 
-| Package | Purpose |
-| --- | --- |
-| [pi-compact-tools](packages/pi-compact-tools) | Group consecutive tool calls into one collapsible card |
-| [pi-clipboard-image](packages/pi-clipboard-image) | Attach clipboard images or copied image files (Alt+V) |
-| [pi-codeblock-borders](packages/pi-codeblock-borders) | Render code fences as rules with titles, line numbers, and highlights |
-| [pi-user-image-previews](packages/pi-user-image-previews) | Collapsible inline previews for newly submitted attachments |
-| [pi-claude-usage](packages/pi-claude-usage) | Show Claude 5h/7d subscription usage in the footer |
-| [pi-prestart-working](packages/pi-prestart-working) | Labelled "Working" spinner while `before_agent_start` hooks run |
+| Package | Purpose | Preview |
+| --- | --- | --- |
+| [pi-compact-tools](packages/pi-compact-tools) | Group consecutive tool calls into one collapsible card | <a href="packages/pi-compact-tools"><img src="packages/pi-compact-tools/screenshot.png" width="280" alt="pi-compact-tools screenshot"></a> |
+| [pi-clipboard-image](packages/pi-clipboard-image) | Attach clipboard images or copied image files (Alt+V) | <a href="packages/pi-clipboard-image"><img src="packages/pi-clipboard-image/screenshot.png" width="280" alt="pi-clipboard-image screenshot"></a> |
+| [pi-codeblock-borders](packages/pi-codeblock-borders) | Render code fences as rules with titles, line numbers, and highlights | <a href="packages/pi-codeblock-borders"><img src="packages/pi-codeblock-borders/screenshot.png" width="280" alt="pi-codeblock-borders screenshot"></a> |
+| [pi-user-image-previews](packages/pi-user-image-previews) | Collapsible inline previews for newly submitted attachments | <a href="packages/pi-user-image-previews"><img src="packages/pi-user-image-previews/screenshot.png" width="280" alt="pi-user-image-previews screenshot"></a> |
+| [pi-claude-usage](packages/pi-claude-usage) | Show Claude 5h/7d subscription usage in the footer | <a href="packages/pi-claude-usage"><img src="packages/pi-claude-usage/screenshot.png" width="280" alt="pi-claude-usage screenshot"></a> |
+| [pi-prestart-working](packages/pi-prestart-working) | Labelled "Working" spinner while `before_agent_start` hooks run | <a href="packages/pi-prestart-working"><img src="packages/pi-prestart-working/screenshot.png" width="280" alt="pi-prestart-working screenshot"></a> |
 
 ### Tools and service adapters
 
-| Package | Purpose |
-| --- | --- |
-| [pi-bg-bash](packages/pi-bg-bash) | Add background execution to the built-in bash/powershell tools |
-| [pi-wait](packages/pi-wait) | Join background jobs (shell:/agent:) with lease-based delivery |
-| [pi-codegraph](packages/pi-codegraph) | CodeGraph CLI adapter: explore tool plus index auto-init/sync |
-| [pi-zvec](packages/pi-zvec) | Workspace search via the zg CLI: exact, lexical, semantic, hybrid |
-| [pi-decisions](packages/pi-decisions) | Agent-facing classify tool backed by configured Decisions endpoints |
-| [pi-tts](packages/pi-tts) | Generate WAV files through an OpenAI-compatible speech endpoint |
-| [pi-vision](packages/pi-vision) | Describe images for text-only models via a configured vision chain |
+| Package | Purpose | Preview |
+| --- | --- | --- |
+| [pi-bg-bash](packages/pi-bg-bash) | Add background execution to the built-in bash/powershell tools | <a href="packages/pi-bg-bash"><img src="packages/pi-bg-bash/screenshot.png" width="280" alt="pi-bg-bash screenshot"></a> |
+| [pi-wait](packages/pi-wait) | Join background jobs (shell:/agent:) with lease-based delivery | <a href="packages/pi-wait"><img src="packages/pi-wait/screenshot.png" width="280" alt="pi-wait screenshot"></a> |
+| [pi-codegraph](packages/pi-codegraph) | CodeGraph CLI adapter: explore tool plus index auto-init/sync | <a href="packages/pi-codegraph"><img src="packages/pi-codegraph/screenshot.png" width="280" alt="pi-codegraph screenshot"></a> |
+| [pi-zvec](packages/pi-zvec) | Workspace search via the zg CLI: exact, lexical, semantic, hybrid | <a href="packages/pi-zvec"><img src="packages/pi-zvec/screenshot.png" width="280" alt="pi-zvec screenshot"></a> |
+| [pi-decisions](packages/pi-decisions) | Agent-facing classify tool backed by configured Decisions endpoints | <a href="packages/pi-decisions"><img src="packages/pi-decisions/screenshot.png" width="280" alt="pi-decisions screenshot"></a> |
+| [pi-tts](packages/pi-tts) | Generate WAV files through an OpenAI-compatible speech endpoint | <a href="packages/pi-tts"><img src="packages/pi-tts/screenshot.png" width="280" alt="pi-tts screenshot"></a> |
+| [pi-vision](packages/pi-vision) | Describe images for text-only models via a configured vision chain | <a href="packages/pi-vision"><img src="packages/pi-vision/screenshot.png" width="280" alt="pi-vision screenshot"></a> |
 
 ### Environment and local observability
 
-| Package | Purpose |
-| --- | --- |
-| [pi-load-pi-dotenv](packages/pi-load-pi-dotenv) | Load the agent-local .env into the environment for tool subprocesses |
-| [pi-root-guard](packages/pi-root-guard) | Block agent writes into the Pi and Claude config roots |
-| [pi-skill-usage-log](packages/pi-skill-usage-log) | Log which skills were actually used; `/skill-usage` summary |
-| [pi-tool-usage-log](packages/pi-tool-usage-log) | Passive log of tool executions (names and status, never contents) |
+| Package | Purpose | Preview |
+| --- | --- | --- |
+| [pi-load-pi-dotenv](packages/pi-load-pi-dotenv) | Load the agent-local .env into the environment for tool subprocesses | <a href="packages/pi-load-pi-dotenv"><img src="packages/pi-load-pi-dotenv/screenshot.png" width="280" alt="pi-load-pi-dotenv screenshot"></a> |
+| [pi-root-guard](packages/pi-root-guard) | Block agent writes into the Pi and Claude config roots | <a href="packages/pi-root-guard"><img src="packages/pi-root-guard/screenshot.png" width="280" alt="pi-root-guard screenshot"></a> |
+| [pi-skill-usage-log](packages/pi-skill-usage-log) | Log which skills were actually used; `/skill-usage` summary | <a href="packages/pi-skill-usage-log"><img src="packages/pi-skill-usage-log/screenshot.png" width="280" alt="pi-skill-usage-log screenshot"></a> |
+| [pi-tool-usage-log](packages/pi-tool-usage-log) | Passive log of tool executions (names and status, never contents) | <a href="packages/pi-tool-usage-log"><img src="packages/pi-tool-usage-log/screenshot.png" width="280" alt="pi-tool-usage-log screenshot"></a> |
 
 ## Individual and collection loading
 
@@ -133,7 +139,7 @@ packages/<extension>/
   src/index.ts       # existing extension implementation
   src/lib/           # only helpers needed by this package, where applicable
   examples/          # sanitized, inert examples where applicable
-scripts/             # boundary checks, isolated sessions, host smoke
+scripts/             # boundary checks, isolated sessions, host smoke, screenshots
 test/                # test-only TS loader and collection behavior checks
 inventory.json       # inclusion/exclusion map
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saifymatteo/pi-extensions",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "type": "module",
   "license": "AGPL-3.0-only",
   "description": "Independently installable Pi extensions",
@@ -14,7 +14,9 @@
     "pack:check": "node scripts/check-pack.mjs",
     "dev": "node scripts/dev.mjs",
     "smoke": "node scripts/smoke.mjs",
-    "context": "node scripts/context-audit.mjs"
+    "context": "node scripts/context-audit.mjs",
+    "screenshots": "node scripts/screenshots/shots.mjs",
+    "demo": "node scripts/screenshots/demo.mjs"
   },
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "1.4.0",
@@ -27,6 +29,7 @@
     "node": ">=24"
   },
   "pi": {
+    "image": "https://raw.githubusercontent.com/saifymatteo/pi-extensions/main/demo.gif",
     "extensions": [
       "./packages/pi-load-pi-dotenv/src/index.ts",
       "./packages/pi-bg-bash/src/index.ts",
@@ -64,10 +67,13 @@
     "url": "git+https://github.com/saifymatteo/pi-extensions.git"
   },
   "keywords": [
-    "pi-package"
+    "pi-package",
+    "pi-extension",
+    "pi-skill"
   ],
   "files": [
     "packages",
+    "!packages/*/screenshot.png",
     "inventory.json",
     "README.md",
     "NOTICE.md",

package/packages/pi-bg-bash/README.md

@@ -1,5 +1,9 @@
 # @saifymatteo/pi-bg-bash
 
+![The agent runs npm test in the background, keeps working, and the result arrives as its own row](screenshot.png)
+
+*The agent starts `npm test` with `background: true` and keeps working. When the job exits, its result arrives as a separate row. Ctrl+O expands that row to the output tail.*
+
 ## Purpose and registrations
 
 Overrides `bash` and, when provided by the host, `powershell`, adding `background` and `job`. Registers `/bg`, result/call renderers, timeout injection, sleep-wait guard, session/settlement hooks, and shell provider discovery.

package/packages/pi-bg-bash/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@saifymatteo/pi-bg-bash",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "license": "AGPL-3.0-only",
   "type": "module",
   "keywords": [
-    "pi-package"
+    "pi-package",
+    "pi-extension"
   ],
   "files": [
     "src",
@@ -14,6 +15,7 @@
     "LICENSE"
   ],
   "pi": {
+    "image": "https://raw.githubusercontent.com/saifymatteo/pi-extensions/main/packages/pi-bg-bash/screenshot.png",
     "extensions": [
       "./src/index.ts"
     ]

package/packages/pi-claude-usage/README.md

@@ -1,5 +1,9 @@
 # Claude subscription usage
 
+![Footer showing Claude 5-hour and 7-day usage with reset timers](screenshot.png)
+
+*An extra footer line shows Claude 5-hour and 7-day usage and when each window resets. Its colour changes at 75% and 90%.*
+
 Displays Claude subscription rate-limit windows from provider message diagnostics.
 
 ## Try locally
@@ -14,7 +18,7 @@ This uses your normal personal resources unless you isolate the agent home. Foll
 
 ## Configuration and requirements
 
-Uses rate-limit diagnostics from the external pi-claude-code provider; it does not poll Anthropic. Caches the most recent windows in <agent-dir>/state/claude-usage.json. No additional configuration.
+Uses rate-limit diagnostics from the external pi-claude-code provider; it does not poll Anthropic. Caches the most recent windows in <agent-dir>/state/claude-usage.json. The footer is shown only while the selected model uses the `claude-code` provider, not for Claude models accessed through other providers. Switching providers hides or restores it immediately. No additional configuration.
 
 ## Compatibility and safety
 

package/packages/pi-claude-usage/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@saifymatteo/pi-claude-usage",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Displays Claude subscription rate-limit windows from provider message diagnostics.",
   "type": "module",
   "license": "AGPL-3.0-only",
   "keywords": [
-    "pi-package"
+    "pi-package",
+    "pi-extension"
   ],
   "files": [
     "src",
@@ -14,6 +15,7 @@
     "LICENSE"
   ],
   "pi": {
+    "image": "https://raw.githubusercontent.com/saifymatteo/pi-extensions/main/packages/pi-claude-usage/screenshot.png",
     "extensions": [
       "./src/index.ts"
     ]

package/packages/pi-claude-usage/src/index.ts

@@ -77,7 +77,11 @@ export default function (pi: ExtensionAPI) {
 	let tick: ReturnType<typeof setInterval> | undefined;
 
 	function render() {
-		if (!ctx || !usage) return;
+		if (!ctx) return;
+		if (ctx.model?.provider !== "claude-code" || !usage) {
+			ctx.ui.setStatus(STATUS_KEY, undefined);
+			return;
+		}
 		const now = Date.now();
 		const text = formatFooter(usage, now);
 		const p = peak(usage, now);
@@ -115,6 +119,11 @@ export default function (pi: ExtensionAPI) {
 		}
 	});
 
+	pi.on("model_select", async (_event, sessionCtx) => {
+		ctx = sessionCtx;
+		render();
+	});
+
 	pi.on("session_shutdown", async () => {
 		if (tick) clearInterval(tick);
 		tick = undefined;

package/packages/pi-claude-usage/test/behavior.test.mjs

@@ -0,0 +1,71 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { loadExtension } from '../../../test/load-extension.mjs';
+
+const cached = { fiveHour: { pct: 42, resetsAt: 4_000_000_000_000 } };
+
+function harness(t, initialModel, cache = cached) {
+  const hooks = {}, statuses = new Map(), timers = new Set(), writes = [];
+  const extension = loadExtension(new URL('../src/index.ts', import.meta.url), {
+    'node:fs': {
+      readFileSync: () => {
+        if (!cache) throw new Error('no cache');
+        return JSON.stringify(cache);
+      },
+      mkdirSync: () => {},
+      writeFileSync: (_path, contents) => writes.push(JSON.parse(contents)),
+    },
+  }, {
+    setInterval: fn => { timers.add(fn); return fn; },
+    clearInterval: fn => timers.delete(fn),
+  });
+  extension.default({ on: (name, fn) => { hooks[name] = fn; } });
+  const ui = {
+    setStatus: (key, value) => { if (value === undefined) statuses.delete(key); else statuses.set(key, value); },
+    theme: { fg: (_color, value) => value },
+  };
+  const context = model => ({ model, ui });
+  const ctx = context(initialModel);
+  t.after(() => hooks.session_shutdown());
+  return {
+    hooks, ctx, statuses, timers, writes,
+    select: model => hooks.model_select({ model }, context(model)),
+  };
+}
+
+for (const model of [undefined, { provider: 'openai', id: 'gpt-5' }, { provider: 'anthropic', id: 'claude-sonnet-4-6' }]) {
+  test(`cached Claude usage stays hidden for ${model?.provider ?? 'no model'}`, async t => {
+    const h = harness(t, model);
+    await h.hooks.session_start({}, h.ctx);
+    assert.equal(h.statuses.has('claude-usage'), false);
+  });
+}
+
+test('model changes hide and restore cached usage immediately, including timer refreshes', async t => {
+  const h = harness(t, { provider: 'claude-code', id: 'sonnet' });
+  await h.hooks.session_start({}, h.ctx);
+  assert.match(h.statuses.get('claude-usage'), /^Claude 5h 42%/);
+
+  await h.select({ provider: 'openai', id: 'gpt-5' });
+  assert.equal(h.statuses.has('claude-usage'), false);
+  for (const refresh of h.timers) refresh();
+  assert.equal(h.statuses.has('claude-usage'), false);
+
+  await h.select({ provider: 'claude-code', id: 'sonnet' });
+  assert.match(h.statuses.get('claude-usage'), /^Claude 5h 42%/);
+});
+
+test('diagnostics update the cache without exposing usage on another provider', async t => {
+  const h = harness(t, { provider: 'openai', id: 'gpt-5' }, null);
+  await h.hooks.session_start({}, h.ctx);
+  await h.hooks.message_end({ message: {
+    role: 'assistant',
+    diagnostics: [{ type: 'claude-code.rate-limit', details: {
+      unifiedWindows: { five_hour: { utilization: 0.75, resetsAt: 4_000_000_000 } },
+    } }],
+  } }, h.ctx);
+  assert.equal(h.statuses.has('claude-usage'), false);
+  assert.equal(h.writes.at(-1).fiveHour.pct, 75);
+  await h.select({ provider: 'claude-code', id: 'sonnet' });
+  assert.match(h.statuses.get('claude-usage'), /^Claude 5h 75%/);
+});

package/packages/pi-clipboard-image/README.md

@@ -1,5 +1,9 @@
 # Clipboard image attachment
 
+![Alt+V pastes a clipboard image into the draft as [Image #1]](screenshot.png)
+
+*Alt+V adds the clipboard image to the draft as `[Image #1]`. Sending the message sends the image to the model with it.*
+
 Attaches clipboard images to the draft, including copied image files on Windows.
 
 ## Try locally

package/packages/pi-clipboard-image/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@saifymatteo/pi-clipboard-image",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Attaches clipboard images to the draft, including copied image files on Windows.",
   "type": "module",
   "license": "AGPL-3.0-only",
   "keywords": [
-    "pi-package"
+    "pi-package",
+    "pi-extension"
   ],
   "files": [
     "src",
@@ -14,6 +15,7 @@
     "LICENSE"
   ],
   "pi": {
+    "image": "https://raw.githubusercontent.com/saifymatteo/pi-extensions/main/packages/pi-clipboard-image/screenshot.png",
     "extensions": [
       "./src/index.ts"
     ]

package/packages/pi-codeblock-borders/README.md

@@ -1,5 +1,9 @@
 # pi-codeblock-borders
 
+![The same reply rendered by stock pi and with codeblock borders](screenshot.png)
+
+*The same reply, rendered by stock pi and then with this extension. Code fences become full-width rules, and `title=`, `:line-numbers` and `{2}` line focus are rendered.*
+
 Render markdown code fences as full-width rules spanning the content area, and upgrade the fence info string with language decoration, titles, and line numbers that Pi's built-in renderer does not support.
 
 ## Running locally

package/packages/pi-codeblock-borders/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@saifymatteo/pi-codeblock-borders",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "license": "AGPL-3.0-only",
   "description": "Decorated code fences",
   "engines": {
     "node": ">=24"
   },
   "pi": {
+    "image": "https://raw.githubusercontent.com/saifymatteo/pi-extensions/main/packages/pi-codeblock-borders/screenshot.png",
     "extensions": [
       "./src/index.ts"
     ]
@@ -22,7 +23,8 @@
     "@earendil-works/pi-tui": "*"
   },
   "keywords": [
-    "pi-package"
+    "pi-package",
+    "pi-extension"
   ],
   "publishConfig": {
     "access": "public"

package/packages/pi-codegraph/README.md

@@ -1,5 +1,9 @@
 # @saifymatteo/pi-codegraph
 
+![codegraph_explore returning source and blast radius, with CodeGraph sync status in the footer](screenshot.png)
+
+*The agent calls `codegraph_explore` and gets back the relevant source with its blast radius (expanded here with Ctrl+O). The footer shows the index status, which is synced after every turn.*
+
 ## Purpose and registrations
 
 Registers `codegraph_explore`, `/codegraph-init`, `/codegraph-sync`, `/codegraph-status`, `/codegraph-unlock`, session startup/shutdown and settle-sync hooks, and footer status.

package/packages/pi-codegraph/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@saifymatteo/pi-codegraph",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "license": "AGPL-3.0-only",
   "type": "module",
   "keywords": [
-    "pi-package"
+    "pi-package",
+    "pi-extension"
   ],
   "files": [
     "src",
@@ -14,6 +15,7 @@
     "LICENSE"
   ],
   "pi": {
+    "image": "https://raw.githubusercontent.com/saifymatteo/pi-extensions/main/packages/pi-codegraph/screenshot.png",
     "extensions": [
       "./src/index.ts"
     ]

package/packages/pi-compact-tools/README.md

@@ -1,5 +1,9 @@
 # Compact tool cards
 
+![Four tool calls folded into one card, then expanded with Ctrl+O](screenshot.png)
+
+*Four tool calls in a row fold into one summary card. Ctrl+O expands it, and each call keeps its own status and output.*
+
 Groups consecutive tool calls into compact expandable transcript cards.
 
 ## Try locally

package/packages/pi-compact-tools/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@saifymatteo/pi-compact-tools",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Groups consecutive tool calls into compact expandable transcript cards.",
   "type": "module",
   "license": "AGPL-3.0-only",
   "keywords": [
-    "pi-package"
+    "pi-package",
+    "pi-extension"
   ],
   "files": [
     "src",
@@ -14,6 +15,7 @@
     "LICENSE"
   ],
   "pi": {
+    "image": "https://raw.githubusercontent.com/saifymatteo/pi-extensions/main/packages/pi-compact-tools/screenshot.png",
     "extensions": [
       "./src/index.ts"
     ]

package/packages/pi-decisions/README.md

@@ -1,5 +1,9 @@
 # @saifymatteo/pi-decisions
 
+![The classify tool returning a structured triage answer with probabilities](screenshot.png)
+
+*The agent calls `classify` against a configured Decisions endpoint and gets structured answers with per-label probabilities.*
+
 ## Purpose and registrations
 
 When configured, registers classifier providers and the `classify` tool (choice/bool/score; JSON state and optional PNG/JPEG/WebP images). No slash commands. Requires Pi's classifier model registry APIs (`findOfType`, `classify`, provider `classifiers`); older hosts may not implement them.

package/packages/pi-decisions/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@saifymatteo/pi-decisions",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "license": "AGPL-3.0-only",
   "type": "module",
   "keywords": [
-    "pi-package"
+    "pi-package",
+    "pi-extension"
   ],
   "files": [
     "src",
@@ -14,6 +15,7 @@
     "LICENSE"
   ],
   "pi": {
+    "image": "https://raw.githubusercontent.com/saifymatteo/pi-extensions/main/packages/pi-decisions/screenshot.png",
     "extensions": [
       "./src/index.ts"
     ]

package/packages/pi-load-pi-dotenv/README.md

@@ -1,5 +1,9 @@
 # Pi dotenv loader
 
+![Environment variables from ~/.pi/agent/.env reaching a bash tool call](screenshot.png)
+
+*With this extension, variables from `~/.pi/agent/.env`, including `${VAR}` expansion, reach the tools the agent runs. Stock pi passes nothing through.*
+
 Loads environment variables from the Pi agent directory without replacing existing environment values.
 
 ## Try locally

package/packages/pi-load-pi-dotenv/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@saifymatteo/pi-load-pi-dotenv",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Loads environment variables from the Pi agent directory without replacing existing environment values.",
   "type": "module",
   "license": "AGPL-3.0-only",
   "keywords": [
-    "pi-package"
+    "pi-package",
+    "pi-extension"
   ],
   "files": [
     "src",
@@ -14,6 +15,7 @@
     "LICENSE"
   ],
   "pi": {
+    "image": "https://raw.githubusercontent.com/saifymatteo/pi-extensions/main/packages/pi-load-pi-dotenv/screenshot.png",
     "extensions": [
       "./src/index.ts"
     ]

package/packages/pi-model-go/README.md

@@ -1,5 +1,9 @@
 # pi-model-go
 
+![/model-go picker sorted by effective price with credit multipliers and intelligence scores](screenshot.png)
+
+*`/model-go` lists OpenCode Go models sorted by effective price (input ÷ plan credit), with context size, intelligence score and credit multiplier.*
+
 Cost-aware model picker showing registry prices/context, OpenCode Go credit multipliers and stencil.so intelligence scores. Source describes it as a port of rizal72/oc-models-pro.
 
 ## Running locally

package/packages/pi-model-go/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@saifymatteo/pi-model-go",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "license": "AGPL-3.0-only",
   "type": "module",
   "keywords": [
-    "pi-package"
+    "pi-package",
+    "pi-extension"
   ],
   "files": [
     "src",
@@ -13,6 +14,7 @@
     "LICENSE"
   ],
   "pi": {
+    "image": "https://raw.githubusercontent.com/saifymatteo/pi-extensions/main/packages/pi-model-go/screenshot.png",
     "extensions": [
       "./src/index.ts"
     ]

package/packages/pi-prestart-working/README.md

@@ -1,5 +1,9 @@
 # @saifymatteo/pi-prestart-working
 
+![Spinner labelled with the extension whose before_agent_start hook is running](screenshot.png)
+
+*A slow `before_agent_start` hook normally leaves the UI silent after you press Enter. With this extension, the spinner names the extension that is running.*
+
 ## Purpose and registrations
 
 Shows Pi's native "Working" spinner, labelled with the extension currently blocking (e.g. `⠙ Loading hindsight-coding-agents`), while `before_agent_start` hooks run. Pi only raises its working indicator at `turn_start`, so slow handlers otherwise leave the UI silent. No tools, commands, or configuration.

package/packages/pi-prestart-working/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@saifymatteo/pi-prestart-working",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Show a labelled Working spinner while before_agent_start hooks run.",
   "type": "module",
   "license": "AGPL-3.0-only",
   "keywords": [
-    "pi-package"
+    "pi-package",
+    "pi-extension"
   ],
   "files": [
     "src",
@@ -14,6 +15,7 @@
     "LICENSE"
   ],
   "pi": {
+    "image": "https://raw.githubusercontent.com/saifymatteo/pi-extensions/main/packages/pi-prestart-working/screenshot.png",
     "extensions": [
       "./src/index.ts"
     ]

package/packages/pi-root-guard/README.md

@@ -1,5 +1,9 @@
 # Agent configuration root guard
 
+![A write into ~/.pi/agent blocked by the guardrail](screenshot.png)
+
+*Stock pi lets the agent rewrite its own config. With the guard, writes into the Pi and Claude config roots are blocked, and the agent is told why.*
+
 Blocks selected write/edit and simple bash writes into Pi and Claude configuration roots.
 
 ## Try locally

package/packages/pi-root-guard/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@saifymatteo/pi-root-guard",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Blocks selected write/edit and simple bash writes into Pi and Claude configuration roots.",
   "type": "module",
   "license": "AGPL-3.0-only",
   "keywords": [
-    "pi-package"
+    "pi-package",
+    "pi-extension"
   ],
   "files": [
     "src",
@@ -14,6 +15,7 @@
     "LICENSE"
   ],
   "pi": {
+    "image": "https://raw.githubusercontent.com/saifymatteo/pi-extensions/main/packages/pi-root-guard/screenshot.png",
     "extensions": [
       "./src/index.ts"
     ]