{"id":50216098,"url":"https://github.com/fgrehm/pi-ollama-cloud","last_synced_at":"2026-05-26T09:03:42.047Z","repository":{"id":353952921,"uuid":"1210406385","full_name":"fgrehm/pi-ollama-cloud","owner":"fgrehm","description":"Ollama Cloud plugin for Pi coding agent (API Key based)","archived":false,"fork":false,"pushed_at":"2026-05-20T02:10:53.000Z","size":325,"stargazers_count":27,"open_issues_count":4,"forks_count":7,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-05-20T05:41:45.608Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fgrehm.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","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-04-14T11:40:24.000Z","updated_at":"2026-05-19T09:41:07.000Z","dependencies_parsed_at":"2026-05-20T04:05:05.881Z","dependency_job_id":null,"html_url":"https://github.com/fgrehm/pi-ollama-cloud","commit_stats":null,"previous_names":["fgrehm/pi-ollama-cloud"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/fgrehm/pi-ollama-cloud","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fgrehm%2Fpi-ollama-cloud","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fgrehm%2Fpi-ollama-cloud/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fgrehm%2Fpi-ollama-cloud/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fgrehm%2Fpi-ollama-cloud/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fgrehm","download_url":"https://codeload.github.com/fgrehm/pi-ollama-cloud/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fgrehm%2Fpi-ollama-cloud/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33512334,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T03:12:49.672Z","status":"ssl_error","status_checked_at":"2026-05-26T03:12:47.976Z","response_time":63,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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-05-26T09:03:35.929Z","updated_at":"2026-05-26T09:03:42.038Z","avatar_url":"https://github.com/fgrehm.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pi-ollama-cloud\n\nOllama Cloud provider plugin for [Pi](https://github.com/badlogic/pi-mono) coding agent.\n\nRegisters Ollama Cloud as a model provider with dynamically fetched models, and provides `ollama_web_search` and `ollama_web_fetch` tools that use the [Ollama Cloud web search API](https://docs.ollama.com/capabilities/web-search) - no local Ollama server required.\n\n## Features\n\n- **Dynamic model discovery** - Fetches the full model list from `ollama.com/v1/models`, then fetches per-model details via `/api/show` to determine capabilities, context length, and tool support.\n- **Curated thinking levels** - Maps Pi's thinking levels to Ollama Cloud's OpenAI-compatible `reasoning_effort` values via `thinking-levels.ts`, with per-model exceptions based on API testing.\n- **Baked-in model list** - A generated model list (`models.generated.ts`) ships with the extension so models are available immediately on first launch without any network calls. Updated by running `npm run generate-models` and releasing a new version.\n- **Persistent cache** - Running `/ollama-cloud-refresh` fetches the latest models from the API and caches them to `~/.pi/agent/cache/ollama-cloud-models.json`. On subsequent launches, this disk cache takes precedence over the baked-in list.\n- **Auto-refresh on stale cache** - When the disk cache is older than 30 days, the extension uses it immediately and shows a visible refresh progress widget on the next `session_start` to pull in any new models.\n- **`/ollama-cloud-refresh` command** - Re-fetches the model list and updates the cache and provider registration live (no restart needed).\n- **`ollama_web_search` tool** - Search the web for real-time information using Ollama Cloud's `/api/web_search` endpoint. Returns titles, URLs, and content snippets.\n- **`ollama_web_fetch` tool** - Fetch and extract text content from a web page URL using Ollama Cloud's `/api/web_fetch` endpoint. Returns page title, content, and links.\n- **Zero cost tracking** - All models are registered with zero costs since Ollama Cloud uses a flat subscription model (Free, Pro, Max) rather than per-token billing. Per-request costs don't apply, so Pi's cost tracker always shows zero. See [ollama.com/pricing](https://ollama.com/pricing) for plan details.\n\n## Prerequisites\n\n- An [Ollama Cloud API key](https://ollama.com)\n\n## Installation\n\n### Option 1: from npm (recommended)\n\n```bash\npi install npm:pi-ollama-cloud\n```\n\nThis installs the latest published version from npm. Run `pi update` to get new versions.\n\n### Option 2: from git\n\n```bash\npi install git:github.com/fgrehm/pi-ollama-cloud\n```\n\nThis clones the repo to `~/.pi/agent/git/` and adds it to your settings.\n\nFor project-local install (stored in `.pi/git/`):\n\n```bash\npi install git:github.com/fgrehm/pi-ollama-cloud --local\n```\n\n### Option 3: `-e` flag (try without installing)\n\n```bash\npi -e npm:pi-ollama-cloud\n```\n\n### Option 4: Clone manually (if you want to make changes and \"try it live\")\n\nPi auto-discovers subdirectories under `~/.pi/agent/extensions/`:\n\n```bash\ngit clone git@github.com:fgrehm/pi-ollama-cloud.git ~/.pi/agent/extensions/pi-ollama-cloud\n```\n\n## Setup\n\n### 1. Get an API key\n\nSign up at [ollama.com](https://ollama.com) and generate an API key.\n\n### 2. Configure the API key\n\nThe simplest way is the `/login` command inside Pi: run `/login`, choose **Use an API key**, pick **Ollama Cloud**, and paste your key. Pi stores it in `~/.pi/agent/auth.json` and `/logout` removes it.\n\nAlternatively, set the `OLLAMA_API_KEY` environment variable:\n\n```bash\nexport OLLAMA_API_KEY=\"your-key\"\n```\n\nOr add it to `~/.pi/agent/auth.json` by hand:\n\n```json\n{\n  \"ollama-cloud\": {\n    \"type\": \"api_key\",\n    \"key\": \"your-key\"\n  }\n}\n```\n\n### 3. Configure the extension (optional)\n\nExtension settings can be set via JSON config files. Project-local settings override global/user-level settings.\n\n| Location | Scope |\n|---|---|\n| `~/.pi/agent/ollama-cloud.json` | Global / user-level (all projects) |\n| `.pi/ollama-cloud.json` | Project-local (takes precedence) |\n\n**Available settings:**\n\n| Setting | Type | Default | Description |\n|---|---|---|---|\n| `webTools` | boolean | `true` | Set to `false` to prevent `ollama_web_search` and `ollama_web_fetch` from being registered |\n\nExample `ollama-cloud.json`:\n\n```json\n{\n  \"webTools\": false\n}\n```\n\nThe `PI_OLLAMA_WEB_TOOLS` environment variable still works as an override above config files. Set it to `0`, `false`, `no`, or `off` to disable web tools regardless of config file settings.\n\n### 4. Fetch models (optional)\n\nOn first launch the plugin uses a baked-in model list shipped with the extension — no network calls needed. If you want the very latest models, run `/ollama-cloud-refresh` to fetch from the API and cache the result to disk. After that, the disk cache is used on subsequent launches.\n\nIf the disk cache is older than 30 days, the extension uses it immediately and runs a visible refresh on the next session start (progress appears in the UI widget). You can also run:\n\n```\n/ollama-cloud-refresh\n```\n\nThis fetches the full model list from the Ollama Cloud API and overwrites the local cache.\n\n### 5. Select a model\n\nUse `/model` or `Ctrl+L` to switch to an Ollama Cloud model. Models appear under the `ollama-cloud` provider.\n\n## How it works\n\nThe plugin uses two Ollama Cloud API endpoints to build the model list:\n\n1. **`GET https://ollama.com/v1/models`** - Returns a list of all available model IDs.\n2. **`POST https://ollama.com/api/show`** - For each model, fetches details including capabilities (`tools`, `thinking`, `vision`) and context length.\n\nOnly models with the `tools` capability are registered - these are the ones Pi can use for tool-calling.\n\nThe raw `/api/show` responses are cached at `~/.pi/agent/cache/ollama-cloud-models.json` with a top-level `timestamp` value. If that local cache is older than 30 days, the plugin keeps using it immediately and runs a visible refresh on `session_start` (progress appears in the UI widget). If the cache is missing, the plugin uses the baked-in model list shipped with the extension (`models.generated.ts`).\n\nModel metadata is derived from the cached data:\n\n| Field | Source |\n|---|---|\n| `reasoning` | `capabilities` includes `\"thinking\"` |\n| `thinkingLevelMap` | [`thinking-levels.ts`](thinking-levels.ts) with 4 maps (DEFAULT, GPT_OSS, QWEN3, NO_OFF) based on API testing |\n| `input` | `[\"text\", \"image\"]` if `capabilities` includes `\"vision\"`, else `[\"text\"]` |\n| `contextWindow` | `model_info.*.context_length` (falls back to 128000) |\n| `maxTokens` | Fixed at 32768 |\n| `cost` | All zeros (Ollama Cloud uses subscription plans, not per-token billing - see [pricing](https://ollama.com/pricing)) |\n\n### Thinking level mapping\n\nPi's thinking levels are mapped to Ollama Cloud's OpenAI-compatible `reasoning_effort` parameter in [`thinking-levels.ts`](thinking-levels.ts). The API accepts `none`, `low`, `medium`, `high`, and `max`. Effects of `max` over `high` vary by model and prompt difficulty - see [`docs/think-experiment.md`](docs/think-experiment.md) for details.\n\n| Map | Models | Levels exposed | Notes |\n|---|---|---|---|\n| `DEFAULT` | Most thinking models | off, low, medium, high, xhigh | `minimal` hidden (duplicate of low) |\n| `GPT_OSS` | `gpt-oss*` | low, medium, high | Can't disable thinking, no off or xhigh |\n| `QWEN3` | `qwen3*` (except `qwen3-vl*`) | off, medium | Binary-only (think/nothink), no gradation |\n| `NO_OFF` | `qwen3-vl*`, `kimi-k2-thinking`, `minimax*` | low, medium, high, xhigh | \"none\" doesn't disable thinking on these models |\n\nSee [docs/think-experiment.md](docs/think-experiment.md) for the testing methodology and results.\n\nRefresh from inside Pi:\n\n```text\n/ollama-cloud-refresh\n```\n\nThat command updates `~/.pi/agent/cache/ollama-cloud-models.json` with a new `timestamp` and re-registers the provider live, so no restart is required.\n\n## Tools\n\n| Tool | Description |\n|---|---|\n| `ollama_web_search` | Search the web via Ollama Cloud's `/api/web_search` |\n| `ollama_web_fetch` | Fetch a web page via Ollama Cloud's `/api/web_fetch` |\n\nBoth tools use the same Ollama Cloud API key configured for the provider. No local Ollama server is needed.\n\n## Commands\n\n| Command | Description |\n|---|---|\n| `/ollama-cloud-refresh` | Fetch models from the Ollama Cloud API, update cache, and re-register the provider |\n| `/ollama-webtools [on\\|off\\|enable\\|disable]` | Enable or disable the `ollama_web_search` and `ollama_web_fetch` tools. Toggles if no argument given. |\n\n## Development\n\n```bash\nnpm install          # install devDependencies (biome)\nnpm run check        # lint + format with auto-fix\nnpm run lint        # lint only (no fixes)\nnpm run format      # format only\n```\n\nThe project uses [Biome](https://biomejs.dev/) for linting and formatting (2-space indent, line width 120).\n\n## How is this different from `ollama launch pi`?\n\n[`ollama launch pi`](https://docs.ollama.com/integrations/pi) is Ollama's built-in one-command setup that configures Pi to talk to your **local Ollama server**. Both local and cloud models work - cloud models (e.g. `qwen3.5:cloud`) are proxied through your local server to `ollama.com`. This extension takes a different approach: it connects Pi **directly** to Ollama's hosted API at `ollama.com`, bypassing the local server entirely.\n\n| | `ollama launch pi` | `pi-ollama-cloud` |\n|---|---|---|\n| **Provider name** | `ollama` | `ollama-cloud` |\n| **Endpoint** | Local Ollama server (`http://localhost:11434/v1`) | Ollama Cloud (`https://ollama.com/v1`) |\n| **Local models** | ✅ Run on your machine | ❌ Not available |\n| **Cloud models** | ✅ Proxied through local server (e.g. `qwen3.5:cloud`) | ✅ Connected directly |\n| **Local Ollama required?** | Yes - must be installed and running | No - works without any local server |\n| **Authentication** | Handled by the local server (sign-in flow via `ollama`) | Ollama Cloud API key (set via `OLLAMA_API_KEY` or `auth.json`) |\n| **Model discovery** | Interactive picker with curated recommendations + pulled models | Dynamic - fetches all available cloud models with tool support from the API |\n| **Web tools** | Auto-installed (`@ollama/pi-web-search`) when cloud is enabled | ✅ Built-in: `ollama_web_search` and `ollama_web_fetch` use the [Ollama Cloud web search API](https://docs.ollama.com/capabilities/web-search) directly (same API key, no local server needed) |\n| **Setup effort** | One command: `ollama launch pi` | Install extension + API key + `/ollama-cloud-refresh` |\n| **Use when** | You're already running Ollama locally and want the default experience | You don't want to run a local server, or want a standalone cloud-only provider alongside your local setup |\n\n**You can use both at the same time.** The providers live under different names (`ollama` vs `ollama-cloud`), so you can switch between them with `/model` or `Ctrl+L`. For example, use your local `ollama` provider for low-latency work on smaller models, and `ollama-cloud` for direct access to the full catalog of cloud models without needing a local server.\n\n\u003e **Note:** The [`@ollama/pi-web-search`](https://www.npmjs.com/package/@ollama/pi-web-search) package (installed automatically by `ollama launch pi`) calls the **local** Ollama server's `/api/experimental/web_search` and `/api/experimental/web_fetch` endpoints and authenticates via `ollama signin`. This extension's `ollama_web_search` and `ollama_web_fetch` tools use the **cloud** API at `ollama.com/api/web_search` and `ollama.com/api/web_fetch` instead - same API key, no local server required. Both can coexist: the local tools register as `web_search`/`web_fetch` and these register as `ollama_web_search`/`ollama_web_fetch` to avoid name conflicts.\n\n## Releasing\n\nPublishing a new version to npm is a two-command process:\n\n```bash\n# 1. Bump version and create a git tag in one step\nnpm version minor   # or patch, or major\n# 2. Push the tag to trigger the GitHub Actions publish workflow\ngit push --tags\n```\n\nThe tag version must match the version in `package.json` - `npm version` handles this automatically. The workflow at `.github/workflows/publish.yml` verifies the match before publishing to npm.\n\nThe workflow uses npm's [trusted publishing](https://docs.npmjs.com/trusted-publishers/) (OIDC) - no tokens stored as secrets. To set it up:\n\n1. Go to [npmjs.com](https://www.npmjs.com) → your avatar → **Packages** → `pi-ollama-cloud` → **Settings** → **Trusted publishing**\n2. Click **GitHub Actions** and enter:\n   - **Workflow filename**: `publish.yml`\n3. Save\n\nEach publish also gets automatic [provenance attestation](https://docs.npmjs.com/generating-provenance-statements).\n\n## Notes\n\n- The fetch timeout is 10 seconds per request. On slow connections, some model detail fetches may time out - the plugin reports how many succeeded vs failed.\n- `deepseek-v4` occasionally emits raw `\u003c｜DSML｜tool_calls｜\u003e` markup as plain text instead of structured tool calls, then stops. This is DeepSeek's native tool-call format leaking through Ollama Cloud's OpenAI-compatible endpoint, so it looks like an upstream Ollama issue rather than something this extension can fix. If you hit it, retry or switch models.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffgrehm%2Fpi-ollama-cloud","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffgrehm%2Fpi-ollama-cloud","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffgrehm%2Fpi-ollama-cloud/lists"}