How alii13/antigravity-cursor-proxy works
This repository is a small Node.js/CJS proxy service whose main job is to sit between Cursor and Google’s agentic model APIs. The architecture is intentionally split into a few thin scripts rather than a large application framework.
1. Client-facing boundary
- The consuming client is Cursor, configured as an OpenAI-compatible model provider.
- Cursor sends standard chat/completions-style traffic to a base URL exposed by this repo.
2. Public ingress layer
- start.cjs launches a local server on localhost:3000 and a Cloudflare Quick Tunnel.
- The tunnel is the public HTTPS entrypoint; Cursor talks to the temporary trycloudflare.com URL instead of directly to localhost.
- This is a transport boundary, not business logic: it exists to satisfy HTTPS/networking requirements.
3. Core proxy / protocol translation layer
- proxy.cjs is the central application module.
- Its role is to translate OpenAI-style requests from Cursor into the Google “agentic” protocol expected by Gemini/Claude-backed flows.
- It also handles response shaping back into the format Cursor expects.
- The README indicates this layer additionally injects the “thought signature” metadata needed for tool use and agentic reasoning.
4. Model routing boundary
- The proxy maps user-facing model IDs such as ag-pro, ag-flash, ag-sonnet, ag-opus, and ag-haiku onto underlying Gemini/Claude variants.
- This is a logical abstraction layer: Cursor only sees the alias, while the proxy chooses the target model family and formatting.
5. Authentication/session bridge
- db_helper.cjs is likely the local-session integration point.
- The README says the proxy extracts Google Cloud Code / Antigravity session tokens from the local IDE environment, rather than requiring manual API keys.
- Architecturally, this means the proxy depends on a local trust boundary: it reads credentials from the developer’s logged-in editor session and forwards them upstream.
6. Workspace/project discovery
- discover_project.cjs appears to inspect the current project/workspace context.
- In an agentic proxy like this, that usually supports richer prompts or tool context by identifying repository structure or project metadata before forwarding requests.
- This is a support subsystem, not the main request path, but it influences what the proxy sends upstream.
7. Bootstrap and environment preparation
- scripts/install-cloudflared.cjs is the setup helper that downloads the correct cloudflared binary for the host OS.
- package.json likely wires this into install/start scripts, making the tunnel dependency part of normal setup rather than a manual prerequisite.
8. Operational flow
- The runtime path is: Cursor → Cloudflare tunnel URL → local proxy on port 3000 → Google agentic service(s).
- In parallel, the proxy also reads local auth/session state from the IDE environment and may inspect workspace/project context.
- The returned model output flows back through the same tunnel to Cursor.
9. What is and is not in the repo
- This is not a full platform or web app; it is a thin proxy bridge plus bootstrap utilities.
- There is no sign of a database service, queue, or frontend application.
- The assets/ directory and README.md support packaging/documentation, not core runtime behavior.
10. Architecture diagram takeaway
- The key boxes to draw are:
- Cursor IDE on one side,
- Cloudflare Quick Tunnel as the public HTTPS bridge,
- Local Node proxy as the translator/orchestrator,
- Local session/token source as a side-channel dependency,
- Google agentic model endpoints as the upstream target.
- The main trust and protocol boundaries are the tunnel edge and the session-token bridge.
Main entry points: proxy.cjs Proxy Core · start.cjs Start Server · package.json Package Scripts · db_helper.cjs Session Bridge
Components 14
Runtime
Main request path and server entrypoints.
- Start Server · Launches the local server on port 3000 and brings up the Quick Tunnel.
start.cjs - Proxy Core · Converts Cursor OpenAI-style requests into the Google agentic protocol and shapes responses back for Cursor.
proxy.cjs - Model Routing · Maps user-facing aliases like ag-pro and ag-sonnet to underlying Gemini/Claude variants.
proxy.cjs - Thought Signatures · Adds agentic reasoning and tool-use metadata required by upstream flows.
proxy.cjs
Support
Authentication, workspace discovery, and setup helpers.
- Session Bridge · Extracts local IDE session tokens and forwards them upstream as credentials.
db_helper.cjs - Project Discovery · Inspects the current workspace to supply project-aware context to the proxy.
discover_project.cjs - Install Cloudflared · Downloads the host-appropriate cloudflared binary for tunnel setup.
scripts/install-cloudflared.cjs
Packaging
Repo metadata and bundled assets.
- Package Scripts · Defines install and start wiring for the proxy and tunnel bootstrap.
package.json - Assets · Bundled non-runtime assets used for distribution and repository support.
assets
Other components
- Cursor IDE · OpenAI-compatible chat/completions client configured to use the proxy as its base URL.
- Cloudflare Tunnel · Public HTTPS ingress that forwards traffic to the local server.
- Google Agentic API · Target model endpoints used by the proxy after protocol translation.
- Local Session · IDE-bound Google Cloud Code / Antigravity session state used for upstream authentication.
- Workspace Context · Current repository or project metadata discovered for richer agentic requests.
Connections 15
- Cursor IDE → Cloudflare Tunnel: HTTPS traffic · Cursor sends OpenAI-style requests to the public tunnel URL.
- Cloudflare Tunnel → Start Server: forward · Quick Tunnel forwards public requests to the local Node server.
- Start Server → Proxy Core: serve · The entrypoint boots the local proxy service.
- Start Server → Install Cloudflared: bootstrap · Startup/setup depends on the cloudflared installer helper.
- Proxy Core → Model Routing: select model · Resolves user-facing aliases to the correct upstream model family.
- Proxy Core → Thought Signatures: inject metadata · Adds thought-signature and tool-use metadata before forwarding upstream.
- Proxy Core → Session Bridge: auth · Pulls local session credentials through the session bridge.
- Proxy Core → Project Discovery: context · Uses workspace discovery to enrich upstream requests.
- Session Bridge → Local Session: read tokens · Reads credentials from the local IDE/session environment.
- Project Discovery → Workspace Context: inspect · Derives repository or project context from the current workspace.
- Proxy Core → Google Agentic API: agentic calls · Forwards translated requests to Google-backed model endpoints.
- Google Agentic API → Proxy Core: responses · Upstream model output returns to the proxy for shaping back to Cursor.
- Package Scripts → Start Server: start script · NPM scripts wire the normal runtime startup path.
- Package Scripts → Install Cloudflared: install hook · Package setup includes cloudflared installation support.
- Assets → Package Scripts: bundle support · Packaged assets accompany the repo distribution and metadata.