ProxyPal Documentation

ProxyPal acts as a bridge between various AI providers and coding clients using an OpenAI-compatible interface.

Supported AI Providers

• Claude
• ChatGPT
• Gemini
• Qwen
• iFlow
• Vertex AI
• Custom OpenAI-compatible endpoints
• GitHub Copilot Bridge: Access Copilot models via an OpenAI-compatible API
• Antigravity Support: Access thinking models through the Antigravity proxy

Supported Clients

ProxyPal works with any OpenAI-compatible client, including:

• Cursor
• Claude Code
• OpenCode
• Cline
• Continue
• GitHub Copilot

ProxyPal detects installed CLI agents by scanning common installation paths rather than using the which shell command (to ensure compatibility with sandboxed macOS environments).

When verifying agent detection in the Dashboard > Agent Setup section, the application scans the following paths:

• /opt/homebrew/bin (Homebrew ARM)
• /usr/local/bin (Homebrew Intel)
• /usr/bin (System)
• ~/.cargo/bin (Rust)
• ~/.npm-global/bin (npm)
• ~/.local/bin (System)
• ~/go/bin (Go)
• ~/.bun/bin (Bun)
• ~/.nvm/versions/node/*/bin (Node via NVM - scanned dynamically)

If an agent (e.g., claude, gemini, or opencode) is present in these paths, it should show as "installed" in the UI.

To use your AI subscriptions (Claude, ChatGPT, Gemini, GitHub Copilot) with any coding tool, follow these steps:

1. Download: Get the latest version from the Releases page.
2. Launch: Open the ProxyPal desktop app and start the proxy service.
3. Authenticate: Connect your AI accounts using OAuth or by providing your existing auth files.
4. Configure Client: In your coding tool (e.g., Cursor, Cline, Continue), set the API base URL to http://localhost:8317/v1.

To develop or test ProxyPal locally, ensure you have pnpm and cargo (Rust) installed. Follow these steps to install dependencies and verify the project builds:

1. Navigate to the project root.
2. Install Node.js dependencies using pnpm install.
3. Verify TypeScript compilation with pnpm tsc --noEmit.
4. Verify Rust/Tauri backend with cd src-tauri && cargo check.

To run the application in development mode, use:

pnpm tauri dev

To build a production version for macOS, use:

pnpm tauri build

This will generate the .app bundle in src-tauri/target/release/bundle/macos/ProxyPal.app.

# Install dependencies
pnpm install

# Verify builds
pnpm tsc --noEmit
cd src-tauri && cargo check

# Start dev server
pnpm tauri dev

# Build for macOS
pnpm tauri build

ProxyPal is built using SolidJS, TypeScript, Tailwind (frontend), and Rust with Tauri v2 (backend). To develop locally, follow these steps:

Installation and Running

pnpm install
pnpm tauri dev

Running Checks

Use these commands to verify code quality:

pnpm check:ts        # Runs tsgo (if installed) or tsc --noEmit
pnpm check:parallel  # Runs check:ts, lint, and format:check in parallel
cd src-tauri && cargo check

Optional TypeScript Optimization

For faster type checking, you can use tsgo:

pnpm add -D @typescript/native-preview

And update your VS Code settings:

{
  "typescript.experimental.useTsgo": true
}

To extend ProxyPal with support for a new agent, you must perform the following tasks:

1. Detection Logic: Add the detection logic in src-tauri/src/lib.rs.
2. Assets: Add a new logo to public/logos/. Ensure the logo uses currentColor to support dark mode.
3. UI Updates: Update the agents array in the relevant frontend components.
4. Verification: Test the auto-configuration flow to ensure the agent is detected and set up correctly.

When a user disconnects a provider via Dashboard > Settings, ProxyPal is designed to delete the associated credential files to prevent the provider from being re-detected as connected on restart.

Verification Steps:

1. Connect a provider (e.g., Claude).
2. Disconnect the provider in the Settings UI.
3. Confirm the success toast appears and the provider card shows as disconnected.
4. Manually verify that the credential files have been removed from the local directory:

   ls ~/.cli-proxy-api/

   The directory should not contain files with the provider's prefix (e.g., claude-*.json).

ProxyPal stores its configuration files in the standard system configuration directory under a proxypal folder.

• Main Config Directory: [Config Dir]/proxypal
• Proxy YAML File: [Config Dir]/proxypal/proxy-config.yaml

On most systems, [Config Dir] refers to the directory returned by dirs::config_dir() (e.g., ~/.config/ on Linux or ~/Library/Application Support/ on macOS).

The translation function t supports dynamic parameter injection using double curly braces. When calling t(key, params), the system replaces {{paramName}} in the translation string with the corresponding value from the params object.

Example Translation String: "Hello {{name}}!"

Usage: t('greeting', { name: 'Alice' }) -> returns "Hello Alice!"

// Internal implementation detail for context:
function interpolate(template: string, params?: TranslationParams): string {
  if (!params) return template;
  return Object.entries(params).reduce((result, [key, value]) => {
    return result.split(`{{${key}}}`).join(String(value));
  }, template);
}

ProxyPal provides logic to determine which reasoning level suffixes are available for a given model. This ensures consistency between the backend proxy configuration and the frontend Settings UI.

• Standard GPT-5 models: Support suffixes: minimal, low, medium, high, xhigh.
• GPT-5.6 variants: Support additional high-end suffixes: minimal, low, medium, high, xhigh, max, ultra.

// The available suffixes depend on the model prefix
// If model starts with 'gpt-5.6-', it includes 'max' and 'ultra'

Logs retrieved via the API are parsed into LogEntry objects. Each entry contains the following fields:

• timestamp: A string representing when the log occurred. This may be empty if the log format does not include a timestamp.
• level: A normalized string representing the severity of the log. Supported normalized levels are ERROR, WARN, INFO, DEBUG, and TRACE.
• message: The actual log message content.

Log Level Normalization

The parser normalizes various shorthand or alternative level names into a standard set:

• ERROR, ERR, E $\rightarrow$ ERROR
• WARN, WARNING, W $\rightarrow$ WARN
• INFO, I $\rightarrow$ INFO
• DEBUG, DBG, D $\rightarrow$ DEBUG
• TRACE, T $\rightarrow$ TRACE