@bytetrue/pi-vision

Let a text-only Pi model understand images through a vision-capable model you already configured.

pi-vision uses models and credentials from your existing models.json. It adds no provider configuration and chooses no model for you.

Install

pi install npm:@bytetrue/pi-vision

Restart or reload Pi, then select a model:

/vision

The menu lists models whose Pi configuration declares image input. There is deliberately no default, so the extension cannot silently choose an expensive provider.

If the list is empty, first add a model whose input includes image to Pi's models.json, then rerun /vision. @bytetrue/pi-vendor can manage that configuration.

Two ways to use it

Mode	Best for	How it works
image_ask(paths, question)	Local files, comparisons, and focused follow-ups	The Agent sends one or more local images plus a specific question to the configured vision model
Automatic attachment analysis	Images attached through Pi startup, print mode, or RPC	The extension analyzes the whole batch before the first text-only main-model call

Enable or disable automatic mode explicitly:

/vision auto on
/vision auto off

Automatic mode is off by default because enabling it sends attachments and the current request to another provider.

[!NOTE] Pi's interactive Ctrl+V image paste becomes a local file path in the input. That path uses image_ask; it is not an automatic attachment. The same applies when you paste or mention any local image path.

image_ask

image_ask(paths, question)

• paths — local PNG, JPEG, GIF, or WebP files, absolute or relative to the current working directory. Each file may be at most 20 MiB; a larger file is rejected before it is read, with a hint to downscale it first. Formats are identified by the file header, not the extension, so a renamed file is judged by its contents.
• question — the specific detail the vision model should answer.

Ask naturally:

Compare /tmp/mockup.png with /tmp/render.png and list the visible layout differences.

Pass several paths together to compare a mockup with a rendered page, or successive screenshots of the same flow. HTTP(S) URLs are not accepted; download the image first.

The 20 MiB cap here applies to each file. It is a different limit from automatic mode's batch below, which allows up to four images with a combined decoded size of 20 MiB.

If a text-only model tries Pi's built-in read tool on an image, the extension appends a short pointer to image_ask instead of leaving the model at a dead end.

Automatic-mode limits

One request may contain up to four images with a combined decoded size of 20 MiB. The batch has a fixed 60-second deadline and is rejected as a whole if validation fails.

Success or failure is injected before the main model starts. A failure explicitly tells the main model that it did not see the images, reducing the risk of a fabricated visual answer.

Trusted project settings may override the global configuration. An untrusted project cannot enable attachment forwarding.

Settings

/vision keeps its own file and preserves every other key in it:

{
  "model": "provider/vision-model",
  "autoAnalyzeAttachments": false
}

The global file is <pkg-config root>/pi-vision/settings.json, where the root is $PI_PKG_CFG_DIR or <agent dir>/pi-pkg-cfg and <agent dir> is $PI_CODING_AGENT_DIR (~/.pi/agent by default). It never touches Pi's settings.json. A trusted project may override it with <project>/.pi/pi-pkg-cfg/pi-vision/settings.json; that project file is read-only, so nothing is ever written into your repository.

Upgrading from 0.2.x: the pi-vision section of Pi's settings.json is lifted into the new file — whole section, in one write — the first time the package reads or writes it. Pi's file is left untouched so downgrading still works. A project pi-vision section in <project>/.pi/settings.json keeps working until you move or delete it, which is deliberate: a project override should outrank the global one. When a value comes from an old path, /vision and status output say legacy (read-only fallback) next to it.

When the current main model already accepts images, image_ask is removed from active tools and the extension stays out of Pi's normal image path.

Development

npm --workspace @bytetrue/pi-vision test
npm --workspace @bytetrue/pi-vision run typecheck
npm --workspace @bytetrue/pi-vision pack --dry-run

Requires @earendil-works/pi-coding-agent >=0.79.10.