How zen4-bit/proxima works
Proxima is a local AI gateway for editor and desktop clients, with browser-session routing and BYOK/local-model routing. A typical request enters through its MCP server, is routed and enriched, then reaches a provider; the MCP pipeline also tracks usage and request state. The repository additionally contains a Python self-healing agent with computer/coding tools, cross-session memory, and a web interface. The README documents these capabilities; source excerpts and the SOURCE INDEX support only some internal call edges, so other links are omitted rather than inferred.
Main entry points: index.js MCP Server · pipeline.js Request Pipeline · main-v2.cjs Local Gateway · agent.py Python Agent
Components 24
Client Gateway
- MCP Server
src/mcp/index.js - Chat Tools
src/mcp/tools-chat.js - Code Tools
src/mcp/tools-code.js - Search Tools
src/mcp/tools-search.js - Workflow Tools
src/mcp/tools-workflow.js
Model Routing
- Request Pipeline
src/mcp/pipeline.js - Smart Router
src/agentic/smart-router.js - Context Middleware
src/agentic/context7-middleware.js - Retry Engine
src/retry/retry-engine.js - Provider IPC
src/mcp/ipc-bridge.js - Local Gateway
electron/main-v2.cjs - Browser Sessions
electron/providers/engines/chatgpt-engine.js - BYOK Router
electron/api/byok/router.cjs - Key Storage
electron/api/byok/keys.cjs
Agent Runtime
- Python Agent
proxima-agent/proxima_agent/agent.py - Agent Tools
proxima-agent/proxima_agent/tools/registry.py
State and Memory
- Usage Tracking
src/cost/token-tracker.js - Memory Intelligence
src/memory/memory-intelligence.js - Memory Store
src/memory/memory-store.js
User Interfaces
- Agent Web Server
proxima-agent/proxima_agent/web/server.py - Web State DB
proxima-agent/proxima_agent/web/db.py - Command Line
cli/proxima-cli.cjs - Client SDKs
sdk/proxima.js
Other components
- Editor Client
Connections 22
- Editor Client → MCP Server: requests tools
README.md - MCP Server → Chat Tools: registers tools
src/mcp/index.js - MCP Server → Code Tools: registers tools
src/mcp/index.js - MCP Server → Search Tools: registers tools
src/mcp/index.js - MCP Server → Workflow Tools: registers tools
src/mcp/index.js - MCP Server → Request Pipeline: uses pipeline
src/mcp/index.js - Request Pipeline → Context Middleware: injects context
src/mcp/pipeline.js - Request Pipeline → Retry Engine: retries calls
src/mcp/pipeline.js - Request Pipeline → Smart Router: records outcomes
src/mcp/pipeline.js - Request Pipeline → Usage Tracking: estimates tokens
src/mcp/pipeline.js - MCP Server → Provider IPC: connects to
src/mcp/index.js - Provider IPC → Local Gateway: forwards requests
- Local Gateway → Browser Sessions: routes sessions
README.md - Local Gateway → BYOK Router: routes BYOK
README.md - BYOK Router → Key Storage: reads keys
electron/api/byok/router.cjs - MCP Server → Memory Intelligence: initializes memory
src/mcp/index.js - MCP Server → Memory Store: initializes store
src/mcp/index.js - Python Agent → Agent Tools: uses tools
- Python Agent → Memory Intelligence: uses cross-session memory
README.md - Agent Web Server → Web State DB: uses database
proxima-agent/proxima_agent/web/server.py - Command Line → Local Gateway: controls local gateway
- Client SDKs → Local Gateway: calls local endpoint