CCursor: pointing Cursor IDE at your own LLM API keys

A binary installer, not a source repository

The first thing to understand about this repository is that it is not one. The README says so plainly: the repository is for issue tracking and documentation only, and the source code is not published. What you install comes from npm as `@cometix/ccursor`, and the tree here holds only `LICENSE`, the English and Chinese READMEs, a logo image, and an `installer/` directory alongside a `Cursor++/` directory. There is nothing in the repository to read as source.

What you do get is a fairly complete architectural description, which is unusual and useful for a closed project. The package installs patches into Cursor in two places and adds an extension. One patch runs in the renderer and intercepts ConnectRPC and REST traffic. A second runs in the extension host and rewrites `http` and `https` request handling, reloading from a routes file so config changes apply without restarting the editor. The third piece is the Cursor++ extension itself, which hosts the BYOK server on `127.0.0.1:9960` using Fastify and ConnectRPC across 27 services, talks to providers through the Anthropic, OpenAI and Gemini SDKs, and runs a multi-round tool-calling orchestrator for agent work.

The README also states that every patch creates backup files and can be reversed through the uninstall command. That reversibility claim matters more than it sounds, because you are modifying the installation of a commercial application on your own machine and cannot read the code doing the modifying.

What BYOK mode changes and what it claims

The core pitch fits in one README sentence: use your own LLM API keys with Cursor IDE, Anthropic, OpenAI, Google Gemini or any OpenAI-compatible provider, without the official subscription. In practice the sidebar panel holds a toggle between BYOK mode and official Cursor, so you can move back to the paid service from inside the editor without reinstalling anything.

The features list is where the ambition shows. Cursor++ claims full agent mode with tool calling, multi-turn conversations, automatic summarization and checkpoint persistence, which is a bigger claim than a plain request rewriter, because agent mode depends on the editor's tool loop behaving correctly against a proxy it does not know about. It lists 22 agent tools including shell, read, grep, glob, string replace, write, task and MCP. Model configuration gets a visual panel with thinking level, context limits and variant display, and errors surface through Cursor's own retry banner with a retryable versus non-retryable classification rather than in a separate error surface.

Per-window logging means each editor window writes to its own log stream with colored output in a LogOutputChannel, which is the practical debugging path given there is no source to step through. One more feature deserves naming: hub integration through LinuxDO Connect using device authorization, which suggests some configuration is retrieved from a remote service rather than living entirely in local files. The project has a homepage at ccursor.cometix.dev for that hub, plus a LinuxDO discussion thread linked from the README.

Editing providers.json to describe an endpoint and its models

Three files live under `~/.ccursor/`: `providers.json` for provider endpoints, keys and model definitions, `routes.json` for the BYOK toggle and a redirect whitelist, and `cursor.db`, a SQLite file for conversation persistence. Only the first has a documented example, and it is worth reading closely because it tells you exactly what the proxy expects from an endpoint.

+{
  "providers": [
    {
      "id": "my-anthropic",
      "name": "Anthropic",
      "type": "anthropic",
      "baseUrl": "https://api.anthropic.com",
      "auth": { "kind": "apiKey", "value": "sk-ant-..." },
      "models": [
        {
          "id": "claude-sonnet-4",
          "apiModel": "claude-sonnet-4-20250514",
          "displayName": "Claude Sonnet 4",
          "thinking": true,
          "thinkingLevel": "medium",
          "contextTokenLimit": 200000,
          "defaultOn": true
        }
      ]
    }
  ]
}

Three fields carry most of the weight. `type` selects which provider path a request takes. `apiModel` is the identifier sent upstream, kept separate from the local `id` so a local alias can point at a dated model name. `defaultOn` marks a model as active without the user selecting it in the sidebar. The `thinking` and `thinkingLevel` pair is the interesting one for anyone with extended reasoning models, since it exposes reasoning effort as a per-model setting rather than a global one.

`contextTokenLimit` is declared per model rather than negotiated with the provider. That is worth keeping in mind: it is a value the editor uses for its own budgeting, so setting it wrong is more likely to produce a truncated context than a rejected request.

Installing, checking status and reversing the patches

The documented entry point is a single npx invocation, and the lifecycle is three commands:

npx @cometix/ccursor install
npx @cometix/ccursor status
npx @cometix/ccursor uninstall

After installing, you restart Cursor and open the Cursor++ sidebar panel to configure providers. The `status` command is the one to reach for first on a new machine, since the whole design assumes files inside the Cursor installation have been modified and you need to know whether the patches are currently in place. Uninstall is the way back, and the README's claim is that it reverses everything because each patch was backed up on the way in.

Platform support covers macOS on both ARM and Intel, Linux and Windows, with Cursor IDE and Node.js 18 or newer as the stated requirements. The npm package page is linked from the README badge at the top, which is where version numbers come from: the project tags 0.0.14, published on 2026-08-26, with a release body that is effectively empty. The last push to the repository was 2026-08-27. That is a pre-1.0 project with one tagged release, and the README is candid about where support happens, through GitHub issues and a LinuxDO thread rather than a tracker with triage.

The troubleshooting table is the real documentation

Three failure modes get their own rows in the README, and they are worth reading as the project's own statement of where it is fragile. The first is being unable to sign in after installing, with the fix being to toggle BYOK off in the sidebar and sign in normally. That tells you the patches touch the sign-in path as well as the model path, which is a wider blast radius than a proxy scoped to completions would have.

The second is a model not being found, fixed by adding it in the sidebar or editing `~/.ccursor/providers.json` directly. The third is an LLM request returning 401, 403 or 404, fixed by checking the API key and base URL in the same file. Notice what is missing: nothing about what to do when a Cursor update lands, when the extension host misbehaves, or what happens to in-flight conversations. Those are exactly the questions a reader would want answered before depending on this daily, and the README leaves them open.

The honest framing is that this is a patch that must be reapplied when the thing it patches changes. Cursor ships updates on its own schedule, and a proxy that rewrites request handling plus intercepts RPC has many places to break. The release tag is the best available signal about how often that has happened so far.

Who should install this

The clearest case for CCursor is someone who already pays an API provider directly and wants Cursor's editor behaviour without a separate subscription, or who needs to route requests to a self-hosted or OpenAI-compatible endpoint the editor will not talk to on its own. For that person the value is real: the README documents the interception path, the config schema and the error classification well enough to work from logs.

The clearest case against is anyone who needs to audit what runs inside their editor, or who cannot accept that an update to Cursor may break their setup on a Tuesday. The code is not published, so the patching logic cannot be read before it modifies a commercial application, and the only rollback path described is the uninstall command. The 17 open issues on the repository are the visible part of a discussion that otherwise lives in the linked LinuxDO thread.

The license is AGPL-3.0, which is worth noting for a project that patches and hosts local traffic: nobody is distributing a modified build here, so the copyleft obligations mostly do not bite, but the choice signals what the author considers the project's character.

Editorial conclusion

CCursor is interesting less as a configuration tool than as a demonstration that Cursor's model traffic can be redirected from a local process at all, and the README documents that mechanism unusually plainly for a closed-source project. Its limits are equally plain: the code is not published, the installer patches Cursor's own files, and a Cursor update can break those patches until the project catches up, which is why the 0.0.14 tag and a release history with a single entry matter more here than any feature count. Start with `npx @cometix/ccursor status`, keep `~/.ccursor/providers.json` out of version control, and read the troubleshooting table before you rely on it daily.

Frequently asked questions

Official sources

1. CometixSpace/CCursor on GitHub
2. License: AGPL-3.0
3. Project website
4. README
5. Releases