npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@happycastle/opencode-litellm

v0.8.0

Published

OpenCode plugin for LiteLLM proxy support with auto-detection and dynamic model discovery

Vulnerabilities

Powered byPowered by Snyk
  • 0High
  • 0Medium
  • 0Low

Links

Git

Maintainers

eddy.soneddy.son

Keywords

opencodelitellmlite-llmpluginllm-proxyopenai-compatible

Readme

LiteLLM client toolkit for OpenCode and Codex

One command to connect OpenCode, Codex, and Claude Code to your LiteLLM gateway — model discovery, search tools, MCP servers, and auth included.

환경별 설치 안내

Quick start

For SSO, install the official LiteLLM CLI with uv. This uses a Python tool environment managed by uv.

uv tool install 'litellm[cli]==1.101.0'
lite --version
# OpenCode
npx @happycastle/opencode-litellm install

# Codex
npx @happycastle/codex-litellm install

# Both at once
npx @happycastle/opencode-litellm install --target both

The interactive installer asks for your gateway URL, walks you through SSO login (or environment-key auth), discovers available models/search/MCP resources, and writes the client config. Restart OpenCode or Codex after install.

One-liner (non-interactive)

LITELLM_BASE_URL=https://your-gateway.com LITELLM_PROXY_API_KEY=your-key \
  npx @happycastle/opencode-litellm install --auth env --non-interactive

# Codex only
LITELLM_BASE_URL=https://your-gateway.com LITELLM_PROXY_API_KEY=your-key \
  npx @happycastle/codex-litellm install --auth env --non-interactive

Requirements

  • Node.js ^22.22.2 || ^24.12.0 || >=26.0.0
  • OpenCode and/or Codex installed
  • Official lite CLI 1.101.0 on PATH for SSO; Python is required by that CLI
  • A reachable LiteLLM gateway

Choose the environment guide above for shell commands and configuration paths.

Usage by client

OpenCode

# 1. Install (interactive — asks gateway URL, auth, models, MCP, etc.)
npx @happycastle/opencode-litellm install

# 2. Launch OpenCode with the installed config
npx @happycastle/opencode-litellm opencode

What it configures:

  • LiteLLM plugin (git-pinned checkout) + @ai-sdk/openai provider
  • Model picker snapshot from GET /v1/models
  • Native web-search from the managed plugin, backed by LiteLLM's Responses web_search interception and the active OpenCode model
  • Named LiteLLM search tools, MCP servers, and MCP toolsets
  • Shared research skill at ~/.agents/skills/litellm-research-router/

Codex

# 1. Install (interactive — asks gateway URL, auth, codex mode, etc.)
npx @happycastle/codex-litellm install

# 2. Launch Codex with the installed config
npx @happycastle/opencode-litellm codex

Codex connection modes (--codex-mode):

| Mode | What it does | |---|---| | gateway | Gateway provider + model catalog from /v1/models | | oauth | ChatGPT OAuth pass-through provider | | both (default) | Gateway as main + OAuth as --profile codex-oauth |

Gateway catalog rows are visible in /model and advertise native search. The installer sets web_search = "live", so Codex sends the Responses web_search tool through LiteLLM. The gateway must enable LiteLLM's documented websearch_interception callback and configure a search tool.

The toolkit launcher refreshes the authorized gateway catalog before each Codex gateway launch. It reads the installed CLI's current native model fields, preserves valid model selections, and stops if discovery or native catalog loading fails. It does not fall back to a stale list after a key or permission change. The 0.8.0 release target is Codex CLI 0.154.0.

Codex desktop setup

The installer writes ~/.codex/config.toml and model catalogs for the Codex desktop app. A compatible codex CLI must be on PATH during setup: the installer reads its native catalog with codex debug models --bundled.

codex --version
npx @happycastle/codex-litellm install --codex-mode gateway

# Then restart the Codex desktop app to load the generated configuration.

Opening the app icon does not run the toolkit launch refresh. Rerun install when its gateway catalog needs updating; CLI users get automatic refresh through codex-litellm codex.

For SSO gateway mode, Codex calls lite --base-url <origin> auth print-token directly through its native auth.command and auth.args settings. Only saved manual API-key mode installs the small reader at ~/.codex/libexec/litellm-auth-token.mjs; it reads the toolkit's separate API-key file. The gateway key is not embedded in the Codex configuration. SSO requires lite to be available to the app's process as well as your shell.

In both mode, the OAuth profile is written to ~/.codex/codex-oauth.config.toml. Launch it with npx @happycastle/codex-litellm codex --profile codex-oauth. Gateway admission for OAuth and configured MCP servers is supplied only to the child process by the toolkit launcher. Opening the app icon does not supply those variables; no key is exported to the macOS login session.

Claude Code (bonus)

npx @happycastle/opencode-litellm claude

Routes Claude Code through the LiteLLM /claude-max pass-through path. Existing Anthropic OAuth stays untouched.

Authentication

SSO (default)

npx @happycastle/opencode-litellm login --base-url https://your-gateway.com
npx @happycastle/opencode-litellm whoami --base-url https://your-gateway.com
npx @happycastle/opencode-litellm logout --base-url https://your-gateway.com

The toolkit delegates login to lite --base-url <url> --api-key '' login --pkce, token resolution/renewal to lite --base-url <url> auth print-token, and logout to lite --base-url <url> logout. It does not implement a separate browser or polling flow. auth print-token emits a credential for its caller; the toolkit captures it instead of displaying it.

The empty login key skips native renewal of a previous credential before a new sign-in. Login succeeds only after native metadata records a newer finite login timestamp and the new exact-origin credential is usable; a failed or cancelled attempt does not reuse the earlier login as proof of success.

LiteLLM stores secrets in the OS keyring and metadata in ~/.litellm/token.json. When a keyring is unavailable, the official CLI uses an owner-only file instead; its login output identifies the storage used. Do not copy this file as a portable login or delete it instead of logging out. If logout finds no metadata, it reports the native credential store as unverified; run lite logout for native diagnostics and cleanup. A missing metadata file does not prove that the OS keyring is empty. See the pinned native authentication contract.

Environment key

export LITELLM_PROXY_API_KEY='your-key'
npx @happycastle/opencode-litellm install --auth env

Or enter the key interactively with --auth env. The toolkit stores this explicit API key in ~/.config/opencode-litellm/api-key.json, or $XDG_CONFIG_HOME/opencode-litellm/api-key.json when configured. The file contains base_url and key and uses mode 0600 on POSIX. The launcher and manual-key Codex reader use this file; the official CLI exclusively owns ~/.litellm/token.json and its SSO/keyring credentials. The configured environment variable takes precedence in environment-key mode.

OpenCode installation records the selected mode as the LiteLLM plugin tuple's auth option ("env" or "sso"). Direct desktop launches then read only that mode's exact-origin credential, so a saved manual key and native SSO login can coexist without switching accounts. An explicitly resolved provider key still takes precedence. Reinstall to update an older plugin tuple; standalone tuples without auth retain native SSO fallback and do not infer a manual key.

Upgrading to 0.8.0: manually entered keys saved by older toolkit versions must be entered again through install --auth env. The toolkit does not automatically infer or copy a manual key from the official SSO store. For SSO, install the official CLI and run login again.

The toolkit never uses launchctl setenv. OAuth and MCP admission keys are passed only to the launched client. Logout retains cleanup for a legacy launchd variable; already running clients must be restarted.

Common flags

--target <opencode|codex|both>     Which client(s) to configure
--base-url <url>                   LiteLLM gateway origin
--auth <sso|env>                   Authentication method
--codex-mode <gateway|oauth|both>  Codex connection mode
--search <name>                    Select search tools (repeatable)
--mcp <name>                       Select MCP servers (repeatable)
--toolset <name>                   Select MCP toolsets (repeatable)
--no-search | --no-mcp | --no-toolsets   Skip discovery
--non-interactive                  Scripted install (needs explicit values)

Post-install checks

npx @happycastle/opencode-litellm doctor --target both --json
opencode models litellm        # OpenCode model picker
# In Codex, use /model to inspect the configured gateway catalog.
# codex debug models --bundled shows the bundled reference catalog, not gateway access.

Release qualification targets Codex CLI 0.154.0 and OpenCode SDK/plugin 1.18.31. Native model inventory is inspected with Codex model/list or OpenCode's provider APIs; the source notes explain why custom LiteLLM discovery still uses the OpenCode config hook.

Discovery endpoints

| Surface | Endpoint | Result | |---|---|---| | Models | GET /v1/models | OpenCode picker + Codex JSON catalog; permitted routing groups appear when the remote gateway is LiteLLM 1.98+ | | Search tools | GET /search_tools/list | OpenCode searchTools | | MCP servers | GET /v1/mcp/server | Remote MCP entries | | MCP toolsets | GET /v1/mcp/toolset | Toolset MCP entries |

Packages

| Package | Binary | Purpose | |---|---|---| | @happycastle/opencode-litellm | opencode-litellm, codex-litellm | Core toolkit + CLI | | @happycastle/codex-litellm | codex-litellm | Thin wrapper (defaults --target codex) |

Development

git clone https://github.com/happycastle114/opencode-litellm.git
cd opencode-litellm
npm ci
npm test          # build + bun test
npm run typecheck

Advanced

LITELLM_BASE_URL=https://llm.example.com \
LITELLM_PROXY_API_KEY='your-key' \
npx @happycastle/opencode-litellm install --auth env --non-interactive

Opt-in LiteLLM Auto Router wizard. Requires uv >= 0.10.9. Affects Claude Code only; OpenCode and Codex configs are unchanged.

npx @happycastle/opencode-litellm install --auto-router configure
npx @happycastle/opencode-litellm install --auto-router dry-run

Start/stop the pinned proxy:

uv tool run --isolated --from 'litellm[proxy]==1.98.0' lite autoroute up
uv tool run --isolated --from 'litellm[proxy]==1.98.0' lite autoroute down

This isolated local pin never changes the remote LiteLLM gateway version.

The installer stages changes atomically. If a forced kill interrupts mid-write, the original file remains at <destination>.<uuid>.rollback.tmp. Rerunning install converges without clobbering recovery files.

Relevant paths (SSO storage is owned by the official CLI):

~/.litellm/token.json
~/.config/opencode-litellm/api-key.json
~/.config/opencode-litellm/launch.json
~/.codex/config.toml
~/.codex/litellm-models.json
~/.codex/codex-oauth.config.toml
~/.agents/skills/litellm-research-router/
~/.claude/settings.json

There is no uninstall command. Restore the newest backup to revert.

export TOOLKIT_SHA='<full-40-char-sha>'
npx --yes --package "github:happycastle114/opencode-litellm#${TOOLKIT_SHA}" opencode-litellm install

This runs the package's prepare lifecycle in npm's detached checkout. Leave npm lifecycle scripts enabled.

The OAuth provider uses base_url = <gateway>/codex-oauth, wire_api = "responses", requires_openai_auth = true, forced_login_method = "chatgpt", and env_http_headers = { "x-litellm-api-key" = "LITELLM_PROXY_API_KEY" }. The toolkit launcher supplies that admission key to the Codex child; Codex continues to own the ChatGPT Authorization header. Use the launcher for OAuth and authenticated MCP access rather than exporting keys globally.

oauth and both modes preflight the installed Codex bundled catalog. The 0.8.0 release target is 0.154.0; the catalog must expose gpt-5.6-sol, gpt-5.6-terra, and gpt-5.6-luna.

Request compression is disabled in OAuth configs to avoid zstd parsing issues with the pinned LiteLLM pass-through.

License

MIT — builds on yuseferi/opencode-litellm.