Disclaimer: This plugin has been developed in co-operation with AI

Pi Neuralwatt Extension

This extension adds Neuralwatt support to the pi coding agent.

Installation

Install with one of the following:

pi install npm:pi-neuralwatt
pi install git:github.com/tedewaard/pi-neuralwatt
pi install https://github.com/tedewaard/pi-neuralwatt

Configuration

API Key Setup

You can provide your Neuralwatt API key in either of two ways:

Option 1: Environment Variable (Recommended)

Set the following variable in your shell or shell configuration before launching pi:

export NEURALWATT_API_KEY=<your_neuralwatt_api_key>

Option 2: Stored Credentials

Run /login in interactive mode and select the neuralwatt provider to store the key in auth.json for future sessions.

Without an API key

The /v1/models catalog is readable without a key, so neuralwatt models are still discovered and registered. Every live API call, however, reports that no key is configured: /neuralwatt:quota and /neuralwatt:energy surface an error, and the status-bar widget (when enabled) displays ⚡no API key configured for neuralwatt.

Feature Highlights

• Dynamic model catalog – Discovers the neuralwatt provider's model catalog at runtime from https://api.neuralwatt.com/v1/models (capabilities, context window, per-million pricing), so new upstream models appear without an extension update. On the first run the catalog is empty until pi starts a session and fetches it; thereafter the fetched list is cached to ~/.pi/agent/pi-neuralwatt.json and re-registered from disk on every startup, so warm starts (and pi --list-models) see it instantly without a network round-trip. The cache is refreshed automatically when it expires, and explicitly with /neuralwatt:refresh.
• Cache-Control aware – The cache expiry is derived from the /v1/models response Cache-Control header (s-maxage, then max-age), falling back to a 24h default when the header is absent. no-cache/no-store mark the catalog immediately stale, so the next startup refetches instead of serving from cache.
• Reasoning-aware models – For each model, reasoning, thinkingLevelMap, and compat (supportsDeveloperRole, supportsReasoningEffort) are derived at fetch time from the API's reported capabilities and pi's curated built-in catalogs (matched by model id), so reasoning models are wired up correctly with no manual configuration. pi uses these fields when crafting requests. If a /v1/models fetch fails, the previously cached list (stale or otherwise) is kept.
• Status-bar widget – When enabled, shows remaining credit balance plus current-month usage (requests and energy) and spend. Refreshes on session start, after each LLM turn, and on model switch (throttled to once per 60s), and only while a Neuralwatt model is the active model. Disabled by default; enable it with /neuralwatt:toggle. The setting is persisted in ~/.pi/agent/pi-neuralwatt.json (under statusBarEnabled) alongside the model cache, so it survives restarts.
• Slash Commands
  • /neuralwatt:energy – Shows an energy-consumption report for the current period: request count, energy scaled to the most readable unit (µWh/mWh/kWh) plus joules, estimated cost, and a recent 7-day daily breakdown.
  • /neuralwatt:quota – Shows your key name, accounting method, account balance (remaining/total and % used), current-month and lifetime usage totals, rate-limit tier, and snapshot timestamp.
  • /neuralwatt:toggle – Enable or disable the status-bar widget (disabled by default; persisted across restarts).
  • /neuralwatt:refresh – Force-refresh the model catalog from /v1/models, bypassing the cache. Reports how many models were refreshed, or falls back to the last cache on failure.

Usage Example

# start pi normally – the extension is auto-loaded
pi

Once pi starts, you can run /models to select a neuralwatt model. On a first run (no cached catalog yet), the model list is populated as soon as pi starts its session and fetches /v1/models; subsequent runs read from the on-disk cache immediately. Then you can run one of the following commands:

/neuralwatt:energy
/neuralwatt:quota
/neuralwatt:toggle
/neuralwatt:refresh

The status-bar widget is disabled by default. Run /neuralwatt:toggle to enable it — live quota information then appears in the status bar (bottom of the terminal). Run it again to hide it. Run /neuralwatt:refresh to force-reload the model catalog from /v1/models (e.g. after a new model ships upstream).

Development

First install the dependencies. This pulls in the @earendil-works/pi-coding-agent peer dependency, which provides both the pi binary and the extension's types:

npm install

Then run pi with the extension loaded straight from source, so you can iterate on extensions/neuralwatt.ts without installing the package:

pi -e ./extensions/neuralwatt.ts

-e (--extension) takes any local path and can be passed multiple times. If pi isn't on your PATH, use the copy installed above with npx pi -e ./extensions/neuralwatt.ts.

Also note that you should not have an instance of this plugin installed via npm or git; I've experienced that if you try to load an extension with the same name via -e as one already installed, the installed one seems to be preferred.

---