pipellm-pi-provider for Pi

Connect Pi to PipeLLM with Anthropic Messages streaming, macOS Keychain login, and gateway management from the TUI or CLI.

Install · Configure · CLI · Security

This extension uses Pi's custom provider API, extension API, and package format. Pi provides native streaming, tools, usage reporting, and thinking behavior.

The package on the npm registry includes compiled JavaScript, source and tests in source/, and dependency notices in THIRD_PARTY_LICENSES/. The source and package use the MIT license.

Install

Pi extension

Register the extension with Pi:

pi install npm:pipellm-pi-provider

Restart Pi or use /reload.

Standalone CLI

Install the CLI:

npm install -g pipellm-pi-provider
pipellm-pi-provider --help

Or run it with npx:

npx --yes pipellm-pi-provider --help

pi install registers the extension. npm install installs the independent CLI. Both require Node.js 22 or later. Pi host packages are optional peers. The package does not bundle them.

Default commands install npm latest. To select a fixed version, use pi install npm:pipellm-pi-provider@0.3.8. The pi-package keyword enables discovery in the Pi package gallery.

curl -fL https://github.com/lwyBZss8924d/pipellm-pi-provider/releases/latest/download/pipellm-pi-provider-install.sh -o pipellm-pi-provider-install.sh
sh pipellm-pi-provider-install.sh

Configure and sign in

Run these commands in Pi's terminal interface (TUI):

1. Run /pipellm-config to select the HTTPS gateway, model, token limits, and thinking policy.
2. Run /pipellm-login to enter the key through hidden input.
3. Run /pipellm-status to check models and credential metadata.
4. Select /model pipellm/claude-sonnet-5-5 or your configured model.

Login shows the destination and model for approval. It sends one small request to check the key before saving it to macOS Keychain. RPC clients use the CLI for login. Cancellation or failed validation saves no key.

Configuration preserves other providers and models. It backs up existing bytes and writes private configuration files atomically. Backups can contain older user-supplied secrets. Keep them private.

Credential sources

The extension selects the first available credential source:

Keychain updates preserve existing service labels. Writes pass the key to security through stdin. The extension checks each Keychain write. Metadata commands never resolve Keychain passwords.

models.json stores a credential reference. This extension never reads or writes Pi's auth.json and ignores its legacy credential. Native /login pipellm directs you to /pipellm-login.

On macOS, configuration uses an environment-first Keychain command so models also work with extensions disabled. Pi resolves this command before extension authentication. Keychain-only requests can read the key twice, and model availability can show a command as configured without checking its result. Use /pipellm-status for credential metadata. Rerun gateway configuration to replace an older Keychain-only command.

Configuration updates preserve non-authentication headers and file symlinks. Backups use private permissions and remain until you remove them.

Do not save or inject PIPELLM_API_KEY through .env files. Use Keychain on macOS. On other platforms, use an authorized secret manager to inject the key into the child process. The extension never loads dotenv credentials. It checks for dotenv use and shows fixed warnings without changing files.

Model behavior

For gateways that require adaptive thinking, select minimal or higher. Pi's off setting sends disabled, which those gateways reject. New custom models show zero estimated cost until you supply pricing in models.json. Keychain persistence requires macOS. Other platforms use the process environment.

Management CLI

Inspect configuration and credential metadata:

pipellm-pi-provider status --json
pipellm-pi-provider config show --json
pipellm-pi-provider auth discover --json
pipellm-pi-provider auth policy --json
pipellm-pi-provider doctor --json

Preview configuration and login, then validate a key:

pipellm-pi-provider config set --base-url https://cc-api.pipellm.ai/anthropic --model claude-sonnet-5-5 --dry-run --json
pipellm-pi-provider auth login --model claude-sonnet-5-5 --dry-run --json
pipellm-pi-provider auth login --model claude-sonnet-5-5 --yes
pipellm-pi-provider auth check --model claude-sonnet-5-5 --yes --json

Remove --dry-run from config set to save configuration. Login accepts hidden terminal input, --from-env, or --stdin. It never accepts a key argument. --yes authorizes validation. Login saves only validated keys. auth check validates without saving.

Authorized agents can inject the key into the child process. They can use auth login --from-env --yes --json. Authentication dry runs read no credentials or dotenv contents. They send no request. The metadata commands above include dotenv-policy flags. Interactive login and check show the policy reminder.

Use --agent-dir DIR or PI_CODING_AGENT_DIR for isolated settings. The Incur CLI supports schemas, field filters, JSON/JSONL, token limits, completions, and optional MCP/skill integration. Use --schema --json or --llms --json to discover commands. The CLI does not start an HTTP listener. Explicit --mcp uses stdin and stdout. Non-TTY output defaults to { ok, data/error, meta } JSON envelopes.

Compatibility and removal

Tests cover Pi 1.0.2 and 1.0.3. Compatible forks must provide the JavaScript extension loader, native custom-provider API, commands, and TUI contracts. Package metadata alone does not establish compatibility. Prime Agent 0.9.8 cannot load this extension because it removed the TS/JS runtime. Prime can use its own model settings.

The installer rejects clients without advertised extension loading before changing settings or files. The default observer preserves requests and tools. It warns once per session when a returned tool is absent from the request. The warning never blocks handling or logs payloads, headers, arguments, or tool names.

Legacy fallback requires an explicit choice and Pi host helpers:

PIPELLM_COMPAT_MODELS=claude-opus-5-5 pi

Remove credentials separately in macOS Keychain Access.

Develop

Root documents and workflows match their distribution/ templates. The development manifest has private: true and points pi.extensions to TypeScript. Packing creates a publishable manifest with compiled JavaScript, bin, exports, and optional peers.

From the repository or the archive's source/ directory:

bun install --frozen-lockfile --ignore-scripts
bun test tests
bun run typecheck
bun run format:check
bun run pack

Build output includes the .tgz, stable and versioned installers, and SHA256SUMS. Use isolated Pi settings and an isolated destination when testing the installer. Release workflows publish the tested archive to npm latest and GitHub Releases. npm publication uses the repository's NPM_TOKEN secret.

Release security

The release workflow uses the pinned OpenAI Codex Security SDK from its official OSS repository. Publication requires these checks:

Scan errors and incomplete coverage block publication. Medium and low findings still require review. View the release checks and security policy.

The v0.3.6 scan completed in 567 seconds with complete coverage, zero deferred review, and zero findings. This result applies to that release.

Roadmap

Future iterations will support 1Password op storage, loading, and automatic discovery with explicit vault and item selection. Current credential sources are the validated session, process environment, and macOS Keychain.

Links and support

PipeLLM lists its public support contact in its service terms. Pi references: upstream repository, package documentation, slash commands, and package gallery.

Brand references: Pi press kit, PipeLLM Code, and Codex Security icon. The marks identify the host and scan tooling. This package is independently maintained. See OpenAI's security administration documentation for its service controls.

npm is a registered trademark of npm, Inc. See the npm logo and usage policy.