From b540106287abd111352d382c5be071688fbd36a7 Mon Sep 17 00:00:00 2001 From: Finessse Date: Thu, 18 Dec 2025 01:58:36 +0700 Subject: [PATCH] docs: rebrand to ProxyPilot with fork attribution --- NOTICE.md | 6 ++ README.md | 38 ++++++------ docs/desktop-ui-spec.md | 16 ++--- docs/proxypilot.md | 132 +++++++--------------------------------- 4 files changed, 55 insertions(+), 137 deletions(-) create mode 100644 NOTICE.md diff --git a/NOTICE.md b/NOTICE.md new file mode 100644 index 00000000..e2977e21 --- /dev/null +++ b/NOTICE.md @@ -0,0 +1,6 @@ +ProxyPilot + +ProxyPilot is a fork and rebrand of the CLIProxyAPI project (the underlying proxy engine). + +This repository is distributed under the MIT License; see LICENSE. + diff --git a/README.md b/README.md index 97894cdf..ce4d9687 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,12 @@ -# CLI Proxy API +# ProxyPilot (CLIProxyAPI fork) English | [中文](README_CN.md) -A proxy server that provides OpenAI/Gemini/Claude/Codex compatible API interfaces for CLI. +ProxyPilot is a desktop-friendly wrapper around the `CLIProxyAPI` proxy engine (this repo), focused on running and managing a local proxy with a tray app + installer. -It now also supports OpenAI Codex (GPT models) and Claude Code via OAuth. +ProxyPilot is forked from the original **CLIProxyAPI** project and rebranded; the underlying engine remains compatible with OpenAI/Gemini/Claude/Codex-style clients and SDKs. -So you can use local or multi-account CLI access with OpenAI(include Responses)/Gemini/Claude-compatible clients and SDKs. +Windows app packaging: `docs/proxypilot.md` ## Sponsor @@ -16,7 +16,7 @@ This project is sponsored by Z.ai, supporting us with their GLM CODING PLAN. GLM CODING PLAN is a subscription service designed for AI coding, starting at just $3/month. It provides access to their flagship GLM-4.6 model across 10+ popular AI coding tools (Claude Code, Cline, Roo Code, etc.), offering developers top-tier, fast, and stable coding experiences. -Get 10% OFF GLM CODING PLAN:https://z.ai/subscribe?ic=8JVLJQFSKB +Get 10% OFF GLM CODING PLAN: https://z.ai/subscribe?ic=8JVLJQFSKB ## Overview @@ -40,28 +40,27 @@ Get 10% OFF GLM CODING PLAN:https://z.ai/subscribe?ic=8JVLJQFSKB - OpenAI-compatible upstream providers via config (e.g., OpenRouter) - Reusable Go SDK for embedding the proxy (see `docs/sdk-usage.md`) -## Getting Started +## Getting Started (Engine) -CLIProxyAPI Guides: [https://help.router-for.me/](https://help.router-for.me/) +Upstream-style docs for the engine live here: + +- CLIProxyAPI Guides: https://help.router-for.me/ +- Management API: https://help.router-for.me/management/api ## Cursor IDE -- Integration guide: [docs/cursor-ide.md](docs/cursor-ide.md) +- Integration guide: `docs/cursor-ide.md` ## Compatibility -- Quick matrix: [docs/compat-matrix.md](docs/compat-matrix.md) - -## Management API - -see [MANAGEMENT_API.md](https://help.router-for.me/management/api) +- Quick matrix: `docs/compat-matrix.md` ## SDK Docs -- Usage: [docs/sdk-usage.md](docs/sdk-usage.md) -- Advanced (executors & translators): [docs/sdk-advanced.md](docs/sdk-advanced.md) -- Access: [docs/sdk-access.md](docs/sdk-access.md) -- Watcher: [docs/sdk-watcher.md](docs/sdk-watcher.md) +- Usage: `docs/sdk-usage.md` +- Advanced (executors & translators): `docs/sdk-advanced.md` +- Access: `docs/sdk-access.md` +- Watcher: `docs/sdk-watcher.md` - Custom Provider Example: `examples/custom-provider` ## Contributing @@ -94,9 +93,10 @@ CLI wrapper for instant switching between multiple Claude accounts and alternati Native macOS GUI for managing CLIProxyAPI: configure providers, model mappings, and endpoints via OAuth - no API keys needed. -> [!NOTE] +> [!NOTE] > If you developed a project based on CLIProxyAPI, please open a PR to add it to this list. ## License -This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. +This project is licensed under the MIT License - see `LICENSE`. + diff --git a/docs/desktop-ui-spec.md b/docs/desktop-ui-spec.md index d03c8f15..5a93ec46 100644 --- a/docs/desktop-ui-spec.md +++ b/docs/desktop-ui-spec.md @@ -1,6 +1,8 @@ -# Desktop UI for CLIProxyAPI — Shared Spec (Windows first) +# Desktop UI (ProxyPilot) — Shared Spec (Windows first) -This doc captures shared architecture and product decisions for a desktop “controller app” that manages a local `CLIProxyAPI` instance. OS-specific details live in: +This doc captures shared architecture and product decisions for a desktop “controller app” that manages a local `CLIProxyAPI` instance. + +OS-specific details live in: - Windows: `docs/windows-ui-spec.md` - macOS (future): `docs/macos-ui-spec.md` (not yet) @@ -9,7 +11,7 @@ This doc captures shared architecture and product decisions for a desktop “con A small tray-first desktop app that can: -- start/stop/restart the local proxy +- start/stop/restart the local proxy engine (CLIProxyAPI) - show health + port + “copy base URL” snippets for IDE/agentic CLIs - surface logs/request diagnostics to debug issues like 400/429, “prompt too long”, streaming quirks @@ -33,7 +35,7 @@ We can support both Wails and Tauri without forking business logic by standardiz ## Shared control interface -### Proposed Go package +### Go package - `internal/desktopctl` - Pure Go logic for process management, config reading/writing, health, logs, autostart primitives. @@ -54,7 +56,7 @@ Wails can call `internal/desktopctl` directly; Tauri can call `cliproxyctl`. ### Core controls -- Start/Stop/Restart `CLIProxyAPI`. +- Start/Stop/Restart the proxy engine. - Detect if a proxy is already running: - If owned by UI: show as “Managed”. - If not owned: show as “External” and offer “Attach” (read-only) vs “Stop anyway” behind a confirmation. @@ -109,7 +111,7 @@ Wails can call `internal/desktopctl` directly; Tauri can call `cliproxyctl`. ## Cross-platform notes -We should split OS-specific operations behind small interfaces in `internal/desktopctl`: +Split OS-specific operations behind small interfaces in `internal/desktopctl`: - Process operations (spawn, signal/terminate, pid discovery) - Autostart @@ -122,6 +124,6 @@ Windows and macOS implementations can live in separate files via Go build tags: ## Open questions -- Should the desktop app bundle `cliproxyapi-latest` or manage an existing install? +- Should the desktop app bundle the engine binary, or manage an existing install? - Do we want a dedicated “desktop control” HTTP endpoint in the proxy (vs local process control only)? diff --git a/docs/proxypilot.md b/docs/proxypilot.md index 21536c4c..1fef7b9c 100644 --- a/docs/proxypilot.md +++ b/docs/proxypilot.md @@ -1,54 +1,29 @@ -# ProxyPilot (CLIProxyAPI Desktop + Agentic CLI Hardening) +# ProxyPilot (Desktop wrapper for CLIProxyAPI) -ProxyPilot is the desktop-facing packaging/branding for running and managing a local `CLIProxyAPI` instance, with extra compatibility features for agentic CLIs (Factory Droid, Codex CLI, Warp). +ProxyPilot is the desktop-facing packaging/branding for running and managing a local `CLIProxyAPI` instance, with extra compatibility features for agentic CLIs (Droid/Factory, Codex CLI, Warp). -This doc summarizes the current behavior and the key “quality of life” features added recently. +ProxyPilot is a fork/rebrand of CLIProxyAPI: the engine is still `CLIProxyAPI`, and ProxyPilot is the Windows tray app + installer + updater UX around it. ## What’s included -- **ProxyPilot tray app (Windows)** to start/stop/restart the proxy, open UI, open logs, and toggle autostart. -- **Droid/Factory reliability fixes** so tool calls are emitted consistently and errors show up even for strict streaming clients. -- **Agentic prompt-budget middleware** to prevent upstream “prompt too long” failures. -- **Long-session memory** with anchored summaries + persistent TODO + pinned state (local disk). +- ProxyPilot tray app (Windows) to start/stop/restart the proxy engine, open the dashboard, open logs, and toggle autostart. +- Prompt-budget middleware to reduce “prompt too long” failures in strict CLIs. +- Long-session memory with pinned state + persistent TODO (local disk). +- Optional auth debugging and cooldown reset endpoints for local troubleshooting. -## Quickstart (Windows) +## Install / uninstall (Windows) -## Build/Package without PowerShell +- Install: run `dist\\ProxyPilot-Setup.exe` +- Launch: Start Menu → ProxyPilot +- Uninstall: Settings → Apps → Installed apps → ProxyPilot → Uninstall -If you have Go installed, you can build/package from a single command (no `.ps1` scripts): +## Build / package -- Build: `go run .\cmd\proxypilotpack build` -- Zip: `go run .\cmd\proxypilotpack package-zip` -- Installer (legacy, IExpress): `go run .\cmd\proxypilotpack package-setup` -- Installer (recommended, Inno Setup): `go run .\cmd\proxypilotpack package-inno` (requires Inno Setup `ISCC.exe`) +If you have Go installed: -### Build the proxy - -- `.\scripts\build-cliproxyapi.ps1` - -### Build ProxyPilot tray app - -- `.\scripts\build-cliproxytray.ps1` - -Output: - -- `bin\ProxyPilot.exe` - -### Package (zip) - -- `.\scripts\package-cliproxytray.ps1` - -Output: - -- `dist\ProxyPilot.zip` - -### Package (self-extracting installer) - -- `.\scripts\package-cliproxytray-installer.ps1` - -Output: - -- `dist\ProxyPilot-Setup.exe` +- Build binaries: `go run .\\cmd\\proxypilotpack build` +- Package zip: `go run .\\cmd\\proxypilotpack package-zip` → `dist\\ProxyPilot.zip` +- Package installer (recommended): `go run .\\cmd\\proxypilotpack package-inno` (requires Inno Setup `ISCC.exe`) → `dist\\ProxyPilot-Setup.exe` ## Endpoints / health @@ -59,75 +34,14 @@ Example: - `curl -H "Authorization: Bearer local-dev-key" http://127.0.0.1:/v1/models` -## Agentic CLI compatibility (Droid / Codex / Warp) - -### Tool-call correctness - -For `/v1/responses` traffic from agentic CLIs, the proxy applies: - -- Tool schema tightening (`additionalProperties:false`) to reduce invalid tool argument payloads. -- Tool argument sanitization (strip unknown fields from tool call args). -- Conversion of plain-text `{...}` blocks into structured Responses `function_call` items (when present). -- If a Factory/Stainless client omits `tools`, the proxy injects a minimal `tools` set and forces `tool_choice:"auto"` so the model can emit tool calls. - -### Streaming behavior (Factory/Stainless) - -Some strict clients request `stream:true` but don’t reliably render JSON error bodies. -For `factory-cli`/Stainless user agents, CLIProxyAPI may: - -- Call upstream non-streaming and synthesize SSE so the client gets usable output/error text. - -## Prompt budget (prevent “prompt too long”) - -The `CodexPromptBudgetMiddleware` applies to agentic CLIs and will trim oversized requests: - -- Keeps recent messages/input items -- Truncates very large text blocks -- Preserves tool call/result pairing to avoid “tool_use/tool_result mismatch” errors -- Avoids disabling tools for Droid/Factory - -Model-aware budget: - -- If the chosen model has a small `context_length`, the middleware uses a smaller max body budget to reduce upstream failures. - -Override: - -- `CLIPROXY_AGENTIC_MAX_BODY_BYTES` (bytes, clamped) - -## Long-session memory (anchored compression + retrieval) - -See `docs/memory.md` for details. - -Key points: - -- Events are stored to `.proxypilot/memory/sessions//events.jsonl` -- Anchored summary: `summary.md` -- Pinned always-on state: `pinned.md` -- Persistent TODO: `todo.md` - -Session key precedence: - -1. `X-CLIProxyAPI-Session` -2. `X-Session-Id` -3. JSON `prompt_cache_key` -4. JSON `metadata.session_id` / `session_id` -5. Hash fallback (auth+UA hashed; raw values not stored) - -### Persistent TODO updates - -You can update the TODO without touching files by sending: - -- `X-CLIProxyAPI-Todo: ` - -The proxy saves it to `todo.md` and strips the header before forwarding upstream. - -## Autostart +## Autostart toggles (tray) ProxyPilot tray app can toggle: -- “Launch on login” (starts ProxyPilot) -- “Auto-start proxy” (starts `cliproxyapi-latest` when ProxyPilot launches) -On Windows this uses a per-user autostart mechanism (no admin required). +- `Launch on login` (starts ProxyPilot) +- `Auto-start proxy` (starts the proxy engine when ProxyPilot launches) + +On Windows this uses a per-user Run entry (no admin required). ## Logs / diagnostics @@ -137,7 +51,3 @@ Useful paths: - `logs/cliproxyapi.err.log` - `logs/v1-responses-*.log` / `logs/v1-chat-completions-*.log` (request logs, if enabled) -## Repo safety / public readiness - -- `config.yaml`, auth files, logs, binaries, and memory state are gitignored. -- Use `local-dev-key` only as an example; real keys should stay out of git.