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.
• 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.

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 writes only the pi-vision section and preserves every other Pi setting:

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

The global file is normally ~/.pi/agent/settings.json. A trusted project may override it with <project>/.pi/settings.json.

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.