pi-free-catalog

Find free models from Kilo and OpenCode Zen in Pi, without keeping a model list up to date yourself.

The package adds two providers, free-kilo and free-zen. It checks live catalogs and pricing information whenever Pi loads the extension, then makes the confirmed-free models available in the model picker. Models with missing or conflicting prices stay visible in the catalog report, but cannot be called as free.

No personal API key, account setup, or running OpenCode CLI is needed for the public endpoints used here. This is an independent community integration, not an official Kilo or OpenCode client. Upstream availability, quotas, and access policies still apply.

Requirements: Pi 1.3.x and Node.js 22.19 or later. Licensed under MIT; maintained by aminmza.

Get started

pi install npm:pi-free-catalog
pi

Open Pi's model picker and choose a model from free-kilo or free-zen.

For a reproducible install, specify the version:

pi install npm:pi-free-catalog@0.1.4

To try the published package for one run without saving it to your settings:

pi -e npm:pi-free-catalog

This is a Pi extension, not a standalone agent. Install it with pi install, rather than npm install -g.

Use a local copy

For development, extract the release source ZIP and keep the extracted folder somewhere permanent:

pi install ./pi-free-catalog-0.1.4
pi

Pi loads local packages from their original folder, so do not move or delete it while the package is installed. If you are replacing an npm installation, remove that installation first:

pi remove npm:pi-free-catalog

Avoid loading both copies at once. From the source folder, pi -e . is another way to test a local copy without saving a new package entry.

What appears in the catalog?

The goal is to keep the full picture visible, not just the models that happened to work in a test.

• Every live model ID is checked. The words free or paid in a model's name do not determine its classification.
• All currently listed, confirmed-free chat models are registered, including models with unknown limits, limited tool support, or previous inference errors.
• Models with uncertain or conflicting prices remain in /free-catalog and /free-export, with calls blocked until they can be verified.
• Previously free, missing, deprecated, and retired models remain in the report and history. They do not quietly disappear from the evidence.
• Native classifiers, such as Zen's jev-1.13-free, are registered separately rather than presented as chat models.
• An unfamiliar operation or transport stays in the report with a clear unsupported notice. Being listed is not a promise that every future protocol is implemented.

How free pricing is checked

For Kilo, the catalog's explicit isFree: true flag is the starting point. A positive charge conflicts with that flag and blocks the model. Zero prices alongside isFree: false are also treated as a conflict. Missing or dynamic prices are retained as evidence when the explicit free flag is present.

For Zen, the live model list is joined by exact ID with official OpenCode metadata, models.dev, and Pi's model metadata. The check includes input, output, cache, and tiered charges. Missing prices are unknown, not assumed to be zero. For an already confirmed-free model, incomplete metadata can retain its last-known free evidence instead of disabling chat. New models without free evidence, fresh paid prices, and price conflicts are still blocked.

The extension cannot verify information that an upstream service does not publish. It keeps that uncertainty visible instead of guessing.

Refreshes and model history

All five sources are fetched on every extension load, before initial model selection, including noninteractive runs. An existing cache does not skip that startup check. After startup, only /free-refresh fetches these sources again. Sending messages, changing thinking, waiting past five minutes, and Pi's internal model-registry refresh do not trigger catalog network requests. Reloading the extension starts a new startup check.

A failed refresh does not erase or disable the last known free catalog. Cached free models stay selectable and requests are sent to their normal anonymous endpoints. A catalog outage is not an inference outage: if the endpoint is reachable, chat and tools can still work. If the model is missing or unavailable upstream, its actual response is returned without a freshness-guard error. A first run without either a usable cache or a successful fetch cannot invent a model list.

Changes are handled according to what the sources actually say:

Change	What happens
Explicit retirement	The model is removed from callable models and kept in history.
Missing from a successful catalog response	It is marked not-listed, not assumed retired. It can return if listed again.
Deprecated, but still listed and free	It remains available with a deprecation label.
Free model becomes paid	Free access is blocked; the model remains in the report.
Timeout, 404, 429, or capacity error	The error is recorded, not treated as proof of retirement.

The cache is stored in free-catalog/catalog.json inside Pi's agent directory, normally ~/.pi/agent/free-catalog/. Despite the filename, the cache is compact, gzip-compressed JSON. Older plain-JSON caches still load. It retains raw source responses, timestamps, classifications, and lifecycle history; the recent change log is limited to 2,000 events, but the model inventory is not.

/free-export writes readable, uncompressed JSON for inspection. Refreshes are bounded by a 12-second timeout and a 16 MiB response limit per source. A successful fetch reflects the upstream data at that moment, not a guarantee that every source agrees instantly.

Commands

Command	What it does
/free-catalog	Show free, uncertain, conflicting, missing, and historical models, plus source health and recent HTTP results.
/free-refresh	Fetch the sources again and reconcile the model lists.
/free-thinking	Show the current model's native thinking options and selection.
/free-thinking MODE	Choose auto, default, or an advertised native mode.
/free-footer compact	Opt into the custom footer on the current free model.
/free-footer default	Release our footer if we still own it; leave other extensions alone.
/free-export [PATH]	Export the complete catalog, including source data and all live IDs, even paid ones.

Thinking that matches the model

Use Pi's normal thinking selector or shortcut as usual. In auto mode, the extension translates the selected level into a setting the provider actually advertises. It does not invent effort levels for models that only have an on/off switch.

You can also choose a native mode directly. For example, after selecting an appropriate model:

/free-thinking low
/free-thinking instant
/free-thinking thinking
/free-thinking auto
/free-thinking default

These are examples for different models, not options supported by every model. Kilo Beam advertises effort levels such as low, medium, high, xhigh, and max. Toggle models use modes such as instant and thinking. Zen effort settings are sent as reasoning_effort; Kilo settings use the provider's native parameters. The available choices come from live metadata, so check /free-thinking rather than relying on a fixed list.

Pi and native choices stay in sync

When a native mode has an exact Pi equivalent, /free-thinking updates Pi's actual level too. For example, an effort model's low maps to Pi low. On a supported toggle model, instant maps to off, and thinking maps to medium as the on/off equivalent—not as an extra provider effort level.

Changing the level in Pi then releases the previous native override for that model and returns it to auto. The current level is also checked before a turn and at payload construction, so another extension delaying an event cannot leave an old override on the wire. This prevents an old native setting from silently overriding what the Pi footer shows. Pi's omitted reasoning option for off is handled explicitly, so an advertised disabled mode is sent when available.

There are a few limits worth knowing:

• default leaves thinking to the provider; it is not another spelling of off.
• A native mode without an exact Pi equivalent remains selectable through /free-thinking. The status bar labels that override rather than pretending Pi's fixed level names cover it.
• Choosing the same Pi level again does not emit a change event in Pi 1.3. Use /free-thinking auto, or change the level, to release an override.
• Saved native preferences return when you start a session or switch back to a model. They can take precedence over Pi's initial level. Choose auto if you want Pi to control it instead.
• If a provider advertises no adjustable controls, its default is preserved. Unsupported effort or disable settings are never guessed.

/free-thinking without an argument shows the current Pi level and effective native request parameters, not just the saved selection name. Preferences are saved per provider and model in thinking.json beside the cache.

A quieter footer

The normal Pi footer is now the default. The extension contributes only the short Free: Kilo … · Zen … status. Source-failure IDs and ordinary "provider default / no advertised controls" messages do not appear in that status. Source health, errors and timestamps remain available through /free-catalog and /free-export. Important manual default/unmapped thinking overrides can still be labelled.

Pi 1.3 has one custom-footer slot and no public composition/ownership getter. Two extensions cannot safely combine arbitrary complete footers automatically. If you want this package to hide only the (free-kilo) or (free-zen) prefix, select a free model and explicitly run /free-footer compact. This reuses Pi's exported renderer and preserves the other statistics and statuses. Provider IDs and model-picker entries never change.

The preference is saved in ui.json. An existing explicitly saved compact preference is respected at startup. If another extension subsequently replaces our footer, its disposal notification relinquishes our ownership. Model switches will not reclaim or erase that extension's footer. /free-footer default releases our footer only while we still own it; it cannot resurrect a custom footer that an explicit compact command previously replaced. Run compact again only when you intend to claim the slot.

Leaving a free model releases an owned compact footer; returning to a free model does not automatically claim the slot again. Print, JSON and RPC modes are unaffected. The implementation and ownership tests use Pi 1.3.0.

Requests, tools, and safety

Requests use Pi's own OpenAI Completions, Responses, Anthropic Messages, and native classifier implementations. Pi's SDK handles streaming, tool calls and results, Unicode, cancellation, usage, and finish reasons. The extension does not replace the global HTTP client or add its own SSE parser.

Before each HTTP request, a scoped guard checks the model ID, approved endpoint, last-known free classification and lifecycle. It does not require a recent catalog fetch. It blocks redirects and paid fallback, and strips personal authorization and API-key headers. Kilo requests carry no Authorization header. Zen uses the literal public placeholder Bearer public, compatible CLI headers, and a stable per-session ID. The User-Agent identifies this integration; no OpenCode binary is launched and no quota identities are rotated.

Anonymous access can break if a service changes its policy or protocol requirements. This package does not promise permanent access, unlimited quota, universal tool support, or a particular response speed. An inference error does not blacklist a model or turn off tools to make a test pass.

Full capability metadata is retained in exports. This chat integration supports text and image inputs; other advertised modalities are not presented as implemented. When required limits are unknown, the model is labelled accordingly and uses local safety defaults of 8,192 context tokens and 2,048 output tokens. Those are not claimed provider limits.

Development and testing

From the release source ZIP or a complete source checkout:

npm ci
npm run verify

Verification checks syntax, runs the offline tests, and inspects the npm package contents. The tests cover catalog classification, lifecycle changes, anonymous free-only guards, compressed caches, failed-refresh continuity, zero per-message catalog fetches, delayed thinking events, the actual Pi session and SDK, root-entry display labels, and Pi's footer renderer and ownership handoff. Network responses in the offline tests are mocked. Passing them is not a claim that every upstream model works.

For an optional live catalog check without inference:

node scripts/catalog.mjs ./catalog-inspection.json

For live inference checks, use scripts/verify-ui-thinking-live.mjs in an isolated HOME with PI_CODING_AGENT_DIR set to a fresh directory. It runs Pi's actual agent session with the default read, write, edit, and bash tools, checks thinking parameters, and verifies real file changes. It makes about 14 inference requests across the two Beam models. --toggle-only runs the separate toggle checks. Model errors stop the run; inspect the result JSON and wire log rather than relying on a confident final answer.

The broader opt-in CLI harnesses, scripts/live_pi.py and scripts/observe_live.py, are also included. They require Python 3 and the PI_NODE, PI_CLI, PI_TEST_DISPATCHER, and FREE_TEST_DIR environment variables. Their test-only wire recorder is never loaded by the extension.

Do not commit or publish credentials, .npmrc, caches, or live test outputs. Review the source and the upstream services' terms before use; the code's MIT license does not grant service access.

Catalog sources

• https://api.kilo.ai/api/gateway/models
• https://opencode.ai/zen/v1/models
• https://models.opencode.ai/api.json
• https://models.dev/api.json
• https://pi.dev/api/models/providers/opencode?types=chat,image,classifier