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