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

Search Method	Average Latency	Data Volume	Context Quality	Token / Message Cost
pi-cliproxy-search (Codex)	~1.9s ⚡	70–80 KB Markdown	Direct raw web crawl (unaltered)	0 Sub-LLM Tokens / 0 Messages
pi-web-search (Sub-LLM)	~6.8s	2–4 KB Summary	Secondary model summary (lossy)	Heavy input & reasoning token burn
Public Scraping (pi-web-access)	~3.5s–8s+	1–3 KB Snippets	Often blocked by anti-bot/Cloudflare	Free public, zero SLA

---

🌟 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"

---

🛠️ 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
}

Parameter	Type	Default	Description
query	string	required	The search keyword or phrase.
engine	enum	"auto"	"auto" (Codex first, Antigravity fallback), "codex", or "antigravity".
deep	boolean	false	When true, includes raw Markdown extracts from crawled pages (useful for in-depth code/API docs).
limit	integer	5	Maximum number of source citations to return (1–10).

---

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
}

Parameter	Type	Default	Description
url	string	required	The target webpage URL to fetch and convert to Markdown.
maxChars	integer	15000	Safety context cap (0 for unlimited). Truncates long pages to protect LLM context windows.

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

---

📄 License

MIT License © 2026 fancyboi999