Pi Neuralwatt Extension

A Pi extension that adds Neuralwatt as a model provider, giving you access to open-source models through an OpenAI-compatible API with energy transparency.

Installation

Get API Key

Sign up here to get an API key (referral link).

Configure Credentials

The extension uses Pi's credential storage. Add your API key to ~/.pi/agent/auth.json (recommended):

{
  "neuralwatt": { "type": "api_key", "key": "your-api-key-here" }
}

Or set environment variable:

export NEURALWATT_API_KEY="your-api-key-here"

Install Extension

# From npm
pi install npm:@aliou/pi-neuralwatt

# From git
pi install git:github.com/aliou/pi-neuralwatt

# Local development
pi -e ./extensions/provider/index.ts

Usage

Once installed, select neuralwatt as your provider and pick a model:

/model neuralwatt kimi-k3

API surface

Neuralwatt serves every model on two APIs. Pick one in /neuralwatt:settings → API (or set provider.api in the extension config):

• openai-completions (default): the OpenAI-compatible chat/completions endpoint.
• anthropic-messages: the Anthropic-compatible POST /v1/messages endpoint, which streams native tool use and thinking blocks.

Both use the same model ids. The setting applies on /reload. Cost, energy, and quota tracking work on both.

Quota Command

Check your API usage at a glance:

/neuralwatt:quota

The quota command shows three tabs:

• Subscription (when subscribed): plan details, energy quota with progress bar, billing period
• Credits: credit balance with progress bar, accounting method
• Usage & Key: monthly usage (cost, requests, tokens, energy), API key info, key allowance, rate limits

https://github.com/user-attachments/assets/a8994940-c467-4744-a0f2-833cb63923ff

Quota Warnings

When enabled, the extension notifies you when credits or energy are running low. With an active subscription, only energy warnings fire (credits are on-demand top-up only).

Library use

Use @aliou/pi-neuralwatt/provider outside the coding agent:

Install the library with its runtime peers, @earendil-works/pi-ai and typebox.

import { InMemoryModelsStore } from "@earendil-works/pi-ai";
import { createModels } from "@earendil-works/pi-ai/models";
import createNeuralwattProvider from "@aliou/pi-neuralwatt/provider";

const models = createModels({ modelsStore: new InMemoryModelsStore() });
models.setProvider(
  createNeuralwattProvider({
    baseUrl: "https://gateway.example.com/v1",
    provenance: { referer: "https://my-app.example" },
  }),
);
await models.refresh();

All options are optional. Without credentials, the provider lists and refreshes the public catalog. NEURALWATT_API_KEY or a stored credential enables keyed models. The X-NW-Conversation-ID header comes from each request's sessionId. Set provenance: { enabled: false } to stop adding the Referer and conversation ID headers to inference requests.

Settings

Configure features with /neuralwatt:settings:

• API — Choose between openai-completions (default) and anthropic-messages; applies on /reload
• API base URL — Send requests to a different base URL, such as a gateway; empty uses the Neuralwatt API
• Quota command — Show/hide /neuralwatt:quota
• Quota warnings — Enable/disable low quota notifications

The provider itself cannot be disabled — it is always loaded.

Model list

The extension ships a built-in model list, so it works offline on first start. Pi refreshes the catalog from the Neuralwatt API in the background (authenticated when an API key is configured, so key-scoped models appear too) and caches it in ~/.pi/agent/models-store.json. pi update --models forces a refresh.

Development

git clone https://github.com/aliou/pi-neuralwatt.git
cd pi-neuralwatt
pnpm install
pnpm run typecheck
pnpm run lint
pnpm run test
pnpm run check:models   # compare the built-in model list with the live API

The pre-commit hook runs typecheck, lint, the lockfile check, and the changeset check. Releases use Changesets.

Requirements

• Pi coding agent 1.4 or later
• Neuralwatt API key (configured in ~/.pi/agent/auth.json or via NEURALWATT_API_KEY)

Links

• Neuralwatt
• Neuralwatt API Docs
• Pi Documentation