{"id":51468540,"url":"https://github.com/cfal/pi-models-dev","last_synced_at":"2026-07-06T14:01:36.473Z","repository":{"id":369509631,"uuid":"1250241678","full_name":"cfal/pi-models-dev","owner":"cfal","description":null,"archived":false,"fork":false,"pushed_at":"2026-07-05T16:27:24.000Z","size":44,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-05T18:10:55.315Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cfal.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-26T12:46:39.000Z","updated_at":"2026-07-05T16:27:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/cfal/pi-models-dev","commit_stats":null,"previous_names":["cfal/pi-models-dev"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/cfal/pi-models-dev","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cfal%2Fpi-models-dev","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cfal%2Fpi-models-dev/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cfal%2Fpi-models-dev/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cfal%2Fpi-models-dev/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cfal","download_url":"https://codeload.github.com/cfal/pi-models-dev/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cfal%2Fpi-models-dev/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35193679,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-06T02:00:07.184Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-07-06T14:01:34.938Z","updated_at":"2026-07-06T14:01:36.302Z","avatar_url":"https://github.com/cfal.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pi-models-dev\n\nRuntime [models.dev](https://models.dev) provider discovery for Pi.\n\nThis Pi package fetches `https://models.dev/api.json` at startup and registers user-enabled OpenAI-compatible providers, without waiting for Pi to ship a newer generated model snapshot.\n\nBy default it does not replace Pi built-in providers. Built-ins are replaced only when explicitly named in `PI_MODELS_DEV_OVERRIDE_PROVIDERS`.\nUse `PI_MODELS_DEV_OVERRIDE_PROVIDERS=all` to select every supported models.dev provider.\n\n## What Is models.dev?\n\n`models.dev` is the public provider and model catalog used by OpenCode. It contains provider IDs, model IDs, API endpoints, environment variable names, context windows, costs, modality support, and model status.\n\nThis extension lets Pi consume that catalog at runtime. To use an OpenCode provider, look up its provider ID on models.dev and use the same ID in Pi config. For example, the OpenCode/models.dev provider ID for GitHub Models is `github-models`, so Pi model IDs become `github-models/openai/gpt-4.1`.\n\nThe current extension registers models.dev providers that use an OpenAI-compatible or OpenRouter-compatible transport. Providers that require a different native SDK are skipped until support is added.\n\n## Install\n\nFrom GitHub:\n\n```bash\npi install https://github.com/cfal/pi-models-dev\n```\n\nEquivalent git source:\n\n```bash\npi install git:github.com/cfal/pi-models-dev\n```\n\nProject-local install:\n\n```bash\npi install -l https://github.com/cfal/pi-models-dev\n```\n\nTemporary run:\n\n```bash\npi -e https://github.com/cfal/pi-models-dev --list-models\n```\n\nLocal development checkout:\n\n```bash\ngit clone https://github.com/cfal/pi-models-dev.git\ncd pi-models-dev\nbun install\npi install \"$PWD\"\npi -e \"$PWD\" --list-models\n```\n\n## Quick Start\n\nEnable GitHub Models in `~/.pi/agent/auth.json`:\n\n```json\n{\n  \"github-models\": {\n    \"type\": \"api_key\",\n    \"key\": \"GITHUB_TOKEN\"\n  }\n}\n```\n\nSet the API key and verify:\n\n```bash\nexport GITHUB_TOKEN=...\npi --list-models\n```\n\nExpected output includes models such as:\n\n```text\ngithub-models  openai/gpt-4.1\n```\n\n## Provider Enablement\n\nA provider is registered only when the extension sees user intent:\n\n| Source | Effect |\n| --- | --- |\n| `auth.json` API key entry | Enables that models.dev provider. |\n| `models.json.providers[id]` override entry | Enables that provider and applies endpoint/request/model overrides. |\n| `PI_MODELS_DEV_OVERRIDE_PROVIDERS` | Allows selected Pi built-ins to be replaced. |\n\nEnvironment variables alone do not enable providers. They only satisfy auth after `auth.json`, `models.json`, or the override env var selects the provider. The special override value `all` selects every supported models.dev provider.\n\nGeneric OpenCode provider template:\n\n```json\n{\n  \"\u003cmodels.dev-provider-id\u003e\": {\n    \"type\": \"api_key\",\n    \"key\": \"\u003cENV_VAR_FROM_MODELS_DEV\u003e\"\n  }\n}\n```\n\n```bash\nexport \u003cENV_VAR_FROM_MODELS_DEV\u003e=...\npi --list-models\n```\n\nUse the provider ID exactly as shown on models.dev. After registration, select models in Pi as `\u003cprovider-id\u003e/\u003cmodel-id\u003e`.\n\nException: models.dev names Fireworks `fireworks-ai`, but Pi uses `fireworks`. This extension registers models.dev Fireworks models under Pi's `fireworks` provider ID, so use `fireworks` in `auth.json`, `models.json`, and `PI_MODELS_DEV_OVERRIDE_PROVIDERS`.\n\n## API Keys\n\nPreferred shape for `~/.pi/agent/auth.json`:\n\n```json\n{\n  \"github-models\": {\n    \"type\": \"api_key\",\n    \"key\": \"GITHUB_TOKEN\"\n  }\n}\n```\n\nThen set:\n\n```bash\nexport GITHUB_TOKEN=...\n```\n\n`key` should usually be an environment variable name rather than a literal secret.\n\nYou can also put the API key reference in `models.json` when you want all provider config in one file:\n\n```json\n{\n  \"providers\": {\n    \"github-models\": {\n      \"baseUrl\": \"https://models.github.ai/inference\",\n      \"apiKey\": \"GITHUB_TOKEN\"\n    }\n  }\n}\n```\n\n## Custom Base URL\n\nUse `~/.pi/agent/models.json` to override a provider endpoint while still using models.dev model metadata:\n\n```json\n{\n  \"providers\": {\n    \"\u003cmodels.dev-provider-id\u003e\": {\n      \"baseUrl\": \"https://your-openai-compatible-endpoint.example/v1\"\n    }\n  }\n}\n```\n\nMost providers, including GitHub Models, do not need this because models.dev already includes the default endpoint. Use `baseUrl` for workspace-specific gateways, proxies, or regional endpoints.\n\nIf the endpoint needs additional request headers:\n\n```json\n{\n  \"providers\": {\n    \"\u003cmodels.dev-provider-id\u003e\": {\n      \"baseUrl\": \"https://your-openai-compatible-endpoint.example/v1\",\n      \"headers\": {\n        \"X-Custom-Header\": \"value\"\n      }\n    }\n  }\n}\n```\n\nIf the provider expects the resolved key in an explicit bearer header:\n\n```json\n{\n  \"providers\": {\n    \"\u003cmodels.dev-provider-id\u003e\": {\n      \"baseUrl\": \"https://your-openai-compatible-endpoint.example/v1\",\n      \"authHeader\": true\n    }\n  }\n}\n```\n\n## Model Overrides\n\nProvider-level compatibility overrides are merged onto every generated model:\n\n```json\n{\n  \"providers\": {\n    \"github-models\": {\n      \"compat\": {\n        \"supportsStrictMode\": false\n      }\n    }\n  }\n}\n```\n\nPer-model overrides use Pi's `modelOverrides` shape:\n\n```json\n{\n  \"providers\": {\n    \"github-models\": {\n      \"modelOverrides\": {\n        \"openai/gpt-4.1\": {\n          \"name\": \"GPT-4.1 via GitHub Models\",\n          \"reasoning\": true,\n          \"headers\": {\n            \"X-Model-Route\": \"default\"\n          }\n        }\n      }\n    }\n  }\n}\n```\n\nIf `models.json.providers[id].models` exists, this extension skips that provider by default so Pi owns the custom model list.\n\n## Built-In Provider Overrides\n\nPi built-ins carry curated compatibility flags and provider behavior, so the extension skips them by default.\n\nTo intentionally replace specific built-ins with models.dev entries:\n\n```bash\nPI_MODELS_DEV_OVERRIDE_PROVIDERS=openrouter,deepseek pi --list-models\n```\n\nTo select every supported models.dev provider:\n\n```bash\nPI_MODELS_DEV_OVERRIDE_PROVIDERS=all pi --list-models\n```\n\nUse overrides sparingly. They can change model lists and provider quirks for existing Pi providers. The `all` wildcard is broader than built-in replacement: it also selects non-built-in models.dev providers, which can then register when their API key environment variables are present.\n\nFor Fireworks, use Pi's built-in provider ID:\n\n```bash\nPI_MODELS_DEV_OVERRIDE_PROVIDERS=fireworks pi --list-models\n```\n\n## Runtime Options\n\n| Variable | Default | Purpose |\n| --- | --- | --- |\n| `PI_MODELS_DEV_ENABLED` | `1` | Disable with `0`. |\n| `PI_MODELS_DEV_SOURCE_URL` | `https://models.dev/api.json` | Catalog URL. |\n| `PI_MODELS_DEV_OVERRIDE_PROVIDERS` | empty | Comma-separated provider IDs to select, or `all` for every supported provider. |\n| `PI_MODELS_DEV_INCLUDE_ALPHA` | `0` | Include alpha models. |\n| `PI_MODELS_DEV_INCLUDE_BETA` | `1` | Include beta models. |\n| `PI_MODELS_DEV_INCLUDE_DEPRECATED` | `0` | Include deprecated models. |\n| `PI_MODELS_DEV_MAX_MODELS_PER_PROVIDER` | empty | Optional per-provider model cap. |\n| `PI_MODELS_DEV_CACHE_TTL_MS` | `86400000` | Catalog cache TTL. |\n| `PI_MODELS_DEV_FETCH_TIMEOUT_MS` | `3000` | Catalog fetch timeout. |\n| `PI_MODELS_DEV_CACHE_DIR` | Pi agent cache dir | Override cache directory. |\n| `PI_MODELS_DEV_OFFLINE` | `0` | Use cache only. |\n| `PI_MODELS_DEV_DEBUG` | `0` | Print startup diagnostics. |\n\n## Cache Behavior\n\nThe extension fetches models.dev during Pi startup. It caches the catalog under Pi's agent cache directory and reuses fresh cache for 24 hours by default.\n\nIf the network fetch fails, stale cache is used when available. If no cache exists, startup continues and the extension registers nothing.\n\nPi's `PI_OFFLINE` setting does not change this extension's cache policy. Use `PI_MODELS_DEV_OFFLINE=1` when models.dev discovery should be cache-only.\n\nForce cache-only mode:\n\n```bash\nPI_MODELS_DEV_OFFLINE=1 pi --list-models\n```\n\nPrint registration diagnostics:\n\n```bash\nPI_MODELS_DEV_DEBUG=1 pi --list-models\n```\n\n## Troubleshooting\n\nNo provider appears:\n\n- Check that `auth.json` or `models.json` contains the provider ID exactly as models.dev uses it, for example `github-models`.\n- Check that the API key environment variable is set in the same shell or service process that starts Pi or Garcon.\n- Run `PI_MODELS_DEV_DEBUG=1 pi --list-models`.\n\nCustom endpoint is ignored:\n\n- Put `baseUrl` under `~/.pi/agent/models.json` at `providers.\u003cproviderId\u003e.baseUrl`.\n- Restart Pi or Garcon after editing config.\n\nGarcon does not show new models:\n\n- Restart the Garcon server, or wait for its Pi model cache to expire.\n- Verify first with `pi --list-models`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcfal%2Fpi-models-dev","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcfal%2Fpi-models-dev","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcfal%2Fpi-models-dev/lists"}