@rwese/minimax-image-understanding

MiniMax image understanding — ships as both a pi coding agent extension and a standalone CLI for npx. Same API, two ways to use it.

Quickstart

Use it from inside pi (primary)

pi install git:github.com/rwese/pi-minimax-image-understanding

Then export your API key and ask the agent anything about a local image:

export MINIMAX_API_KEY="your-api-key"

• "Describe this image" (./screenshot.png)
• "Read the text from this screenshot"
• "What does this chart show?"

The extension registers the image_understanding tool; pi decides when to call it.

Use it once from the command line

npx @rwese/minimax-image-understanding --prompt "Describe this image" ./photo.png

That's it — npx fetches the package on first run, prints the model's response to stdout, exits.

Installation

As a pi extension

pi install git:github.com/rwese/pi-minimax-image-understanding

As a standalone CLI

# one-off, no install required
npx @rwese/minimax-image-understanding --prompt "Describe this image" ./screenshot.png

# or install globally
npm install -g @rwese/minimax-image-understanding
minimax-image-understanding --prompt "Describe this image" ./screenshot.png

The CLI runs TypeScript source via tsx at runtime — there is no build step in the published package. On first invocation, npx will fetch tsx (~1 MB, cached afterwards). Until tsx migrates off module.register() (it currently emits a DEP0205 deprecation warning on Node 22+), --quiet cannot suppress the warning because it is printed by the loader, not by the CLI.

Configuration

Both the extension and the CLI read the same environment variables:

Variable	Required	Default
MINIMAX_API_KEY	Yes	—
MINIMAX_API_HOST	No	https://api.minimax.io

Supported image formats: PNG, JPG/JPEG, WebP, GIF. Anything else falls back to image/jpeg.

Usage as a pi extension

The extension registers an image_understanding tool. pi calls it automatically when the user's request fits; you don't invoke it directly. Example prompts that trigger it:

• "Describe this image"
• "Read the text from this screenshot"
• "What does this chart show?"
• "Analyze the diagram"

The result is rendered in pi's TUI with the query in the result header.

Usage as a CLI

minimax-image-understanding --prompt <text> <image> [options]

Option	Description
--prompt <text>	Required. Question or instruction about the image.
<image>	Required positional. Path to the image file.
--json	Emit { "content": "..." } instead of raw text.
-o, --output <file>	Write response to <file> instead of stdout.
--quiet	Suppress progress messages on stderr.
-h, --help	Show help and exit.
-v, --version	Print version and exit.

Examples

# Basic description
MINIMAX_API_KEY=... npx @rwese/minimax-image-understanding \
    --prompt "Describe this image" ./photo.png

# Pipe JSON to jq
MINIMAX_API_KEY=... npx @rwese/minimax-image-understanding \
    --prompt "Extract all text" --json screenshot.png | jq -r .content

# Save to a file (clean stdout)
MINIMAX_API_KEY=... npx @rwese/minimax-image-understanding \
    --prompt "OCR this" --quiet -o extracted.txt ./scan.jpg

Exit codes

Code	Meaning
0	Success.
1	Usage / validation error.
2	Configuration error (missing API key).
3	API or network error.

Platform notes

The bin script uses a Unix shebang (#!/usr/bin/env -S npx -y tsx). On Windows, invoke through npx directly:

npx -y @rwese/minimax-image-understanding --prompt "describe" image.png

Features

• Vision-language model via MiniMax API
• Local image file paths (PNG, JPG/JPEG, WebP, GIF)
• Describe screenshots, diagrams, charts, documents
• Extract text from images (OCR-style)
• --json / -o for scripting and pipelines (CLI)
• Custom TUI rendering showing the query in the result header (pi extension)

Development

npm install
npm run validate   # typecheck + lint + tests

Layout:

• bin/minimax-image-understanding — Unix shebang entry point; calls into src/cli.ts via tsx.
• src/cli.ts — argument parsing and run().
• src/config.ts, src/image.ts, src/vlm.ts — pure core shared with the pi extension.
• extensions/index.ts — the pi extension entry, imports the same src/ modules.
• tests/ — vitest unit + integration tests (37 tests).