@odinlayer/pi-provider-litellm

LiteLLM proxy provider extension for Pi.

Discovers models from a self-hosted LiteLLM proxy and registers them under the litellm provider. Supports /login litellm, /litellm:models-refresh, /litellm:skills, LiteLLM MCP tools, LiteLLM Skill Hub prompt injection, and Google ADC token auth. Both Chat Completions (mode: "chat") and Responses API (mode: "responses") models are discovered — response-mode models (e.g. gpt-5.3-codex-openai) are tagged with a per-model api: "openai-responses" override so Pi routes them through the Responses API instead of Chat Completions. Tries /model/info first (admin endpoint with rich metadata), falls back to /v1/models (OpenAI-compatible) on 401/403/404, then tries /health plus per-endpoint /model/info for older LiteLLM proxies.

Install

pi install npm:@odinlayer/pi-provider-litellm

Pi fetches the package from npm and registers it. Add -l to install into project settings (.pi/settings.json) instead of global.

To try it without installing (one-off, current run only):

pi -e npm:@odinlayer/pi-provider-litellm

git clone <your-repo-url> ~/.pi/agent/extensions/pi-provider-litellm
cd ~/.pi/agent/extensions/pi-provider-litellm
npm ci
npm run clean && npm run build

Configure

Option A — interactive login

Inside pi:

/login litellm

You can also run /login, select Use a subscription, then select LiteLLM.

You'll be prompted for the base URL and API key. Credentials are persisted to ~/.pi/agent/auth.json.

Enterprise SSO login

If your LiteLLM proxy requires SSO/OAuth authentication (enterprise deployments), you can authenticate via a browser SSO flow and optionally pair the resulting JWT with a stable virtual key:

1. Run /login litellm inside pi
2. Enter the proxy URL
3. At the login method prompt, enter 2 for SSO / Enterprise JWT
4. Your default browser opens the LiteLLM SSO login URL (e.g. https://litellm.your-domain.com/sso/key/generate) automatically — the URL is also displayed in case it can't be opened. Authenticate via SSO
5. Copy your token from the LiteLLM UI and paste it at the prompt (copying a full Bearer ... header value is fine — the prefix is stripped automatically)
6. When prompted to generate a virtual key, press Enter to accept (recommended) or enter n to use the JWT directly

When you generate a virtual key, the resulting sk-... key is stored as your credential and used for all API requests. If the proxy's key policy attaches an expiry to the generated key, Pi will prompt you to re-authenticate when it nears expiry; otherwise the key is treated as permanent until revoked in LiteLLM.

When using a JWT directly, the extension reads its exp claim and Pi will prompt you to re-authenticate when the token nears expiry. Run /login litellm again to refresh.

Option B — environment variables

export LITELLM_BASE_URL="https://litellm.your-domain.com"
export LITELLM_API_KEY="sk-..."

Stored pi credentials for litellm take precedence over LITELLM_API_KEY; the environment key is used when no saved credential exists. LITELLM_BASE_URL is used when no saved login base URL exists.

Use

/model

Optional environment variables

| Variable | Default | Effect | |---|---|---| | LITELLM_API_KEY_HELPER | unset | Command that prints a fresh LiteLLM bearer token. Takes precedence over LITELLM_API_KEY. Registered as a !command provider key; Pi re-runs it on every request (the per-request auth path is uncached), so rotating/short-lived tokens stay fresh. | | LITELLM_GCLOUD_TOKEN_AUTH | unset | If set to a non-empty value other than 0, use Google Application Default Credentials as the LiteLLM bearer token source. This takes precedence over LITELLM_API_KEY_HELPER and LITELLM_API_KEY when no stored /login litellm credential exists. | | GOOGLE_APPLICATION_CREDENTIALS | Google default ADC path | Optional path to an ADC JSON file used by LITELLM_GCLOUD_TOKEN_AUTH. If unset, the extension checks the default gcloud ADC locations. | | LITELLM_OFFLINE | unset | If 1, skip discovery on this start; use cache only | | LITELLM_DISCOVERY_TIMEOUT_MS | 5000 | Discovery fetch timeout in ms; 0 to skip discovery |

LITELLM_DISCOVERY_TIMEOUT_MS=0 only disables startup and refresh model discovery. It does not replace the base URL or API key settings required to send requests when you are not using /login litellm.

Google ADC token auth

When your LiteLLM proxy accepts Google OAuth access tokens, you can let the extension refresh tokens from Application Default Credentials:

gcloud auth application-default login
export LITELLM_BASE_URL="https://litellm.your-domain.com"
export LITELLM_GCLOUD_TOKEN_AUTH=1

Only authorized_user ADC files are supported. Service account JSON files are rejected with a warning. Tokens are cached in memory for 50 minutes and the registered provider key is a Pi !command, so request-time auth resolves a fresh token when Pi sends model requests.

LiteLLM MCP tools

If your LiteLLM proxy exposes MCP REST endpoints, this extension discovers tools from:

• GET /mcp-rest/tools/list
• POST /mcp-rest/tools/call

Each discovered tool is registered as a native Pi tool named mcp_<server>_<tool>, with simple JSON Schema parameters mapped to Pi/TypeBox parameters. Complex schemas fall back to a single args object. MCP discovery runs after successful live model discovery, /login litellm, or /litellm:models-refresh; it does not force network or helper-token access when a fresh model cache is used.

By default, MCP tools render as compact status lines in Pi's interactive tool output:

• MCP (10s · mcp_<server>_<tool>) · running
• MCP (12s · mcp_<server>_<tool>) · done
• MCP (12s · mcp_<server>_<tool>) · error

Line color is soft blue while running/done. On failures, only the error status token is colored red.

Use /litellm:mcp-reveal or Pi's built-in Ctrl+O tool toggle to expand or collapse tool output for the current session.

MCP tools are registered with executionMode: "parallel". Pi executes tool calls in parallel when the assistant emits multiple tool calls in the same turn; if any tool in that batch is marked executionMode: "sequential", the entire batch runs sequentially.

MCP tool calls automatically retry once for retryable failures (HTTP 408/425/429/500/502/503/504 and retryable network/timeout errors). Non-retryable errors (for example auth failures) are returned immediately.

Known UI limitation in current Pi core: self-rendered tool rows include a leading spacer line. This extension cannot remove that spacing without a Pi core patch.

LiteLLM Skill Hub

Skills are discovered from LiteLLM Skill Hub marketplace endpoint (not Anthropic /v1/skills):

• GET /claude-code/marketplace.json (public marketplace catalog)

Enabled skills are fetched before each agent turn and appended to the system prompt as a litellm_skills section (name + description metadata).

The extension also registers Pi tools for basic Skill Hub management:

• litellm_skill_list
• litellm_skill_create (register via Skill Hub source JSON)
• litellm_skill_delete

Mocked LiteLLM smoke workflow

The LiteLLM Smoke GitHub Actions workflow starts VidaiMock and a real LiteLLM proxy on the runner. LiteLLM exposes OpenAI-compatible and Anthropic routes whose upstreams are served by VidaiMock, then this extension's smoke runner discovers those models through LiteLLM and sends /v1/chat/completions requests through the proxy.

This keeps the LiteLLM integration path under test but does not call real LLM APIs. No provider API keys or GitHub Models permission are required. The workflow also runs a non-interactive Pi CLI smoke with --list-models and -p so extension loading, model discovery, and a real completion path are covered without opening the TUI.

Development

This package requires Node.js >=22.19.0. CI currently uses Node 24.16.0.

npm ci
npm run check
npm run clean && npm run build

npm run check runs Biome, type checking, and the Vitest suite. Runtime changes must be built before local Pi smoke checks because the extension entrypoint is ./dist/index.js.

Before changing package contents or dependency policy, also run:

npm run supply-chain:guard
npm pack --dry-run

The published npm package should contain only dist, README.md, and LICENSE.

Release

Releases are driven by semver tags named v*.*.*. The GitHub release workflow installs from the lockfile, runs the checks, builds dist, verifies the package tarball, publishes to npm with provenance, and creates a GitHub release.

Before tagging a release, keep package.json and package-lock.json versions in sync and verify the dry-run package contents.

Slash commands

• /litellm:models-refresh — force re-fetch the model list, ignoring cache
• /litellm:skills — open interactive skills manager (tab to switch Available/Installed, i to install, u to uninstall)
• /litellm:mcp-reveal — toggle LiteLLM MCP tool output expansion for the current session

Cache

The model list is cached at ~/.pi/agent/litellm-models.json with a keyed fingerprint of the base URL + API key. Changing either invalidates the cache automatically.

If the cache is older than 24 hours, the extension refreshes it in the background on session start (non-blocking). Failures are silent — the cached models remain in use. Run /litellm:models-refresh to force an immediate refresh.

Troubleshooting

| Symptom | Likely cause | |---|---| | "no credentials" warning at startup | Env vars not set and no OAuth credential — run /login litellm | | "discovered no models" | Proxy returned an empty list — check pi's startup log and verify /model/info, /v1/models, or /health responds | | /model/info returning 401/403/404 | Expected behavior with virtual keys — extension falls back to /v1/models | | Discovery times out | Increase LITELLM_DISCOVERY_TIMEOUT_MS or set LITELLM_OFFLINE=1 to fall back on cached models | | 401 Token expired | Set LITELLM_API_KEY_HELPER. | | No models with gcloud auth | Verify gcloud auth application-default login has been run or set GOOGLE_APPLICATION_CREDENTIALS to an authorized_user ADC file | | Enterprise SSO login shows "virtual key generation failed" | The LiteLLM instance may lack a database (/key/generate requires one), your user account may lack key-generation permission, or the request timed out; the JWT is used directly as a fallback | | Enterprise SSO token prompt fails with "SSO token is required" | The token field was left empty — paste the token copied from the LiteLLM UI | | MCP tools not showing | Verify the proxy exposes /mcp-rest/tools/list and run /litellm:models-refresh after fixing the proxy | | Skills not affecting prompts | Verify /claude-code/marketplace.json returns enabled plugins and that the proxy is reachable from Pi |

License

MIT — see LICENSE.