zen4-bit/proxima

---

Demo

App Demo · CLI · Webhook Live Chat & Battle · Application Overview

---

---

Overview

Proxima is a local AI gateway that connects multiple AI providers to your development environment. It communicates with each provider at the browser level through your active login sessions — the same way you’d chat with them in your browser.

---

What’s New in v4.1.0

Bug fixes & improvements:

• 🔧 Staggered multi-provider queries — prevents UI freezes during parallel requests
• 🔧 Smart provider selection — routes coding tasks to Claude, research to Perplexity
• 🔧 Response caching with TTL (5 min) and automatic eviction (max 100 entries)
• 🔧 Rate limit handling — detects 429 responses, auto-recovery on expired sessions
• 🔧 Engine auto-injection on page navigation with duplicate guard
• 🔧 Claude conversation auto-recovery (handles 404/410 expired sessions)
• 🔧 ChatGPT SHA3-512 proof-of-work challenge solver
• 🔧 10MB body size limit on REST API with CORS headers
• 🔧 Socket leak prevention on IPC reconnect

---

Getting Started

Requirements

• Node.js 18+ (for MCP server and CLI)
• Windows 10/11 — pre-built installer available
• macOS / Linux — supported via source code

Install

Electron will open the Proxima window. Log in to your AI providers, enable REST API in Settings, and you’re ready.

CLI install:

• Windows: Settings → ⚡ Install CLI to PATH, or npm link
• macOS / Linux: npm link (may need sudo npm link)

Connect to your editor

1. Open Proxima and log into your AI providers (one-time setup)
2. Go to Settings → MCP Configuration → copy the config
3. Paste into your editor’s MCP config file:

{
  "mcpServers": {
    "proxima": {
      "command": "node",
      "args": ["C:/path/to/Proxima/src/mcp-server-v3.js"]
    }
  }
}

4. Restart your editor. The tools will appear.

Tip: Use the copy button in Settings — don’t type the path manually.

Works with: Cursor · VS Code (MCP extension) · Claude Desktop · Windsurf · Gemini CLI · any MCP-compatible client

---

Supported Providers

Each provider runs through a dedicated engine script that handles communication at the browser level. Responses are streamed via SSE using your existing login. If an engine can’t connect, Proxima falls back to DOM-based interaction automatically.

---

How It Works

In v4.1.0, Proxima uses a Provider Engine System instead of DOM scraping.

When you send a query, Proxima uses a lightweight engine script within the provider’s browser tab. That script handles communication at the browser level and streams the response back via SSE. If the engine fails for any reason, Proxima automatically falls back to DOM-based interaction — so it keeps working either way.

Your editor → MCP tool call → Proxima local server
                                      ↓
                           Engine injected into session
                                      ↓
                      Browser-level communication (SSE stream)
                                      ↓
                              Response returned

CLI Tool

The proxima CLI lets you use any AI provider from your terminal.

Install

Commands

# Ask any provider
proxima ask "How does async/await work in JS?"
proxima ask claude "Review this approach"
proxima ask chatgpt "Explain this error"

# Search
proxima search "latest Node.js release"

# Code
proxima code "REST API with Express and JWT auth"
proxima code review "function fetchUser(id) { ... }"
proxima code explain "async/await"

# Smart tools
proxima fix "SyntaxError: Unexpected token '<'"
proxima debate "tabs vs spaces"
proxima audit "SELECT * FROM users WHERE id=" + req.query.id
proxima brainstorm "features for a dev productivity tool"

# Translate
proxima translate "Hello world" --to Hindi

# Compare all providers
proxima compare "Bun vs Node.js for production"

# Utilities
proxima status                     # server status
proxima stats                      # response time stats
proxima models                     # list available providers
proxima new                        # reset all conversations

Pipe Support

# Fix build errors directly
npm run build 2>&1 | proxima fix

# Review a git diff
git diff | proxima code review

# Pass file as context
proxima ask "What does this do?" --file src/server.js

Flags

---

REST API

Proxima runs an OpenAI-compatible REST API at http://localhost:3210.

Enable it in Settings → REST API & CLI.

Endpoints

POST /v1/chat/completions   — OpenAI-compatible chat
GET  /v1/models             — List available models
GET  /v1/functions          — API function catalog with examples
GET  /v1/stats              — Response time stats per provider
POST /v1/conversations/new  — Reset all conversations
GET  /api/status            — Server status
GET  /docs                  — Interactive API docs (with live chat widget)
GET  /cli                   — CLI documentation
GET  /ws                    — WebSocket documentation

Functions

The "function" field controls what happens. No function = normal chat.

Examples

Chat:

curl http://localhost:3210/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "claude", "message": "What is AI?"}'

Search:

curl http://localhost:3210/v1/chat/completions \
  -d '{"model": "perplexity", "message": "AI news 2026", "function": "search"}'

Translate:

curl http://localhost:3210/v1/chat/completions \
  -d '{"model": "gemini", "message": "Hello world", "function": "translate", "to": "Hindi"}'

Code Generate:

curl http://localhost:3210/v1/chat/completions \
  -d '{"model": "claude", "message": "Sort algorithm", "function": "code", "action": "generate", "language": "Python"}'

Query All Providers:

curl http://localhost:3210/v1/chat/completions \
  -d '{"model": "all", "message": "Explain quantum computing"}'

Security Audit:

curl http://localhost:3210/v1/chat/completions \
  -d '{"model": "claude", "function": "security_audit", "code": "db.query(\"SELECT * FROM users WHERE id=\" + req.query.id)"}'

Multi-model queries

model: "all"                       // all enabled providers
model: ["claude", "chatgpt"]       // specific providers

Response Format

{
  "id": "proxima-abc123",
  "model": "claude",
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "AI response here..."
    }
  }],
  "proxima": {
    "provider": "claude",
    "responseTimeMs": 2400
  }
}

When using model: "all", each provider gets its own entry in choices[].

---

SDKs

SDK Configuration

client = Proxima(base_url="http://192.168.1.100:3210")   # custom URL
client = Proxima(default_model="claude")                  # default model

---

WebSocket

Real-time streaming AI at ws://localhost:3210/ws.

Requires REST API to be enabled in Settings.

Example

const ws = new WebSocket("ws://localhost:3210/ws");

ws.send(JSON.stringify({
  action: "ask",
  model: "claude",
  message: "What is a closure?",
  id: "req_1"
}));

ws.onmessage = (e) => {
  const msg = JSON.parse(e.data);
  // { type: "status",   id: "req_1", status: "processing", model: "claude" }
  // { type: "response", id: "req_1", model: "claude", content: "...", responseTimeMs: 2400 }
};

Available Actions

---

MCP Tools

🤖 AI Provider Tools

🔧 Development Tools

⚔️ Multi-AI Tools

💻 Code Tools

🔍 Search Tools

📝 Content Tools

🔬 Analysis Tools

📁 File Tools

🪟 Window Controls

🔄 Session Tools

---

Security & Privacy

Since Proxima works without API keys, a few things worth knowing:

• No credentials stored. Proxima uses your existing browser session cookies — the same way you’re already logged in.
• Nothing leaves your machine except the queries you send to AI providers you’re logged into.
• Runs on localhost. The MCP server, REST API, and WebSocket are all local. Nothing is exposed to the internet.
• No telemetry. Proxima doesn’t collect or send any usage data anywhere.
• Sessions are yours. If you log out from a provider’s website or clear browser data, you’ll need to log in again through Proxima.

Proxima doesn’t bypass authentication — it uses the sessions you already have. Same as using the site in a browser.

---

Project Structure

Proxima/
├── electron/
│   ├── main-v2.cjs                  # Electron main process
│   ├── browser-manager.cjs          # Browser session management
│   ├── rest-api.cjs                 # REST API server (OpenAI-compatible)
│   ├── ws-server.cjs                # WebSocket server
│   ├── provider-api.cjs             # Provider engine injection manager
│   ├── index-v2.html                # App UI
│   ├── preload.cjs                  # Renderer preload bridge
│   └── providers/
│       ├── chatgpt-engine.js        # SHA3-512 POW + SSE streaming
│       ├── claude-engine.js         # Org auth + SSE streaming
│       ├── gemini-engine.js         # Session SSE streaming
│       └── perplexity-engine.js     # SSE streaming
├── cli/
│   └── proxima-cli.cjs              # Terminal CLI
├── src/
│   ├── mcp-server-v3.js             # MCP server (50+ tools)
│   └── enabled-providers.json       # Provider config
├── sdk/
│   ├── proxima.py                   # Python SDK
│   └── proxima.js                   # JavaScript SDK
├── assets/                          # Icons, screenshots, demo
└── package.json

---

Troubleshooting

Windows Firewall prompt on first launch Proxima runs on localhost:19223 and localhost:3210. Click Allow — it only accepts local connections.

Provider shows “Not logged in” Each provider has a different login method:

• ChatGPT, Claude, Perplexity — click the provider tab and log in using OTP (email code). Google Sign-In is restricted in embedded browsers by Google’s policy.
• Gemini — uses cookie-based authentication. Log in to Google in your regular browser first, then Proxima picks up the session automatically.

REST API not responding Check that REST API is enabled in Settings → REST API & CLI section. Visit http://localhost:3210 in your browser to verify.

MCP tools not showing in editor

1. Make sure Proxima is running
2. Verify the path in your MCP config (use the Settings copy button)
3. Restart your editor

CLI: proxima not found after install Open a fresh terminal. If still not found, click 🔧 Fix in Settings → CLI section.

CLI: “Cannot connect to Proxima” Proxima must be running and REST API must be enabled. The CLI connects to localhost:3210.

WebSocket won’t connect WebSocket shares the REST API server. Enable REST API in Settings first.

---

Sponsors 💖

With ongoing development of Proxima, contributes to maintaining and improving the project on GitHub

License

Proxima is licensed for non-commercial use only. See LICENSE for full terms.

---