@blackbelt-technology/pi-image-fit

Pi extension that resizes oversize images at Read-time so they fit model byte and pixel ceilings.

The extension hooks pi.on("tool_call", ...). When the agent runs the built-in read tool with an image path (.png, .jpg, .jpeg, .webp, .gif), the extension:

1. Stats the file and (lazily) probes dimensions via jimp.
2. If the image already fits both thresholds, leaves event.input.path untouched — built-in Read sees the original bytes, no temp file, no telemetry.
3. Otherwise, re-encodes the image (long-edge scaled, aspect-ratio preserved) into a session-scoped temp file under os.tmpdir()/pi-image-fit/<session>/<sha256>.<ext> and mutates event.input.path to point at it. Built-in Read attaches the smaller image to the agent's context window.

No native binary deps — jimp only. No electron-rebuild step, no platform-specific prebuilt downloads. Pure JS install on every supported pi target.

Install

pi install @blackbelt-technology/pi-image-fit

The next pi session loads the extension. No dashboard or other workspace package required.

Default thresholds

| Setting | Default | Env var | | --- | --- | --- | | Long-edge pixels | 1568 | PI_IMAGE_FIT_MAX_EDGE | | Byte size | 4,194,304 (4 MiB) | PI_IMAGE_FIT_MAX_BYTES | | JPEG quality | 85 | PI_IMAGE_FIT_QUALITY | | Kill switch | off | PI_IMAGE_FIT_DISABLE |

Resize triggers when either the byte size or the long edge exceeds its threshold. When both are at or below their thresholds, the extension is a no-op.

Environment variables

• PI_IMAGE_FIT_DISABLE — truthy (1, true, yes, case-insensitive) skips the pi.on("tool_call", ...) registration entirely; the extension logs a single disabled-message line on load and does nothing else.
• PI_IMAGE_FIT_MAX_EDGE=<px> — positive integer; override the long-edge threshold.
• PI_IMAGE_FIT_MAX_BYTES=<bytes> — positive integer; override the byte threshold.
• PI_IMAGE_FIT_QUALITY=<1-100> — JPEG output quality. Ignored for PNG-in → PNG-out path (always lossless).

Invalid values fall back to the documented default and log a single warning line naming the variable.

Output format

Format-adaptive:

• .png source → PNG output (lossless re-encode preserves transparency).
• everything else → JPEG at the configured quality.

Cache file extension matches the chosen output format.

Telemetry

On a successful resize the extension emits exactly one line:

[pi-image-fit] <path> <srcW>×<srcH> <srcBytes>B → <dstW>×<dstH> <dstBytes>B

No log on already-small pass-throughs, on non-image reads, or on non-read tool calls. Failures log a single [pi-image-fit] WARN ... line and fall through to the original path (the agent's Read behaves exactly as if the extension were not installed).

Caveat: silent quality loss

A 4K screenshot squashed to 1568 px may lose fine text. The agent has no way to tell that resize fired beyond the console log line. If pixel perfect Read matters for a workflow, set PI_IMAGE_FIT_DISABLE=1 in that environment.

License

MIT. Part of the pi-agent-dashboard monorepo; versions move in lockstep with the rest of the workspace.