Proxima
All your AI models, working under one roof.
Run frontier LLMs directly inside Cursor, VS Code, Windsurf, or Claude Desktop using free browser login sessions or local offline providers. Ships with a self-healing Python agent, multi-agent delegation, and cross-session memory.
- Why Proxima?
- Interface Preview
- Routing Modes
- Sponsor Wall
- Meet Proxima Agent
- State, Memory & Prompt Management
- Quick Start
- Architecture
- All MCP Tools (40)
- REST API
- WebSocket
- CLI
- SDKs
- Security & Privacy
Why Proxima?
In late 2025, I hit a massive roadblock with AI coding tools. Outdated training data caused coding models to frequently hallucinate, guess wrong solutions, and ruin codebases. I tried setting up local agents using Model Context Protocol (MCP) APIs, but the results were disappointing. The API responses were subpar and inaccurate, all while running up a bill for every single prompt.
That’s when a wild idea struck: What if we could turn actual web-based models—like ChatGPT, Gemini, Claude, and Perplexity—into local MCP servers? By routing queries directly through free, logged-in browser accounts, I could give my local agents access to frontier reasoning models. No expensive API keys required.
Proxima was born as a personal utility. I used it heavily for months to streamline my own work with no plans to open-source it. However, seeing other developers struggle with the same API costs and model hallucinations, I decided to share it. Proxima was created to provide a local, privacy-focused routing engine that connects development tools to active sessions without requiring paid subscriptions or API plans.
- API Subscription Fatigue: Stacking multiple AI subscriptions (ChatGPT Plus, Claude Pro, Perplexity Pro) adds up fast.
- Costly Development Keys: Querying raw API endpoints directly from code editor extensions drains credits quickly on large codebases.
- Local-Model Privacy: When running fully local models via Ollama or LM Studio, your code never leaves your machine — no cloud provider, no data exposure.
- Fragmented Tooling: Constantly switching between browser windows, terminals, and editor panels disrupts your cognitive coding flow.
The Solution: Proxima
Proxima serves as a local development gateway that centralizes and runs all your AI models together on 127.0.0.1. By handling protocol translation and session routing in the background, it enables your coding agents and development clients to interact with multiple advanced providers or offline engines as a single, standard local endpoint.
Interface Preview
Routing Modes
Proxima supports two primary modes to power your editor and agent integrations:
1. Session Routing (Default)
- Free Account Emulation: Routes prompts through your logged-in browser accounts (ChatGPT, Claude, Gemini, Perplexity) inside sandboxed background browser views.
- No API Keys Required: Reuses standard local cookies and browser sessions. No passwords or credentials are saved.
- Renderer-Level Interception: Captures tokens directly from internal WebSocket and API streams, bypassing brittle HTML selectors for faster and more stable routing.
2. BYOK (Bring Your Own Key) Routing
- Broad Model Support: Support for OpenAI, Anthropic, Google, DeepSeek, Groq, xAI, OpenRouter, Together, Fireworks, Mistral, and NVIDIA.
- Local Offline Hardware: Intercepts configurations to run local models via Ollama or LM Studio.
- Secure Storage: Keys are saved locally using your operating system's native keychain vault (via Electron's SafeStorage).
- Local Brain Integration: Automatically applies context compaction, factual recall, and prompt-injection screening.
Sponsor Wall
Proxima keeps evolving thanks to these amazing people
Bloome
💎 Featured Sponsor
Multiple AI agents in one shared chat — not one assistant, but a whole team. Drop in a task and they split the work, hand off, cross-check details, and push back until the output is right. They generate tables, docs and dashboards inline — zero setup, runs in the cloud on web and mobile, and shareable with your team. 👉 Try Bloome
@TheNetworker
⭐ Star Sponsor · 🥇 First Sponsor
Great things are built together — Be a part of our journey →
Meet Proxima Agent
The repository contains proxima-agent/, a local Python assistant. It executes codebase edits, runs test suites, and drives browser tasks by routing LLM calls through Proxima. This allows the agent to run completely free using your website providers or with custom API keys via BYOK mode.
Core Agent Capabilities
- Self-Healing Debugging Loop: Executes code, captures terminal and test-suite errors, and iteratively refactors the codebase until all tests pass.
- Autonomous Browser Control: Drives Chrome instances via Chrome DevTools Protocol (CDP) to interact with frontends, verify UI layouts, and test user flows.
- Dynamic Skill Generation: Writes custom Python helper scripts on the fly, tests them, and packages them into reusable runtime skills (
skills.db) to expand its capabilities. - Symbol-Mapped Codebase Analysis: Maps local files, builds class/function symbol hierarchies, and isolates relevant code blocks to handle large context limits efficiently.
A Real-World Agent Scenario
Imagine you instruct the agent: "Find the bug in my token verification module, patch it, and verify that the authentication tests pass."
Here is the exact trace of how Proxima Agent executes this task:
sequenceDiagram
autonumber
actor User
participant Agent as Proxima Agent
participant Code as Codebase
participant Test as Test Suite
participant Browser as Chrome (CDP)
participant Audit as Reviewer Agent
User->>Agent: "Find the bug in token verification..."
Agent->>Code: 1. Ingest files & build symbol map
Agent->>Test: 2. Run test suite to capture failure trace
Agent->>Code: 3. Synthesize & write code patch
Agent->>Browser: 4. Emulate login & verify user flow
Agent->>Audit: 5. Spawn sub-agent to audit security
Agent->>User: 6. Request approval (present diff & logs)
Gated Execution Safety
The agent is bound by customizable safety permissions:
- Full Auto: Executes all file writes and terminal commands instantly.
- Smart: Auto-approves reading/searching but prompts you before running commands or overwriting code.
- Suggest: Shows proposed code diffs and command lines, waiting for your manual approval.
State, Memory & Prompt Management
To keep workflows fast and context accurate, Proxima features separate prompt and memory systems depending on the active routing engine.
Context Tracking & Prompt Routing
- Session Mode: In this mode, the target provider website (e.g., ChatGPT, Claude) maintains the active conversation state. Sending a massive system prompt containing 40+ tool definitions on every message would bloat the browser's context window, increasing latency and cost. Instead, Proxima runs a fast local classifier every turn. It dynamically analyzes your task and injects only the necessary tool references and relevant self-generated procedural hints.
- BYOK & Local Mode: Proxima's prompt compiler manages the message payload lifecycle for custom API keys and offline endpoints. It formats the conversation history, applies system instructions dynamically, and executes a context compaction loop to summarize older chat turns, preventing token limit errors during large developer prompts.
Local SQLite Memory Engines
Proxima maintains four separate, local, SQLite-backed databases (~/.proxima-agent/*.db) to enable cross-session statefulness:
- Conversation Vault (
vault.db): Tracks session lineage (supporting parent-child structures for multi-agent forks) and stores message histories securely. - Insight Store (
insights.db): Extracts and stores cross-session user preferences, workspace patterns, and environmental facts to prevent repetitive setups. - Experience Learning (
memory.db): Automatically caches compilation errors, syntax exceptions, and the edits that resolved them. The agent queries this history during self-healing loops to apply proven fixes instantly. - Procedural Skills (
skills.db): Caches and evaluates custom script actions generated during tasks. The agent evaluates new skills through a Bayesian priority model, promoting them to "proven" or demoting/deprecating them based on Exponential Moving Average (EMA) success rates.
Quick Start
Follow these steps to configure and connect Proxima to your local environment.
1. Prerequisites
2. Install & Start
# Clone the repository
git clone https://github.com/Zen4-bit/Proxima.git
cd Proxima
# Install dependencies & start
npm install
npm start
💡 Windows Users: You can also download and run the latest
.exeinstaller directly from the Releases page.
Once the desktop app opens:
- Session mode: Log into ChatGPT, Claude, Gemini, or Perplexity in their respective tabs.
- BYOK mode: Click Settings and paste your custom API keys or local host addresses.
3. Connect to Your Editor (MCP)
Add this server configuration block to your editor's MCP configuration settings (for example, in Cursor under Settings -> Features -> MCP):
{
"mcpServers": {
"proxima": {
"command": "node",
"args": [
"C:/absolute/path/to/Proxima/src/mcp/index.js"
]
}
}
}
💡 Tip: You can copy the exact configuration block with your machine's absolute paths directly from the Settings ➔ MCP Configuration tab inside the Proxima desktop app window.
Troubleshooting
Python 3.10+ Environment shows "Error" or "Missing"
Symptoms: The Diagnostics panel shows a red ✗ next to Python 3.10+ Environment even though Python is installed on your system.
Cause: On Windows, the app installs to C:\Program Files\Proxima which is a protected directory. During first-time setup, pip install needs to write temporary files in the source folder and fails with "Access is denied" for standard (non-admin) users.
Versions 5.0.0+ with bundled wheel: This issue is resolved automatically. The installer bundles a pre-built
.whlpackage that installs directly into the virtual environment without writing to the app directory. If you still see this error, make sure you're running the latest build.
Quick Fix (older builds):
- Close Proxima completely.
- Right-click the Proxima app (desktop shortcut or Start menu).
- Select "Run as administrator".
- Wait for the setup to complete — you'll see the Python status turn green ✓.
- Close and reopen normally. Admin mode is only needed once.
macOS / Linux: This is rare on these platforms since app directories are usually user-owned. If it occurs, run the app once with sudo to complete the initial setup.
Python is installed but Proxima can't find it
Make sure Python is on your system PATH:
- Windows: During Python installation, check "Add Python.exe to PATH" at the bottom of the installer. If you missed it, re-run the installer → Modify → check the PATH option.
- macOS / Linux: Run
python3 --versionin a terminal. If not found, install via python.org or your package manager.
Proxima requires Python 3.10 or higher.
Architecture
The system consists of three primary layers: the Proxima Runtime Host, the Model Context Protocol (MCP) Server, and the Local Agent Runtime.
1. System Topology & Data Flow
Below is the complete architectural map showing how protocols, IPC bridges, and providers communicate:
graph TD
subgraph Client Layer [Development Client]
Cursor[Cursor / VS Code / Windsurf]
ClaudeClient[Claude Desktop Client]
end
subgraph MCPServer [MCP Server - Node.js]
MCPIndex[src/mcp/index.js]
ToolHandlers["Modular Tool Handlers<br/>(tools-chat / tools-code / tools-search / tools-content / tools-workflow)"]
end
subgraph CoreEngine [Proxima Core Process - Electron]
HTTPServer["HTTP Server :3210<br/>(OpenAI REST & WS)"]
MessageBus["handleMCPRequest()<br/>(Central Message Bus)"]
PythonAgent["Local Agent Runtime<br/>(python-env)"]
end
subgraph RoutingEngines [Routing Engines]
SessionMode["Session Mode<br/>(Browser Manager & background BrowserViews)"]
BYOKMode["BYOK Mode<br/>(BYOK Router & Context Pipeline)"]
end
subgraph Providers [AI Providers]
WebSessions["Active Web Sessions<br/>(ChatGPT / Claude / Gemini / Perplexity)"]
OfficialAPIs["Official LLM APIs<br/>(OpenAI / Anthropic / Groq / etc.)"]
end
%% Communications
Cursor -->|StdIO JSON-RPC| MCPIndex
ClaudeClient -->|StdIO JSON-RPC| MCPIndex
MCPIndex --> ToolHandlers
ToolHandlers -->|IPC TCP:19222| MessageBus
HTTPServer --> MessageBus
PythonAgent --> MessageBus
MessageBus --> SessionMode
MessageBus --> BYOKMode
SessionMode -->|Session Compliance| WebSessions
BYOKMode -->|Dynamic Fallback / Decryption| OfficialAPIs
2. Core Subsystems
Browser Session Compliance Layer
For Session Mode, Proxima loads each provider inside isolated BrowserView containers. The compliance layer includes:
- User-Agent Management: Maintains standard browser user-agent strings for compatibility.
- Page Context Configuration: Sets up standard preload scripts for correct rendering and provider compatibility.
- Direct Response Streaming: Engine scripts (
electron/providers/engines/*) capture streaming tokens directly from provider HTTP responses for real-time output.
Worker Control Protocol (WCP)
The Agent's workflow engine uses an internal command protocol (WCP) for multi-step task delegation, research routing, and temporary state management across sub-agents. See docs/architecture.md for protocol details.
BYOK Local Brain & Context Pipeline
When BYOK Mode is active, Proxima utilizes a local intelligence buffer:
- Factual Recall & Experience Log: Stores previous code errors, terminal exceptions, and successful fixes in an encrypted SQLite database to avoid repeating programming mistakes.
- Context Compaction Pipeline: Uses token-estimation and cheap pruning heuristics (
byok/context/) to summarize long conversation loops when approaching provider limits (preventing out-of-context crashes). - Ollama/LM Studio Bridge: Intercepts unknown custom provider configurations and loops them through standard OpenAI-compatible endpoints to support offline, local hardware execution.
Read docs/architecture.md for structural diagrams and docs/MIGRATION-v5.0-to-v5.5.md for v5.0.0 → v5.5.0 upgrade notes.
All MCP Tools (41)
Registered by the modular MCP server (src/mcp/). Proxima also provides dynamic model inspection via the proxima://models MCP resource.
Core Orchestration Tools
The following signature capabilities represent Proxima's custom orchestration logic:
Tool Catalog
REST API
OpenAI-compatible HTTP gateway running at http://localhost:3210 by default (configurable via PROXIMA_REST_PORT or automatically discovered via rest-port.json).
Endpoints
POST /v1/chat/completions # OpenAI-compatible chat (stream, tools, thinking controls)
POST /v1/cancel # Cancel in-flight provider generation and flush queue
GET /v1/models # List dynamically discovered and BYOK models
GET /v1/functions # Function catalog
GET /v1/stats # Per-provider response statistics
POST /v1/conversations/new # Reset conversation memory for a provider
# BYOK brain endpoints
GET /v1/byok/keys # BYOK key management
GET /v1/byok/models # BYOK model management
GET /v1/brain/recall # Cross-session recall
GET /v1/brain/experience # Learned experiences
GET /v1/brain/skills # Stored skills
GET /v1/brain/stats # Brain statistics
GET /api/status # Server status (returns active bound port & providers)
GET / # Interactive documentation & Battle Mode Chat Widget
Example Request
curl http://localhost:3210/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "gemini",
"message": "Analyze this architectural trade-off",
"thinking_level": "high"
}'
- Model Selection: Accepts
auto, core provider names (claude,chatgpt,gemini,perplexity), sub-engines (e.g.gemini:pro,gemini:argon), dynamically discovered model slugs (queried viaGET /v1/models), or multi-provider arrays["claude", "chatgpt"]. - Thinking Controls: Optional
thinking_level(default,low,medium,high) or OpenAI-compatiblereasoning_effort. - Cancellation: Send
POST /v1/cancelwith optional{"provider": "gemini"}to abort in-flight generations immediately.
Interactive Documentation & Battle Mode
The gateway hosts interactive documentation at http://localhost:3210 with an embedded live chat widget:
- Model Discovery: Automatically populates available models from active sessions with capability badges (
Fast,Reasoning,Pro). - Battle Mode: Benchmark two or more models side-by-side on the same prompt with real-time status and timing comparisons.
- Reasoning Selector: Dynamically displays thinking depth options when reasoning models are selected.
WebSocket
Real-time bidirectional streaming at ws://localhost:3210/ws (requires REST API enabled).
const ws = new WebSocket("ws://localhost:3210/ws");
ws.onopen = () => {
ws.send(JSON.stringify({
action: "ask",
model: "gemini",
thinking_level: "high",
message: "Explain closures in JavaScript",
id: "req-1"
}));
};
ws.onmessage = (e) => {
const data = JSON.parse(e.data);
console.log(data); // Streamed chunks, status events, or completion
};
CLI
Install via Settings ➔ Install CLI to PATH, or npm link.
# Ask any provider
proxima ask "How does async/await work?"
proxima ask claude "Explain React hooks"
# Code tools
proxima code review "function f(){...}" # actions: generate/review/debug/explain
proxima fix "SyntaxError: Unexpected token"
# Pipe build errors directly
npm run build 2>&1 | proxima fix
proxima audit 'SELECT * FROM users WHERE id=' + input
# Content tools
proxima debate "tabs vs spaces"
proxima brainstorm "dev productivity features"
proxima compare "Bun vs Node.js"
proxima translate "Hello world" --to Hindi
# Search & analyze
proxima search "latest Node.js release"
proxima analyze "https://example.com" -q "what is this?"
# Session management
proxima new <provider> # reset a conversation
proxima models | status | stats
Flags: -m/--model, --json, --file, --to, --from, -q/--question
SDKs
Python
# Requires: pip install requests
# Copy sdk/proxima.py into your project
from proxima import Proxima
client = Proxima()
response = client.chat("Hello", model="claude")
print(response.text)
JavaScript
// Node 18+
const { Proxima } = require('./sdk/proxima');
const res = await new Proxima().chat("Hello", {
model: "claude"
});
console.log(res.text);
Security & Privacy
Found a vulnerability? Follow SECURITY.md — use GitHub Security Advisories, don't open a public issue.
Frequently Asked Questions
Is Proxima really free?
Yes. If you use Session Mode, it communicates with the official web platforms through your active browser login sessions. There are no fees, and you don't need any paid API keys. You only pay if you explicitly choose BYOK Mode to connect your own API tokens.
Is my data private?
Yes. Proxima itself stores nothing on external servers—no logs, chats, keys, or sessions leave your machine, and your configuration remains encrypted locally (using SafeStorage). However, remember that Session Mode still sends your prompts to the third-party AI provider you're logged into (that's how any AI chat works). For fully offline privacy where your code never leaves your local hardware, use local models via BYOK Mode.
How does Session Mode work without passwords?
Proxima loads secure, isolated browser tabs (called BrowserViews) inside the background. When you log into ChatGPT or Claude inside these views, the browser maintains your active session logins locally on your device, just like Chrome or Firefox does. Proxima simply uses these local sessions to send standard prompts.
Can I run local offline models?
Yes. BYOK mode supports any OpenAI-compatible custom endpoints. You can run Ollama or LM Studio offline on your own machine and route all requests through Proxima.
Does the Python agent delete or modify my code automatically?
No. By default, the agent runs in Suggest or Smart mode. It will show you exactly what changes it wants to make and wait for you to click "Approve" before modifying any files or running commands.
Testing
# JavaScript test suite
npm test
# Python agent test suite
cd proxima-agent && python -m unittest discover -s tests -p "test_*.py"
See TESTING.md for the full testing strategy and coverage details.
Contributing
Contributions are welcome! See CONTRIBUTING.md for:
- Fork ➔ Branch ➔ PR workflow
- Coding style guidelines
- Mock-at-boundary test strategy
Please read our Code of Conduct before contributing.
License
Proxima is licensed under the Proxima Personal Use License (Personal, Non-Commercial use only).
See LICENSE for the full license text and terms. For commercial licensing inquiries, please contact the repository author.
Proxima v5.5.0 — Making every AI work together
Built by Zen4-bit
Website · Releases · Architecture · Changelog
