claude-cursor-proxy

中文 | English

Adapted from raine/claude-code-proxy. This project is a Cursor-first local proxy for Claude Code and Grok Build (grok / grok-build).

Run Cursor models (Fable 5) from Claude Code or grok-build — stably.

Claude Code ──Anthropic /v1/messages──► claude-cursor-proxy (:18765)
grok-build  ──Responses / Messages ──►        │
                                              ├── Cursor (Fable 5)   ← primary
                                              ├── Codex             ← additional
                                              ├── Kimi
                                              └── Grok

Quick start · Models · Sand mode · Features · Config · MCP troubleshooting · Limitations

---

What it does

Claude Code speaks Anthropic (/v1/messages). grok-build speaks OpenAI Responses (/v1/responses). Cursor uses its own Agent protocol. They do not talk to each other directly.

This tool runs a local one-way proxy (default 127.0.0.1:18765):

1. Claude Code or grok-build send their usual requests to the proxy
2. The proxy translates them for Cursor and forwards upstream
3. It streams the matching SSE back — Anthropic ping keep-alive for Claude Code, Responses events for grok-build

Primary upstream: Cursor (Fable 5). Additional backends in the same process: Codex, Kimi, Grok.

Not affiliated with Anthropic, Cursor, OpenAI, Moonshot, or xAI.

---

Why

| | | | --- | --- | | Stable sessions | HTTP/2 BiDi upstream + Anthropic ping SSE keep-alive downstream | | Fable 5 | Set ANTHROPIC_MODEL=claude-fable-5[1m] (and the same for ANTHROPIC_SMALL_FAST_MODEL) | | Usage / ctx | Cursor turn usage mapped onto Anthropic usage for status lines and compaction | | Tools | Cursor exec / native tools remapped into Claude Code and grok-build tool loops (best-effort) | | Simple install | Checksummed binaries; macOS ad-hoc codesign; config under ~/.config/claude-cursor-proxy |

Honest scope: best-effort compatibility — not a full Cursor IDE mirror. See Limitations.

---

Quick start

Install

curl -fsSL https://raw.githubusercontent.com/YeautyYE/claude-cursor-proxy/main/install.sh | bash

macOS / Linux. Windows: download the .zip from Releases (or use WSL).

<details> <summary>Other install options</summary>

| Method | Command | | --- | --- | | Pin version | CLAUDE_CURSOR_PROXY_VERSION=v0.1.115 curl -fsSL …/install.sh \| bash | | Custom dir | CLAUDE_CURSOR_PROXY_INSTALL_DIR=/opt/bin bash install.sh | | From source | cargo install --git https://github.com/YeautyYE/claude-cursor-proxy --locked | | Fork / mirror | GITHUB_REPO=owner/repo curl -fsSL https://raw.githubusercontent.com/owner/repo/main/install.sh \| bash |

</details>

Log in + serve

claude-cursor-proxy cursor auth login
claude-cursor-proxy serve                 # 127.0.0.1:18765 + monitor TUI
claude-cursor-proxy serve --no-monitor    # logs only
claude-cursor-proxy serve --port 11435    # custom port

Hot account switch (no restart)

Run claude-cursor-proxy cursor auth login in another terminal while serve is running. Credentials are re-read from the store on every request, so:

• new requests use the new account immediately;
• in-flight runs keep the token they captured at start and finish on the previous login — nothing is interrupted;
• existing sessions start a fresh Cursor conversation on their next turn (the client resends its history automatically).

cursor auth status shows the active account. Note: if CCP_CURSOR_AUTH_TOKEN/CURSOR_AUTH_TOKEN is set in the serve process's environment, the env token shadows the store and a login hot swap will not take effect until you unset it.

Multiple Cursor accounts

Use login when you want the newly authenticated account to become active. Use add when you want to keep the current account active and append another login to the local account pool:

claude-cursor-proxy cursor auth add --label work
claude-cursor-proxy cursor auth list
claude-cursor-proxy cursor auth use ACCOUNT_ID
claude-cursor-proxy cursor auth usage                 # every saved account
claude-cursor-proxy cursor auth usage ACCOUNT_ID      # one account
claude-cursor-proxy cursor auth usage --json          # machine-readable

ACCOUNT_ID may be the id printed by list, an unambiguous email, or a label. The pool is stored in cursor/accounts.json; the selected credential remains mirrored to the existing cursor/auth.json so older installations continue to work. In the monitor TUI, press a to open the account panel, Enter to switch, u to fetch the selected account, and U to fetch every account in parallel. Each account has its own refresh worker, so moving to another row does not cancel the account that was just refreshed. Successful snapshots are cached under the state directory and shown again on the next TUI open; the Updated column (or the selected-row detail on narrow terminals) shows the last dashboard fetch time. Press r to refresh the account list and all usage. Press d on a selected account, then y/Enter to confirm deletion (n/Esc cancels). Removing the active account immediately activates the next available account. Adding, switching, or removing accounts does not require restarting serve.

To reserve a saved account for particular models, press m from the main TUI or the account panel. Use j/k to select a model and Enter/Space to choose a saved account or automatic; press x to clear an assignment or a to enter a catalog id that is not listed yet. Changes apply to new requests immediately without changing the active account. Model-bound live runs, conversation checkpoints, KV state, and tool continuations are partitioned by account, so two models can use different accounts concurrently in one serve process. The TUI stores the stable account id; labels and emails remain useful selectors for headless configuration.

Point Claude Code at the proxy (Fable 5)

export ANTHROPIC_BASE_URL=http://127.0.0.1:18765
export ANTHROPIC_AUTH_TOKEN=unused
export ANTHROPIC_MODEL=claude-fable-5[1m]
export ANTHROPIC_SMALL_FAST_MODEL=claude-fable-5[1m]
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
export CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1
claude

Same keys work under "env" in ~/.claude/settings.json.

Always set ANTHROPIC_SMALL_FAST_MODEL to a full model id (same as ANTHROPIC_MODEL is fine). Otherwise Claude Code’s background small-model calls return HTTP 400.

<details> <summary>Codex / Kimi / Grok</summary>

claude-cursor-proxy codex auth login
ANTHROPIC_BASE_URL=http://127.0.0.1:18765 ANTHROPIC_AUTH_TOKEN=unused \
  ANTHROPIC_MODEL=gpt-5.6-sol[1m] ANTHROPIC_SMALL_FAST_MODEL=gpt-5.6-luna[1m] \
  CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1 \
  claude

claude-cursor-proxy kimi auth login   # or: grok auth login

</details>

Point grok-build at the proxy

grok-build 1.0.13 has two endpoint layers. Startup account settings and the model catalog use the global GROK_CLI_CHAT_PROXY_BASE_URL setting (or [endpoints].cli_chat_proxy_base_url); a [model.*].base_url only controls inference after startup. Point the global endpoint at this proxy as well as each model block below. The environment variable is convenient for a one-shot run; the TOML setting is persistent.

1. Log in (once) and start the proxy

claude-cursor-proxy grok auth login      # required for grok-4.5 / grok-4.6 chat
claude-cursor-proxy cursor auth login    # only if you also route Fable / Composer
claude-cursor-proxy serve                # 127.0.0.1:18765

2. Edit ~/.grok/config.toml — set the global startup endpoint and override the official ids so Fast + effort menus stay enabled. Fast is reasoning.effort = "low".

# ~/.grok/config.toml

[endpoints]
# Grok startup settings/model-catalog requests (required for local proxy):
cli_chat_proxy_base_url = "http://127.0.0.1:18765/v1"
# Optional image/video tools (also a global endpoint):
xai_api_base_url = "http://127.0.0.1:18765/v1"

[auth]
# Do not let an expired grok.com OIDC token block local-proxy startup.
# The proxy uses its own saved upstream credential for these requests.
preferred_method = "api_key"

[model.grok-4.6]
base_url = "http://127.0.0.1:18765/v1"
api_key = "unused"

[model.grok-4.5]
base_url = "http://127.0.0.1:18765/v1"
api_key = "unused"

# Cursor catalog via grok-build (official OpenAI Responses, not Claude Messages)
[model.cursor-grok]
model = "cursor-grok-4.6-xhigh-fast"
base_url = "http://127.0.0.1:18765/v1"
api_backend = "responses"
api_key = "unused"

# Optional: Claude Code-style Anthropic Messages (not the grok-build default)
[model.via-ccp]
model = "claude-fable-5[1m]"
base_url = "http://127.0.0.1:18765/v1"
api_backend = "messages"
context_window = 1000000
api_key = "unused"
supports_reasoning_effort = true
reasoning_effort = "high"

3. Run grok-build

grok --model grok-4.6
# or: grok --model grok-4.5
# or: grok --model cursor-grok
# or: grok --model via-ccp

For a temporary shell/session, the equivalent global override is:

GROK_CLI_CHAT_PROXY_BASE_URL=http://127.0.0.1:18765/v1 \
  grok --model grok-4.6

Inbound api_key is accepted (Authorization: Bearer … or x-api-key; unused, other placeholders, and JWT-looking session tokens are treated as empty) and is not used as a user/tenant id. Grok /v1/responses passthrough forwards conversation, compaction (x-compaction-at, x-compactions-remaining), doom-loop, and a charset-limited x-grok-model-override — never Authorization, Cookie, or x-grok-user-id.

GET /v1/models advertises model, context_window, api_backend=responses (grok-build's official OpenAI Responses backend), supports_reasoning_effort, and reasoning_efforts (grok-4.6 includes xhigh / high / medium / low). A custom [model.*] block that omits api_backend defaults to Chat Completions in grok-build; set api_backend = "responses". This proxy does not implement /v1/chat/completions. /v1/messages remains for Claude Code.

Media routes (/v1/images/*, /v1/videos/*) proxy to https://api.x.ai/v1 (override with CCP_GROK_MEDIA_BASE_URL). A real client key is forwarded; placeholders and grok-build session JWTs fall back to the stored Grok OAuth token.

---

Models

Set ANTHROPIC_MODEL and ANTHROPIC_SMALL_FAST_MODEL to full model ids. Recommended Cursor default: claude-fable-5[1m].

Other backends use their own full ids (for example gpt-5.6-sol[1m], kimi-for-coding, grok-composer-2.5-fast). Unknown ids return 400.

How to list supported models

# Built-in registry
claude-cursor-proxy models
claude-cursor-proxy models --full

# While serve is running — Anthropic-compatib