Cursor Agents Integration

HighFly integrates with Cursor Cloud Agents to enable AI-powered code generation directly from your issues. Launch agents to automatically implement features, fix bugs, and create pull requests.

Overview

Cursor Agents are AI-powered coding assistants that can:

• Generate code based on issue descriptions
• Create pull requests automatically
• Work on specific branches in your GitHub repositories
• Use different AI models based on your preferences

Connecting Your Cursor Account

Prerequisites

• A Cursor account with API access
• A Cursor API key (obtainable from your Cursor Dashboard)
• Important: Ensure your Cursor privacy settings are not set to "Privacy Mode (Legacy)" as this disables cloud agents. Check your Cursor Settings to verify.

Setup Steps

1. Navigate to your organization's Settings
2. Go to "Connected Accounts"
3. Find the "Cursor Account" section
4. Click "Connect Account"
5. Enter your Cursor API key
6. Click "Connect"

Your Cursor account is now connected and ready to use.

Configuring Preferences

Once connected, you can configure default settings for Cursor agents:

Default Repository

Set a default GitHub repository that will be pre-filled when launching agents:

1. Go to Settings → Connected Accounts → Cursor
2. Under "Preferences", find "Default GitHub Repository"
3. Select a repository from your available repositories, or enter a repository URL manually
4. Click "Save Settings"

Note: The repository list is automatically synced from Cursor and refreshed every 2 minutes.

Default Model

Choose a default AI model for your agents:

1. Under "Preferences", find "Default Model"
2. Select from available models:
   • Auto (Recommended): Lets Cursor choose the most appropriate model
   • Specific models: Choose a model like claude-4-sonnet-thinking, o3, etc.
3. Click "Save Settings"

The model list is automatically synced from Cursor when repositories are refreshed.

Auto-Create Pull Requests

Enable automatic pull request creation when agents complete their work:

1. Under "Preferences", toggle "Default: Auto create a pull request"
2. When enabled, agents will automatically create PRs upon completion
3. Click "Save Settings"

Launching Agents from Issues

Basic Launch

1. Open any issue in HighFly
2. Click the "Build with Cursor" button
3. The launch dialog will appear with pre-filled values from your preferences
4. Configure the launch:
   • GitHub Repository: Select or enter the repository URL
   • Branch Name (Optional): Specify a branch name, or leave empty for auto-generation
   • Model (Optional): Override your default model for this launch
   • Automatically Create Pull Request: Toggle PR creation for this launch
5. Click "Launch Agent"

The agent will start working on the issue, using the issue title and description as the prompt.

Agent Workflow

1. Agent Launch: The agent is created with your issue details
2. Code Generation: The agent analyzes the issue and generates code
3. Branch Creation: A new branch is created (or uses your specified branch)
4. Pull Request (if enabled): A PR is automatically created when work is complete
5. Webhook Updates: HighFly receives updates about the agent's progress

Viewing Agent Status

After launching an agent:

• A link to view the agent in Cursor is provided
• Agent status is tracked in HighFly
• You can view agent progress and results in Cursor's interface

Model Selection

Choosing a Model

• Auto is recommended for most use cases
• Use specific models when you need particular capabilities or performance characteristics
• You can override your default model for individual agent launches

Best Practices

Issue Descriptions

Write clear, detailed issue descriptions to help agents understand the task:

• Include context about what needs to be implemented
• Specify any requirements or constraints
• Mention related files or components if relevant
• Include examples or expected behavior

Repository Selection

• Use your default repository for consistency
• Ensure the repository has the necessary dependencies and setup
• Verify you have write access to the repository

Branch Naming

• Let HighFly auto-generate branch names for consistency
• Or use descriptive names like feature/add-authentication or fix/login-bug
• Branch names are automatically prefixed with cursor/ when auto-generated. You can predefine the prefixes in your Cursor Settings

Pull Request Management

• Enable auto-create PRs for faster workflow
• Review generated code before merging
• Use PR comments to request changes or refinements

Troubleshooting

Can't connect account: Verify your Cursor API key is correct and has the necessary permissions. Check that you have an active Cursor subscription.

Cloud agents disabled: If you're unable to launch agents, verify that your Cursor privacy settings are not set to "Privacy Mode (Legacy)". This mode disables cloud agents. Update your settings in Cursor Settings → Privacy and ensure you're not using the legacy privacy mode.

Repository not appearing: Repositories are synced from Cursor. Wait a few minutes and refresh, or manually enter the repository URL. Note that repository syncing has rate limits (1 request per minute, 30 per hour).

Agent launch fails:

• Verify the repository URL is correct and accessible
• Ensure you have write access to the repository
• Check that your Cursor API key is valid and not expired
• Review the error message for specific issues

Model not available: Models are synced from Cursor. If a model doesn't appear, it may not be available for your account or subscription tier.

Webhook not receiving updates:

• In development, ensure you're running the smee client for webhook forwarding
• In production, verify webhook configuration in your environment variables
• Check that CURSOR_WEBHOOK_SECRET is set correctly

Preferences not saving: Ensure you're connected to Cursor and that the repository/model you're selecting is in your available lists.

For additional help, check the Support & Resources page.