@devries-cameron20 / t3code Mirror · read-only
Fork 0

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

main
md 103 lines 5.89 KB
Rendered Raw
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.