| 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 model accepted by the Cursor SDK. `auto` is sent to the SDK as its `default` model selection. |
| 12 | |
| 13 | The adapter currently uses the SDK's local-agent runtime so runs operate in the selected T3 Code |
| 14 | workspace. Cursor cloud agents need repository and cloud-environment configuration that T3 Code does |
| 15 | not expose yet. |
| 16 | |
| 17 | ## Sign in |
| 18 | |
| 19 | Choose **Sign in**, then open the sign-in page and complete it in your browser. T3 Code |
| 20 | updates automatically when sign-in finishes. This works when connected to a remote environment too. |
| 21 | On mobile, use **Settings > Provider accounts** for an already configured Cursor instance. |
| 22 | |
| 23 | Each provider instance keeps its own login on the environment that runs it. Your Cursor editor and |
| 24 | CLI login are separate. A configured `CURSOR_API_KEY` overrides browser sign-in; remove that override |
| 25 | to use the browser flow. |
| 26 | |
| 27 | Use **Change account** or **Sign out** in the same settings section. Both stop that |
| 28 | instance's running threads and keep their history. Sign-out forgets the saved credential; to revoke |
| 29 | the generated key before it expires, remove it from your Cursor dashboard's API keys. |
| 30 | |
| 31 | ## V2 Capability Mapping |
| 32 | |
| 33 | The adapter supports: |
| 34 | |
| 35 | - creating and resuming local Cursor agent threads; |
| 36 | - changing the model and model parameters between turns; |
| 37 | - assistant text, reasoning, tool activity, plans, and todo streaming; |
| 38 | - thread-scoped T3 Code MCP tools; |
| 39 | - image attachments; |
| 40 | - interruption, queued app messages, and orchestrator-owned interrupt/restart steering; |
| 41 | - provider conversation snapshots through `Agent.messages.list()`; |
| 42 | - Cursor `task` subagents, projected as read-only child app threads with their tool activity and |
| 43 | final result. |
| 44 | |
| 45 | The public SDK does not currently expose native agent fork, conversation rollback, active steering, |
| 46 | or interactive approval callbacks. Direct active steering is advertised as unsupported, while V2 |
| 47 | steering uses the orchestrator's interrupt-and-restart path and preserves the app run identity across |
| 48 | provider turns. Same-provider Cursor forks use the orchestrator's portable full-thread context |
| 49 | handoff into a fresh Cursor agent. The SDK has in-process custom callback tools, but the V2 adapter |
| 50 | intentionally uses the authenticated, thread-scoped MCP server instead. |
| 51 | |
| 52 | Portable handoffs summarize eligible timeline items and can omit the end of long messages. Read |
| 53 | [Context in portable handoffs](./portable-handoffs.md) before using a fork for work whose exact |
| 54 | instructions must carry forward. |
| 55 | |
| 56 | Cursor task events include an `agentId`, but the local SDK does not register that identifier as a |
| 57 | resumable agent: `Agent.resume()` returns `AgentNotFoundError`. The adapter therefore does not attach |
| 58 | a provider thread to native task projections or advertise subagent thread IDs. A projected child is |
| 59 | read-only: send messages from the parent thread. |
| 60 | |
| 61 | Runtime modes map to the controls the local SDK exposes: full access disables its sandbox, while |
| 62 | restricted modes and explicit non-full-access sandbox policies enable it. Explicit approval policy |
| 63 | overrides also control Cursor Auto-review. Auto-review is not represented as an interactive T3 Code |
| 64 | approval flow. |
| 65 | |
| 66 | The existing Cursor binary path and API endpoint settings belong to the CLI/ACP integration. Cursor |
| 67 | V2 execution does not launch that binary, and the SDK does not expose an API endpoint override. |
| 68 | |
| 69 | ## Replay And Live Testing |
| 70 | |
| 71 | Cursor replay fixtures preserve the SDK boundary: agent open/resume, sends, ordered `onDelta` |
| 72 | updates, terminal results, cancellation, message snapshots, and close. The real V2 adapter, |
| 73 | orchestrator, event store, projections, and checkpoint logic still run in tests. |
| 74 | |
| 75 | Record a fixture against the real SDK with: |
| 76 | |
| 77 | ```bash |
| 78 | pnpm --filter t3 record:cursor-replay --scenario simple |
| 79 | ``` |
| 80 | |
| 81 | Use `--out <path>` to record a temporary probe without replacing a checked-in fixture. Supported |
| 82 | scenarios are listed by the recorder when an invalid scenario is supplied. |