The best way to control Claude Code, Codex and more from any computer or phone
Mirrored from https://github.com/Camo67/t3code.git
Synced Nov 21, 03:37 UTC
| 1 | # Cursor |
| 2 | |
| 3 | Cursor V2 runs through the official [`@cursor/sdk`](https://cursor.com/docs/api/sdk/typescript) |
| 4 | TypeScript package. It does not use Cursor's ACP transport for V2 execution. |
| 5 | |
| 6 | ## Prerequisites |
| 7 | |
| 8 | - Node.js 22.13 or newer. The repository's supported Node version satisfies this requirement. |
| 9 | - Sign in with Cursor in **Settings > Providers > Cursor**, or provide a Cursor API key in |
| 10 | `CURSOR_API_KEY`. |
| 11 | - A paid Cursor plan on the account used for browser sign-in or `CURSOR_API_KEY`. |
| 12 | - A model accepted by the Cursor SDK. `auto` is sent to the SDK as its `default` model selection. |
| 13 | |
| 14 | The adapter currently uses the SDK's local-agent runtime so runs operate in the selected T3 Code |
| 15 | workspace. Cursor cloud agents need repository and cloud-environment configuration that T3 Code does |
| 16 | not expose yet. |
| 17 | |
| 18 | Custom Cursor MCP servers and plugins are not configured in T3 Code. They load from the environment |
| 19 | machine's Cursor config when the agent opens: project `.cursor/mcp.json`, user `~/.cursor/mcp.json`, |
| 20 | and installed plugins under `~/.cursor/plugins`. Plugin tools |
| 21 | can appear without a login; OAuth MCP servers still need credentials. Run `agent mcp login <server>` |
| 22 | with the cwd set to the T3 project root (tokens land in |
| 23 | `~/.cursor/projects/<folder-slug>/mcp-auth.json`). Cursor desktop Connections auth does not write |
| 24 | that file, and the local SDK cannot complete interactive MCP OAuth itself—auth attempts fail with |
| 25 | messages such as "MCP authentication is not supported in local SDK runs" or that the auth server |
| 26 | does not support dynamic client registration. After you add or change skills, plugins, or MCP |
| 27 | servers, or after a successful CLI login, use **Restart agent session**. |
| 28 | |
| 29 | ## Sign in |
| 30 | |
| 31 | Choose **Sign in**, then open the sign-in page and complete it in your browser. T3 Code |
| 32 | updates automatically when sign-in finishes. This works when connected to a remote environment too. |
| 33 | On mobile, use **Settings > Providers** for an already configured Cursor instance. |
| 34 | |
| 35 | Each provider instance keeps its own login on the environment that runs it. Your Cursor editor and |
| 36 | CLI login are separate. A configured `CURSOR_API_KEY` overrides browser sign-in; remove that override |
| 37 | to use the browser flow. |
| 38 | |
| 39 | Use **Change account** or **Sign out** in the same settings section. Both stop that |
| 40 | instance's running threads and keep their history. Sign-out forgets the saved credential; to revoke |
| 41 | the generated key before it expires, remove it from your Cursor dashboard's API keys. |
| 42 | |
| 43 | ## V2 Capability Mapping |
| 44 | |
| 45 | The adapter supports: |
| 46 | |
| 47 | - creating and resuming local Cursor agent threads; |
| 48 | - changing the model and model parameters between turns; |
| 49 | - assistant text, reasoning, tool activity, plans, and todo streaming; |
| 50 | - thread-scoped T3 Code MCP tools alongside ambient Cursor MCP/plugins from disk; |
| 51 | - image attachments; |
| 52 | - interruption, queued app messages, and in-turn steering; |
| 53 | - provider conversation snapshots through `Agent.messages.list()`; |
| 54 | - Cursor `task` subagents, projected as read-only child app threads with their tool activity and |
| 55 | final result. |
| 56 | |
| 57 | The public SDK does not currently expose native agent fork or interactive approval callbacks. A |
| 58 | text-only steer reaches the current run without restarting it. |
| 59 | When Cursor cannot deliver the steer, the same message is queued for the next turn after |
| 60 | this run finishes. If you press Stop, that follow-up stays held until you resume the queue. Steers |
| 61 | with attachments and provider or runtime changes that must apply immediately interrupt and restart |
| 62 | the run. |
| 63 | Same-provider Cursor forks use the orchestrator's portable full-thread context handoff into a fresh |
| 64 | Cursor agent. **Edit from here** and checkpoint rollback rewind the same Cursor agent to just before |
| 65 | the selected message, as `cursor-agent`'s `/rewind` does, so it keeps its exact earlier history. |
| 66 | Rewinding to the thread's first message starts a fresh Cursor agent instead. |
| 67 | The SDK has in-process custom callback tools, but the V2 adapter intentionally uses the |
| 68 | authenticated, thread-scoped MCP server instead. |
| 69 | |
| 70 | Portable handoffs summarize eligible timeline items and can omit the end of long messages. Read |
| 71 | [Context in portable handoffs](./portable-handoffs.md) before using a fork for work whose exact |
| 72 | instructions must carry forward. |
| 73 | |
| 74 | Cursor task events include an `agentId`, but the local SDK does not register that identifier as a |
| 75 | resumable agent: `Agent.resume()` returns `AgentNotFoundError`. The adapter therefore does not attach |
| 76 | a provider thread to native task projections or advertise subagent thread IDs. A projected child is |
| 77 | read-only: send messages from the parent thread. |
| 78 | |
| 79 | Runtime modes map to the controls the local SDK exposes: full access disables its sandbox, while |
| 80 | restricted modes normally enable it. On Windows, Auto and Supervised run without filesystem |
| 81 | isolation when Cursor Auto-review is enabled, because the SDK does not support a filesystem sandbox |
| 82 | there. Restricted modes without Auto-review, including the default Auto-accept edits mode, still |
| 83 | request the sandbox and cannot start on Windows. Explicit sandbox policies remain authoritative, |
| 84 | including restrictive policies that the Windows SDK rejects. Explicit approval policy overrides |
| 85 | control Auto-review, which is not represented as an interactive T3 Code approval flow. |
| 86 | |
| 87 | The existing Cursor binary path and API endpoint settings belong to the CLI/ACP integration. Cursor |
| 88 | V2 execution does not launch that binary, and the SDK does not expose an API endpoint override. |
| 89 | |
| 90 | ## Replay And Live Testing |
| 91 | |
| 92 | Cursor replay fixtures preserve the SDK boundary: agent open/resume, sends, ordered `onDelta` |
| 93 | updates, terminal results, cancellation, message snapshots, and close. The real V2 adapter, |
| 94 | orchestrator, event store, projections, and checkpoint logic still run in tests. |
| 95 | |
| 96 | Record a fixture against the real SDK with: |
| 97 | |
| 98 | ```bash |
| 99 | pnpm --filter t3 record:cursor-replay --scenario simple |
| 100 | ``` |
| 101 | |
| 102 | Use `--out <path>` to record a temporary probe without replacing a checked-in fixture. Supported |
| 103 | scenarios are listed by the recorder when an invalid scenario is supplied. |