# Cursor

The Cursor connector lets [Agent Mode](/use-groundcover/agent-mode.md) launch [Cursor Background Agents](https://docs.cursor.com/background-agent) on your repositories. When you ask Agent Mode to make a code change, it runs Cursor's cloud coding agent remotely using your Cursor API key, creating branches, writing code, and opening pull requests on your behalf.

{% hint style="info" %}
The Cursor connector must be enabled by a workspace admin before users can connect their accounts. See [Connectors](/use-groundcover/connectors.md) for details.
{% endhint %}

## Prerequisites

* A [Cursor](https://www.cursor.com/) account with API access
* A Cursor API key (generated from your Cursor account settings)
* The Cursor connector enabled for your organization (by an admin)

## Setup

### Generate a Cursor API Key

1. Open Cursor and go to **Settings → API Keys** (or visit your Cursor account settings page)
2. Create a new API key
3. Copy the key. You'll need it in the next step

### Connect Your Account in groundcover

1. Go to **Integrations → Connectors**
2. Select **Cursor Cloud Agent**
3. Paste your API key
4. Give the credential a name (e.g., `my-cursor-key`)
5. Click **Connect**

Once connected, you'll see the configuration page where you can set defaults.

## Configuration

After connecting, you can configure the following settings from **Integrations → Connectors → Cursor**:

| Setting                  | Description                                                                           | Default        |
| ------------------------ | ------------------------------------------------------------------------------------- | -------------- |
| **Default Repository**   | The repository the Agent uses when you don't specify one                              | None           |
| **Default Model**        | The AI model Cursor uses for code generation                                          | None           |
| **Create Pull Requests** | Whether Cursor automatically creates PRs when a job completes, or waits for approval  | Needs approval |
| **Create Branch**        | Whether Cursor automatically creates branches for code changes, or waits for approval | Auto           |
| **API Key**              | Your Cursor API key. Can be updated at any time                                       | -              |

{% hint style="info" %}
You can have multiple Cursor credentials connected to the same account. If you have more than one, the Agent will ask you which one to use.
{% endhint %}

## Using Cursor Through the Agent

### Starting a Code Change

Ask the Agent to make a code change in natural language:

> "Use Cursor to add a CPU limit of 500m to the checkout deployment in my-org/infra-manifests"

> "Use Cursor to scale up the payments deployment to 5 replicas in my-org/k8s-config"

The Agent will:

1. Select your Cursor connector (or ask you to choose if you have multiple)
2. Identify the target repository
3. Prepare the code change and present an **Approve** button

### Approval Flow

The Agent always asks for your permission before running Cursor. Before any code is changed, the Agent presents its plan and an **Approve Cursor Job** button in the conversation. Only after you click approve does the Agent send the instructions to Cursor for execution.

This ensures you stay in control. No code is modified without your explicit approval.

### Monitoring Progress

Once approved, the Agent displays a live status card showing:

* **Status**: The current state of the job (queued, running, completed, error, expired, cancelled)
* **Repository**: Which repo and branch Cursor is working on
* **Branch**: The branch created for the changes (once available)
* **Pull Request**: A link to the PR (once created)

You can check on a running job at any time:

> "What's the status of the Cursor job?"

### Following Up

While a Cursor job is running (or after it completes), you can send follow-up instructions:

> "Also update the HPA to match the new replica count"

> "The PR looks good but add a comment explaining why we raised the CPU limit"

Follow-ups also require approval before being sent.

### Cancelling a Job

To stop a running Cursor job:

> "Cancel the Cursor job"

## How It Works

When you use the Cursor connector through the Agent:

1. The Agent resolves your Cursor credentials from the connector you configured
2. It sends instructions to the Cursor Cloud API using your API key
3. Cursor's cloud coding agent runs remotely, cloning the repository, making changes, and pushing code
4. The Agent polls for status updates and displays progress in the conversation
5. When complete, Cursor creates a branch and (optionally) a pull request

All actions are performed using your Cursor API key and your permissions. groundcover acts as a proxy and does not store or access your source code.

## Troubleshooting

| Issue                            | Resolution                                                                                      |
| -------------------------------- | ----------------------------------------------------------------------------------------------- |
| "No active Cursor connectors"    | Ensure you've connected your Cursor account in **Integrations → Connectors**                    |
| "Connector not enabled"          | Ask a workspace admin to enable the Cursor connector for your organization                      |
| Agent can't find your repository | Verify the repository is accessible with your Cursor API key and try listing repositories first |
| Job fails with rate limit error  | Cursor enforces rate limits on API usage. Wait a few minutes and try again                      |
| Job status shows "expired"       | Cursor jobs have a time limit. Try again with a more focused prompt                             |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.groundcover.com/use-groundcover/connectors/cursor.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.