|
1 | 1 | --- |
2 | | -title: "Cursor Integration" |
3 | | -description: "Use Cursor as an agent provider in ADE — launch sessions, route models, and track work through the Cursor SDK." |
| 2 | +title: "Cursor" |
| 3 | +description: "Run Cursor as an agent provider in ADE through the Cursor SDK — one of ADE's five agents, scoped to a lane." |
4 | 4 | icon: "arrow-pointer" |
5 | 5 | --- |
6 | 6 |
|
7 | | -## Overview |
| 7 | +[Cursor](https://cursor.com) runs inside ADE as one of its five agent providers, alongside Claude Code, Codex, Factory Droid, and OpenCode. ADE drives Cursor's agent through the official **Cursor SDK** — ADE owns the lane scope, permissions, and system prompt; the SDK owns the model and tool execution. |
8 | 8 |
|
9 | | -ADE integrates with [Cursor](https://cursor.com) in two ways: |
| 9 | +## Connect Cursor |
10 | 10 |
|
11 | | -1. **Launch Cursor from ADE** — open your project or a lane's worktree in Cursor from the Run tab |
12 | | -2. **Cursor as an agent provider** — use Cursor's AI agent as a chat provider inside ADE via the Cursor SDK |
| 11 | +Cursor chat authenticates with an API key. Add a Cursor API key in **Settings → AI**, or set `CURSOR_API_KEY` in the environment ADE launches from — ADE accepts either. |
13 | 12 |
|
14 | | -The SDK integration means Cursor's agent capabilities are available directly in ADE's chat interface, alongside Claude, Codex, and other providers. You can switch between providers per-session. |
15 | | - |
16 | | ---- |
17 | | - |
18 | | -## Requirements |
19 | | - |
20 | | -| Requirement | Details | |
21 | | -|------------|---------| |
22 | | -| **Cursor installed** | Cursor desktop app must be installed to launch Cursor from ADE | |
23 | | -| **Cursor SDK auth** | Cursor chat requires `CURSOR_API_KEY` or a Cursor API key saved in ADE Settings | |
24 | | -| **Authentication** | ADE uses API-key authentication for Cursor chat. Cursor desktop sign-in is only needed for launching the editor. | |
25 | | - |
26 | | -ADE checks Cursor API-key authentication during onboarding and in **Settings → AI**. When `CURSOR_API_KEY` is present, ADE recognizes it as a valid authentication signal. You can also save the key in ADE's encrypted provider settings. |
27 | | - |
28 | | ---- |
29 | | - |
30 | | -## Launching Cursor from ADE |
31 | | - |
32 | | -Open the **Run** tab and click the **Cursor** launcher. ADE opens the current project (or the selected lane's worktree) in Cursor as a separate application window. |
33 | | - |
34 | | -The session is linked back to the active lane for tracking. File changes made in Cursor appear in the lane's diff view as soon as they are saved. |
35 | | - |
36 | | ---- |
37 | | - |
38 | | -## Cursor as an agent provider |
39 | | - |
40 | | -When Cursor API-key auth is configured, ADE can use Cursor as a chat provider through the **Cursor SDK**. |
41 | | - |
42 | | -### How it works |
43 | | - |
44 | | -1. ADE starts an isolated SDK worker for the active lane |
45 | | -2. The worker creates or resumes a Cursor SDK agent with the selected model |
46 | | -3. Chat messages are routed through SDK runs, and Cursor has access to the `ade` CLI for ADE workflows |
47 | | -4. Model discovery queries Cursor SDK metadata for available models and capabilities |
48 | | - |
49 | | -### Selecting Cursor in chat |
50 | | - |
51 | | -In any Agent Chat session, use the **model selector** in the chat header to choose a Cursor-provided model. Models discovered from Cursor appear alongside Claude, GPT, and other configured providers. |
52 | | - |
53 | | -### Model discovery |
54 | | - |
55 | | -ADE queries Cursor for its available models at startup and caches the result. The discovered models appear in: |
56 | | -- The chat model selector |
57 | | -- The worker run model configuration |
58 | | -- The unified model selector throughout the app |
59 | | - |
60 | | -### Session behavior |
61 | | - |
62 | | -| Behavior | Details | |
63 | | -|----------|---------| |
64 | | -| **Session lifecycle** | Managed by the Cursor SDK pool; sessions are reused when possible | |
65 | | -| **Event mapping** | SDK events are mapped to ADE's chat event model for consistent UI | |
66 | | -| **ADE CLI access** | The `ade` CLI is on `PATH` so Cursor agents can call ADE lane, git, PR, and action tools | |
67 | | -| **Interrupts** | Supported via SDK run cancel | |
68 | | - |
69 | | ---- |
70 | | - |
71 | | -## Connection status |
72 | | - |
73 | | -ADE shows Cursor's connection status in **Settings → AI**: |
74 | | - |
75 | | -| Status | Meaning | |
76 | | -|--------|---------| |
77 | | -| **Connected** (green) | Cursor API key found and ready | |
78 | | -| **Not authenticated** (amber) | Cursor API key is missing or invalid | |
79 | | -| **Not found** (gray) | Cursor desktop is not detected for editor launch | |
80 | | - |
81 | | ---- |
82 | | - |
83 | | -## Troubleshooting |
| 13 | +Once connected, ADE discovers Cursor's available models and they appear in the model picker alongside every other provider. Pick one in any chat header to route that session through Cursor. |
84 | 14 |
|
85 | 15 | <AccordionGroup> |
86 | | - <Accordion title="Cursor not detected" icon="circle-question"> |
87 | | - ADE checks standard installation paths for the Cursor desktop app when launching the editor. If Cursor is installed in a non-standard location, open the project directly from Cursor or add the app to the standard Applications location. |
| 16 | + <Accordion title="How the SDK provider works" icon="gear"> |
| 17 | + When a Cursor key is configured, ADE runs the official `@cursor/sdk` in a Node worker pool. The worker creates or resumes a Cursor SDK agent with the selected model in the active lane's worktree, and routes chat turns through SDK runs. Sessions are pooled and reused, SDK events map to ADE's chat event model, and interrupts cancel the run. Because the `ade` CLI is on `PATH`, Cursor agents can call ADE's lane, git, PR, and action tools. |
| 18 | + </Accordion> |
| 19 | + <Accordion title="Connection status" icon="signal"> |
| 20 | + ADE shows Cursor's status in **Settings → AI**: |
| 21 | + |
| 22 | + | Status | Meaning | |
| 23 | + |--------|---------| |
| 24 | + | **Connected** (green) | Cursor API key found and ready. | |
| 25 | + | **Not authenticated** (amber) | Cursor API key is missing or invalid. | |
88 | 26 | </Accordion> |
89 | | - <Accordion title="Authentication failed" icon="lock"> |
90 | | - Add a Cursor API key in **Settings → AI Providers** or set `CURSOR_API_KEY` in the environment used to launch ADE. |
| 27 | + <Accordion title="Cursor Agent CLI in the Work tab" icon="terminal"> |
| 28 | + You can also launch the `cursor-agent` CLI as a tracked terminal session in the Work tab. ADE probes `cursor-agent` for CLI-only models and merges them into the picker, so the chat-vs-CLI distinction stays clear. This needs the `cursor-agent` binary on your `PATH`. |
91 | 29 | </Accordion> |
92 | | - <Accordion title="Models not appearing" icon="list"> |
93 | | - Model discovery runs at ADE startup. If you installed Cursor after starting ADE, restart ADE or go to **Settings → AI** and click **Refresh** to re-run model discovery. |
| 30 | + <Accordion title="Cursor Cloud agents" icon="cloud"> |
| 31 | + Kick off Cursor's hosted cloud agents from ADE and follow them in a lane: |
| 32 | + |
| 33 | + ```bash |
| 34 | + ade cursor cloud agents list --text |
| 35 | + ade cursor cloud agents create --repo https://github.com/owner/repo --prompt "fix flaky test" --auto-pr |
| 36 | + ``` |
| 37 | + |
| 38 | + The chat panel can open a cloud agent as an ADE chat (replies still run in the cloud) or jump to it on cursor.com. |
94 | 39 | </Accordion> |
95 | | - <Accordion title="Session errors" icon="circle-exclamation"> |
96 | | - If SDK sessions fail, check that the Cursor API key is configured and that the selected model is available. Check ADE's developer logs (**Settings → Developer → Log file**) for detailed SDK worker errors. |
| 40 | + <Accordion title="Troubleshooting" icon="circle-question"> |
| 41 | + - **Authentication failed** — add a Cursor API key in **Settings → AI**, or set `CURSOR_API_KEY` in ADE's launch environment. |
| 42 | + - **Models not appearing** — discovery serves last-known-good rows and revalidates in the background. If Cursor was just connected, restart ADE or refresh in **Settings → AI**. |
| 43 | + - **Session errors** — confirm the key is valid and the selected model is available; check developer logs at **Settings → Developer → Log file**. |
97 | 44 | </Accordion> |
98 | 45 | </AccordionGroup> |
| 46 | + |
| 47 | +<CardGroup cols={2}> |
| 48 | + <Card title="AI providers" icon="brain" href="/configuration/ai-providers"> |
| 49 | + Connect each agent and set defaults. |
| 50 | + </Card> |
| 51 | + <Card title="Agent chat" icon="comments" href="/chat/overview"> |
| 52 | + Run Cursor in a lane and compare it with other providers. |
| 53 | + </Card> |
| 54 | +</CardGroup> |
0 commit comments