@czottmann/pi-umans

Umans provider extension for pi. It registers tool-capable Umans models under the umans provider.

How is it different from the official Umans pi extension?

This extension is just the provider connection: it registers the Umans models and handles the subscription login. Nothing else.

Besides extra tools, the official extension also ships a client-side vision proxy. If you already run a pi media proxy plugin, the bundled one gets in the way. It kept interfering with mine. This package ships no media-handling code of its own. Models that Umans marks vision-capable take images straight through the gateway; for text-only models, image handling stays with whatever media proxy you run (see Vision and images).

Install

From npm:

pi install npm:@czottmann/pi-umans

From a local checkout:

cd path/to/pi-umans
npm install
pi install "$PWD"

Set up auth

Umans is a subscription, so it logs in under subscriptions, not API keys:

pi
/login
# Under "Subscriptions", choose "Umans".
# pi shows the API-keys page; create a key there and paste it when prompted.

Get the key from https://app.umans.ai/billing?context=personal&tab=api-keys. pi stores it in ~/.pi/agent/auth.json.

Or set an environment variable before starting pi:

export UMANS_API_KEY=your-key-here

Use

List registered models:

pi --list-models | grep umans

Start pi with Umans:

pi --provider umans

In interactive mode, /umans-models lists the Umans models registered by the extension.

How it works

On startup the extension fetches GET https://api.code.umans.ai/v1/models/info, keeps the models that support tools, and registers them with pi.registerProvider() using pi's anthropic-messages API adapter.

Model metadata comes from the Umans catalog:

• capabilities.context_window becomes pi's context window.
• capabilities.recommended_max_tokens becomes pi's max output tokens, clamped just below max_completion_tokens so it never trips the gateway's hard cap.
• capabilities.reasoning marks a model as reasoning-capable and maps pi's thinking levels to Umans effort levels (pi's xhigh reaches Umans max; models that can't disable thinking keep it on).
• capabilities.supports_vision adds image input when it is true or "via-handoff" (see below).

The catalog reports no per-token pricing because Umans bills a flat subscription, so registered models carry a cost of 0.

The login flow only needs the static API key. The catalog endpoint is public, so models register without a key, but inference needs either a key saved through /login or UMANS_API_KEY.

Vision and images

This provider talks to Umans over the Anthropic Messages endpoint, so every model Umans marks vision-capable accepts images: both native vision (supports_vision: true) and gateway-handoff models (supports_vision: "via-handoff", e.g. umans-glm-5.2). For handoff models the gateway runs the vision step server-side; nothing on the client analyzes the image.

Models with no vision support register text-only. To send images to those, run a separate media proxy plugin that turns images into text before they reach the model. That part is out of scope here.

Development

npm run check
npm run build
pi -e . --provider umans

Publishing

GitHub Actions publishes the package to npm when a GitHub Release is published. The release tag must match package.json exactly, with or without a leading v (v1.0.0 and 1.0.0 both work for version 1.0.0).

The workflow uses npm Trusted Publishing, so it does not need an npm token secret. Configure this package on npm with this repository and workflow file (.github/workflows/publish.yml). The workflow builds the package, runs npm run check, and publishes with npm provenance.

Author

Carlo Zottmann, carlo@zottmann.dev

• Website: https://actions.work
• GitHub: https://github.com/czottmann
• Bluesky: https://bsky.app/profile/zottmann.dev
• Mastodon: https://norden.social/@czottmann