pi-cliproxy-search

Blazing-fast, multi-engine web search extension for Pi Coding Agent powered by your local CLIProxyAPI gateway.

⚡ Overview

pi-cliproxy-search bridges your Pi Coding Agent directly to local AI gateway endpoints, providing instant, high-relevance web search and documentation retrieval without third-party API keys or rate-limits.

Instead of relying on fragile public search scrapers or slow secondary sub-LLM summarizers, this package routes queries straight through your authenticated OpenAI Codex and Google Antigravity accounts via CLIProxyAPI.

🚀 Benchmarks at a Glance

🌟 Key Features

• ⚡ ~2s Pure Raw Search (Codex Alpha Search): Uses OpenAI's backend cluster crawler (/v1/alpha/search) to retrieve 30–40 authoritative sources and clean Markdown extracts in under 2 seconds.
• 🛡️ Dual-Engine Automatic Fallback (Google Antigravity): Seamlessly falls back to Antigravity Google Search Grounding with verified source citations if Codex credentials are busy or rate-limited.
• ⏳ Smart Rate-Limit & Cooldown Window: When Codex returns HTTP 429/quota limits, the extension parses retry-after and nested reset_seconds, persists recovery timestamps (~/.pi/agent/cliproxy-cooldown.json), and automatically routes all subsequent queries directly to Antigravity until the cooldown expires without wasted network roundtrips.
• 🧠 100% Model-Agnostic: Works with any active Pi conversation model — whether you are coding with Claude 3.7 Sonnet, DeepSeek V3, Qwen 2.5, or local Ollama models.
• 🔌 Zero-Configuration Auto-Discovery: Automatically parses your local ~/.cli-proxy-api/config.yaml to resolve loopback host, port (8317), and authentication tokens.
• 🛡️ Context Window & Token Protection: Extracts clean structured titles, URLs, and concise snippets by default (~3 KB). Full Markdown text is strictly opt-in via deep: true.
• 🩺 Built-in Health Command: Run /cliproxy-status right inside Pi to verify live gateway and engine connectivity.

📐 Architecture & Routing Logic

┌─────────────────────────────────────────────────────────────┐
│                    Pi Coding Agent Session                  │
│       (Claude 3.7 / DeepSeek V3 / Qwen / Any Model)         │
└──────────────────────────────┬──────────────────────────────┘
                               │ Calls cliproxy_search / web_search
                               ▼
┌─────────────────────────────────────────────────────────────┐
│                  pi-cliproxy-search Router                  │
│               (Zero-config local discovery)                 │
└──────────────┬───────────────────────────────┬──────────────┘
               │ Primary (~1.9s)               │ Fallback (on 429/error)
               ▼                               ▼
  ┌─────────────────────────┐     ┌─────────────────────────┐
  │   Codex Alpha Search    │     │  Google Antigravity     │
  │    (/v1/alpha/search)   │     │    (/v1/messages)       │
  │   38 Sources Markdown   │     │  Google Search Ground   │
  └─────────────────────────┘     └─────────────────────────┘
               │                               │
               └───────────────┬───────────────┘
                               ▼
               Clean Structured Markdown Output
               (with optional deep page extracts)

📦 Installation

Option 1: Direct Git Install (Recommended)

Run directly from your terminal:

pi install git:github.com/fancyboi999/pi-cliproxy-search

Option 2: Project-Local Installation

To install only for the current project:

pi install --local git:github.com/fancyboi999/pi-cliproxy-search

Option 3: Local Development Mode

Clone the repository and install from the directory:

git clone https://github.com/fancyboi999/pi-cliproxy-search.git
cd pi-cliproxy-search
pi install .

To test without installation:

pi -e ./pi-cliproxy-search/extensions/index.ts

⚙️ Configuration & Remote Gateways

pi-cliproxy-search supports both local and remote CLIProxyAPI instances (e.g. deployed on a remote VPS, homelab NAS, or Tailscale private network) through a 4-tier cascading resolution strategy:

1. Dedicated Config File (~/.pi/agent/cliproxy-search.json)  <-- Highest precedence
2. Environment Variables (CLIPROXY_ENDPOINT / CLIPROXY_API_KEY)
3. Local Auto-Detection (~/.cli-proxy-api/config.yaml)        <-- Zero-config for local users
4. Default Loopback (http://127.0.0.1:8317)                  <-- Safe fallback

1. Zero-Config for Local Users

If you run CLIProxyAPI locally on the same machine, no configuration is required. The extension automatically inspects ~/.cli-proxy-api/config.yaml to extract the loopback port and local API key.

2. For Remote Instances (VPS / NAS / Tailnet)

Method A: Interactive Command inside Pi

Run the built-in command directly in your Pi chat:

/cliproxy-config http://192.168.1.100:8317 your-secret-key

This automatically writes to ~/.pi/agent/cliproxy-search.json with secure 0600 permissions and hot-reloads instantly.

To view current active configuration and source:

/cliproxy-config

Method B: JSON Config File

Create or edit ~/.pi/agent/cliproxy-search.json:

{
  "endpoint": "https://my-proxy.tailnet-xyz.ts.net",
  "apiKey": "your-secret-token"
}

Method C: Environment Variables (CI / Docker)

export CLIPROXY_ENDPOINT="http://remote-server:8317"
export CLIPROXY_API_KEY="your-secret-token"
export CLIPROXY_ANTIGRAVITY_MODEL="gemini-3.8-flash-high" # Optional model override (defaults to auto-detected active model)

🛠️ Tool Usage & Parameters

The extension exposes two complementary tools for your coding agent:

1. cliproxy_search (or web_search): High-speed query search with multi-engine fallback.
2. cliproxy_fetch (or web_fetch): High-fidelity web page reader converting raw HTML/SPAs directly into clean Markdown via Jina Reader.

1. cliproxy_search (Search Engine)

{
  "query": "Go 1.27 release notes and runtime changes",
  "engine": "auto",
  "limit": 5,
  "deep": false
}

2. cliproxy_fetch (Clean Page Reader)

When you need to inspect an exact article, GitHub documentation, or blog post from a specific URL:

{
  "url": "https://go.dev/doc/devel/release",
  "maxChars": 15000
}

The reader gets up to 12 seconds (60% of shorter budgets). Direct fallback gets up to 8 seconds, limited by the remaining total budget. For example, timeoutMs: 8000 gives the reader up to 4.8 seconds and leaves at least 3.2 seconds for fallback, excluding scheduling overhead. Caller cancellation stops the operation without starting fallback. If both routes fail, the error includes each route's failure; an origin HTTP 404 remains an error.

Independent fetches in a codemode batch should use Promise.allSettled or local error handling so one unavailable page does not interrupt unrelated work.

Why cliproxy_fetch over curl?

• Clean Markdown Extraction: Powered by Jina Reader (r.jina.ai) — eliminates <script>, <style>, navigation bars, cookie banners, and ads.
• Bypasses Cloudflare & SPAs: Successfully fetches dynamic Single Page Applications (React/Vue/Next.js) that return empty divs under curl.
• Zero LLM Hallucination / Bias: Direct algorithmic DOM-to-Markdown conversion — not a secondary LLM summary. Function signatures, type definitions, and code blocks remain 100% exact.
• Resilient Direct Fallback: Automatically falls back to native HTTP fetch + text stripper if external reader services are unavailable.

🩺 Diagnostics Command

In any Pi chat session, type:

/cliproxy-status

The extension performs live probes against your local CLIProxyAPI instance and reports:

• Gateway loopback reachability
• Codex Alpha Search status (READY / COOLING DOWN (Until xx:xx:xx, ~xxm left) / OFFLINE)
• Google Antigravity Grounding status (READY / OFFLINE)
• Active routing strategy

To manually reset a cooldown cache at any time:

/cliproxy-status reset

🤝 Contributing

Contributions, bug reports, and pull requests are warmly welcome!

• To report a bug or suggest a feature: Open an Issue
• Pull requests should pass test suites: bun test or node --test

Publishing

.github/workflows/publish.yml publishes through npm Trusted Publishing using GitHub Actions OIDC. It uses GitHub-hosted runners, Node.js 24, and npm 11. No NPM_TOKEN secret is required.

For a new release, dispatch the workflow on main:

gh workflow run publish.yml --ref main -f release_type=patch

The workflow installs dependencies and type-checks before committing the version bump, pushing its tag, and publishing to npm. Use minor or major when appropriate. If a manual dispatch fails after pushing the version tag, confirm that version is not yet on npm and publish a GitHub Release for the existing tag to retry without another version bump. Failed release-triggered runs can use Re-run failed jobs.

Publishing a GitHub Release also triggers the workflow, without a version bump. Its tag must match v<package.json version> and contain this workflow. Do not publish a GitHub Release for a version already published to npm.

Maintainers must configure the package's npm Trusted Publisher for fancyboi999/pi-cliproxy-search, workflow filename publish.yml, with Allow npm publish enabled. No GitHub environment is configured. After the first successful OIDC publish, disallow token-based publishing and revoke unused automation tokens. A newly configured publisher must complete its first publish within two days.

📄 License

MIT License © 2026 fancyboi999