Integrations JetBrains Use Cursor's AI agent in IntelliJ IDEA, PyCharm, WebStorm, and other JetBrains IDEs through the Agent Client Protocol (ACP). ACP lets you stay in your JetBrains IDE while Cursor handles agent-driven development. You get access to frontier models from OpenAI, Anthropic, Google, and Cursor, along with secure codebase indexing and semantic search. Prerequisites A paid Cursor plan A JetBrains IDE with the AI Assistant plugin enabled (2025.1+) Get started 1 Open the AI Chat plugin Open the AI Chat panel in your JetBrains IDE. You can find it in the right sidebar or through View > Tool Windows > AI Chat . 2 Install Cursor from the ACP registry In the AI Chat panel, open the agent provider list and select Add Agent from Registry . Search for Cursor and install it. 3 Authenticate After installing, select Cursor as your agent provider. 4 Start coding Send a prompt in the AI Chat panel. Cursor's agent reads your project, edits files, runs terminal commands, and creates code directly in your JetBrains IDE. What you get Cursor ACP in JetBrains IDEs provides many of the same agent capabilities available across other Cursor surfaces. Model selection — Choose from frontier models suited to your task. Different models handle different kinds of work better; switch between them as needed. Codebase understanding — Cursor indexes your codebase and uses semantic search to find relevant code across large projects. File editing — The agent reads and writes files in your project, with changes reflected in your JetBrains editor. Terminal commands — The agent runs shell commands in the IDE's integrated terminal. How it works Cursor ACP uses the Agent Client Protocol , an open standard for connecting AI agents to IDEs. Your JetBrains IDE acts as the ACP client, and Cursor's agent acts as the server. When you send a prompt, the AI Chat plugin forwards it to Cursor's agent through ACP. The agent processes your request, reads your project files, and streams edits and terminal commands back to the IDE. Pricing Cursor ACP uses the same usage-based pricing as your Cursor subscription. See pricing for details. Related ACP reference Full ACP protocol details, transport, and client examples Models Available models and their capabilities English English 简体中文 日本語 繁體中文 Español Français Português 한국어 Русский Türkçe Bahasa Indonesia Deutsch हिन्दी

CLI Using Headless CLI Use Cursor CLI in scripts and automation workflows for code analysis, generation, and refactoring tasks. How it works Use print mode ( -p, --print ) for non-interactive scripting and automation. File modification in scripts Combine --print with --force (or --yolo ) to modify files in scripts: # Enable file modifications in print mode agent -p --force "Refactor this code to use modern ES6+ syntax" # Without --force, changes are only proposed, not applied agent -p "Add JSDoc comments to this file" # Won't modify files # Batch processing with actual file changes find src/ -name "*.js" | while read file ; do agent -p --force "Add comprehensive JSDoc comments to $file " done The --force flag allows the agent to make direct file changes without confirmation Setup See Installation and Authentication for complete setup details. # Install Cursor CLI (macOS, Linux, WSL) curl https://cursor.com/install -fsS | bash # Install Cursor CLI (Windows PowerShell) irm 'https://cursor.com/install?win32=true' | iex # Set API key for scripts export CURSOR_API_KEY = your_api_key_here agent -p "Analyze this code" Example scripts Use different output formats for different script needs. See Output format for details. Searching the codebase By default, --print uses text format for clean, final-answer-only responses: #!/bin/bash # Simple codebase question - uses text format by default agent -p "What does this codebase do?" Automated code review Use --output-format json for structured analysis: #!/bin/bash # simple-code-review.sh - Basic code review script echo "Starting code review..." # Review recent changes agent -p --force --output-format text \ "Review the recent code changes and provide feedback on: - Code quality and readability - Potential bugs or issues - Security considerations - Best practices compliance Provide specific suggestions for improvement and write to review.txt" if [ $? -eq 0 ]; then echo "✅ Code review completed successfully" else echo "❌ Code review failed" exit 1 fi Real-time progress tracking Use --output-format stream-json for message-level progress tracking, or add --stream-partial-output for incremental streaming of deltas: #!/bin/bash # stream-progress.sh - Track progress in real-time echo "🚀 Starting stream processing..." # Track progress in real-time accumulated_text = "" tool_count = 0 start_time = $( date +%s ) agent -p --force --output-format stream-json --stream-partial-output \ "Analyze this project structure and create a summary report in analysis.txt" | \ while IFS = read -r line ; do type = $( echo " $line " | jq -r '.type // empty' ) subtype = $( echo " $line " | jq -r '.subtype // empty' ) case " $type " in "system" ) if [ " $subtype " = "init" ]; then model = $( echo " $line " | jq -r '.model // "unknown"' ) echo "🤖 Using model: $model " fi ;; "assistant" ) # Only process streaming deltas (timestamp_ms present, no model_call_id). # Skip buffered flushes before tool calls and at end of turn. has_ts = $( echo " $line " | jq 'has("timestamp_ms")' ) has_mc = $( echo " $line " | jq 'has("model_call_id")' ) if [ " $has_ts " = "true" ] && [ " $has_mc " = "false" ]; then content = $( echo " $line " | jq -r '.message.content[0].text // empty' ) accumulated_text = " $accumulated_text$content " printf "\r📝 Generating: %d chars" ${ # accumulated_text} fi ;; "tool_call" ) if [ " $subtype " = "started" ]; then tool_count = $(( tool_count + 1 )) # Extract tool information if echo " $line " | jq -e '.tool_call.writeToolCall' > /dev/null 2>&1 ; then path = $( echo " $line " | jq -r '.tool_call.writeToolCall.args.path // "unknown"' ) echo -e "\n🔧 Tool # $tool_count : Creating $path " elif echo " $line " | jq -e '.tool_call.readToolCall' > /dev/null 2>&1 ; then path = $( echo " $line " | jq -r '.tool_call.readToolCall.args.path // "unknown"' ) echo -e "\n📖 Tool # $tool_count : Reading $path " fi elif [ " $subtype " = "completed" ]; then # Extract and show tool results if echo " $line " | jq -e '.tool_call.writeToolCall.result.success' > /dev/null 2>&1 ; then lines = $( echo " $line " | jq -r '.tool_call.writeToolCall.result.success.linesCreated // 0' ) size = $( echo " $line " | jq -r '.tool_call.writeToolCall.result.success.fileSize // 0' ) echo " ✅ Created $lines lines ( $size bytes)" elif echo " $line " | jq -e '.tool_call.readToolCall.result.success' > /dev/null 2>&1 ; then lines = $( echo " $line " | jq -r '.tool_call.readToolCall.result.success.totalLines // 0' ) echo " ✅ Read $lines lines" fi fi ;; "result" ) duration = $( echo " $line " | jq -r '.duration_ms // 0' ) end_time = $( date +%s ) total_time = $(( end_time - start_time )) echo -e "\n\n🎯 Completed in ${ duration }ms (${ total_time }s total)" echo "📊 Final stats: $tool_count tools, ${ # accumulated_text } chars generated" ;; esac done Working with images To send images, media files, or other binary data to the agent, include file paths in your prompts. The agent can read any files through tool calling, including images, videos, and other formats. Including file paths in prompts Simply reference file paths in your prompt text. The agent will automatically read the files when needed: # Analyze an image agent -p "Analyze this image and describe what you see: ./screenshot.png" # Process multiple media files agent -p "Compare these two images and identify differences: ./before.png ./after.png" # Combine file paths with text instructions agent -p "Review the code in src/app.ts and the design mockup in designs/homepage.png. Suggest improvements to match the design." How it works When you include file paths in your prompt: The agent receives your prompt with the file path references The agent uses tool calling to read the files automatically Images are handled transparently You can reference files using relative or absolute paths Example: Image analysis script #!/bin/bash # analyze-image.sh - Analyze images using the headless CLI IMAGE_PATH = "./screenshots/ui-mockup.png" agent -p --output-format json \ "Analyze this image and provide a detailed description: $IMAGE_PATH " | \ jq -r '.result' Example: Batch media processing #!/bin/bash # process-media.sh - Process multiple media files for image in images/*.png ; do echo "Processing $image ..." agent -p --output-format text \ "Describe what's in this image: $image " > "${ image % . png }.description.txt" done File paths can be relative to the current working directory or absolute paths. The agent will read files through tool calls, so ensure the files exist and are accessible from where you run the command. English English 简体中文 日本語 繁體中文 Español Français Português 한국어 Русский Türkçe Bahasa Indonesia Deutsch हिन्दी

Cloud Agents Setup Cloud agents run on isolated Ubuntu machines. Configure the environment so the agent has the same repos, tools, dependencies, secrets, and network access a developer would use. Create a new environment in your Cloud Agents dashboard . Environment options There are two main ways to configure the environment for your cloud agent: Let Cursor's agent set up its own environment from the Cloud Agents dashboard . After the agent is done, you will have the option to create a snapshot of its virtual machine that can be reused for future agents. Manually configure the environment with a Dockerfile. If you choose this option, you can specify the Dockerfile in a .cursor/environment.json file. Both options generate an environment, and also allow you to specify an update command that will be run before the agent starts to ensure that its dependencies are up to date (e.g. npm install , pip install , etc.). Multi-repo environments Use a multi-repo environment when an agent needs to work across more than one repository. Select multiple repositories when you create the environment. Cursor clones each selected repo into the agent machine and reuses the environment for future agent runs and automations that use the same repo group. Multi-repo environments are useful when your frontend, backend, infrastructure, or shared libraries live in separate repos. The agent can inspect the full workspace, make coordinated changes, run tests across repos, and open pull requests in the repos it changes. You can see which environment is active, along with all past active versions, by visiting the environment's configuration page on the Cloud Agents dashboard . Environment resolution order Cursor resolves environment configuration by repository or repo group, using the first match: .cursor/environment.json in the repository A personal saved environment A team saved environment This gives you predictable defaults at the team level while still letting individual users override with a personal environment when a repo-level .cursor/environment.json is not present. User overrides are also useful to allow testing out a new environment configuration before rolling it out to the entire team. Agent-driven setup (recommended) You will be asked to connect your GitHub or GitLab account and select one or more repositories. Then, you provide Cursor with the environment variables and secrets it will need to install dependencies and run the code. Finally, after Cursor has installed dependencies and verified the code is working, you can save a snapshot of its virtual machine to be reused for future agents. Manual setup with Dockerfile (advanced) For advanced cases, configure the environment with a Dockerfile: Create a Dockerfile to install system-level dependencies, use specific compiler versions, install debuggers, or switch the base OS image Do not COPY the full project; Cursor manages the workspace and checks out the correct commit Edit .cursor/environment.json directly to configure runtime settings Use build secrets for private package registries or build-time credentials Here's an example .cursor/environment.json referencing a .cursor/Dockerfile (relative path) and a custom_script.sh install script: { "build" : { "dockerfile" : "Dockerfile" , "context" : ".." }, "install" : "pnpm install && ./custom_script.sh" } If your repo needs Docker or Tailscale, see Running Docker and Running Tailscale below. You configure the environment with a Dockerfile; you do not get direct access to the remote machine. Dockerfile builds use layer caching. When you change a Dockerfile, Cursor rebuilds the changed layers instead of rebuilding every layer from scratch. Cursor-configured Dockerfiles (private beta) For teams that do not want to write a Dockerfile from scratch, Cursor can configure one for you. During setup, Cursor inspects your repos, identifies tools and dependencies, and produces a Dockerfile-based environment configuration you can edit and version. This flow is in private beta for Enterprise teams. To request access, contact your Cursor account representative or email hi@cursor.com from your team admin account. Computer Use Support for Dockerfile Repos Computer use is supported for repos with Dockerfiles based on Debian/Ubuntu-based Linux distributions. If you require support for a different Linux distribution, please contact support. Resource limits Each cloud agent runs on a default VM profile with limited memory and CPU. If you are on an Enterprise plan and your repo needs more resources, contact support and we can increase limits for your workspace. Self-serve custom resource configuration is coming soon. Update command When a new machine boots, Cursor starts from the base environment, then runs the update command (called install in environment.json ). For most repos, the update script is npm install , bazel build , or a similar dependency setup command. Update script idempotency The update script must be idempotent. It can run more than once, and it may run on partially cached state. How caching works After update completes, if it took more than a few seconds to run, Cursor will take an internal checkpoint snapshot and will attempt to start future cloud agents from this checkpoint. This is why update commands like pnpm install usually lead to fast startup - if dependencies changed, the command only needs to do incremental work. Caching is best effort; you may see slower startup times on infrequently used repositories. Environment configuration recovery Agents no longer hard fail when Cursor can recover from an environment configuration issue. Saved environments often start from a snapshot. If the requested snapshot cannot be used, Cursor falls back to the default base image and warns you. Cursor falls back when: The snapshot expired after inactivity The snapshot is invalid or failed You do not have access to the snapshot When fallback happens, Cursor keeps the rest of the environment configuration and swaps the image back to the default base image. The update command still runs, so dependency setup can repair the environment during startup. The agent view shows Environment ready (with warnings) and a warning banner explaining what happened. The warning stays visible in the conversation as an environment configuration issue card. Open setup from the warning to inspect or repair the environment. Cursor does not automatically switch to an older saved environment version. If you want to roll back the saved configuration, open the environment from the Cloud Agents dashboard , review Version history , and restore a previous version. How to decide what to put in your update script There is a tradeoff between caching work in update and doing setup on demand during a run. Placing infrequently run or expensive commands (such as starting services or building docker images) in update can slow down startup time. A practical pattern is to run basic cached dependency updates (such as pnpm install ) in your update script, then adding instructions in AGENTS.md so the agent can figure out which commands it needs to run for each specific task. Startup commands After install , the machine starts and runs the start command, then any configured terminals . Use this to start processes that should stay alive while the agent runs. You can skip start in many repos. If your environment depends on Docker, add sudo service docker start in start . terminals are for app code processes. These terminals run in a tmux session shared by you and the agent. Add cloud-specific instructions to AGENTS.md Cloud agents read AGENTS.md files. We recommend adding a dedicated section for Cloud-only setup and testing instructions, with a title such as Cursor Cloud specific instructions . If this section gets large, we recommend including references to other files that can contain detailed instructions for specific tasks. See our AGENTS.md docs for more information. Environment variables and secrets Cloud agents need environment variables and secrets such as API keys and database credentials. Recommended: use the Secrets tab in Cursor settings The easiest way to manage secrets is through cursor.com . Add secrets as key-value pairs. Secrets are: Encrypted at rest with KMS Exposed to cloud agents as environment variables Scoped to the user, team, or environment you choose As an additional level of security, you have the option to specify secrets as redacted. Redacted secrets are scanned in commits the agent makes to prevent the agent from accidentally committing secrets to the repository. They are also redacted in the tool call results so they are not exposed to the agent, or stored in the chat transcript. Environment-scoped secrets Use environment-scoped secrets when a credential should only be available to agents that use one environment. This is useful for multi-repo environments, staging credentials, or repository groups with different access needs. Environment-scoped secrets apply to every repo in that environment. They are not available to other environments. Sign-in credentials and 2FA If your app requires login, add the same credentials you use locally as secrets, such as a username, email, and password. If your login flow uses TOTP-based 2FA, add the TOTP secret, sometimes called the shared or root secret, as a secret too. The agent can generate the current 6-digit code with oathtool --totp -b "$TOTP_SECRET" . Monorepos with multiple .env files If your monorepo has multiple .env.local files: Add values from all .env.local files to the same Secrets tab Use unique variable names when keys overlap, such as NEXTJS_* and CONVEX_* Reference those variables from each app as needed If you include .env.local files while taking a snapshot, they can be saved and available to cloud agents. The Secrets tab remains the recommended approach for security and management. Using AWS IAM Roles Cursor supports assuming customer-provided IAM roles for deeper integration with AWS. This allows you to grant specific AWS permissions to cloud agents without sharing long-lived credentials. Create the IAM role : In your AWS account, create the IAM role that you'd like the cloud agent to assume, and note its ARN (e.g. arn:aws:iam::123456789012:role/acmeRole ). Configure the IAM role secret : Navigate to Cursor Dashboard → Cloud Agents , and add a user or team secret named CURSOR_AWS_ASSUME_IAM_ROLE_ARN set to the ARN of the IAM role you created. Generate an external ID : Navigate to Cursor Dashboard → Settings and find the External ID settings. If you don't see an external ID displayed, enter a placeholder value in the "AWS IAM Role ARN" field, click "Validate & Save", and reload the page. This will generate an external ID for your team (e.g. cursor-xxx-yyy-zzz ). Configure IAM role trust policy : In your AWS account, update the IAM role's trust policy to trust Cursor's role assumer. The trust policy should look like this: { "Version" : "2012-10-17" , "Statement" : [ { "Sid" : "AllowCursorAssume" , "Effect" : "Allow" , "Principal" : { "AWS" : "arn:aws:iam::289469326074:role/roleAssumer" }, "Action" : "sts:AssumeRole" , "Condition" : { "StringEquals" : { "sts:ExternalId" : "cursor-xxx-yyy-zzz" } } } ] } Replace cursor-xxx-yyy-zzz with the external ID generated for your team. Environment variables: When configured, Cursor sets these environment variables so AWS tooling uses the cursor-cloud-agent profile: AWS_CONFIG_FILE points to a Cursor-managed AWS config file AWS_PROFILE is set to cursor-cloud-agent AWS_SDK_LOAD_CONFIG is set to 1 The AWS CLI and AWS SDKs that use the default credential chain pick up this profile automatically during setup commands and while the agent is running. You don't need to export AWS_ACCESS_KEY_ID , AWS_SECRET_ACCESS_KEY , or AWS_SESSION_TOKEN yourself. Cursor assumes the role with STS credentials that expire after 1 hour. When the agent wakes, Cursor refreshes credentials that are missing, invalid, or within 15 minutes of expiration. Build secrets During builds of Dockerfiles set in .cursor/environment.json , build secrets can be set at the team level from the Cloud Agents dashboard . Reference them from a RUN step in your Dockerfile using a Docker secret mount : RUN --mount=type=secret,id=MY_TOKEN,env=MY_TOKEN,required=true \ ./scripts/install-private-deps.sh Build secrets are scoped to the build step and aren't passed to the running agent's environment. Configuration in code with environment.json If you prefer to keep your environment configuration defined in code, you can commit a .cursor/environment.json to your repository. Cloud agents will use the configuration at the commit they start from, so to test a new configuration, you can commit and push the change to a new branch, and start a cloud agent from that branch. Sample environment.json using a snapshot-based config (the snapshot ID is accessible from the environments page of the dashboard): { "snapshot" : "snapshot-20260212-00000000-0000-0000-0000-000000000000" , "install" : "npm install" } Here is a sample .cursor/environment.json referencing a .cursor/Dockerfile (relative path) and a custom_script.sh install script: { "build" : { "dockerfile" : "Dockerfile" , "context" : ".." }, "install" : "pnpm install && ./custom_script.sh" } Important path behavior The dockerfile and context paths in build are relative to .cursor . The install command runs from your project root. The full schema is defined here . Running Docker Cloud agents support Docker workflows. We use this internally for full-stack repos that run many services. For simple setups, installing Docker is often enough. Commands like docker run hello-world usually work once Docker is installed and the daemon is running. Docker has edge cases in Cloud Agents because it runs inside another container layer. Simple workflows usually work. More complex setups should start from the fuse-overlayfs and iptables-legacy configuration below. For more complex Docker setups, use fuse-overlayfs , iptables-legacy , and make sure your cloud agent user can run Docker. Recommended Dockerfile for complex Docker setups ######################################################## # DOCKER INSTALLATION ######################################################## # Install Docker RUN install -m 0755 -d /etc/apt/keyrings && \ curl --retry 3 --retry-delay 5 -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg && \ chmod a+r /etc/apt/keyrings/docker.gpg && \ echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \ $(. /etc/os-release && echo " $VERSION_CODENAME ") stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null && \ apt-get update && \ apt-get install -y \ docker-ce=5:28.5.2-1~ubuntu.24.04~noble \ docker-ce-cli=5:28.5.2-1~ubuntu.24.04~noble \ containerd.io \ docker-buildx-plugin \ docker-compose-plugin \ && rm -rf /var/lib/apt/lists/* RUN apt-get update && apt-get install -y fuse-overlayfs && rm -rf /var/lib/apt/lists/* RUN mkdir -p /etc/docker && \ printf '%s \n ' '{' \ ' "storage-driver": "fuse-overlayfs"' \ '}' > /etc/docker/daemon.json RUN apt-get update && apt-get install -y iptables && rm -rf /var/lib/apt/lists/* RUN update-alternatives --set iptables /usr/sbin/iptables-legacy && \ update-alternatives --set ip6tables /usr/sbin/ip6tables-legacy ######################################################## # CONFIG UBUNTU USER ######################################################## # ensure no password authentication RUN echo 'PasswordAuthentication no \n ChallengeResponseAuthentication no \n UsePAM no' > /etc/ssh/sshd_config.d/disable_password_auth.conf # Create non-root user (only if it doesn't exist) RUN id -u ubuntu &>/dev/null || useradd -m -s /bin/bash ubuntu # Create docker group if it doesn't exist and add ubuntu user to it RUN groupadd -f docker && usermod -aG docker ubuntu RUN usermod -aG sudo ubuntu # Configure passwordless sudo for ubuntu user RUN echo "ubuntu ALL=(ALL) NOPASSWD:ALL" > /etc/sudoers.d/ubuntu # Set a password for ubuntu user RUN echo "ubuntu:ubuntu" | chpasswd Running Tailscale Tailscale does not work in its default networking mode in Cloud agent VMs. Use userspace networking mode instead. Start tailscaled with: tailscaled --tun=userspace-networking \ --outbound-http-proxy-listen=localhost:1054 \ --socks5-server=localhost:1055 Then export these proxy variables in the shell where you want traffic to flow through Tailscale: export ALL_PROXY = socks5h://localhost:1055/ export HTTP_PROXY = http://localhost:1054/ export HTTPS_PROXY = http://localhost:1054/ After that, run your usual tailscale up ... flow. If you want a working reference, some customers have used tailscale-orb successfully because its Docker mode follows this pattern. Userspace networking does not let the VM appear as a tailnet exit node. English English 简体中文 日本語 繁體中文 Español Français Português 한국어 Русский Türkçe Bahasa Indonesia Deutsch हिन्दी

Cloud Agents Best Practices Use these recommendations to get more reliable Cloud Agent runs. Set up the environment first Use Cloud agent setup so that Cursor has its environment configured. Like a human developer, Cursor does better work if its environment is set up correctly. Ensure the agent can access what it needs Before running a Cloud Agent, verify these prerequisites: Secrets : Make sure the agent has access to required secrets (API keys, database credentials, etc.) through the Secrets tab in your dashboard. Egress controls : If you have network access restrictions enabled, ensure all URLs your local development requires are whitelisted. Local testability : Your repo should be set up to run well locally without requiring external services that cannot be reached from a VM. If it is hard for a human developer to test locally, it will also be hard for an agent. Use skills and agents.md to configure your agent If the cloud agent is having difficulty testing its changes, we recommend using skills and agents.md to configure your agent. Think of the agent as a smart, but low-context human developer. The best way to make sure it does the right thing is to give it the context it needs to understand what to do. For example, at Cursor our agents.md lists tips for running and debugging the most commonly used microservices in our mono-repo. We also have lots of skills about how to test and debug key services, each with clear instructions on when to use the skill. The skills contain in-depth details, such as how to debug a specific microservice or how to set up a third-party dependency when needed for testing. Give the agent the tools it needs We have often found that agents are limited by the tools they have access to. We recommend using MCP and creating custom tools so that the agent has access to the same systems a human developer would. Mold the tools to the agent It is important to create tools that the agent is good at using. We recommend creating tools, and iterating based on observations of how the agent uses them. For example, at Cursor we have created a custom CLI for the model to run micro-services in our codebase. We found that when running custom dev commands, e.g. from a package.json file, some models would forget arguments, or agents would get distracted by noisy build logs which human developers knew to ignore. English English 简体中文 日本語 繁體中文 Español Français Português 한국어 Русский Türkçe Bahasa Indonesia Deutsch हिन्दी

Get Started Cursor Documentation Cursor is an AI editor and coding agent. Use it to understand your codebase, plan and build features, fix bugs, review changes, and work with the tools you already use. Start here Get started Go from install to your first useful change in Cursor Models & Pricing Compare models, usage pools, and plan pricing Changelog Stay up to date with the latest features and improvements What you can do with Cursor Understand your code Trace how a repo fits together and find the right places to start Plan and build features Scope changes, use Plan Mode, and ship bigger work with confidence Find and fix bugs Reproduce issues, narrow the root cause, and verify the fix Review changes Inspect diffs, run checks, and catch problems before you merge Customize Cursor Use rules, skills, and prompts that match how your team works Connect your workflow Work with GitHub, GitLab, JetBrains, Slack, Linear, and more Models See all model attributes on the Models & Pricing page. Name Default Context Max Mode Capabilities Claude 4.6 Sonnet 200k 1M Agent Thinking Claude 4.7 Opus 200k 1M Agent Thinking Composer 2 200k - Agent Thinking Gemini 3.1 Pro 200k 1M Agent Thinking GPT-5.3 Codex 272k - Agent Thinking GPT-5.5 272k 1M Agent Thinking Grok 4.3 200k 1M Agent Thinking Show more models More resources Downloads Get Cursor for your computer Help Find answers to common questions and troubleshooting guides Support For account and billing questions, contact our support team English English 简体中文 日本語 繁體中文 Español Français Português 한국어 Русский Türkçe Bahasa Indonesia Deutsch हिन्दी

Agent Cursor Agent Agent is Cursor's assistant that can complete complex coding tasks independently, run terminal commands, and edit code. Access in sidepane with Cmd+I Ctrl+I . Learn more about how agents work and help you build faster. How Agent works An agent is built on three components: Instructions : The system prompt and rules that guide agent behavior Tools : File editing, codebase search, terminal execution, and more Model : The agent model you pick for the task Cursor's agent orchestrates these components for each model we support, tuning instructions and tools specifically for every frontier model. As new models are released, you can focus on building software while Cursor handles the model-specific optimizations. Tools Tools are the building blocks of Agent. They are used to search your codebase and the web to find relevant information, make edits to your files, run terminal commands, and more. To understand how tool calling works under the hood, see our tool calling fundamentals . There is no limit on the number of tool calls Agent can make during a task. Semantic search Perform semantic searches within your indexed codebase . Finds code by meaning, not just exact matches. Search files and folders Search for files by name, read directory structures, and find exact keywords or patterns within files. Web Generate search queries and perform web searches. Fetch Rules Retrieve specific rules based on type and description. Read files Intelligently read the content of a file. Also supports image files (.png, .jpg, .gif, .webp, .svg) and includes them in the conversation context for analysis by vision-capable models. Edit files Suggest edits to files and apply them automatically. Run shell commands Execute terminal commands and monitor output. By default, Cursor uses the first terminal profile available. To set your preferred terminal profile: Open Command Palette ( Cmd/Ctrl+Shift+P ) Search for "Terminal: Select Default Profile" Choose your desired profile Browser Control a browser to take screenshots, test applications, and verify visual changes. Agent can navigate pages, interact with elements, and capture the current state for analysis. See the Browser documentation for details. Image generation Generate images from text descriptions or reference images. Useful for creating UI mockups, product assets, and visualizing architecture diagrams. Images are saved to your project's assets/ folder by default and shown inline in chat. message-circle-question Ask questions Ask clarifying questions during a task. While waiting for your response, the agent continues reading files, making edits, or running commands. Your answer is incorporated as soon as it arrives. Checkpoints Checkpoints save snapshots of your codebase during an Agent session. Agent automatically creates them before making significant changes, capturing the state of all modified files. If Agent takes a wrong turn, click any checkpoint in the chat timeline to preview your files at that point, then restore to revert all files to that state. You can also restore from the Restore Checkpoint button on previous requests or the + button when hovering over a message. Checkpoints are useful for exploratory work, complex refactoring, and iterative development where you want safe rollback points. Checkpoints are stored locally and separate from Git. Only use them for undoing Agent changes; use Git for permanent version control. Queued messages Queue follow-up messages while Agent is working on the current task. Your instructions wait in line and execute automatically when ready. Using the queue While Agent is working, type your next instruction Press Enter to add it to the queue Messages appear in order below the active task Drag to reorder queued messages as needed Agent processes them sequentially after finishing Keyboard shortcuts While Agent is working: Press Enter to queue your message (it waits until Agent finishes the current task) Press Cmd+Enter Ctrl+Enter to send immediately, bypassing the queue Immediate messaging When you use Cmd+Enter Ctrl+Enter to send immediately, your message is appended to the most recent user message in the chat and processed right away without waiting in the queue. Your message attaches to tool results and sends immediately This creates a more responsive experience for urgent follow-ups Use this when you need to interrupt or redirect Agent's current work English English 简体中文 日本語 繁體中文 Español Français Português 한국어 Русский Türkçe Bahasa Indonesia Deutsch हिन्दी

Agent Plan Mode Plan Mode creates detailed implementation plans before writing any code. Agent researches your codebase, asks clarifying questions, and generates a reviewable plan you can edit before building. Press Shift+Tab from the chat input to rotate to Plan Mode. Cursor also suggests it automatically when you type keywords that indicate complex tasks. How it works Agent asks clarifying questions to understand your requirements Researches your codebase to gather relevant context Creates a comprehensive implementation plan You review and edit the plan through chat or markdown files Click to build the plan when ready Plans are saved by default in your home directory. Click "Save to workspace" to move it to your workspace for future reference, team sharing, and documentation. When to use Plan Mode Plan Mode works best for: Complex features with multiple valid approaches Tasks that touch many files or systems Unclear requirements where you need to explore before understanding scope Architectural decisions where you want to review the approach first For quick changes or tasks you've done many times before, jumping straight to Agent mode is fine. Starting over from a plan Sometimes Agent builds something that doesn't match what you wanted. Instead of trying to fix it through follow-up prompts, go back to the plan. Revert the changes, refine the plan to be more specific about what you need, and run it again. This is often faster than fixing an in-progress agent, and produces cleaner results. For larger changes, spend extra time creating a precise, well-scoped plan. The hard part is often figuring out what change should be made. With the right instructions, delegate implementation to Agent. Switching modes Use the mode picker dropdown in Agent Press Shift+Tab for quick switching English English 简体中文 日本語 繁體中文 Español Français Português 한국어 Русский Türkçe Bahasa Indonesia Deutsch हिन्दी

Cloud Agents Cloud Agents Cloud agents use the same agent fundamentals but run in isolated environments in the cloud instead of on your local machine. An environment includes the repos, dependencies, secrets, startup commands, and network access the agent needs to do its work. Why use Cloud Agents? You can run as many agents as you want in parallel, and they do not require your local machine to be connected to the internet. Because they have access to their own virtual machine, cloud agents can build, test, and interact with the changed software. They can also use computers to control the desktop and browser. Cloud agents support MCP servers , giving them access to external tools and data sources like databases, APIs, and third-party services. Cloud agents can also run in multi-repo environments. Use one when a task spans separate frontend, backend, infrastructure, or shared-library repositories. The agent can inspect the full workspace, make coordinated changes, and open pull requests in the repos it changes. How to access You can kick off cloud agents from wherever you work: Cursor Web : Start and manage agents from cursor.com/agents on any device Cursor Desktop : Select Cloud in the dropdown under the agent input Slack : Use the @cursor command to kick off an agent GitHub : Comment @cursor on a PR or issue to kick off an agent Linear : Use the @cursor command to kick off an agent API : Use the API to kick off an agent For a native-feeling mobile experience, install Cursor as a Progressive Web App (PWA). On iOS , open cursor.com/agents in Safari, tap the share button, then "Add to Home Screen". On Android , open the URL in Chrome, tap the menu, then "Install App". Use Cursor in Slack Learn more about setting up and using the Slack integration, including triggering agents and receiving notifications. How it works GitHub or GitLab connection Cloud agents clone your repo from GitHub or GitLab and work on a separate branch, then push changes to your repo for handoff. You need read-write privileges to your repo and any dependent repos or submodules. Support for other providers like Bitbucket is coming later. Environments Each cloud agent starts from an environment selected for the repo or repo group. You can configure environments with agent-led setup, a saved snapshot, or a Dockerfile in .cursor/environment.json . The Cloud Agents dashboard shows which environment an agent used, along with environment details and version history. On the agent page, hover over the repository name at the top of the page to inspect the environment used for that run. See Cloud agent setup for configuration details. Models Cloud Agents use a curated selection of models that always run in Max Mode . There is no toggle to turn Max Mode off for Cloud Agents. MCP support Cloud agents can use MCP (Model Context Protocol) servers configured for your team. Add and manage MCP servers through the MCP dropdown in cursor.com/agents . Both HTTP and stdio transports are supported. OAuth is supported for MCP servers that need it. See Cloud Agent capabilities for setup details. Hooks support Cloud agents run project hooks from .cursor/hooks.json . On Enterprise plans, they also run team hooks and enterprise-managed hooks. This lets you keep formatters, audit scripts, and policy checks active when work runs in the cloud whether you manage them in the repo or from the dashboard. See Hooks for the hook model and configuration format. Artifacts and remote desktop control Cloud agents produce merge-ready PRs with artifacts to demo their changes. You can also control the agent's remote desktop to use the modified software. Artifacts : Agents produce screenshots, videos, and logs so you can see exactly what changed and how the agent verified its work. Remote desktop control : Take control of the agent's desktop to test the software yourself in a full development environment without checking out the branch locally. Release control back to the agent for it to keep working. See Cloud agent capabilities for details on artifacts, computer use, and remote desktop control. Related pages Learn more about Cloud agent capabilities . Learn more about Cloud agent setup . Learn more about Cloud agent security . Learn more about Cloud agent settings . Billing Cloud Agents are charged at API pricing for the selected model . You'll be asked to set a spend limit when you first start using them. Troubleshooting Agent runs are not starting Ensure you're logged in and have connected your GitHub or GitLab account. Check that you have the necessary repository permissions. You need to be on a paid Cursor plan. My secrets aren't available to the cloud agent Ensure you've added secrets in cursor.com/dashboard/cloud-agents Secrets are workspace/team-scoped; make sure you're using the correct account Try restarting the cloud agent after adding new secrets Can't find the Secrets tab If you don't see it, ensure you have the necessary permissions Do snapshots copy .env.local files? Snapshots save your base environment configuration (installed packages, system dependencies, etc.). If you include .env.local files during snapshot creation, they will be saved. However, using the Secrets tab in Cursor Settings is the recommended approach for managing environment variables. Slack integration not working Verify that your workspace admin has installed the Cursor Slack app and that you have the proper permissions. Naming History Cloud Agents were formerly called Background Agents. English English 简体中文 日本語 繁體中文 Español Français Português 한국어 Русский Türkçe Bahasa Indonesia Deutsch हिन्दी

SDK Cursor SDK Public beta The TypeScript SDK is in public beta. APIs may change before general availability. The @cursor/sdk package lets you call Cursor's agent from your own code. The same agent that runs in the Cursor IDE, CLI, and web app is now scriptable from TypeScript. You can also use Cursor's native /sdk skill to help you start building. Overview The SDK wraps local and cloud runtimes behind one interface. You write the same code regardless of where the agent runs. Runtime What it does When to use Local Runs the agent inline in your Node process. Files come from disk. Dev scripts and CI checks against a working tree. Cloud (Cursor-hosted) Runs in an isolated VM with your repo cloned in. Cursor runs the VMs. When the caller doesn't have the repo, you want many agents in parallel, or runs need to survive the caller disconnecting. Cloud (self-hosted) Same shape, but you run the VMs via a self-hosted pool . Same reasons as Cursor-hosted, plus code, secrets, and build artifacts must stay in your environment. Runtime is picked by which key you pass to Agent.create() ( local or cloud ). Use the same CURSOR_API_KEY for either. For the REST API, see the Cloud Agents API . Authentication Set CURSOR_API_KEY (or pass apiKey ) before creating an agent. The SDK accepts user API keys and service account API keys for both local and cloud runs. Team Admin API keys are not yet supported. User API key from Cursor Dashboard → Integrations Service account API key from Team settings . See Service accounts export CURSOR_API_KEY = "your-key" Usage and billing SDK runs follow the same pricing, request pools, and Privacy Mode rules as runs from the IDE and Cloud Agents. Spend shows up in your team's usage dashboard under the SDK tag. Core concepts Concept Description Agent Durable container that holds conversation state, workspace config, and settings. Survives across multiple prompts. Run One prompt submission. Owns its own stream, status, result, and cancellation. SDKMessage Normalized stream events emitted during a run. Same shape across all runtimes. Installation npm install @cursor/sdk Quick start The fastest way in: a local agent against your current working tree, streaming events as they come in. Cloud setup is in Creating agents below. import { Agent } from "@cursor/sdk" ; const agent = await Agent. create ({ apiKey: process.env. CURSOR_API_KEY ! , model: { id: "composer-2" }, local: { cwd: process. cwd () }, }); const run = await agent. send ( "Summarize what this repository does" ); for await ( const event of run. stream ()) { console. log (event); } Each event is a discriminated SDKMessage . Streaming shows how to extract assistant text, handle tool calls, and clean up with await using . For a one-shot prompt (create, run, dispose), see Agent.prompt() . Creating agents function Agent . create ( options : AgentOptions ) : Promise < SDKAgent >; Agent.create() validates options and returns a handle immediately. Pass either local or cloud to pick a runtime. // Local agent const agent = await Agent. create ({ apiKey: process.env. CURSOR_API_KEY ! , model: { id: "composer-2" }, local: { cwd: "/path/to/repo" }, }); // Cloud agent const agent = await Agent. create ({ apiKey: process.env. CURSOR_API_KEY ! , model: { id: "composer-2" }, cloud: { repos: [{ url: "https://github.com/your-org/your-repo" , startingRef: "main" }], autoCreatePR: true , }, }); agent.agentId is populated immediately. Local agents get an agent- ID; cloud agents get a bc- ID. Cloud agents started by the SDK are filtered out of the default agent list. To view them in Cursor Web or a Cursor window, click Filter > Source > SDK . Session environment variables For cloud agents, pass cloud.envVars when a run needs short-lived credentials or other values that should live only with that agent. const agent = await Agent. create ({ apiKey: process.env. CURSOR_API_KEY ! , cloud: { repos: [{ url: "https://github.com/your-org/your-repo" }], envVars: { STAGING_API_TOKEN: process.env. STAGING_API_TOKEN ! , }, }, }); These values are encrypted at rest, injected into the cloud agent's shell, and deleted with the agent. envVars can't be used with a caller-supplied agentId ; omit agentId and read the server-minted ID from agent.agentId . Variable names can't start with CURSOR_ . Model parameters Use model.params to pass per-model options such as reasoning effort. Parameter ids and values vary by model. Use Cursor.models.list() to discover supported parameters and preset variants for your account. When a selected model requires Max Mode , Cursor enables it automatically for the SDK request. const agent = await Agent. create ({ apiKey: process.env. CURSOR_API_KEY ! , model: { id: "composer-2" , params: [{ id: "thinking" , value: "high" }], }, local: { cwd: process. cwd () }, }); SDKAgent The handle returned by Agent.create() and Agent.resume() . interface SDKAgent { readonly agentId : string ; readonly model : ModelSelection | undefined ; send ( message : string | SDKUserMessage , options ?: SendOptions ) : Promise < Run >; close () : void ; reload () : Promise < void >; [Symbol.asyncDispose]() : Promise < void >; listArtifacts () : Promise < SDKArtifact []>; downloadArtifact ( path : string ) : Promise < Buffer >; } Member Description agentId Stable agent identifier. agent- for local, bc- for cloud. model Current model selection. Updates after every successful send({ model }) . undefined until something sets it (including resumed agents whose caller did not pass model ). send Start a new run with the given prompt. Returns a Run handle. close Begin disposal without awaiting. Fire-and-forget. reload Re-read filesystem config (hooks, project MCP, subagents) without disposing. [Symbol.asyncDispose] Async disposal. Pair with await using for automatic cleanup. listArtifacts List files produced by the agent (cloud only; local returns empty). downloadArtifact Download a file by path (cloud only; local throws). Agent.prompt() function Agent . prompt ( message : string , options ?: AgentOptions ) : Promise < RunResult >; One-shot convenience: creates an agent, sends a single prompt, waits for the run to finish, and disposes. const result = await Agent. prompt ( "What does the auth middleware do?" , { apiKey: process.env. CURSOR_API_KEY ! , model: { id: "composer-2" }, local: { cwd: process. cwd () }, }); Sending messages Each agent.send() returns a Run . The agent retains conversation context across runs; the run is the unit of work for one prompt. Run type RunStatus = "running" | "finished" | "error" | "cancelled" ; type RunOperation = "stream" | "wait" | "cancel" | "conversation" ; interface Run { readonly id : string ; readonly agentId : string ; readonly status : RunStatus ; readonly result ?: string ; readonly model ?: ModelSelection ; readonly durationMs ?: number ; readonly git ?: RunGitInfo ; readonly createdAt ?: number ; stream () : AsyncGenerator < SDKMessage , void >; wait () : Promise < RunResult >; cancel () : Promise < void >; conversation () : Promise < ConversationTurn []>; supports ( operation : RunOperation ) : boolean ; unsupportedReason ( operation : RunOperation ) : string | undefined ; onDidChangeStatus ( listener : ( status : RunStatus ) => void ) : () => void ; } interface RunGitInfo { branches : Array <{ repoUrl : string ; branch ?: string ; prUrl ?: string }>; } interface RunResult { id : string ; status : "finished" | "error" | "cancelled" ; result ?: string ; model ?: ModelSelection ; durationMs ?: number ; git ?: RunGitInfo ; } Streaming const run = await agent. send ( "Find the bug in src/auth.ts" ); for await ( const event of run. stream ()) { switch (event.type) { case "assistant" : for ( const block of event.message.content) { if (block.type === "text" ) process.stdout. write (block.text); } break ; case "thinking" : process.stdout. write (event.text); break ; case "tool_call" : console. log ( `[tool] ${ event . name }: ${ event . status }` ); break ; case "status" : console. log ( `[status] ${ event . status }` ); break ; } } // Follow-up. Full context is retained. const run2 = await agent. send ( "Fix it and add a regression test" ); await run2. wait (); To send images alongside text: const run = await agent. send ({ text: "What's in this screenshot?" , images: [{ data: base64Png, mimeType: "image/png" }], }); Waiting without streaming const result = await run. wait (); console. log (result.status); // "finished" | "error" | "cancelled" console. log (result.result); // final assistant text, if any console. log (result.model); // resolved ModelSelection used for this run console. log (result.durationMs); console. log (result.git); // { branches: [{ repoUrl, branch?, prUrl? }] } on cloud Cancelling a run await run. cancel (); Cancels the run. The status moves to "cancelled" , the live stream aborts, in-flight tool calls stop, and run.wait() resolves with status: "cancelled" . Partial output (assistant text written so far) stays on the Run object. Cancel is supported on running local and cloud runs and is a no-op if the run already finished. Reading run state console. log (run.status); // "running" | "finished" | "error" | "cancelled" const stop = run. onDidChangeStatus (( status ) => { console. log ( `status changed to ${ status }` ); }); // Call `stop()` to remove the listener. // Structured per-turn view of the conversation accumulated in this run const turns = await run. conversation (); run.conversation() returns the run's ConversationTurn[] (an agent turn with steps, or a shell turn with command and output). Use it to render or persist the run's structured history without subscribing to the live stream. Per-run model override The model you pass to agent.send() overrides the agent's selection for that run, then becomes sticky: subsequent sends without an override continue to use the new model. To switch back, pass another model override or read the current selection from agent.model . const run = await agent. send ( "Plan the refactor" , { model: { id: "composer-2" , params: [{ id: "thinking" , value: "high" }] }, }); console. log (agent.model); // updated to the override after the send succeeds run.model and result.model reflect the selection that this specific run actually used and are immutable once the run starts. Streaming raw deltas run.stream() yields normalized SDKMessage events. For lower-level updates (per-token text, tool-call args streaming in, thinking deltas, step boundaries), pass onDelta and onStep callbacks to send() : const run = await agent. send ( "Refactor the utils module" , { onDelta : ({ update }) => { if (update.type === "text-delta" ) process.stdout. write (update.text); if (update.type === "thinking-delta" ) process.stdout. write (update.text); }, onStep : ({ step }) => { console. log ( `[step] ${ step . type }` ); }, }); The callbacks are awaited before the next update is processed, so you can apply backpressure. InteractionUpdate covers text-delta , thinking-delta , thinking-completed , tool-call-started , tool-call-completed , partial-tool-call , token-delta , step-started , step-completed , turn-ended , and a handful of summary and shell-output deltas. Per-send options Property Type Description model ModelSelection Per-send model override. If omitted, uses agent.model . Sticky: a successful send updates agent.model . mcpServers Record Inline MCP server definitions. Fully replaces creation-time servers for this run. onStep (args: { step }) => void | Promise Callback after each completed conversation step (text, thinking, or tool batch). onDelta (args: { update }) => void | Promise Callback per raw InteractionUpdate . local.force boolean Local agents only. Defaults to false . Expire a stuck active run before starting this message. Cloud returns 409 agent_busy server-side, so no equivalent is needed. The next three sections are detailed reference for SDKMessage , InteractionUpdate , and ConversationTurn . Skim or skip on a first read; Resuming agents picks up the narrative. Stream events Events from run.stream() . Discriminate on type . All events include agent_id and run_id . type SDKMessage = | SDKSystemMessage | SDKUserMessageEvent | SDKAssistantMessage | SDKThinkingMessage | SDKToolUseMessage | SDKStatusMessage | SDKTaskMessage | SDKRequestMessage ; type Description Key fields "system" Init metadata. Emitted once at the start of a run. subtype? ( "init" ), model? , tools? "user" Echo of the user prompt for this run. message.content: TextBlock[] "assistant" Model text output. message.content: (TextBlock | ToolUseBlock)[] "thinking" Reasoning content. text , thinking_duration_ms? "tool_call" Tool invocation lifecycle. Emitted at start with args , then again on completion with result . call_id , name , status , args? , result? , truncated? "status" Cloud run lifecycle transitions. status , message? "task" Task-level milestones and summaries. status? , text? "request" Awaiting user input or approval. request_id Result data (final text, model, duration, git metadata) lives on the Run object after the stream completes. Use run.wait() to read it. Tool call schema is not stable. The args and result payloads on tool_call events reflect each tool's internal shape and can change as tools evolve. Tool names can also be renamed or replaced. Treat args and result as unknown and parse defensively. The event envelope ( type , call_id , name , status ) is stable. Message types interface SDKSystemMessage { type : "system" ; subtype ?: "init" ; agent_id : string ; run_id : string ; model ?: ModelSelection ; tools ?: string []; } interface SDKUserMessageEvent { type : "user" ; agent_id : string ; run_id : string ; message : { role : "user" ; content : TextBlock [] }; } interface SDKAssistantMessage { type : "assistant" ; agent_id : string ; run_id : string ; message : { role : "assistant" ; content : Array < TextBlock | ToolUseBlock >; }; } interface SDKThinkingMessage { type : "thinking" ; agent_id : string ; run_id : string ; text : string ; thinking_duration_ms ?: number ; } interface SDKToolUseMessage { type : "tool_call" ; agent_id : string ; run_id : string ; call_id : string ; name : string ; status : "running" | "completed" | "error" ; args ?: unknown ; result ?: unknown ; truncated ?: { args ?: boolean ; result ?: boolean }; } interface SDKStatusMessage { type : "status" ; agent_id : string ; run_id : string ; status : "CREATING" | "RUNNING" | "FINISHED" | "ERROR" | "CANCELLED" | "EXPIRED" ; message ?: string ; } interface SDKTaskMessage { type : "task" ; agent_id : string ; run_id : string ; status ?: string ; text ?: string ; } interface SDKRequestMessage { type : "request" ; agent_id : string ; run_id : string ; request_id : string ; } interface TextBlock { type : "text" ; text : string ; } interface ToolUseBlock { type : "tool_use" ; id : string ; name : string ; input : unknown ; } SDKToolUseMessage is emitted twice for most tool calls: first with status: "running" and args populated, then again on completion with status: "completed" (or "error" ) and result populated. truncated flags whether the SDK truncated args or result because the payload was too large. SDKStatusMessage covers cloud-side lifecycle transitions. CREATING covers VM provisioning and repo cloning; RUNNING is the agent doing work; the rest are terminal. Interaction updates InteractionUpdate is the raw delta type passed to the onDelta callback on agent.send() . Updates are finer-grained than SDKMessage events: text streams in token-by-token, tool calls report partial state as args accumulate, thinking arrives as it happens. type InteractionUpdate = | TextDeltaUpdate | ThinkingDeltaUpdate | ThinkingCompletedUpdate | ToolCallStartedUpdate | ToolCallCompletedUpdate | PartialToolCallUpdate | TokenDeltaUpdate | StepStartedUpdate | StepCompletedUpdate | TurnEndedUpdate | UserMessageAppendedUpdate | SummaryUpdate | SummaryStartedUpdate | SummaryCompletedUpdate | ShellOutputDeltaUpdate ; Update types interface TextDeltaUpdate { type : "text-delta" ; text : string ; } interface ThinkingDeltaUpdate { type : "thinking-delta" ; text : string ; } interface ThinkingCompletedUpdate { type : "thinking-completed" ; thinkingDurationMs : number ; } interface ToolCallStartedUpdate { type : "tool-call-started" ; callId : string ; toolCall : ToolCall ; modelCallId : string ; } interface PartialToolCallUpdate { type : "partial-tool-call" ; callId : string ; toolCall : ToolCall ; modelCallId : string ; } interface ToolCallCompletedUpdate { type : "tool-call-completed" ; callId : string ; toolCall : ToolCall ; modelCallId : string ; } interface TokenDeltaUpdate { type : "token-delta" ; tokens : number ; } interface StepStartedUpdate { type : "step-started" ; stepId : number ; } interface StepCompletedUpdate { type : "step-completed" ; stepId : number ; stepDurationMs : number ; } interface TurnEndedUpdate { type : "turn-ended" ; usage ?: { inputTokens : number ; outputTokens : number ; cacheReadTokens : number ; cacheWriteTokens : number ; }; } interface UserMessageAppendedUpdate { type : "user-message-appended" ; userMessage : UserMessage ; } interface SummaryUpdate { type : "summary" ; summary : string ; } interface SummaryStartedUpdate { type : "summary-started" ; } interface SummaryCompletedUpdate { type : "summary-completed" ; } interface ShellOutputDeltaUpdate { type : "shell-output-delta" ; event : Record < string , unknown >; } PartialToolCallUpdate is emitted as the model streams arguments into a tool call before it commits. The same stability disclaimer that applies to SDKToolUseMessage.args applies here. Conversation types The structured per-turn view of a run, returned by run.conversation() and used in the onStep callback's argument. type ConversationTurn = | { type : "agentConversationTurn" ; turn : AgentConversationTurn } | { type : "shellConversationTurn" ; turn : ShellConversationTurn }; interface AgentConversationTurn { userMessage ?: UserMessage ; steps : ConversationStep []; } interface ShellConversationTurn { shellCommand ?: ShellCommand ; shellOutput ?: ShellOutput ; } type ConversationStep = | { type : "assistantMessage" ; message : AssistantMessage } | { type : "toolCall" ; message : ToolCall } | { type : "thinkingMessage" ; message : ThinkingMessage }; interface AssistantMessage { text : string ; } interface ThinkingMessage { text : string ; thinkingDurationMs ?: number ; } interface UserMessage { text : string ; } interface ShellCommand { command : string ; workingDirectory ?: string ; } interface ShellOutput { stdout : string ; stderr : string ; exitCode : number ; } ToolCall is a discriminated union over every built-in tool (shell, edit, read, write, glob, grep, ls, semSearch, mcp, task, and others). Its shape is internal-facing; see the stability note under Stream events. Resuming agents function Agent . resume ( agentId : string , options ?: Partial < AgentOptions >) : Promise < SDKAgent >; Use Agent.resume() to reattach to an existing agent by ID. Common flows: reconnecting to a long-running cloud agent that was kicked off earlier, or continuing a conversation after the local process restarted. Runtime is auto-detected from the ID prefix ( bc- is cloud, anything else is local). await using agent = await Agent. resume ( "bc-abc123" , { apiKey: process.env. CURSOR_API_KEY ! , }); const run = await agent. send ( "Also update the changelog" ); await run. wait (); agent.model is undefined on resume unless you pass model again. Inline mcpServers are not persisted across resume — they often carry secrets and live in memory only. Pass them again on resume, or use file-based MCP config ( .cursor/mcp.json + local.settingSources ) for servers that should survive. Inspecting agents and runs List, fetch, and reload past agents. List endpoints return { items, nextCursor? } for cursor-based pagination. Agent.list() function Agent . list ( options ?: ListAgentsOptions ) : Promise < ListResult < SDKAgentInfo >>; type ListAgentsOptions = { limit ?: number ; cursor ?: string ; } & ( | { runtime ?: undefined } | { runtime : "local" ; cwd ?: string } | { runtime : "cloud" ; prUrl ?: string ; includeArchived ?: boolean ; apiKey ?: string ; } ); const { items , nextCursor } = await Agent. list ({ runtime: "local" , cwd: process. cwd (), }); Agent.get() function Agent . get ( agentId : string , options ?: GetAgentOptions ) : Promise < SDKAgentInfo >; interface GetAgentOptions { cwd ?: string ; // local routing apiKey ?: string ; // cloud routing } Runtime is auto-detected from the agent ID prefix ( bc- → cloud, otherwise local). Agent.listRuns() function Agent . listRuns ( agentId : string , options ?: ListRunsOptions ) : Promise < ListResult < Run >>; type ListRunsOptions = { limit ?: number ; cursor ?: string ; } & ( | { runtime ?: "local" ; cwd ?: string } | { runtime : "cloud" ; apiKey ?: string } ); Agent.getRun() function Agent . getRun ( runId : string , options ?: GetRunOptions ) : Promise < Run >; type GetRunOptions = | { runtime ?: "local" ; cwd ?: string } | { runtime : "cloud" ; agentId : string ; apiKey ?: string }; Cloud getRun requires the parent agentId . Cloud agent lifecycle Cloud agents stay in your team's workspace until you archive or delete them. Agent.list({ runtime: "cloud" }) hides archived agents by default; pass includeArchived: true to see them. Filter by prUrl to find the agent that opened a specific pull request. function Agent . archive ( agentId : string , options ?: AgentOperationOptions ) : Promise < void >; function Agent . unarchive ( agentId : string , options ?: AgentOperationOptions ) : Promise < void >; function Agent . delete ( agentId : string , options ?: AgentOperationOptions ) : Promise < void >; interface AgentOperationOptions { cwd ?: string ; apiKey ?: string ; } await Agent. archive (agentId); // soft-delete; transcript stays readable await Agent. unarchive (agentId); // restore an archived agent await Agent. delete (agentId); // permanent; subsequent reads return 404 SDKAgentInfo The metadata shape returned by Agent.list() and Agent.get() . type SDKAgentInfo = { agentId : string ; name : string ; summary : string ; lastModified : number ; status ?: "running" | "finished" | "error" ; createdAt ?: number ; archived ?: boolean ; } & ( | { runtime ?: undefined } | { runtime : "local" ; cwd ?: string } | { runtime : "cloud" ; env ?: { type : "cloud" | "pool" | "machine" ; name ?: string }; repos ?: string []; } ); The Cursor namespace Account-level and catalog reads. All methods take an optional { apiKey } and otherwise fall back to CURSOR_API_KEY . Cursor.me() function Cursor . me ( options ?: CursorRequestOptions ) : Promise < SDKUser >; interface CursorRequestOptions { apiKey ?: string ; } interface SDKUser { apiKeyName : string ; userEmail ?: string ; createdAt : string ; } Cursor.models.list() function Cursor . models . list ( options ?: CursorRequestOptions ) : Promise < SDKModel []>; type SDKModel = ModelListItem ; interface ModelListItem { id : string ; displayName : string ; description ?: string ; parameters ?: ModelParameterDefinition []; variants ?: ModelVariant []; } interface ModelParameterDefinition { id : string ; displayName ?: string ; values : Array <{ value : string ; displayName ?: string }>; } interface ModelVariant { params : ModelParameterValue []; displayName : string ; description ?: string ; isDefault ?: boolean ; } Use Cursor.models.list() to discover valid model ids and per-model params before calling Agent.create() or agent.send() . Parameters are model-specific. Common examples include reasoning effort. const models = await Cursor.models. list (); const composer = models. find (( model ) => model.id === "composer-2" ); console. log (composer?.parameters); // [ // { // id: "thinking", // displayName: "Thinking", // values: [ // { value: "low", displayName: "Low" }, // { value: "high", displayName: "High" }, // ], // }, // ] Pass selected parameter values through model.params . Preset variants already contain valid params , so you can copy them into a model selection. const agent = await Agent. create ({ apiKey: process.env. CURSOR_API_KEY ! , model: { id: "composer-2" , params: [{ id: "thinking" , value: "high" }], }, local: { cwd: process. cwd () }, }); Cursor.repositories.list() function Cursor . repositories . list ( options ?: CursorRequestOptions ) : Promise < SDKRepository []>; interface SDKRepository { url : string ; } Returns the GitHub repositories connected for the calling user's team. Cloud only. MCP servers Agents can pick up MCP servers from several sources. Inline definitions in Agent.create() or agent.send() are the most common path. File-based and dashboard-managed configs are also supported. What gets loaded Local agents load servers from up to five sources, with first-match-wins precedence on conflicting names: mcpServers on agent.send() . Fully replaces creation-time servers for that run (not merged). mcpServers on Agent.create() . Used when no per-send override is provided. Plugin servers, if local.settingSources includes "plugins" . Project servers from .cursor/mcp.json , if local.settingSources includes "project" . User servers from ~/.cursor/mcp.json , if local.settingSources includes "user" . Without local.settingSources , only inline servers are loaded. If a local MCP server requires OAuth login, the SDK can't prompt you to sign in. It only works if you've already signed in to that server from the Cursor app, in which case the SDK reuses that saved login. Cloud agents load servers from: mcpServers on agent.send() . Fully replaces creation-time servers for that run (not merged). mcpServers on Agent.create() . Used when no per-send override is provided. Your user and team MCP servers from cursor.com/agents . If an inline server doesn't include auth or headers and you've previously authorized that server URL on cursor.com/agents, runs authenticated with a personal API token reuse those OAuth tokens automatically. Service account API keys cannot fall back to user auth as they are not associated with a user. local.settingSources does not apply to cloud agents. Local const agent = await Agent. create ({ apiKey: process.env. CURSOR_API_KEY ! , model: { id: "auto" }, local: { cwd: process. cwd () }, mcpServers: { docs: { type: "http" , url: "https://example.com/mcp" , auth: { CLIENT_ID: "client-id" , scopes: [ "read" , "write" ], }, }, filesystem: { type: "stdio" , command: "npx" , args: [ "-y" , "@modelcontextprotocol/server-filesystem" , process. cwd ()], cwd: process. cwd (), }, }, }); Cloud Cloud agents can receive authenticated MCP configs inline too. Use HTTP auth when Cursor should proxy a remote MCP through the backend. Use stdio env when the server runs inside the cloud VM and reads credentials from environment variables. const agent = await Agent. create ({ apiKey: process.env. CURSOR_API_KEY ! , model: { id: "composer-2" }, cloud: { repos: [{ url: "https://github.com/your-org/your-repo" , startingRef: "main" }], }, mcpServers: { linear: { type: "http" , url: "https://mcp.linear.app/sse" , headers: { Authorization: `Bearer ${ process . env . LINEAR_API_KEY ! }` , }, }, figma: { type: "http" , url: "https://api.figma.com/mcp" , auth: { CLIENT_ID: process.env. FIGMA_CLIENT_ID ! , CLIENT_SECRET: process.env. FIGMA_CLIENT_SECRET ! , scopes: [ "file_content:read" ], }, }, github: { type: "stdio" , command: "npx" , args: [ "-y" , "@modelcontextprotocol/server-github" ], env: { GITHUB_TOKEN: process.env. GITHUB_TOKEN ! , }, }, }, }); Use headers for static API keys or Bearer tokens — Cursor passes them through on every request. Use auth for OAuth-protected servers. For cloud, Cursor runs the OAuth flow once server-side and reuses the token across runs. Locally, the SDK can't open a browser to sign you in; it only reuses tokens you've already obtained by signing in through the Cursor app. HTTP headers and auth are handled by Cursor's backend. Sensitive fields are redacted and do not enter the VM. Stdio env values are passed into the VM because the server runs there. Treat them like any other runtime secret. OAuth for MCP servers configured on cursor.com/agents stays per-user, even for team-level servers. See MCP for the full config format and Cloud Agent capabilities for cloud-specific behavior. Subagents Define named subagents that the main agent spawns via the Agent tool. Pass them inline: const agent = await Agent. create ({ model: { id: "composer-2" }, apiKey: process.env. CURSOR_API_KEY ! , local: { cwd: process. cwd () }, agents: { "code-reviewer" : { description: "Expert code reviewer for quality and security." , prompt: "Review code for bugs, security issues, and proven approaches." , model: "inherit" , }, "test-writer" : { description: "Writes tests for code changes." , prompt: "Write comprehensive tests for the given code." , }, }, }); Subagents committed to the repo at .cursor/agents/*.md (with name , description , and optional model frontmatter) are also picked up. Inline definitions override file-based ones with the same name. Hooks Hooks are file-based only. There is no programmatic hook callback. Hooks are a project policy boundary, not a per-run knob. Local: Add .cursor/hooks.json to the repo passed as local.cwd , or add ~/.cursor/hooks.json for user-level hooks. Cloud: Commit .cursor/hooks.json and its scripts to the repo passed in cloud.repos . SDK-created cloud agents load project hooks automatically. On Enterprise plans, they also run team hooks and enterprise-managed hooks. See Hooks for the configuration format and Cloud Agents hooks support for cloud behavior. Artifacts List and download files from the agent's workspace. interface SDKArtifact { path : string ; sizeBytes : number ; updatedAt : string ; } const artifacts : SDKArtifact [] = await agent. listArtifacts (); for ( const artifact of artifacts) { console. log (artifact.path, artifact.sizeBytes); } const buffer = await agent. downloadArtifact (artifacts[ 0 ].path); Artifact support is runtime-dependent. Local SDK agents currently return no artifacts and throw for downloadArtifact . Resource management Always dispose agents when done. The cleanest pattern is await using : await using agent = await Agent. create ({ /* ... */ }); // disposed automatically when the block exits To dispose explicitly: await agent[Symbol.asyncDispose](); agent.close() starts disposal without awaiting. agent.reload() picks up filesystem config changes (hooks, project MCP, subagents) without disposing. Configuration reference AgentOptions Property Type Default Description model ModelSelection Required for local; cloud falls back to the server-resolved default Model to use. See ModelSelection . apiKey string CURSOR_API_KEY env User API key or service account key. Team Admin keys are not yet supported. name string Auto-generated Human-readable agent name surfaced as title in Agent.list() / Agent.get() . local { cwd?: string | string[]; settingSources?: SettingSource[]; sandboxOptions?: { enabled: boolean } } Local agent config. settingSources picks ambient settings layers: "project" , "user" , "team" , "mdm" , "plugins" , or "all" . cloud CloudOptions Cloud agent config. mcpServers Record Inline MCP server definitions. agents Record Subagent definitions. agentId string Auto-generated Durable agent ID. Pass to keep a stable ID across invocations. CloudOptions Property Type Default Description env { type: "cloud"; name?: string } | { type: "pool"; name?: string } | { type: "machine"; name?: string } { type: "cloud" } Execution environment target. cloud uses Cursor-hosted VMs; set name to use a saved Cursor-hosted environment. pool routes to a Self-Hosted Pool ; machine routes to a specific My Machines worker. Omit repos and leave env at the default for a no-repo agent with an empty workspace. Named Cursor-hosted environments and explicit repos are mutually exclusive. repos Array<{ url: string; startingRef?: string; prUrl?: string }> Repositories to clone into the VM. Pass one entry for a single-repo agent, or up to 20 for a multi-repo agent. Mutually exclusive with a named env.name for Cursor-hosted environments. Pass prUrl to attach the agent to an existing PR. workOnCurrentBranch boolean false Push commits to the existing branch instead of a new one. autoCreatePR boolean false Open a PR when the run finishes. skipReviewerRequest boolean false Skip requesting the calling user as a reviewer on the PR. AgentDefinition Property Type Default Description description string required When to use this subagent. Shown to the parent agent so it knows when to spawn. prompt string required System prompt for the subagent. model ModelSelection | "inherit" "inherit" Model override. Pass "inherit" to use the parent's selection. mcpServers Array> MCP servers available to this subagent. Names reference servers from the parent's mcpServers . ModelSelection interface ModelSelection { id : string ; params ?: ModelParameterValue []; } interface ModelParameterValue { id : string ; value : string ; } id is the model identifier (for example, "composer-2" ). params carries per-model parameters such as reasoning effort. Use Cursor.models.list() to discover valid ids, parameter definitions, and preset variants for your account. McpServerConfig type McpServerConfig = // stdio | { type ?: "stdio" ; command : string ; args ?: string []; env ?: Record < string , string >; cwd ?: string ; // local only; cloud rejects this field } // HTTP / SSE | { type ?: "http" | "sse" ; url : string ; headers ?: Record < string , string >; // passed through; Authorization here works auth ?: { CLIENT_ID : string ; CLIENT_SECRET ?: string ; scopes ?: string []; }; }; For HTTP servers running in the cloud, headers and auth are handled by Cursor's backend. Sensitive fields are redacted before the VM sees them. For stdio servers in the cloud, env values are passed into the VM (treat them like any runtime secret). SDKUserMessage interface SDKUserMessage { text : string ; images ?: SDKImage []; } The structured form of agent.send() 's message argument. Use it to send images alongside text. SDKImage type SDKImage = | { url : string ; dimension ?: SDKImageDimension } | { data : string ; mimeType : string ; dimension ?: SDKImageDimension }; interface SDKImageDimension { width : number ; height : number ; } Pass either a remote url or base64 data with a mimeType . SettingSource type SettingSource = | "project" | "user" | "team" | "mdm" | "plugins" | "all" ; Controls which on-disk settings layers a local agent loads. Cloud agents always load project / team / plugins and ignore this field. Value Source "project" .cursor/ in the workspace "user" ~/.cursor/ "team" Team settings synced from the dashboard "mdm" MDM-managed enterprise settings "plugins" Plugin-provided settings "all" Shorthand for all of the above ListResult interface ListResult < T > { items : T []; nextCursor ?: string ; } Returned by Agent.list() and Agent.listRuns() . nextCursor is absent when there are no more pages. Errors All SDK errors extend CursorAgentError . Use isRetryable to drive retry logic. class CursorAgentError extends Error { readonly isRetryable : boolean ; readonly code ?: string ; readonly cause ?: unknown ; readonly protoErrorCode ?: string ; } Error When AuthenticationError Invalid API key, not logged in, insufficient permissions. RateLimitError Too many requests or usage limits exceeded. ConfigurationError Invalid model, bad request parameters. AgentBusyError Sending a follow-up while the agent already has a run in CREATING or RUNNING state (HTTP 409 , code agent_busy ). IntegrationNotConnectedError Creating a cloud agent for a repo whose SCM provider is not connected. NetworkError Service unavailable, timeout. UnknownAgentError Catch-all for unclassified server or runtime errors. IntegrationNotConnectedError class IntegrationNotConnectedError extends ConfigurationError { readonly provider : string ; // e.g. "github", "gitlab", "azuredevops" readonly helpUrl : string ; // dashboard link to reconnect } Use helpUrl to point the user at the right reconnect flow. New providers will be added without an SDK release. AgentBusyError Cloud agents allow only one active run at a time. AgentBusyError is thrown when you call agent.send() (or otherwise create a run) while another run on the same agent is still CREATING or RUNNING . class AgentBusyError extends CursorAgentError { readonly code : "agent_busy" ; readonly status : 409 ; readonly isRetryable : false ; } isRetryable is false . Retrying immediately will keep failing until the active run reaches a terminal status or you cancel it. Other 409 responses, such as agent_archived , throw ConfigurationError instead. Wait for the active run to finish, cancel it with run.cancel() , or poll Agent.listRuns() before sending again: import { Agent, AgentBusyError } from "@cursor/sdk" ; const agent = await Agent. resume ( "bc-00000000-0000-0000-0000-000000000001" ); try { await agent. send ({ text: "Also add tests for the auth middleware." }); } catch (err) { if (err instanceof AgentBusyError ) { const runs = await Agent. listRuns (agent.agentId, { runtime: "cloud" , limit: 1 }); const active = runs.items[ 0 ]; if (active?.status === "running" ) { await active. cancel (); } await agent. send ({ text: "Also add tests for the auth middleware." }); return ; } throw err; } Local agents do not return agent_busy . Use send({ local: { force: true } }) to expire a stuck local run before starting a new one. UnsupportedRunOperationError class UnsupportedRunOperationError extends Error { readonly operation : RunOperation ; } Thrown when a Run operation is not available on the current runtime. Use run.supports(operation) and run.unsupportedReason(operation) to check before calling. Known limitations Inline mcpServers are not persisted across Agent.resume() . Pass them again on resume if needed. Artifact download is not implemented for local agents ( agent.listArtifacts() returns an empty list and agent.downloadArtifact() throws). local.settingSources (and the file-based MCP / subagent paths it gates) does not apply to cloud agents. Cloud always loads project / team / plugins . Hooks are file-based only ( .cursor/hooks.json ). No programmatic callbacks. English English 简体中文 日本語 繁體中文 Español Français Português 한국어 Русский Türkçe Bahasa Indonesia Deutsch हिन्दी

Agent Prompting agents Direct Agent with text prompts in the chat input. You can attach context, images, and voice, and switch models at any point. @ mentions Type @ in the chat input to attach specific context to your prompt. Start typing after @ and Cursor shows matching suggestions. Files & Folders : @auth.ts or @src/components/ to include files or folders (type / after selecting a folder to navigate deeper) Docs : @Docs to search indexed documentation, including your own (add via @Docs > Add new doc ) Terminals : @Terminals to include terminal output as context Past Chats : @Past Chats to reference context from a previous conversation Git diffs : @Commit (Diff of Working State) for uncommitted changes, or @Branch (Diff with Main) for your full branch diff Browser : @Browser to attach context from the built-in browser Use @ mentions when you know which files are relevant. If you're not sure which files matter, skip it — Agent finds relevant files through its own search. Image input Attach images to your prompt to provide visual context for UI work, debugging, and design implementation. Drag and drop an image file into the chat input Paste from clipboard with Cmd+V Ctrl+V , including screenshots This is useful for implementing design mockups, debugging visual issues, and referencing error messages or stack traces without manual transcription. Voice input Click the microphone icon in the chat input to dictate your prompt instead of typing. Speak naturally, include technical details like file and function names, and review the transcription before sending. Context usage Every chat shares a fixed context window with the model. As you add files, run tools, and exchange messages, those tokens fill up. When the window gets close to full, Cursor compresses older parts of the conversation into a summary to leave more room for new conversation. The context ring next to your prompt input shows how full the window is at a glance. Click the ring to open the breakdown tray, which shows the total tokens used split by category: System prompt : Cursor's built-in instructions for the model Tools : definitions of every tool available to the agent Rules : project and user rules included in the prompt Skills : skill descriptions injected into the system context MCP : instructions and catalog from connected MCP servers Subagents : documentation for subagent types the agent can launch Summarized conversation : compressed summaries of earlier turns Conversation : your messages, the agent's replies, and tool results Hover a segment in the bar or a row in the list to highlight that category. Changing models Use the model picker dropdown at the top of the chat input to switch models, or press Cmd / Ctrl / to cycle through models. The change applies to the current conversation going forward. Set a default model in Cursor Settings > Models . Faster models work well for quick edits and routine tasks More capable models are better for complex reasoning and multi-file refactoring You can switch models mid-conversation, for example when a faster model handled exploration but you need deeper reasoning for implementation. See Models & Pricing for the full list. English English 简体中文 日本語 繁體中文 Español Français Português 한국어 Русский Türkçe Bahasa Indonesia Deutsch हिन्दी

Integrations Microsoft Teams With Cursor's integration for Microsoft Teams, you can use Cloud Agents to work on tasks directly from Microsoft Teams by mentioning @Cursor with a prompt. Get started Installation Go to Cursor integrations Click Connect next to Microsoft Teams or go to the Microsoft Marketplace listing Install the Cursor app in your Microsoft Teams workspace After installing in Microsoft Teams, you'll be redirected back to Cursor to finalize setup Connect GitHub or GitLab, if you haven't connected a repository provider yet Enable usage-based pricing Confirm privacy settings Start using Cloud Agents in Microsoft Teams by mentioning @Cursor How to use Mention @Cursor and give your prompt. Cursor automatically picks the right repository and model based on your message, the thread context, and your recent agent activity. To use a specific repository, include its name in your message: @Cursor in cursor-app, fix the login bug @Cursor fix the auth issue in backend-api To use a specific model, mention it in your message: @Cursor with opus, fix the login bug @Cursor use gpt-5.2 to refactor the auth module Commands Run @Cursor help for an up-to-date command list. Command Description @Cursor [prompt] Start a Cloud Agent. In channel threads with existing agents, adds follow-up instructions @Cursor help Show setup and usage help @Cursor unlink Disconnect your Cursor account from Microsoft Teams @Cursor disconnect Disconnect your Cursor account from Microsoft Teams @Cursor [options] [prompt] Use advanced options: repo , branch , model Options Customize Cloud Agent behavior with these options: Option Description Example repo Specify repository repo=acme/web-app branch Specify base branch branch=main model Specify model model=opus Syntax formats Natural: @Cursor with opus, fix the login bug in backend-api Inline: @Cursor repo=acme/backend branch=dev model=opus Fix the login bug Option precedence When combining options: Explicit values override defaults Inline options override model and repository values inferred from your message Dashboard settings apply when no value is specified or inferred The bot parses options from anywhere in the message, allowing natural command writing. Using thread context Cloud Agents understand and use context from existing Microsoft Teams discussions. This is useful when your team discusses an issue and you want the agent to make the code change based on that conversation. Cloud Agents read the relevant thread or chat context when invoked, understanding and acting on your team's discussion. Follow-up instructions In channel threads, reply in the agent's thread with another @Cursor mention to add follow-up instructions. In personal chats and group chats, continue the conversation from Cursor using Open in Web or Open in Desktop . Status updates & handoff When Cloud Agent starts, Microsoft Teams shows a launch card with the selected repository, model, and branch. The card includes options to Open in Web , Open in Desktop , and Switch repository . When Cloud Agent completes, you get a Microsoft Teams notification with the result. If the agent opened a pull request, the card includes an option to view the PR. Managing agents Manage Cloud Agents using actions on the Microsoft Teams cards. Available options: Add follow-up : Add instructions to an existing agent from a channel thread Switch repository : Relaunch the same request against a different repository Delete : Stop and archive the Cloud Agent Open in Web : Continue in the web interface Open in Desktop : Continue in Cursor Update settings : Manage your Cloud Agent defaults Give feedback : Send feedback about agent performance Configuration Manage default settings and privacy options from Dashboard -> Cloud Agents . Settings Default model Used when no model is specified in your message. See settings for available options. Repository selection Cursor automatically selects the right repository based on: Your message content : repository names or keywords in your prompt Recent agent activity : repositories you've used recently Default repository : fallback when no match is found To use a specific repository, include its name in your message. For example: @Cursor in mobile-app, fix the login bug . Base branch Starting branch for Cloud Agent. Leave blank to use the repository's default branch, often main . Routing behavior Cursor evaluates your Microsoft Teams message in this order: Explicit options : repo , branch , and model values in your prompt Your message content : repository names, model names, or branch names in your prompt Recent agent activity : repositories you've used recently Default repository : fallback when no match is found Privacy Cloud Agents support Privacy Mode. Read more about Privacy Mode or manage your privacy settings . Privacy Mode (Legacy) is not supported. Cloud Agents require temporary code storage while running. Display agent summary Display agent summaries and diff images. They may contain file paths or code snippets. You can turn this on or off. Permissions Cursor requests these Microsoft Teams permissions for Cloud Agents to work in your workspace: Permission Description identity Identifies the Microsoft Teams user starting or managing an agent messageTeamMembers Sends direct messages for setup, account linking, and notifications ChannelMessage.Read.Group Reads channel messages and replies for thread context ChatMessage.Read.Chat Reads personal and group chat messages for conversation context ChannelSettings.Read.Group Reads channel metadata, including channel names and descriptions TeamSettings.Read.Group Reads team metadata, including team names and descriptions The Cursor app supports personal chats, team channels, and group chats in Microsoft Teams. Disclaimer Cursor can make mistakes. Please double-check code and responses. Privacy Policy For information about how Cursor collects, uses, and protects your data, see our Privacy Policy . English English 简体中文 日本語 繁體中文 Español Français Português 한국어 Русский Türkçe Bahasa Indonesia Deutsch हिन्दी

CLI Using Agent in CLI Modes The CLI supports the same modes as the editor. Switch modes using slash commands or the --mode flag. Plan mode Use Plan mode to design your approach before coding. The agent asks clarifying questions to refine your plan. Press Shift+Tab to rotate to Plan mode Use /plan to switch to Plan mode Start with --plan or --mode=plan flag Ask mode Use Ask mode to explore code without making changes. The agent searches your codebase and provides answers without editing files. Use /ask to switch to Ask mode Start with --mode=ask flag Prompting Stating intent clearly is recommended for the best results. For example, you can use the prompt "do not write any code" to ensure that the agent won't edit any files. This is generally helpful when planning tasks before implementing them. Agent has tools for file operations, searching, running shell commands, and web access. MCP Agent supports MCP (Model Context Protocol) for extended functionality and integrations. The CLI will automatically detect and respect your mcp.json configuration file, enabling the same MCP servers and tools that you've configured for the editor. ACP Agent also supports ACP (Agent Client Protocol) for custom client integrations. Use agent acp to run Cursor CLI as an ACP server over stdio with JSON-RPC messaging. Rules The CLI agent supports the same rules system as the editor. You can create rules in the .cursor/rules directory to provide context and guidance to the agent. These rules will be automatically loaded and applied based on their configuration, allowing you to customize the agent's behavior for different parts of your project or specific file types. The CLI also reads AGENTS.md and CLAUDE.md at the project root (if present) and applies them as rules alongside .cursor/rules . Working with Agent Navigation Previous messages can be accessed using arrow up ( ArrowUp Arrow Up ) where you can cycle through them. Input shortcuts Shift+Tab — Rotate between modes (Agent, Plan, Ask) Shift+Enter — Insert a newline instead of submitting, making it easier to write multi-line prompts. Ctrl+D — Exit the CLI. Follows standard shell behavior, requiring a double-press to exit. Ctrl+J or +Enter — Universal alternatives for inserting newlines that work in all terminals. Shift+Enter works in iTerm2, Ghostty, Kitty, Warp, and Zed. For tmux users, use Ctrl+J instead. See Terminal Setup for configuration options and troubleshooting. Review Review changes with Ctrl+R . Press i to add follow-up instructions. Use ArrowUp Arrow Up / ArrowDown Arrow Down to scroll, and ArrowLeft Arrow Left / ArrowRight Arrow Right to switch files. Selecting context Select files and folders to include in context with @ . Free up space in the context window by running /compress . Cloud Agent handoff Push your conversation to a Cloud Agent and let it keep running while you're away. Prepend & to any message to send it to the cloud. Pick it back up on web or mobile at cursor.com/agents . # Send a task to Cloud Agent mid-conversation & refactor the auth module and add comprehensive tests CLI worktrees Pass --worktree to run the agent in a new Git worktree instead of editing your current checkout directly. Cursor creates these checkouts under ~/.cursor/worktrees , alongside worktrees created from the editor. Cursor cleans up CLI worktrees with the same retention rules it uses for editor worktrees. For cleanup settings and limits, see How are old worktrees cleaned up? . Combine --workspace when you need an explicit repository root. Otherwise the CLI uses the current working directory. --worktree only changes where the agent makes file edits inside that project. # Create a temporary worktree from the current repository agent --worktree "upgrade the test runner and fix any broken snapshots" # Target a repository from anywhere, but keep the changes isolated agent --workspace ~/src/my-app --worktree "fix the flaky auth test and open a PR" History Continue from an existing thread with --resume [thread id] to load prior context. To resume the most recent conversation, use agent resume , --continue , or the /resume slash command. You can also run agent ls to see a list of previous conversations. Command approval Before running terminal commands, CLI will ask you to approve ( y ) or reject ( n ) execution. Non-interactive mode Use -p or --print to run Agent in non-interactive mode. This will print the response to the console. With non-interactive mode, you can invoke Agent in a non-interactive way. This allows you to integrate it in scripts, CI pipelines, etc. You can combine this with --output-format to control how the output is formatted. For example, use --output-format json for structured output that's easier to parse in scripts, or --output-format text for plain text output of the agent's final response. Cursor has full write access in non-interactive mode. English English 简体中文 日本語 繁體中文 Español Français Português 한국어 Русский Türkçe Bahasa Indonesia Deutsch हिन्दी

CLI Cursor CLI Cursor CLI lets you interact with AI agents directly from your terminal to write, review, and modify code. Whether you prefer an interactive terminal interface or print automation for scripts and CI pipelines, the CLI provides powerful coding assistance right where you work. Getting started # Install (macOS, Linux, WSL) curl https://cursor.com/install -fsS | bash # Install (Windows PowerShell) irm 'https://cursor.com/install?win32=true' | iex # Run interactive session agent Interactive mode Start a conversational session with the agent to describe your goals, review proposed changes, and approve commands: # Start interactive session agent # Start with initial prompt agent "refactor the auth module to use JWT tokens" Modes The CLI supports the same modes as the editor. Switch between modes using slash commands, keyboard shortcuts, or the --mode flag. Mode Description Shortcut Agent Full access to all tools for complex coding tasks Default (no --mode value needed) Plan Design your approach before coding with clarifying questions Shift+Tab , /plan , --plan , --mode=plan Ask Read-only exploration without making changes /ask , --mode=ask Non-interactive mode Use print mode for non-interactive scenarios like scripts, CI pipelines, or automation: # Run with specific prompt and model agent -p "find and fix performance issues" --model "gpt-5.2" # Use with git changes included for review agent -p "review these changes for security issues" --output-format text Cloud Agent handoff Push your conversation to a Cloud Agent to continue running while you're away. Prepend & to any message: # Send a task to Cloud Agent mid-conversation & refactor the auth module and add comprehensive tests Pick up your Cloud Agent tasks on web or mobile at cursor.com/agents . Sessions Resume previous conversations to maintain context across multiple interactions: # List all previous chats agent ls # Resume latest conversation agent resume # Continue the previous session agent --continue # Resume specific conversation agent --resume= "chat-id-here" Sandbox controls Configure command execution settings with /sandbox or the --sandbox flag ( enabled or disabled ). Toggle sandbox mode on or off and control network access through an interactive menu. Settings persist across sessions. Max Mode Toggle Max Mode on models that support it using /max-mode [on|off] . Sudo password prompting Run commands requiring elevated privileges without leaving the CLI. When a command needs sudo , Cursor displays a secure, masked password prompt. Your password flows directly to sudo via a secure IPC channel; the AI model never sees it. English English 简体中文 日本語 繁體中文 Español Français Português 한국어 Русский Türkçe Bahasa Indonesia Deutsch हिन्दी

CLI Installation Installation macOS, Linux and Windows (WSL) Install Cursor CLI with a single command: curl https://cursor.com/install -fsS | bash Windows (native) Install Cursor CLI on Windows using PowerShell: irm 'https://cursor.com/install?win32=true' | iex Verification After installation, verify that Cursor CLI is working correctly: agent --version Post-installation setup Add ~/.local/bin to your PATH: For bash: echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc source ~/.bashrc For zsh: echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc source ~/.zshrc Start using Cursor Agent: agent Updates Cursor CLI will try to auto-update by default to ensure you always have the latest version. To manually update Cursor CLI to the latest version: agent update English English 简体中文 日本語 繁體中文 Español Français Português 한국어 Русский Türkçe Bahasa Indonesia Deutsch हिन्दी

CLI ACP Overview Cursor CLI supports ACP (Agent Client Protocol) for advanced integrations. You can run agent acp and connect a custom client over stdio using JSON-RPC. Learn more in the official Agent Client Protocol docs . ACP is intended for building custom clients and integrations. For normal terminal workflows, use the interactive CLI with agent . Start ACP server Start Cursor CLI in ACP mode: agent acp Transport and message format Transport: stdio Protocol envelope: JSON-RPC 2.0 Framing: newline-delimited JSON (one message per line) Direction: Client writes requests/notifications to stdin Cursor CLI writes responses/notifications to stdout Logs may be written to stderr Request flow Typical ACP session flow: initialize authenticate with methodId: "cursor_login" session/new (or session/load ) session/prompt Handle session/update notifications while the model streams output Handle session/request_permission by returning a decision Optionally send session/cancel Authentication Cursor CLI advertises cursor_login as the ACP auth method. In practice, you can pre-authenticate before startup using existing CLI auth paths: agent login --api-key (or CURSOR_API_KEY ) --auth-token (or CURSOR_AUTH_TOKEN ) You can also pass endpoint and TLS options from the root CLI command: agent --api-key " $CURSOR_API_KEY " acp agent -e https://api2.cursor.sh acp agent -k acp Sessions, modes, and permissions Sessions Create a session with session/new Resume an existing conversation with session/load Modes ACP sessions support the same core modes as CLI: agent (full tool access) plan (planning, read-only behavior) ask (Q&A/read-only behavior) Permissions When tools need approval, Cursor sends session/request_permission . Clients should return one of: allow-once allow-always reject-once If your client does not answer permission requests, tool execution can block. MCP servers ACP supports MCP servers defined in a project-level or user-level .cursor/mcp.json . Launch agent from your project directory and approve the servers you want to use. Team-level MCP servers configured through the Cursor dashboard are not supported in ACP mode. Cursor extension methods Cursor sends ACP extension methods for richer client UX. There are two types: Blocking methods ( cursor/ask_question , cursor/create_plan ): The agent waits for a response before continuing. Your client must reply with a JSON-RPC response. Notification methods ( cursor/update_todos , cursor/task , cursor/generate_image ): The agent sends these as fire-and-forget notifications. Your client can display them but doesn't need to respond. Method Type Use cursor/ask_question Blocking Ask users multiple-choice questions cursor/create_plan Blocking Request explicit plan approval cursor/update_todos Notification Notify client about todo state updates cursor/task Notification Notify client about subagent task completion cursor/generate_image Notification Notify client about generated image output cursor/ask_question Present multiple-choice questions to the user. The agent blocks until the client responds. Request: interface CursorAskQuestionRequest { toolCallId : string ; title ?: string ; questions : Array <{ id : string ; prompt : string ; options : Array <{ id : string ; label : string }>; allowMultiple ?: boolean ; }>; } Response: interface CursorAskQuestionResponse { outcome : | { outcome : "answered" ; answers : Array <{ questionId : string ; selectedOptionIds : string []; }>; } | { outcome : "skipped" ; reason ?: string } | { outcome : "cancelled" }; } Example request: { "toolCallId" : "call_123" , "title" : "Need input" , "questions" : [ { "id" : "q1" , "prompt" : "Which mode should I use?" , "options" : [ { "id" : "agent" , "label" : "Agent" }, { "id" : "plan" , "label" : "Plan" } ], "allowMultiple" : false } ] } cursor/create_plan Request plan approval from the user. The agent blocks until the client accepts or rejects the plan. Request: interface CursorCreatePlanRequest { toolCallId : string ; name ?: string ; overview ?: string ; plan : string ; todos : Array <{ id : string ; content : string ; status : "pending" | "in_progress" | "completed" | "cancelled" ; }>; isProject ?: boolean ; phases ?: Array <{ name : string ; todos : Array <{ id : string ; content : string ; status : "pending" | "in_progress" | "completed" | "cancelled" ; }>; }>; } plan : A markdown string describing the full plan. phases : Optional grouping of todos into named phases for larger plans. Response: interface CursorCreatePlanResponse { outcome : | { outcome : "accepted" ; planUri ?: string } | { outcome : "rejected" ; reason ?: string } | { outcome : "cancelled" }; } Example request: { "toolCallId" : "call_124" , "name" : "Refactor tabs layout" , "overview" : "Tighten layout behavior and preserve existing UX." , "plan" : "1. Inspect current tab sizing logic. \n 2. Update layout calculations. \n 3. Verify editor behavior." , "todos" : [ { "id" : "todo-1" , "content" : "Inspect current tab sizing logic" , "status" : "completed" }, { "id" : "todo-2" , "content" : "Update layout calculations" , "status" : "in_progress" }, { "id" : "todo-3" , "content" : "Verify editor behavior" , "status" : "pending" } ], "isProject" : false } cursor/update_todos Update the client's todo list. Sent as a notification; no response required. Request: interface CursorUpdateTodosRequest { toolCallId : string ; todos : Array <{ id : string ; content : string ; status : "pending" | "in_progress" | "completed" | "cancelled" ; }>; merge : boolean ; } merge : When true , merge these todos into the existing list. When false , replace the entire list. Response: interface CursorUpdateTodosResponse { outcome : | { outcome : "accepted" ; todos : Array <{ id : string ; content : string ; status : "pending" | "in_progress" | "completed" | "cancelled" ; }>; } | { outcome : "rejected" ; reason ?: string } | { outcome : "cancelled" }; } Example request: { "toolCallId" : "call_125" , "todos" : [ { "id" : "1" , "content" : "Set up project structure" , "status" : "completed" }, { "id" : "2" , "content" : "Add authentication" , "status" : "in_progress" }, { "id" : "3" , "content" : "Write unit tests" , "status" : "pending" } ], "merge" : true } cursor/task Notify the client about a subagent task. Sent as a notification; no response required. Request: interface CursorTaskRequest { toolCallId : string ; description : string ; prompt : string ; subagentType : | "unspecified" | "computer_use" | "explore" | "video_review" | "browser_use" | "shell" | "vm_setup_helper" | { custom : string }; model ?: string ; agentId ?: string ; durationMs ?: number ; } subagentType : The type of subagent to run. Use { custom: "your_type" } for custom subagent types. agentId : Set this to resume a previously created subagent. durationMs : How long the task ran, included in the response. Response: interface CursorTaskResponse { outcome : | { outcome : "completed" ; agentId ?: string ; durationMs ?: number } | { outcome : "rejected" ; reason ?: string } | { outcome : "cancelled" }; } Example request: { "toolCallId" : "call_126" , "description" : "Explore codebase" , "prompt" : "Find where authentication is handled and report the file paths." , "subagentType" : "explore" } cursor/generate_image Notify the client about a generated image. Sent as a notification; no response required. Request: interface CursorGenerateImageRequest { toolCallId : string ; description : string ; filePath ?: string ; referenceImagePaths ?: string []; } filePath : Suggested file path for the generated image. referenceImagePaths : Paths to reference images used as input. Response: interface CursorGenerateImageResponse { outcome : | { outcome : "generated" ; filePath : string ; imageData ?: string } | { outcome : "rejected" ; reason ?: string } | { outcome : "cancelled" }; } Example request: { "toolCallId" : "call_127" , "description" : "Minimal flat app icon for a note-taking app" , "filePath" : "/tmp/icon.png" , "referenceImagePaths" : [ "/tmp/reference.png" ] } Minimal Node.js client This example shows the minimum control flow for a custom ACP client: import { spawn } from "node:child_process" ; import readline from "node:readline" ; const agent = spawn ( "agent" , [ "acp" ], { stdio: [ "pipe" , "pipe" , "inherit" ] }); let nextId = 1 ; const pending = new Map (); function send ( method , params ) { const id = nextId ++ ; agent.stdin. write ( JSON . stringify ({ jsonrpc: "2.0" , id, method, params }) + " \n " ); return new Promise (( resolve , reject ) => pending. set (id, { resolve, reject })); } function respond ( id , result ) { agent.stdin. write ( JSON . stringify ({ jsonrpc: "2.0" , id, result }) + " \n " ); } const rl = readline. createInterface ({ input: agent.stdout }); rl. on ( "line" , line => { const msg = JSON . parse (line); if (msg.id && (msg.result || msg.error)) { const waiter = pending. get (msg.id); if ( ! waiter) return ; pending. delete (msg.id); msg.error ? waiter. reject (msg.error) : waiter. resolve (msg.result); return ; } if (msg.method === "session/update" ) { const update = msg.params?.update; if (update?.sessionUpdate === "agent_message_chunk" && update.content?.text) { process.stdout. write (update.content.text); } return ; } if (msg.method === "session/request_permission" ) { respond (msg.id, { outcome: { outcome: "selected" , optionId: "allow-once" } }); } }); const init = async () => { await send ( "initialize" , { protocolVersion: 1 , clientCapabilities: { fs: { readTextFile: false , writeTextFile: false }, terminal: false }, clientInfo: { name: "acp-minimal-client" , version: "0.1.0" } }); await send ( "authenticate" , { methodId: "cursor_login" }); const { sessionId } = await send ( "session/new" , { cwd: process. cwd (), mcpServers: [] }); const result = await send ( "session/prompt" , { sessionId, prompt: [{ type: "text" , text: "Say hello in one sentence." }] }); console. log ( ` \n\n [stopReason=${ result . stopReason }]` ); }; init (). finally (() => { agent.stdin. end (); agent. kill (); }); IDE integrations ACP enables Cursor's AI agent to work with editors beyond the Cursor desktop app. Build or use third-party integrations for your preferred development environment. Example use cases JetBrains IDEs — Connect IntelliJ IDEA, WebStorm, PyCharm, or other JetBrains IDEs to Cursor's agent. See the JetBrains integration guide for setup instructions. Neovim (avante.nvim) — Use avante.nvim to connect Neovim to Cursor's agent through ACP. See Neovim setup below. Zed — Integrate with Zed's modern editor by spawning agent acp and communicating over stdio. Zed extensions can implement the ACP client protocol to route AI requests to Cursor. Custom editors — Any editor with extension support can implement an ACP client. Spawn the agent process, send JSON-RPC messages over stdio, and handle responses in your editor's UI. Neovim (avante.nvim) avante.nvim is a Neovim plugin that provides an AI-powered coding assistant. It supports ACP, so you can connect it to Cursor's agent for agentic coding inside Neovim. Add the following to your lazy.nvim plugin configuration (e.g., ~/.config/nvim/lua/plugins/avante.lua ): return { { "yetone/avante.nvim" , event = "VeryLazy" , version = false , build = "make" , opts = { provider = "cursor" , mode = "agentic" , acp_providers = { cursor = { command = os.getenv ( "HOME" ) .. "/.local/bin/agent" , args = { "acp" }, auth_method = "cursor_login" , env = { HOME = os.getenv ( "HOME" ), PATH = os.getenv ( "PATH" ), }, }, }, }, dependencies = { "nvim-lua/plenary.nvim" , "MunifTanjim/nui.nvim" , "nvim-tree/nvim-web-devicons" , { "MeanderingProgrammer/render-markdown.nvim" , opts = { file_types = { "markdown" , "Avante" }, }, ft = { "markdown" , "Avante" }, }, }, }, } Key settings: provider : Set to "cursor" to route requests through Cursor's agent. mode : Set to "agentic" for full tool access (file edits, terminal commands). Use "normal" for chat-only mode. command : Points to the agent binary. The default install path is ~/.local/bin/agent . Adjust if you installed it elsewhere. auth_method : Uses "cursor_login" . Run agent login in your terminal first to authenticate. Building an integration Spawn agent acp as a child process Communicate over stdin/stdout using JSON-RPC Handle session/update notifications to display streaming responses Respond to session/request_permission when tools need approval Optionally implement Cursor extension methods for richer UX See the minimal Node.js client above for a working reference implementation. Related MCP in CLI Manage and use MCP servers from Cursor CLI MCP Overview Learn MCP transports, configuration, and server setup English English 简体中文 日本語 繁體中文 Español Français Português 한국어 Русский Türkçe Bahasa Indonesia Deutsch हिन्दी

Models Claude 4.7 Opus Model ID claude-opus-4-7 Context window 200k Max context 1M Provider Anthropic Capabilities Agent Thinking Speed Medium Cost High Intelligence Frontier Opus 4.7 is Anthropic's strongest model and a meaningful jump over Opus 4.6 on CursorBench . It excels at autonomous, multi-step work: it holds intent across long sessions, self-corrects when it hits friction, and writes production-ready code without hand-holding. We recommend the high thinking variant for the best results. Strengths Autonomous and self-directed. Opus 4.7 drives multi-step tasks to completion without losing track of the goal, even across large codebases and long conversations. Creative reasoning. It approaches problems from unexpected angles, explores alternative solutions, and produces more inventive code than its predecessor. Strong at planning. It maps out work before executing, catches edge cases early, and builds coherent architectures across many files. Reliable tool use. It calls tools purposefully, chains tool results into follow-up actions, and adapts when tool output surprises it. Limitations Most expensive model. Consumes usage limits faster than alternatives. Can over-elaborate in long sessions where brevity matters more than depth. Tools Opus 4.7 has access to all agent tools when used with Cursor including: Semantic search Search your indexed codebase by meaning, not exact matches. Search files and folders Find files by name, read directory structures, and grep for patterns. Web Generate search queries and fetch results from the web. Read files Read file contents, including images for vision-capable models. Edit files Suggest edits and apply them automatically. Run shell commands Execute terminal commands and monitor output. Browser Control a browser to take screenshots, test applications, and verify visual changes. See the Browser documentation . Image generation Generate images from text descriptions or reference images. Ask questions Ask clarifying questions while continuing to work in the background. Fetch rules Retrieve rules based on type and description. Learn more about how tools work and tool calling fundamentals . Pricing Cursor plans include two usage pools. Opus 4.7 draws from the API pool, which charges at the rates below. Individual plans include at least $20 of API usage each month (more on higher tiers). All prices are per million tokens. Name Input Cache Write Cache Read Output Claude 4.7 Opus $5 $6.25 $0.5 $25 All Opus 4.7 prompts bill at the base per-token rates in the table above, including when you use Max Mode and context goes above 200k. There is no separate long-context multiplier for Opus 4.7; up to 1M tokens at the same rates. Opus 4.7 supports a thinking variant for deeper reasoning. We recommend using the high thinking variant for the strongest results. English English 简体中文 日本語 繁體中文 Español Français Português 한국어 Русский Türkçe Bahasa Indonesia Deutsch हिन्दी

Customizing Model Context Protocol (MCP) What is MCP? Model Context Protocol (MCP) enables Cursor to connect to external tools and data sources. Why use MCP? MCP connects Cursor to external systems and data. Instead of explaining your project structure repeatedly, integrate directly with your tools. Write MCP servers in any language that can print to stdout or serve an HTTP endpoint - Python, JavaScript, Go, etc. Browse official plugins in the Cursor Marketplace . For community plugins and MCP servers, browse cursor.directory . How it works MCP servers expose capabilities through the protocol, connecting Cursor to external tools or data sources. Cursor supports three transport methods: Transport Execution environment Deployment Users Input Auth stdio Local Cursor manages Single user Shell command Manual SSE Local/Remote Deploy as server Multiple users URL to an SSE endpoint OAuth Streamable HTTP Local/Remote Deploy as server Multiple users URL to an HTTP endpoint OAuth Protocol and extension support Cursor supports these MCP protocol capabilities and extensions: Feature Support Description Tools Supported Functions for the AI model to execute Prompts Supported Templated messages and workflows for users Resources Supported Structured data sources that can be read and referenced Roots Supported Server-initiated inquiries into URI or filesystem boundaries Elicitation Supported Server-initiated requests for additional information from users Apps (extension) Supported Interactive UI views returned by MCP tools MCP apps Cursor supports the MCP Apps extension . MCP tools can return interactive UI along with standard tool output. MCP Apps follow progressive enhancement. If a host cannot render app UI, the same tool still works through normal MCP responses. Installing MCP servers One-click installation Browse the Cursor Marketplace for official plugins with one-click install. For community plugins and MCP servers, browse cursor.directory . Click "Add to Cursor" on a marketplace entry to install it and authenticate with OAuth. Using mcp.json Configure custom MCP servers with a JSON file: CLI Server - Node.js { "mcpServers" : { "server-name" : { "command" : "npx" , "args" : [ "-y" , "mcp-server" ], "env" : { "API_KEY" : "value" } } } } CLI Server - Python { "mcpServers" : { "server-name" : { "command" : "python" , "args" : [ "mcp-server.py" ], "env" : { "API_KEY" : "value" } } } } Remote Server // MCP server using HTTP or SSE - runs on a server { "mcpServers" : { "server-name" : { "url" : "http://localhost:3000/mcp" , "headers" : { "API_KEY" : "value" } } } } Static OAuth for remote servers For MCP servers that use OAuth, you can provide static OAuth client credentials in mcp.json instead of dynamic client registration. Use this when: The MCP provider gives you a fixed Client ID (and optionally Client Secret ) The provider requires whitelisting a redirect URL (e.g. Figma, Linear) The provider does not support OAuth 2.0 Dynamic Client Registration Add an auth object to remote server entries that use url : Remote Server with Static OAuth { "mcpServers" : { "oauth-server" : { "url" : "https://api.example.com/mcp" , "auth" : { "CLIENT_ID" : "your-oauth-client-id" , "CLIENT_SECRET" : "your-client-secret" , "scopes" : [ "read" , "write" ] } } } } Field Required Description CLIENT_ID Yes OAuth 2.0 Client ID from the MCP provider CLIENT_SECRET No OAuth 2.0 Client Secret (if the provider uses confidential clients) scopes No OAuth scopes to request. If omitted, Cursor will use /.well-known/oauth-authorization-server to discover scopes_supported Static redirect URL Cursor uses a fixed OAuth redirect URL for all MCP servers: cursor://anysphere.cursor-mcp/oauth/callback When configuring the MCP provider's OAuth app, register this URL as an allowed redirect URI. The server is identified via the OAuth state parameter, so one redirect URL works for all MCP servers. Combining with config interpolation auth values support the same interpolation as other fields: { "mcpServers" : { "oauth-server" : { "url" : "https://api.example.com/mcp" , "auth" : { "CLIENT_ID" : "${env:MCP_CLIENT_ID}" , "CLIENT_SECRET" : "${env:MCP_CLIENT_SECRET}" } } } } Use environment variables for Client ID and Client Secret instead of hardcoding them. STDIO server configuration For STDIO servers (local command-line servers), configure these fields in your mcp.json : Field Required Description Examples type Yes Server connection type "stdio" command Yes Command to start the server executable. Must be available on your system path or contain its full path. "npx" , "node" , "python" , "docker" args No Array of arguments passed to the command ["server.py", "--port", "3000"] env No Environment variables for the server {"API_KEY": "${env:api-key}"} envFile No Path to an environment file to load more variables ".env" , "${workspaceFolder}/.env" The envFile option is only available for STDIO servers. Remote servers (HTTP/SSE) do not support envFile . For remote servers, use config interpolation with environment variables set in your shell profile or system environment instead. Using the Extension API For programmatic MCP server registration, Cursor provides an extension API that allows dynamic configuration without modifying mcp.json files. This is particularly useful for enterprise environments and automated setup workflows. Extension API reference Register MCP servers programmatically using vscode.cursor.mcp.registerServer() Configuration locations Project Configuration Create .cursor/mcp.json in your project for project-specific tools. Global Configuration Create ~/.cursor/mcp.json in your home directory for tools available everywhere. Config interpolation Use variables in mcp.json values. Cursor resolves variables in these fields: command , args , env , url , and headers . Supported syntax: ${env:NAME} environment variables ${userHome} path to your home folder ${workspaceFolder} project root (the folder that contains .cursor/mcp.json ) ${workspaceFolderBasename} name of the project root ${pathSeparator} and ${/} OS path separator Examples { "mcpServers" : { "local-server" : { "command" : "python" , "args" : [ "${workspaceFolder}/tools/mcp_server.py" ], "env" : { "API_KEY" : "${env:API_KEY}" } } } } { "mcpServers" : { "remote-server" : { "url" : "https://api.example.com/mcp" , "headers" : { "Authorization" : "Bearer ${env:MY_SERVICE_TOKEN}" } } } } Authentication MCP servers use environment variables for authentication. Pass API keys and tokens through the config. Cursor supports OAuth for servers that require it. Using MCP in chat Agent automatically uses MCP tools listed under Available Tools when relevant. This includes Plan Mode . Ask for a specific tool by name or describe what you need. Enable or disable tools from settings. Tool approval Agent asks for approval before using MCP tools by default. Click the arrow next to the tool name to see arguments. Auto-run Enable auto-run for Agent to use MCP tools without asking. Works like terminal commands. Read more about Auto-run settings here . To pre-configure which MCP tools can auto-run without using the settings UI, add them to ~/.cursor/permissions.json . Tool response Cursor shows the response in chat with expandable views of arguments and responses: Images as context MCP servers can return images - screenshots, diagrams, etc. Return them as base64 encoded strings: const RED_CIRCLE_BASE64 = "/9j/4AAQSkZJRgABAgEASABIAAD/2w..." ; // ^ full base64 clipped for readability server. tool ( "generate_image" , async ( params ) => { return { content: [ { type: "image" , data: RED_CIRCLE_BASE64 , mimeType: "image/jpeg" , }, ], }; }); See this example server for implementation details. Cursor attaches returned images to the chat. If the model supports images, it analyzes them. Security considerations When installing MCP servers, consider these security practices: Verify the source : Only install MCP servers from trusted developers and repositories Review permissions : Check what data and APIs the server will access Limit API keys : Use restricted API keys with minimal required permissions Audit code : For critical integrations, review the server's source code Remember that MCP servers can access external services and execute code on your behalf. Always understand what a server does before installation. Real-world examples For practical examples of MCP in action: Xcode integration — Connect Cursor to Xcode 26.3+ for builds, tests, SwiftUI previews, and Apple documentation search Web Development guide — Integrate Linear, Figma, and browser tools into your development workflow FAQ What's the point of MCP servers? MCP servers connect Cursor to external tools like Google Drive, Notion, and other services to bring docs and requirements into your coding workflow. How do I debug MCP server issues? View MCP logs by: Open the Output panel in Cursor ( Cmd+Shift+U Ctrl+Shift+U ) Select "MCP Logs" from the dropdown Check for connection errors, authentication issues, or server crashes The logs show server initialization, tool calls, and error messages. Can I temporarily disable an MCP server? Yes! Toggle servers on/off without removing them: Open Settings ( Cmd+Shift+J Ctrl+Shift+J ) Go to Features → Model Context Protocol Click the toggle next to any server to enable/disable Disabled servers won't load or appear in chat. This is useful for troubleshooting or reducing tool clutter. What happens if an MCP server crashes or times out? If an MCP server fails: Cursor shows an error message in chat The tool call is marked as failed You can retry the operation or check logs for details Other MCP servers continue working normally Cursor isolates server failures to prevent one server from affecting others. How do I update an MCP server? For npm-based servers: Remove the server from settings Clear npm cache: npm cache clean --force Re-add the server to get the latest version For custom servers, update your local files and restart Cursor. Can I use MCP servers with sensitive data? Yes, but follow security best practices: Use environment variables for secrets, never hardcode them Run sensitive servers locally with stdio transport Limit API key permissions to minimum required Review server code before connecting to sensitive systems Consider running servers in isolated environments English English 简体中文 日本語 繁體中文 Español Français Português 한국어 Русский Türkçe Bahasa Indonesia Deutsch हिन्दी

Models Grok 4.3 Model ID grok-4-3 Context window 200k Max context 1M Provider xAI Capabilities Agent Thinking Speed Fast Cost Medium Intelligence High Grok 4.3 is xAI's fastest and most capable model. It uses thinking mode by default, and supports a 200k context window (up to 1M in Max Mode). Strengths Up to 1M tokens of context in Max Mode. Useful for large repositories, long transcripts, and multi-file tasks. Thinking is always on, which helps with harder coding and debugging work. Priced at $1.25/$2.50 per 1M input/output tokens, roughly half the cost of Grok 4.20. Tools Grok 4.3 has access to all agent tools when used with Cursor, including: Semantic search Search your indexed codebase by meaning, not exact matches. Search files and folders Find files by name, read directory structures, and grep for patterns. Web Generate search queries and fetch results from the web. Read files Read file contents, including images for vision-capable models. Edit files Suggest edits and apply them automatically. Run shell commands Execute terminal commands and monitor output. Browser Control a browser to take screenshots, test applications, and verify visual changes. See the Browser documentation . Image generation Generate images from text descriptions or reference images. Ask questions Ask clarifying questions while continuing to work in the background. Fetch rules Retrieve rules based on type and description. Learn more about how tools work and tool calling fundamentals . Pricing Cursor plans include two usage pools. Grok 4.3 draws from the API pool, which charges at the rates below. Pricing is $1.25 per 1M input tokens, $0.20 per 1M cached tokens, and $2.50 per 1M output tokens. All prices are per million tokens. Name Input Cache Write Cache Read Output Grok 4.3 $1.25 - $0.2 $2.5 English English 简体中文 日本語 繁體中文 Español Français Português 한국어 Русский Türkçe Bahasa Indonesia Deutsch हिन्दी

Integrations Linear Use Cloud Agents directly from Linear by delegating issues to Cursor or mentioning @Cursor in comments. Get started Installation You must be a Cursor admin to connect the Linear integration. Other team settings are available to non-admin members. Go to Cursor integrations Click Connect next to Linear Connect your Linear workspace and select team Click Authorize Complete any remaining Cloud Agent setup in Cursor: Connect GitHub and select default repository Enable usage-based pricing Confirm privacy settings Account linking First use prompts account linking between Cursor and Linear. GitHub connection required for PR creation. How to use Delegate issues to Cursor or mention @Cursor in comments. Cursor analyzes issues and filters out non-development work automatically. Delegating issues Open Linear issue Click assignee field Select "Cursor" Mentioning Cursor Mention @Cursor in a comment to assign a new agent or provide additional instructions, for example: @Cursor fix the authentication bug described above . Workflow Cloud Agents show real-time status in Linear and create PRs automatically when complete. Track progress in Cursor dashboard . Follow-up instructions You can respond in the agent session and it'll get sent as a follow-up to the agent. Simply mention @Cursor in a Linear comment to provide additional guidance to a running Cloud Agent. Configuration Configure Cloud Agent settings from Dashboard → Cloud Agents . Setting Location Description Default Repository Cursor Dashboard Primary repository when no project repository configured Default Model Cursor Dashboard AI model for Cloud Agents Base Branch Cursor Dashboard Branch to create PRs from (typically main or develop ) Configuration options You can configure Cloud Agent behavior using several methods: Issue description or comments : Use [key=value] syntax, for example: @cursor please fix [repo=anysphere/everysphere] @cursor implement feature [model=claude-3.5-sonnet] [branch=feature-branch] Issue labels : Use parent-child label structure where the parent label is the configuration key and the child label is the value. Project labels : Same parent-child structure as issue labels, applied at the project level. Supported configuration keys: repo : Specify target repository (e.g., owner/repository ) branch : Specify base branch for PR creation model : Specify AI model to use Repository selection Cursor determines which repository to work on using this priority order: Issue description/comments : [repo=owner/repository] syntax in issue text or comments Issue labels : Repository labels attached to the specific Linear issue Project labels : Repository labels attached to the Linear project Default repository : Repository specified in Cursor dashboard settings Setting up repository labels To create repository labels in Linear: Go to Settings in your Linear workspace Click Labels Click New group Name the group "repo" (case insensitive - must be exactly "repo", not "Repository" or other variations) Within that group, create labels for each repository using the format owner/repo These labels can then be assigned to issues or projects to specify which repository the Cloud Agent should work on. Advanced features Triage rules (Advanced) Set up automation rules in Linear to automatically delegate issues to Cursor: Go to Linear project settings Navigate to triage rules Create rules that automatically: Add specific labels Assign issues to Cursor Trigger Cloud Agents based on conditions Triage rules are an advanced feature with some current limitations. Linear requires a human assignee for rules to fire, though this requirement may be removed in future updates. Getting help Check agent activity and include request IDs when contacting support. Feedback Share feedback through Linear comments or your Cursor dashboard support channels. English English 简体中文 日本語 繁體中文 Español Français Português 한국어 Русский Türkçe Bahasa Indonesia Deutsch हिन्दी

Integrations Deeplinks Deeplinks allow you to share prompts, commands, and rules with others, enabling collaboration and knowledge sharing across teams and communities. Links can also be opened via cursor.com . Append the path and url params to the end of the url, for example: cursor.com/link/prompt?text=... Always review your prompts and commands before sharing to ensure they don't contain sensitive information like API keys, passwords, or proprietary code. Prompts Share prompts that others can use to get started quickly with specific tasks or workflows. When someone clicks a prompt deeplink, it opens Cursor with the prompt pre-filled in the chat. The user must review and confirm the prompt before it gets executed. Deeplinks never trigger automatic execution. Research and find one bug in this codebase Cursor Logo Try in Cursor Playground TypeScript Python Text Progress circle Copy link Commands Share commands that others can execute directly in their Cursor environment. Command deeplinks allow you to share custom commands defined in your .cursor/commands directory. When someone clicks a command deeplink, it opens Cursor and creates a new command with the specified name and content. The user must review and confirm the command before it gets executed. debug-api: Add console.log statements to debug API responses Cursor Logo Add to Cursor Playground TypeScript Python Name Use letters, numbers, dots, hyphens, and underscores only Content Progress circle This will be saved as a command in .cursor/commands/ Copy link Rules Share rules that others can add to their Cursor environment. Rule deeplinks allow you to share custom rules defined in your .cursor/rules directory. When someone clicks a rule deeplink, it opens Cursor and creates a new rule with the specified name and content. The user must review and confirm the rule before it gets added. typescript-strict: Always use strict TypeScript types and avoid 'any' Cursor Logo Add to Cursor Playground TypeScript Python Name Use letters, numbers, dots, hyphens, and underscores only Content Progress circle This will be saved as a rule in .cursor/rules/ Copy link FAQ What is the maximum length for deeplink URLs? Deeplink URLs have a maximum length of 8,000 characters. When generating deeplinks programmatically, ensure your content doesn't exceed this limit when URL-encoded. The interactive generators above will show you the current URL length and remaining characters as you type. How do I use deeplinks on the web instead of in the Cursor app? You can swap the deeplink protocol for web links by changing the base URL from cursor://anysphere.cursor-deeplink/ to https://cursor.com/link/ . For example: cursor://anysphere.cursor-deeplink/prompt?text=Hello%20world https://cursor.com/link/prompt?text=Hello%20world Web links will redirect users to cursor.com where they can open the deeplink in their browser or copy it to use in Cursor. English English 简体中文 日本語 繁體中文 Español Français Português 한국어 Русский Türkçe Bahasa Indonesia Deutsch हिन्दी

Cloud Agents My Machines My Machines lets you run Cloud Agents on a machine you already use: your laptop, a devbox, or a remote VM. It is the fastest way to give Cloud Agents access to your local repo, dependencies, build cache, and private network. A worker on your machine opens an outbound connection to Cursor. The agent loop runs in Cursor's cloud, but terminal commands, file edits, browser actions, and other tool calls execute on your machine. No inbound ports or firewall changes are required. Use My Machines when you want to: Use a devbox or remote workstation that already has your repo and tools Run Cloud Agents against services only available from your network Keep build caches, test outputs, and secrets on your machine Try self-hosted Cloud Agents quickly For org-wide worker fleets, see Self-Hosted Pool . Quickstart 1. Install the CLI # macOS, Linux, and WSL curl https://cursor.com/install -fsS | bash # Windows PowerShell irm 'https://cursor.com/install?win32=true' | iex Confirm the CLI is available: agent --version 2. Sign in For a personal machine, browser login is the easiest path: agent login 3. Start the worker agent worker start Keep this process running while you use the machine. By default, a My Machines worker is long-lived: it stays connected until you stop it and can be reused for future Cloud Agent sessions. 4. Run an agent Go to cursor.com/agents . The machine should show up in the environment dropdown. Send a task. Common options Name the machine Use a friendly name when you have multiple machines for the same repo: agent worker start --name "my-devbox" Run from a different repo directory agent worker start --worker-dir /path/to/repo Use an API key For shared devboxes or automation, use a service account API key: agent worker start --api-key "your-api-key" Use a user-scoped token For self-managed per-user workers, mint a short-lived user-scoped token with POST /v1/sub-tokens , then start the worker with that token: agent worker start --auth-token "your-user-scoped-token" For long-lived workers, read the token from a file: agent worker start --auth-token-file /var/run/cursor/token This is useful in Kubernetes because environment variables from Secrets are fixed when the pod starts. Secret volumes update while the pod runs, while mounted token paths can be live updated within the pod giving you the chance to refresh the token while the pod is running. Trigger this machine from a chat surface Use worker= or machine= when you want Slack, GitHub, or Linear requests to run on one of your named machines. These are the only trigger options that target My Machines. Start the machine with --name , then include that name in the request: In Slack, use @Cursor worker=my-devbox fix the flaky test or @Cursor machine=my-devbox fix the flaky test . In GitHub, comment @cursoragent worker=my-devbox fix the flaky test or @cursoragent machine=my-devbox fix the flaky test . You must be a trusted repo commenter, and the target machine must belong to the Cursor user linked to your GitHub account. In Linear, add worker=my-devbox or machine=my-devbox to the issue body. You can also use a parent label named worker or machine with a child label named my-devbox . How Cursor picks your machine A worker= request runs on a machine only when all three are true: The machine belongs to the Cursor user who triggered the request. The machine's --name matches the requested . The machine's registered repo matches the trigger's target repo. The trigger's target repo comes from the surface, not from the machine name: Slack uses repo= in your message if present, then the channel default repo, your user default repo, then the team default repo. Linear uses the repo resolved from the issue or project (for example [repo=] , issue labels, project labels, or the dashboard default). See Repository selection . GitHub uses the repo of the issue, pull request, or review comment where @cursoragent was mentioned. Each machine's registered repo comes from the git remote in the directory where you started the worker. To serve more than one repo, start a worker in each repo's checkout. When a worker= request can't run If you have a machine with that name but it's registered for a different repo, Cursor rejects the request rather than running it on the wrong checkout: worker= is registered on your machine but for a different repository. Start the worker in a checkout of the target repo first. The error appears as an ephemeral reply in Slack, an agent activity error in Linear, and a @cursoragent reply on GitHub for trusted commenters. The behavior is intentional: a request for repo A should never run on a machine checkout for repo B. If no machine matches the linked user and target repo, the request fails instead of falling back to another environment. Confirm the machine name, your Cursor account linking, and the worker directory's git remote. self_hosted , pool= , and repo= on their own don't target My Machines. Use them with Self-Hosted Pool workers. When you pair repo= with worker= , it sets which repo Cursor matches against your machines. Artifacts Artifact behavior is identical on self-hosted workers and Cursor-hosted agents. The agent produces the artifact inside the worker and the worker uploads it to Cursor-managed storage over HTTPS. Everything downstream (PR embeds, dashboard previews, notification attachments) is handled by Cursor's backend and doesn't depend on where the worker runs. Artifacts are on by default. See Capabilities for what they look like in the UI. To disable artifact uploads, block outbound traffic to cloud-agent-artifacts.s3.us-east-1.amazonaws.com . The agent session keeps working; artifacts produced during the session fail to upload. Networking Workers need outbound HTTPS access to: api2.cursor.sh and api2direct.cursor.sh for the agent session cloud-agent-artifacts.s3.us-east-1.amazonaws.com for artifact uploads If your firewall can only match wildcards, *.s3.us-east-1.amazonaws.com covers the artifact host, but also opens every other bucket in the region. Prefer an exact-host rule when the firewall supports it. No inbound ports, public IPs, or VPN tunnels are required. If you use a proxy, set HTTPS_PROXY or https_proxy in the worker environment. Failure modes If you block... Effect api2.cursor.sh or api2direct.cursor.sh The worker can't start or continue an agent session. cloud-agent-artifacts.s3.us-east-1.amazonaws.com Artifact uploads fail. PR embeds, dashboard previews, and notification attachments that depend on artifacts are missing. The agent session and other tool calls keep working. An outbound host a specific tool or integration needs Only that tool or integration fails. The agent continues. MCP servers MCP servers are routed by transport type: Transport Runs on Use case Command (stdio) Your machine The MCP process starts on your machine and can reach private networks, internal APIs, and local services. HTTP / SSE (url) Cursor backend Cursor handles OAuth, session caching, and auth for HTTP-based MCP servers. If your MCP server needs to reach endpoints on your private network, use the command (stdio) transport. The process runs directly on your machine and shares its network. For HTTP-based MCP servers, Cursor manages the connection from its backend. Troubleshooting Run a preflight debug report: agent worker start --debug This checks authentication, privacy routing, repo labels, and whether Cursor can see matching workers. Related Self-Hosted Pool Cloud Agent security and network Service accounts English English 简体中文 日本語 繁體中文 Español Français Português 한국어 Русский Türkçe Bahasa Indonesia Deutsch हिन्दी

Models Claude 4.6 Sonnet Model ID claude-4-6-sonnet Context window 200k Max context 1M Provider Anthropic Capabilities Agent Thinking Speed Medium Cost Medium Intelligence High Sonnet 4.6 is Anthropic's medium-tier intelligence model. It costs the same as Sonnet 4.5 and supports thinking mode with a 200k default context window expandable to 1M in Max Mode. It's a solid pick for teams standardized on Claude who want reasoning without Opus pricing. Strengths More affordable than Opus while keeping strong coding abilities and thinking support. Good for everyday coding tasks. Supports extended reasoning for tasks that benefit from deeper analysis. Same provider and style as Opus at a lower price point. Limitations Codex and Composer offer more capability per dollar for most coding tasks. For peak quality, Opus remains the stronger choice. Tools Sonnet 4.6 has access to all agent tools when used with Cursor including: Semantic search Search your indexed codebase by meaning, not exact matches. Search files and folders Find files by name, read directory structures, and grep for patterns. Web Generate search queries and fetch results from the web. Read files Read file contents, including images for vision-capable models. Edit files Suggest edits and apply them automatically. Run shell commands Execute terminal commands and monitor output. Browser Control a browser to take screenshots, test applications, and verify visual changes. See the Browser documentation . Image generation Generate images from text descriptions or reference images. Ask questions Ask clarifying questions while continuing to work in the background. Fetch rules Retrieve rules based on type and description. Learn more about how tools work and tool calling fundamentals . Pricing Cursor plans include two usage pools. Sonnet 4.6 draws from the API pool, which charges at the rates below. Individual plans include at least $20 of API usage each month (more on higher tiers). All prices are per million tokens. Name Input Cache Write Cache Read Output Claude 4.6 Sonnet $3 $3.75 $0.3 $15 All Sonnet 4.6 prompts bill at the base per-token rates in the table above, including when you use Max Mode and context goes above 200k. There is no separate long-context multiplier for Sonnet 4.6. A thinking variant is available for deeper reasoning. English English 简体中文 日本語 繁體中文 Español Français Português 한국어 Русский Türkçe Bahasa Indonesia Deutsch हिन्दी

Cloud Agents Self-Hosted Cloud: Deploying with Cloud Run Worker Pools Deploy and manage Self-Hosted Pool workers on Google Cloud using Cloud Run Worker Pools . A second Worker Pool runs a custom autoscaler that polls the Cursor fleet management API and scales the worker pool up or down based on utilization. This guide covers a minimal reference setup. Adapt the image contents, secrets, and autoscaling logic to match your own infrastructure. Architecture Two Cloud Run Worker Pools work together: Cursor worker pool. Each instance runs a container that starts the agent CLI as a pool worker and holds an outbound HTTPS connection to Cursor. Sessions are routed to idle instances. Autoscaler pool. A single-instance Worker Pool that polls https://api.cursor.com/v0/private-workers/summary on an interval and calls the Cloud Run Admin API to resize the worker pool based on utilization. Prerequisites A Google Cloud project with billing enabled gcloud CLI installed and authenticated ( gcloud auth login , gcloud config set project ) The following APIs enabled in your project: Cloud Run ( run.googleapis.com ), Artifact Registry ( artifactregistry.googleapis.com ), Cloud Build ( cloudbuild.googleapis.com ), and Secret Manager ( secretmanager.googleapis.com ) A Cursor team plan with Self-Hosted Cloud Agents enabled A Cursor team-level API key — see Self-Hosted Pool for authentication setup A Git token (e.g. a GitHub personal access token or fine-grained token) with read/write access to the repositories your agents will operate on Your worker pool needs outbound HTTPS access to: api2.cursor.sh api2direct.cursor.sh cloud-agent-artifacts.s3.us-east-1.amazonaws.com (for artifact uploads) Your git host (for example github.com ) and any package registries your builds need No inbound ports or firewall rules are required. Step 1: Prepare your environment Set the environment variables used throughout this guide: export PROJECT_ID = $( gcloud config get-value project ) export LOCATION = "us-central1" export REPO_NAME = "cursor-workers" export IMAGE_NAME = "cursor-agent-worker" export SCALER_IMAGE_NAME = "cursor-agent-scaler" export CURSOR_AGENTS_POOL = "cursor-agents-pool" Step 2: Build the worker container Create a directory for the worker image and add the two files below. Dockerfile FROM ubuntu:24.04 ENV DEBIAN_FRONTEND=noninteractive # - curl/ca-certificates: to download the Cursor CLI # - git: required by the worker to identify and operate on the repo # - build-essential/python3/nodejs: common tools the agent might need RUN apt-get update && \ apt-get install -y \ curl \ git \ ca-certificates \ build-essential \ python3 \ nodejs \ npm \ && rm -rf /var/lib/apt/lists/* # Install the Cursor Agent CLI RUN curl -fsSL https://cursor.com/install | bash # Ensure the 'agent' binary is available in PATH ENV PATH= "/root/.cursor/bin:/root/.local/bin:/usr/local/bin:$PATH" WORKDIR /workspace COPY entrypoint.sh /entrypoint.sh RUN chmod +x /entrypoint.sh # Cloud Run injects the PORT env var (default 8080). The management/health # server binds to it so Cloud Run's TCP health checks pass. ENV PORT=8080 ENTRYPOINT [ "/entrypoint.sh" ] entrypoint.sh #!/bin/bash set -e # Disable git terminal prompts so the container crashes cleanly if auth fails # instead of hanging. export GIT_TERMINAL_PROMPT = 0 if [ -z " $CURSOR_API_KEY " ]; then echo "FATAL: CURSOR_API_KEY environment variable is missing." exit 1 fi if [ -z " $REPO_URL " ]; then echo "FATAL: REPO_URL environment variable is missing." echo "Example: https://github.com/your-org/your-repo.git" exit 1 fi # Configure Git authentication for private repos. if [ -n " $GIT_TOKEN " ]; then echo "Configuring git credentials using provided GIT_TOKEN..." git config --global credential.helper "!f() { echo username=oauth2; echo password= $GIT_TOKEN ; }; f" fi REPO_DIR = "/workspace/repo" if [ ! -d " $REPO_DIR /.git" ]; then echo "Cloning repository: $REPO_URL ..." git clone " $REPO_URL " " $REPO_DIR " fi # Cursor workers require the CWD to be the git repo. cd " $REPO_DIR " AGENT_BIN = $( command -v agent || find /root -name agent -type f | head -n 1 ) if [ -z " $AGENT_BIN " ]; then echo "FATAL: Could not find the Cursor 'agent' binary." exit 1 fi echo "Starting Cursor Cloud Agent Worker..." # - `exec` replaces the shell so the agent handles container termination signals. # - `--management-addr` binds to Cloud Run's PORT for TCP health checks. # - `"$@"` forwards extra flags (for example `--pool-name`) passed at deploy time. exec " $AGENT_BIN " worker start \ --api-key " $CURSOR_API_KEY " \ --management-addr ":${ PORT }" \ --pool \ --idle-release-timeout 600 \ " $@ " --pool registers the worker for pool assignment, where each Cloud Agent session claims one worker at a time. --idle-release-timeout (in seconds) keeps the worker alive briefly after the session ends for follow-up messages, then exits with code 0 so Cloud Run replaces the instance. Cloud Run workers support the same hooks model as other Self-Hosted Pool workers. They run project hooks from .cursor/hooks.json , and on Enterprise also support team hooks and enterprise-managed hooks. Step 3: Create an Artifact Registry repository Create a Docker repository to host both images: gcloud artifacts repositories create $REPO_NAME \ --repository-format=docker \ --location= $LOCATION \ --description= "Docker repository for Cursor self-hosted agents" Step 4: Build and push the worker image From the directory containing the Dockerfile and entrypoint.sh : gcloud builds submit \ -t $LOCATION -docker.pkg.dev/ $PROJECT_ID / $REPO_NAME / $IMAGE_NAME :latest . If you'd rather not build and push the image ahead of time, you can use Cloud Run's source deploy in Step 6 instead. Step 5: Create secrets Store the Cursor API key and Git token in Secret Manager so they're never baked into images. CURSOR_API_KEY gcloud secrets create CURSOR_API_KEY --replication-policy= "automatic" echo -n "YOUR_CURSOR_API_KEY" | \ gcloud secrets versions add CURSOR_API_KEY --data-file=- GIT_TOKEN gcloud secrets create GIT_TOKEN --replication-policy= "automatic" echo -n "YOUR_GIT_TOKEN" | \ gcloud secrets versions add GIT_TOKEN --data-file=- Grant your Git token the permissions the worker needs. For most agent workflows, that means read and write access to contents and the ability to open and merge pull requests on the repositories the workers operate on. Step 6: Deploy the Cursor worker as a Worker Pool gcloud run worker-pools deploy $CURSOR_AGENTS_POOL \ --image $LOCATION -docker.pkg.dev/ $PROJECT_ID / $REPO_NAME / $IMAGE_NAME :latest \ --region $LOCATION \ --set-env-vars= "REPO_URL=https://github.com/your-org/your-repo.git" \ --set-secrets= "CURSOR_API_KEY=CURSOR_API_KEY:latest,GIT_TOKEN=GIT_TOKEN:latest" Replace REPO_URL with the git URL of the repository this pool should serve. Once the pool rolls out, its workers should appear in the Self-Hosted section of the Cloud Agents dashboard . Each worker serves one repository. To support multiple repositories, deploy an additional Cloud Run Worker Pool per repo and use pool names or labels to route agent sessions to the right pool. Step 7: Deploy the autoscaler The worker pool is deployed with a static instance count. To scale based on utilization, deploy a small Node.js app as a second Worker Pool that polls the Cursor fleet management API and calls the Cloud Run Admin API to resize the worker pool. Create a directory for the autoscaler and add the three files below. package.json { "name" : "cursor-worker-autoscaler" , "version" : "1.0.0" , "description" : "Autoscaler for Cursor Cloud Run Worker Pools" , "main" : "index.js" , "scripts" : { "start" : "node index.js" }, "dependencies" : { "@google-cloud/run" : "latest" } } index.js const { WorkerPoolsClient } = require ( '@google-cloud/run' ).v2; const CURSOR_API_KEY = process.env. CURSOR_API_KEY ; const PROJECT_ID = process.env. GOOGLE_CLOUD_PROJECT ; const LOCATION = process.env. CLOUD_RUN_LOCATION ; const TARGET_POOL_NAME = process.env. WORKER_SERVICE_NAME ; const TARGET_UTILIZATION = parseFloat (process.env. TARGET_UTILIZATION || '0.5' ); const MIN_INSTANCES = parseInt (process.env. MIN_INSTANCES || '1' , 10 ); const MAX_INSTANCES = parseInt (process.env. MAX_INSTANCES || '50' , 10 ); const POLLING_INTERVAL_MS = parseInt (process.env. POLLING_INTERVAL_MS || '30000' , 10 ); if ( ! PROJECT_ID || ! LOCATION || ! TARGET_POOL_NAME ) { console. error ( 'FATAL: Missing required environment variables.' ); process. exit ( 1 ); } const workerPoolClient = new WorkerPoolsClient (); async function scaleCursorWorkers () { try { const response = await fetch ( 'https://api.cursor.com/v0/private-workers/summary' , { method: 'GET' , headers: { 'Authorization' : 'Basic ' + Buffer. from ( `${ CURSOR_API_KEY }:` ). toString ( 'base64' ), }, }); if ( ! response.ok) { throw new Error ( `Cursor API responded with status: ${ response . status }` ); } const summary = await response. json (); const team = summary.teamSummary; const user = summary.userSummary; let inUse = 0 ; let totalConnected = 0 ; if (team && team.totalConnected > 0 ) { inUse = team.inUse; totalConnected = team.totalConnected; } else if (user && user.totalConnected > 0 ) { inUse = user.inUse; totalConnected = user.totalConnected; } else { console. log ( 'Current state: 0 workers connected. Waiting for next cycle...' ); return ; } console. log ( `Current state: ${ inUse } workers in use out of ${ totalConnected } total connected.` ); let desiredInstances = Math. ceil (inUse / TARGET_UTILIZATION ); desiredInstances = Math. max ( MIN_INSTANCES , Math. min (desiredInstances, MAX_INSTANCES )); if (desiredInstances !== totalConnected) { console. log ( `Utilization threshold breached. Scaling Worker Pool from ${ totalConnected } to ${ desiredInstances } instances...` ); await updateCloudRunWorkerPool (desiredInstances); } else { console. log ( 'Utilization is stable. No scaling action required.' ); } } catch (error) { console. error ( 'Error in scaling execution:' , error); } } async function updateCloudRunWorkerPool ( instanceCount ) { const workerPoolPath = workerPoolClient. workerPoolPath ( PROJECT_ID , LOCATION , TARGET_POOL_NAME ); const request = { workerPool: { name: workerPoolPath, scaling: { manualInstanceCount: instanceCount, }, }, updateMask: { paths: [ 'scaling.manual_instance_count' ], }, }; const [ operation ] = await workerPoolClient. updateWorkerPool (request); console. log ( 'Waiting for Cloud Run scaling operation to apply...' ); await operation. promise (); console. log ( `Successfully patched Cloud Run Worker Pool. Pool scaled to ${ instanceCount } workers.` ); } console. log ( `Starting background autoscaler loop (Interval: ${ POLLING_INTERVAL_MS }ms)` ); scaleCursorWorkers (); setInterval (scaleCursorWorkers, POLLING_INTERVAL_MS ); Dockerfile FROM node:20-alpine WORKDIR /usr/src/app COPY package.json ./ RUN npm install --omit=dev COPY index.js ./ CMD [ "npm" , "start" ] Build and deploy the autoscaler Optionally build and push the image first: gcloud builds submit \ -t $LOCATION -docker.pkg.dev/ $PROJECT_ID / $REPO_NAME / $SCALER_IMAGE_NAME :latest . Or skip the build step and let Cloud Run build from source on deploy: gcloud run worker-pools deploy cursor-autoscaler-pool --project $PROJECT_ID \ --region $LOCATION \ --source . \ --instances 1 \ --set-env-vars= "GOOGLE_CLOUD_PROJECT= $PROJECT_ID ,CLOUD_RUN_LOCATION= $LOCATION ,WORKER_SERVICE_NAME= $CURSOR_AGENTS_POOL ,MIN_INSTANCES=1,MAX_INSTANCES=10,TARGET_UTILIZATION=0.5,POLLING_INTERVAL_MS=30000" \ --set-secrets= "CURSOR_API_KEY=CURSOR_API_KEY:latest" The autoscaler's service account needs permission to update the worker pool. Grant it the Cloud Run Admin role (or a more scoped custom role) on the project, or directly on the $CURSOR_AGENTS_POOL resource. Autoscaler configuration Variable Default Description GOOGLE_CLOUD_PROJECT — Project ID that hosts the worker pool. CLOUD_RUN_LOCATION — Region of the worker pool, for example us-central1 . WORKER_SERVICE_NAME — Name of the Cursor worker pool to scale. CURSOR_API_KEY — Team-level Cursor API key used to query the fleet management API. TARGET_UTILIZATION 0.5 Desired fraction of workers in use. Lower values scale up more aggressively. MIN_INSTANCES 1 Floor on the worker pool size. MAX_INSTANCES 50 Ceiling on the worker pool size. POLLING_INTERVAL_MS 30000 How often to poll the Cursor API and reconcile. Testing Once the worker pool is running: Go to cursor.com/agents . Select Self-hosted from the worker selector. Your Cloud Run workers should appear in the list of available workers. Start a task, and the agent will execute its tool calls inside your Cloud Run containers. You can also verify workers are connected from the command line using the fleet management API : curl --request GET \ --url "https://api.cursor.com/v0/private-workers/summary" \ -u " $CURSOR_API_KEY :" Related Self-Hosted Pool Kubernetes deployment guide Cloud Agents overview Service accounts English English 简体中文 日本語 繁體中文 Español Français Português 한국어 Русский Türkçe Bahasa Indonesia Deutsch हिन्दी

Customizing Plugins Plugins package rules, skills, agents, commands, MCP servers, and hooks into distributable bundles. Browse official plugins in the Cursor Marketplace . For community plugins and MCP servers, browse cursor.directory . You can also build your own to share with other developers. What plugins contain A plugin can bundle any combination of these components: Component Description Rules Persistent AI guidance and coding standards ( .mdc files) Skills Specialized agent capabilities for complex tasks Agents Custom agent configurations and prompts Commands Agent-executable command files MCP Servers Model Context Protocol integrations Hooks Automation scripts triggered by events The marketplace The Cursor Marketplace is where you discover and install official plugins. Plugins are distributed as Git repositories and submitted through the Cursor team. Every plugin is manually reviewed before it's listed. Browse official plugins at cursor.com/marketplace or search by keyword in the marketplace panel. For community plugins and MCP servers, browse cursor.directory . Team marketplaces Team marketplaces are available on Teams and Enterprise plans. Teams plan: up to 1 team marketplace Enterprise plan: unlimited team marketplaces Contact sales for unlimited team marketplaces and Enterprise admin controls. The Team Marketplaces section appears below Plugins in dashboard settings. On Enterprise plans, only admins can add team marketplaces from Dashboard -> Settings -> Plugins . Required vs optional plugins When you assign a plugin to a distribution group, you can set it as required or optional: Required : After you click Save , the plugin is installed automatically for everyone in that distribution group. Optional : The plugin is available to everyone in that distribution group, and each developer can choose whether to install it. How do distribution groups work with SCIM? Distribution groups can be controlled with SCIM -synced directory groups. If your organization uses SCIM, manage group membership in your identity provider, and Cursor will sync those group updates. Add a team marketplace Use this flow to import a GitHub repository as a team marketplace: Go to Dashboard -> Settings -> Plugins . In Team Marketplaces , click Import . Paste the GitHub repository URL and continue. Review the parsed plugins. Optionally set Team Access groups, then continue. Set the marketplace name and description, then save. Example repository to try: fieldsphere/cursor-team-marketplace-template Where developers find team marketplaces Developers can find team marketplaces in the marketplace panel in Cursor. Open the marketplace panel in Cursor. Look for plugins from your team marketplace. Install optional plugins directly from that panel. Required plugins are installed automatically when admins save the required setting for your distribution group. Installing plugins Install plugins from the marketplace. Plugins can be scoped to a project or installed at the user level. MCP Apps deeplinks Share MCP server configurations using install links: cursor://anysphere.cursor-deeplink/mcp/install?name=$NAME&config=$BASE64_ENCODED_CONFIG See MCP install links for details on generating these links. Managing installed plugins MCP servers Toggle MCP servers on or off from Cursor Settings: Open Settings ( Cmd+Shift+J Ctrl+Shift+J ) Go to Features > Model Context Protocol Click the toggle next to any server Disabled servers won't load or appear in chat. Rules and skills Manage rules and skills from the Rules section of Cursor Settings. Toggle individual rules between Always , Agent Decides , and Manual modes. Skills appear in the Agent Decides section and can be invoked manually with /skill-name in chat. Using the workspaceOpen hook A workspaceOpen hook can return plugin paths to load on workspace open, which is useful when the set of plugins depends on the workspace itself. Hooks reference Register plugin paths from a workspaceOpen hook script Creating plugins A plugin is a directory with a .cursor-plugin/plugin.json manifest and your components (rules, skills, agents, commands, hooks, or MCP servers). Start from the plugin template repository or create one from scratch: my-plugin/ ├── .cursor-plugin/ │ └── plugin.json ├── rules/ │ └── coding-standards.mdc ├── skills/ │ └── code-reviewer/ │ └── SKILL.md └── mcp.json The manifest only requires a name field. Components are discovered automatically from their default directories, or you can specify custom paths in the manifest. { "name" : "my-plugin" , "description" : "Custom development tools" , "version" : "1.0.0" , "author" : { "name" : "Your Name" } } Test plugins locally Before you publish, load your plugin from ~/.cursor/plugins/local : Create a folder for your plugin: ~/.cursor/plugins/local/my-plugin Copy your plugin files into that folder. Make sure .cursor-plugin/plugin.json is at the plugin root. Restart Cursor, or run Developer: Reload Window . Verify your plugin components load in Cursor, such as rules, skills, or MCP servers. For faster iteration, symlink your plugin repository: ln -s /path/to/my-plugin ~/.cursor/plugins/local/my-plugin When your plugin is ready, submit it for review at cursor.com/marketplace/publish . For multi-plugin repositories, add a marketplace manifest at .cursor-plugin/marketplace.json . See the Plugins reference for the full manifest schema, component formats, and submission checklist. Team and Enterprise marketplaces Upgrade for private team marketplaces and organization-wide plugin distribution. Contact Sales FAQ Are marketplace plugins reviewed for security? Yes. Every plugin is manually reviewed before it's listed. All plugins must be open source, and we review each update before publishing. See Marketplace security for details on vetting, update reviews, and how to report issues. How do I create a plugin? Create a directory with a .cursor-plugin/plugin.json manifest file, add your rules, skills, agents, commands, or other components, and submit it to the Cursor team. See the Plugins reference for the full guide. English English 简体中文 日本語 繁體中文 Español Français Português 한국어 Русский Türkçe Bahasa Indonesia Deutsch हिन्दी

Models GPT-5.3 Codex Model ID gpt-5.3-codex Context window 272k Max context - Provider OpenAI Capabilities Agent Thinking Speed Medium Cost Medium Intelligence Frontier GPT-5.3 Codex is OpenAI's flagship coding model. It leads Terminal-Bench by a wide margin and performs on par with Opus 4.6 on our internal benchmarks, at roughly one-third the price. Much faster than previous GPT generations. A strong default for most coding tasks. Strengths Leads Terminal-Bench by a wide margin. Competitive with Opus 4.6 on our internal benchmarks. About one-third the price of Opus with comparable quality on most tasks. Good for daily coding, long debugging sessions, and cost-conscious teams. Grinds through complex, multi-step problems and deep debugging sessions. Limitations Code style is less polished than Opus on architecture-heavy tasks. Terminal-Bench skews toward general reasoning; real-world coding gains may differ. Tools GPT-5.3 Codex has access to all agent tools when used with Cursor including: Semantic search Search your indexed codebase by meaning, not exact matches. Search files and folders Find files by name, read directory structures, and grep for patterns. Web Generate search queries and fetch results from the web. Read files Read file contents, including images for vision-capable models. Edit files Suggest edits and apply them automatically. Run shell commands Execute terminal commands and monitor output. Browser Control a browser to take screenshots, test applications, and verify visual changes. See the Browser documentation . Image generation Generate images from text descriptions or reference images. Ask questions Ask clarifying questions while continuing to work in the background. Fetch rules Retrieve rules based on type and description. Learn more about how tools work and tool calling fundamentals . Pricing Cursor plans include two usage pools. GPT-5.3 Codex draws from the API pool, which charges at the rates below. Individual plans include at least $20 of API usage each month (more on higher tiers). All prices are per million tokens. Name Input Cache Write Cache Read Output GPT-5.3 Codex $1.75 - $0.175 $14 A high reasoning effort variant ( gpt-5.3-codex-high ) is available for tasks that need deeper analysis. English English 简体中文 日本語 繁體中文 Español Français Português 한국어 Русский Türkçe Bahasa Indonesia Deutsch हिन्दी

Cloud Agents Bugbot Bugbot reviews pull requests and identifies bugs, security issues, and code quality problems. How it works Bugbot analyzes PR diffs and leaves comments with explanations and fix suggestions. It runs automatically on each PR update or manually when triggered. Runs automatic reviews on every PR update Manual trigger by commenting cursor review or bugbot run on any PR Uses existing PR comments as context : reads GitHub PR comments (top‑level and inline) to avoid duplicate suggestions and build on prior feedback Fix in Cursor links open issues directly in Cursor Fix in Web links open issues directly in cursor.com/agents Setup Connect your repositories through the Cursor dashboard to start using Bugbot. GitHub (including GitHub Enterprise Server): See the GitHub integration page GitLab (including GitLab Self-Hosted): See the GitLab integration page After connecting, return to the Bugbot dashboard to enable Bugbot on specific repositories. CI check statuses Bugbot publishes a GitHub check named Cursor Bugbot for each review run. The check uses these conclusions: success : Bugbot found no issues, and there are no unresolved Bugbot comments from earlier runs. neutral : Bugbot found issues, the run was cancelled by a newer commit, or Bugbot hit an internal error. This is the default conclusion when Bugbot reports findings. failure : Bugbot found issues and the check is configured to fail on unresolved issues. If you use branch protection, require the Cursor Bugbot check to make sure Bugbot runs before merge. Requiring the check alone does not block merges on findings because findings default to neutral . If fail-on-unresolved-issues behavior is available for your organization, enable it to make unresolved findings produce a failing check. Bugbot does not emit a skipped conclusion. When Bugbot Autofix is enabled, GitHub may also show a separate Cursor Bugbot Autofix check. That check only uses success or neutral . Configuration Individual Team Repository settings Team admins can enable Bugbot per repository, configure allow/deny lists for reviewers, and set: Run only once per PR per installation, skipping subsequent commits Bugbot runs for all contributors to enabled repositories, regardless of team membership. Personal settings Team members can override settings for their own PRs: Run only when mentioned by commenting cursor review or bugbot run Run only once per PR, skipping subsequent commits Enable reviews on draft PRs to include draft pull requests in automatic reviews Analytics Effort Levels Effort levels control how much time Bugbot spends reasoning during a review. Higher effort levels can find more bugs, but each review may take longer and take more up usage. Choose from these effort levels: Default : Optimizes for efficiency and speed. Reviews are less expensive, but Bugbot may find fewer bugs. High : Spends more time reasoning. Reviews are more expensive and take longer, but Bugbot may find more bugs. Custom : Lets you describe when Bugbot should use longer and deeper reviews. Cursor dynamically sets effort levels based on your instructions. Effort levels are available only for usage-based Bugbot plans. Team rules Team admins can create rules from the Bugbot dashboard that apply to all repositories in the team. These rules are available to every enabled repository, making it easy to enforce organization-wide standards. When Team Rules, repository rules, and project rule files all apply, Bugbot merges them. Order of application: Team Rules → repository rules (learned and manual) → project BUGBOT.md (including nested files) → User Rules . Repository rules Project rules Create .cursor/BUGBOT.md files to provide project-specific context for reviews. Bugbot always includes the root .cursor/BUGBOT.md file and any additional files found while traversing upward from changed files. project/ .cursor/BUGBOT.md # Always included (project-wide rules) backend/ .cursor/BUGBOT.md # Included when reviewing backend files api/ .cursor/BUGBOT.md # Included when reviewing API files frontend/ .cursor/BUGBOT.md # Included when reviewing frontend files Learned rules In the Bugbot dashboard , enable learning for your organizations and repositories. Rules are generated automatically from your team's activity on GitHub for that repository or by manually backfilling from the history of the repository. You can also teach Bugbot new rules inline by commenting @cursor remember [fact] on any PR. Bugbot saves the fact as a learned rule and applies it to future reviews. Cursor will automatically enable or disable rules as it learns more about your team's activity over time. Field Description Name Short title for the rule. Rule content The instructions Bugbot should follow (i.e. style gates, paths, or review expectations). Scoped paths Optional glob patterns such as src/components/** . Leave empty to apply the rule across the whole repository. Manual rules In the Bugbot dashboard , you can create manual rules for individual repositories. Field Description Name Short title for the rule. Rule content The instructions Bugbot should follow (i.e. style gates, paths, or review expectations). Scoped paths Optional glob patterns such as src/components/** . Leave empty to apply the rule across the whole repository. Rule analytics Analytics on a Bugbot rule show how it performs on real PRs: Metric Meaning Issues found Number of findings Bugbot reported that involve this rule. PRs reviewed Number of pull requests where those findings appeared. Accepted issues Number of findings your team accepted. Acceptance rate Percentage of findings that were accepted. Examples Security: Flag any use of eval() or exec() If any changed file contains the string pattern /\beval\s*\(|\bexec\s*\(/i, then: - Add a blocking Bug with title "Dangerous dynamic execution" and body: "Usage of eval/exec was found. Replace with safe alternatives or justify with a detailed comment and tests." - Assign the Bug to the PR author. - Apply label "security". OSS licenses: Prevent importing disallowed licenses If the PR modifies dependency files (package.json, pnpm-lock.yaml, yarn.lock, requirements.txt, go.mod, Cargo.toml), then: - Run the built-in License Scan. - If any new or upgraded dependency has license in {GPL-2.0, GPL-3.0, AGPL-3.0}, then: - Add a blocking Bug titled "Disallowed license detected" - Include the offending package names, versions, and licenses in the Bug body - Apply labels "compliance" and "security" Language standards: Flag React componentWillMount usage For files matching **/*.{js,jsx,ts,tsx} in React projects: If a changed file contains /componentWillMount\s*\(/, then: - Add a blocking Bug titled "Deprecated React lifecycle method" - Body: "Replace componentWillMount with constructor or useEffect. See React docs." - Suggest an autofix snippet that migrates side effects to useEffect. Standards: Require tests for backend changes If the PR modifies files in {server/**, api/**, backend/**} and there are no changes in {**/*.test.*, **/__tests__/**, tests/**}, then: - Add a blocking Bug titled "Missing tests for backend changes" - Body: "This PR modifies backend code but includes no accompanying tests. Please add or update tests." - Apply label "quality" Style: Disallow TODO comments If any changed file contains /(?:^|\s)(TODO|FIXME)(?:\s*:|\s+)/, then: - Add a non-blocking Bug titled "TODO/FIXME comment found" - Body: "Replace TODO/FIXME with a tracked issue reference, e.g., `TODO(#1234): ...`, or remove it." - If the TODO already references an issue pattern /#\d+|[A-Z]+-\d+/, mark the Bug as resolved automatically. Autofix Bugbot Autofix automatically spawns a Cloud Agent to fix bugs found during PR reviews. How it works When Bugbot finds bugs during a PR review, it can automatically: Spawn a Cloud Agent to analyze and fix the reported issues Push fixes to the existing branch or a new branch (depending on your settings) Post a comment on the original PR with the results Configuration Configure autofix behavior from the Bugbot dashboard . Individual Team Team admins can set a default autofix mode for all team members in a GitHub organization: Off — autofix is disabled by default Create New Branch (Recommended) — Push fixes to a new branch for team members Commit to Existing Branch — Push fixes directly to the PR branch (max 3 attempts per PR to prevent loops) Individual team members can override these defaults in their personal settings. Autofix uses your Default agent model from Settings → Models . If you haven't set a personal model preference, autofix falls back to your team's default model (if you're on a team) or the system default. Requirements Autofix requires: On-demand usage pricing enabled Storage enabled (not in Legacy Privacy Mode) Billing Autofix uses Cloud Agent credits and is billed at your plan rates. Cloud Agent billing follows your existing pricing plan . MCP support Bugbot is integrated with your MCP servers so your AI tools can interact with Bugbot directly. Use the MCP server to provide additional tools to guide Bugbot's review process. To get started: Follow the MCP documentation for MCP server setup instructions. Add the tools to Bugbot in the Bugbot dashboard . MCP support is available on Team and Enterprise plans only. Admin Configuration API Team admins can use the Bugbot Admin API to manage repositories and control which users can use Bugbot. Use it to automate repository management, enable Bugbot across multiple repositories, or integrate user provisioning with internal tools. Authentication All endpoints require a team Admin API Key passed as a Bearer token: Authorization: Bearer $API_KEY To create an API key: Visit the Settings tab in the Cursor dashboard Under Advanced , click New Admin API Key Save the API key All endpoints are rate-limited to 60 requests per minute per team. Enabling or disabling repositories Use the /bugbot/repo/update endpoint to toggle Bugbot on or off for a repository: curl -X POST https://api.cursor.com/bugbot/repo/update \ -H "Authorization: Bearer $API_KEY " \ -H "Content-Type: application/json" \ -d '{ "repoUrl": "https://github.com/your-org/your-repo", "enabled": true }' Parameters: repoUrl (string, required): The full URL of the repository enabled (boolean, required): true to enable Bugbot, false to disable it The dashboard UI may take a moment to reflect changes made through the API due to caching. The API response shows the current state in the database. Listing repositories Use the /bugbot/repos endpoint to list all repositories with their Bugbot settings for your team: curl https://api.cursor.com/bugbot/repos \ -H "Authorization: Bearer $API_KEY " The response includes each repository's enabled status, manual-only setting, and timestamps. Managing user access Use the /bugbot/user/update endpoint to control which GitHub or GitLab users can use your team's Bugbot licenses. Enterprises use this to integrate Bugbot provisioning with internal access-request tools. Prerequisites Before calling this endpoint, enable an allowlist or blocklist mode in your team Bugbot settings : Allowlist mode ("Only...") : Only users on the list can use Bugbot Blocklist mode ("Everyone but...") : All users can use Bugbot except those on the list If neither mode is enabled, the API returns an error. Adding or removing a user curl -X POST https://api.cursor.com/bugbot/user/update \ -H "Authorization: Bearer $API_KEY " \ -H "Content-Type: application/json" \ -d '{ "username": "octocat", "allow": true }' Parameters: username (string, required): The GitHub or GitLab username (case-insensitive) allow (boolean, required): Whether to grant or revoke access How allow behaves depends on the active mode: Mode allow: true allow: false Allowlist Adds user to list (can use Bugbot) Removes user from list (cannot use Bugbot) Blocklist Removes user from blocklist (can use Bugbot) Adds user to blocklist (cannot use Bugbot) Response: { "outcome" : "success" , "message" : "Updated team-level allowlist for @octocat" , "updatedTeamSettings" : true , "updatedInstallations" : 0 } The allowlist is stored at the team level and applies across all GitHub and GitLab installations owned by that team. Usernames are normalized to lowercase. Example: provisioning users through an internal tool Connect this API to an internal access-request portal. When an employee requests Bugbot access, the portal calls the API to add them. When they leave or lose access, it calls the API to remove them. Grant access: curl -X POST https://api.cursor.com/bugbot/user/update \ -H "Authorization: Bearer $API_KEY " \ -H "Content-Type: application/json" \ -d '{"username": "employee-github-name", "allow": true}' Revoke access: curl -X POST https://api.cursor.com/bugbot/user/update \ -H "Authorization: Bearer $API_KEY " \ -H "Content-Type: application/json" \ -d '{"username": "employee-github-name", "allow": false}' Pricing Bugbot uses usage-based billing. Bugbot pricing changed with the May 2026 pricing update. See the announcement blog post for background. If you're still on the old seat-based plan, see legacy Bugbot pricing . Billing Individuals Teams Usage-based billing Bugbot Teams includes: Code reviews on all PRs Analytics and reporting dashboard The ability to set the effort level Bugbot uses for reviews Advanced rules and settings Bugbot Teams bills from on-demand spend. See the pricing page for current rates. Getting started Subscribe through your team dashboard to enable billing. Troubleshooting If Bugbot isn't working: Enable verbose mode by commenting cursor review verbose=true or bugbot run verbose=true for detailed logs and request ID Check permissions to verify Bugbot has repository access Verify installation to confirm the GitHub app is installed and enabled Include the request ID from verbose mode when reporting issues. FAQ Does Bugbot read GitHub PR comments? Yes. Bugbot reads both top‑level and inline GitHub pull request comments and includes them as context during reviews. This helps avoid duplicate suggestions and allows Bugbot to build on prior feedback from reviewers. Is Bugbot privacy-mode compliant? Yes, Bugbot follows the same privacy compliance as Cursor and processes data identically to other Cursor requests. What happens when I use all included Bugbot usage? When you use all included Bugbot usage, additional Bugbot reviews bill from on-demand spend. How do I give Bugbot access to my GitLab or GitHub Enterprise Server instance? See the setup and networking guides on the respective integration pages: GitHub Enterprise Server GitLab Self-Hosted English English 简体中文 日本語 繁體中文 Español Français Português 한국어 Русский Türkçe Bahasa Indonesia Deutsch हिन्दी

Cloud Agents Automations Cursor Automations run cloud agents in the background, either on a schedule or in response to events from GitHub, Slack, Sentry, and more. Automations can be used to automate tasks like tedious code maintenance , performing deep review for vulnerabilities , triaging bugs in Slack , and investigating Sentry issues . Getting started Create a new automation at cursor.com/automations , or start from a template in the marketplace . Choose a trigger, e.g. every hour or when a pull request is opened. Write a prompt with instructions for the automation. Choose the tools the agent is able to use, such as Send to Slack, Comment on Pull Request, or tools from MCP. Create the automation and watch it run! Billing Automations create cloud agents and are billed based on cloud agent usage. See cloud agent pricing for details. How usage is billed depends on the automation's permission scope : Team Owned : Usage is billed to the team's usage pool. Automations execute under a shared team service account, so no individual user's usage is affected. Private : Usage is billed to the user who created the automation. Team Visible : Usage is billed to the user who created the automation, the same as Private. Triggers Triggers decide when an automation runs. An automation can have more than one trigger and is run when any trigger fires. For certain triggers like schedules or Slack, you also choose a repository and branch. Cursor cannot infer them from a pull request. Scheduled triggers Scheduled triggers run on a recurring schedule. Choose from preset options or enter a cron expression for precise control. Scheduled triggers may run with a delay but will not start before the indicated time. GitHub triggers GitHub triggers respond to GitHub events, such as when a pull request is opened or merged. Draft opened - When a draft pull request is created. Pull request opened - When a non-draft PR is created or a draft is marked ready for review. Pull request pushed - When new commits are pushed to an existing PR. Pull request label changed - When a specific label, or any label, is added to or removed from an existing PR. Pull request merged - When a PR is merged. Pull request commented - When someone comments on a PR. Push to branch - When commits are pushed to a specific branch outside a pull request. CI completed - When a GitHub Check finishes on a pull request or branch. Slack triggers Slack triggers respond to events from the Cursor Slack integration . Only public Slack channels are visible to Slack triggers at this time. New message in channel - When a message is sent to a connected Slack channel. Without a message filter, the trigger only fires on top-level channel messages. Add a keyword or regex filter if you want runs from threaded replies as well. Channel created - When a new public Slack channel is created in your workspace. Webhook triggers Webhook triggers create a private HTTP endpoint for your automation. POST to the endpoint to start a run. You can use webhooks to connect automations to internal systems, CI pipelines, monitoring tools, and more. To retrieve the webhook URL, you must save the automation first, which will then generate a webhook URL to call and an API key for authentication. Linear triggers Linear triggers respond to events from the Cursor Linear integration . Issue created - When a new issue is created. Status changed - When an issue's status changes. End of cycle - When a Linear cycle completes. Sentry triggers Sentry triggers run when error and issue events occur in your Sentry project. Use them to automatically investigate errors, identify root causes, and propose fixes. See the Investigate Sentry issues marketplace template for a ready-made example. Issue created - When a new issue is created in Sentry. Issue updated - When an existing issue changes, such as a status or assignment update. Any issue event - Matches all issue event types. PagerDuty triggers PagerDuty triggers run on incident events and can be helpful to automatically triage or even resolve incidents. Incident triggered - When a new incident is created. Incident acknowledged - When an incident is acknowledged. Incident resolved - When an incident is resolved. Any incident event - Matches all incident event types. Tools Cursor Automations can have tools enabled for richer capabilities around GitHub, Slack, memory, MCP, and more. Automations also include the same base set of tools as other cloud agents. See Cloud agent capabilities for details. Open pull request Lets the agent create a new pull request on GitHub. The agent can write code, create a branch, and open the pull request. Use this when the automation should make code changes. The pull request is opened against the repository from the GitHub trigger. For non-GitHub triggers, it uses the repository selected in the trigger settings. Comment on pull request Posts comments on the triggering pull request. Supports top-level review comments and inline code comments. This action requires a pull request trigger. If you enable approvals, the agent can also approve, request changes, and dismiss reviews. Otherwise, it can only post comments. Request reviewers Requests reviewers on the triggering pull request. The agent can use git , memory, and other tools to identify domain experts. This action requires a pull request trigger. Send to Slack Sends messages to a Slack channel. You can target a specific channel or let the agent dynamically choose any channel. When you allow any channel, Cursor also includes the read access needed for the agent to discover available public channels. Note that the agent is granted read access to public channels that it can send messages to. Read Slack channels Gives the agent read-only access to list and read messages from public Slack channels. Use this when the agent needs more context before it replies or opens a pull request. MCP server Connects an MCP (Model Context Protocol) server so the agent can use external tools and data sources. Connecting an MCP server gives the agent access to every tool exposed by that server. Only connect servers you trust with the permissions your automation needs. Memories Memories let the agent read and write persistent notes across runs for the same automation. Use this to build agents that remember and improve over time. Each memory is stored as a named entry ( MEMORIES.md by default) that exists outside the agent's working filesystem. Memories are enabled by default but can be disabled. Memories can be viewed and edited from the tool configuration UI. Memories persist across runs and should be used with caution if your automation handles untrusted input. Inputs may lead to misleading or malicious memories that unintentionally impact future automation runs. Automation settings Model Choose which model the agent uses. The same models as cloud agents are available, which are tailored for autonomous use cases. Cursor chooses a default model when you create the automation. Environment Automations inherit environment configuration from your Cloud Agents dashboard and Cloud agent setup . Enabled : The agent installs dependencies before running. Use this when the automation needs to build, test, or execute code. Disabled : The agent skips dependency installation. Use this when it only needs to read or review code. Configure environment settings and secrets in the Cloud Agents dashboard . The automation uses the same settings for the selected repository or multi-repo environment. Use a multi-repo environment when an automation needs to investigate or change code across repos. For example, a Slack-triggered automation can read a report from a public channel, inspect the selected repo group, and open pull requests in the repos it changes. Permissions Control who can view and manage the automation. The permission scope also determines how usage is billed . Private : Only you can manage the automation. Team admins can view and disable the automation. Team Visible : Only you can manage the automation. Team members can view the automation, and team admins can disable the automation. It still runs with your auth. Team Owned : Team members can view the automation. Only team admins can manage the automation. It runs with the team's shared automations service account. Promoting an automation from Private or Team Visible to Team Owned changes the identity it runs as. It stops using your auth and starts using the team's shared automations service account. If the automation uses webhook triggers, regenerate its webhook API key after the scope change. If it uses MCPs or other integrations that rely on personal OAuth credentials, make sure those are configured for the team's service account instead. Only team admins can promote an automation to Team Owned. Identity When an automation acts on external services, it uses the following identities: GitHub comments, review approvals, and reviewer requests run as cursor . Team-scoped automations open pull requests as cursor . Private automations open pull requests as your GitHub account. Slack messages are sent as the Cursor bot. Writing prompts Prompts define what the agent should do. Write them the same way you would write instructions for a cloud agent run. Tips: Be specific about what the agent should check, change, or produce. Reference the actions you enabled - you can at-mention tools or informally mention their names. Include decision rules for what to do in different cases. Set a quality bar for when the agent should open a pull request, comment, or do nothing. Describe the output format you want. Related Cloud agents overview Cloud agent setup Cloud agent pricing GitHub integration Slack integration Linear integration English English 简体中文 日本語 繁體中文 Español Français Português 한국어 Русский Türkçe Bahasa Indonesia Deutsch हिन्दी

Cloud Agents Cloud Agents settings Workspace admins can configure Cloud Agents from the Cloud Agents dashboard . Environment management The Environments view lists the saved environments available to your team. Environments can be scoped to one repo or to a group of repos. Open an environment to review: The repositories it applies to Whether it uses a snapshot or .cursor/environment.json The update script that runs before an agent starts Runtime secrets and build secrets Network access settings Version history and setup runs Use Update with Agent when you want Cursor to inspect the current environment and propose a new setup. Use New Setup Run when you want Cursor to start setting up the environment fresh. Use Restore from version history to make a prior environment version active again. Default settings Default model – the model used when a run does not specify one. Pick any model that supports Max Mode. Default repository – when empty, agents ask the user to choose a repo. Supplying a repo here lets users skip that step. Base branch – the branch agents fork from when creating pull requests. Leave blank to use the repository’s default branch. Network access settings Control which network resources Cloud Agents can reach. User and team settings support three modes: Allow all network access – no domain restrictions. Default + allowlist – the default domains plus any domains you add. Allowlist only – only domains you explicitly add. Users, team admins, and environment owners can configure network access. Environment-level settings can inherit user or team policy, add an environment allowlist, or define their own access mode. See Network Access for full details. Security settings All security options require admin privileges. Display agent summary – controls whether Cursor shows the agent's file-diff images and code snippets. Disable this if you prefer not to expose file paths or code in the sidebar. Display agent summary in external channels – extends the previous toggle to Slack or any external channel you've connected. Team follow-ups – controls whether team members can send follow-up messages to cloud agents created by other users on the team. See team follow-ups below. Team feature settings Team admins can enable or disable these features for their team: Long running agents – controls whether team members can run agents for extended durations. Admins can enable or restrict this capability at the team level. Computer use – controls whether agents can use computer interaction capabilities (available to enterprise teams only). Changes save instantly and affect new agents immediately. Team follow-ups Team members can send follow-up messages to cloud agents created by other users on the same team. This is useful when a teammate starts an agent and you need to course-correct, add context, or continue the work while they're unavailable. Team admins control this behavior from the Cloud Agents security settings with three options: Setting Behavior Disabled Only the original creator can send follow-ups to their agent. No team follow-ups are allowed. Service accounts only Team members can send follow-ups to agents created by a service account , but not to agents created by other human users. All Any team member can send follow-ups to any agent on the team, regardless of who created it. Lateral movement and secret exposure Enabling team follow-ups means a user can influence the execution of a cloud agent that runs with another user's secrets and credentials. A follow-up message can instruct the agent to read environment variables, print secrets to logs, push credentials to an external endpoint, or perform actions using the original creator's access tokens. A team member with limited permissions could escalate their access by directing an agent that holds a more privileged user's secrets. Treat this setting with the same care you would give shared SSH keys or service credentials. English English 简体中文 日本語 繁體中文 Español Français Português 한국어 Русский Türkçe Bahasa Indonesia Deutsch हिन्दी

Integrations GitHub The Cursor GitHub app connects your repositories so you can use features like Cloud Agents and Bugbot . Setup GitHub.com GitHub Enterprise Server Requires Cursor admin access and GitHub org admin access. Go to Integrations in the dashboard Click Connect next to GitHub (or Manage Connections if already connected) Choose All repositories or Selected repositories Return to the dashboard to configure features on your repositories To disconnect your GitHub account, return to the integrations dashboard and click Disconnect Account . IP allow list configuration If your organization uses GitHub's IP allow list feature to restrict access to your repositories, Cursor can be configured to use a hosted egress proxy with a narrow set of IPs. Before configuring IP allowlists, contact hi@cursor.com to enable this feature for your team. This is required for either configuration method below. Enable IP allow list configuration for installed GitHub Apps (recommended) The Cursor GitHub app has the IP list already pre-configured. You can enable the allowlist for installed apps to automatically inherit this list. This is the recommended approach , as it allows us to update the list and your organization receives updates automatically. To enable this: Go to your organization's Security settings Navigate to IP allow list settings Check "Allow access by GitHub Apps" For detailed instructions, see GitHub's documentation . Add IPs directly to your allowlist If your organization uses IdP-defined allowlists in GitHub or otherwise cannot use the pre-configured allowlist, add the proxy IPs listed in Git egress proxy and IP allow list . Advanced networking Self-hosted instances support multiple connection methods beyond IP whitelisting. PrivateLink (AWS) or Private Service Connect (GCP) Available for Enterprise customers. Allow Cursor to access your instance over a private network connection. Contact your Cursor representative for setup. Best for: Instances behind a firewall on a private network in AWS, Azure, or GCP Security: HTTPS encryption with optional mTLS, PrivateLink/Service Connect, VPC allowlisting, service account access tokens Drawbacks: Only supports public clouds with private networking connections between VPCs Reverse Proxy Tunnel Available for Enterprise customers. Run a reverse proxy tunnel on-premises that establishes a long-lived websocket connection to Cursor's servers. Network requests are forwarded through to your instance. Requires no inbound network access. Contact your Cursor representative for setup. Best for: Environments without inbound network access Security: HTTPS encryption, service account access tokens Drawbacks: Introduces additional complexity, maintenance requirements, and potential security considerations compared to more direct connection methods Permissions The GitHub app requests the following permissions to support Cursor features: Permission Purpose Repository access Clone your code and create working branches Pull requests Create PRs and leave review comments Issues Track bugs and tasks discovered during reviews Checks and statuses Report on code quality and test results Actions and workflows Monitor CI/CD pipelines and deployment status All permissions follow the principle of least privilege. Troubleshooting Agent can't access repository Install the GitHub app with repository access Check repository permissions for private repos Verify your GitHub account permissions Permission denied for pull requests Grant the app write access to pull requests Check branch protection rules Reinstall if the app installation expired App not visible in GitHub settings Check if installed at organization level Reinstall from github.com/apps/cursor Contact support if installation is corrupted Next steps Once your GitHub integration is connected, configure the features that use it: Bugbot — automated PR reviews that catch bugs and security issues Cloud Agents — AI agents that run in the cloud on your repositories English English 简体中文 日本語 繁體中文 Español Français Português 한국어 Русский Türkçe Bahasa Indonesia Deutsch हिन्दी

Agent Agent Security AI can behave unexpectedly due to prompt injection, hallucinations, and other issues. We protect users with guardrails that limit what agents can do. By default, sensitive actions require your manual approval. This document explains our guardrails and what they mean for you. These controls and behaviors are our defaults. We recommend keeping them enabled. First-party tool calls Cursor includes tools that help agents write code: reading files, editing files, running terminal commands, searching the web, and more. Reading files and searching code don't require approval. Use .cursorignore to block agent access to specific files. Actions that could expose sensitive data require your explicit approval. Agents can modify workspace files without approval, except for configuration files. Changes save immediately to disk. Always use version control so you can revert changes. Configuration files (like workspace settings) need your approval first. Warning: If you have auto-reload enabled, agent changes might execute before you can review them. Terminal commands need your approval by default. Review every command before letting the agent run it. You can enable auto-approval if you accept the risk. We have an allowlist feature, but it's not a security guarantee. The allowlist is best-effort—bypasses are possible. Never use "Run Everything" mode, which skips all safety checks. You can manage allowlists for both terminal commands and MCP tools through the settings UI or ~/.cursor/permissions.json . Third-party tool calls You can connect external tools using MCP . All MCP connections need your approval. After you approve an MCP connection, each tool call still needs individual approval before running. You can pre-approve specific tools with an MCP allowlist . Network requests Attackers could use network requests to steal data. Our tools only make network requests to: GitHub Direct link retrieval Web search providers Agents cannot make arbitrary network requests with default settings. Workspace trust Cursor supports workspace trust , but it's disabled by default. When enabled, it prompts you to choose between normal or restricted mode for new workspaces. Restricted mode breaks AI features. For untrusted repos, use a basic text editor instead. To enable workspace trust: Open your user settings.json file Add the following configuration: "security.workspace.trust.enabled" : true Organizations can enforce this setting through MDM solutions. Responsible disclosure Found a vulnerability? Email security-reports@cursor.com with details and steps to reproduce. We acknowledge vulnerability reports within 5 business days. For critical incidents, we notify all users via email. English English 简体中文 日本語 繁體中文 Español Français Português 한국어 Русский Türkçe Bahasa Indonesia Deutsch हिन्दी

Customizing Rules Rules provide system-level instructions to Agent. They bundle prompts, scripts, and more together, making it easy to manage and share workflows across your team. Cursor supports four types of rules: Project Rules Stored in .cursor/rules , version-controlled and scoped to your codebase. User Rules Global to your Cursor environment. Used by Agent (Chat). Team Rules Team-wide rules managed from the dashboard. Available on Team and Enterprise plans. AGENTS.md Agent instructions in markdown format. Simple alternative to .cursor/rules . How rules work Large language models don't retain memory between completions. Rules provide persistent, reusable context at the prompt level. When applied, rule contents are included at the start of the model context. This gives the AI consistent guidance for generating code, interpreting edits, or helping with workflows. Project rules Project rules live in .cursor/rules as markdown files and are version-controlled. They are scoped using path patterns, invoked manually, or included based on relevance. Use project rules to: Encode domain-specific knowledge about your codebase Automate project-specific workflows or templates Standardize style or architecture decisions Rule file structure Each rule is a markdown file that you can name anything you want. Cursor supports .md and .mdc extensions. Use .mdc files with frontmatter to specify description and globs for more control over when rules are applied. .cursor/rules/ react-patterns.mdc # Rule with frontmatter (description, globs) api-guidelines.md # Simple markdown rule frontend/ # Organize rules in folders components.md Rule anatomy Each rule is a markdown file with frontmatter metadata and content. Control how rules are applied from the type dropdown which changes properties description , globs , alwaysApply . Rule Type Description Always Apply Apply to every chat session Apply Intelligently When Agent decides it's relevant based on description Apply to Specific Files When file matches a specified pattern Apply Manually When @-mentioned in chat (e.g., @my-rule ) Under the hood, the three frontmatter fields interact to determine when a rule is included: alwaysApply description globs Behavior true — — Always included. Globs and description are ignored. false — provided Auto-attached when a matching file is in context. false provided omitted Agent reads the description and pulls the rule in when relevant. false omitted omitted Included only when you @ -mention the rule in chat. Always applied --- alwaysApply: true --- - All source files must include the company copyright header - When you are unsure about implementation details, read the relevant source files before proposing changes - Never modify generated files in the `dist/` or `build/` directories Auto-attached by file pattern --- globs: src/components/* */* .tsx alwaysApply: false --- - Use named exports, not default exports - Co-locate styles in a module CSS file next to the component - Keep components under 200 lines. Extract subcomponents into the same directory when a file grows beyond that - Prefer composition over prop drilling. Pass children or render props instead of threading data through multiple layers Agent-selected based on description --- description: RPC service conventions and patterns for the backend alwaysApply: false --- - Define each service in its own file under `src/services/` - Always validate inputs at the service boundary before passing data to internal functions - Return structured error objects with a `code` and `message` field, never throw raw strings - Add a `@service-template.ts` reference file when creating a new service for the standard boilerplate Manual — only via @-mention --- alwaysApply: false --- - Every database migration must have both `up` and `down` functions so it can be fully reversed - Never alter a column type in-place. Add a new column, backfill, then drop the old one in a separate migration - Reference the template for the expected file structure @migration-template.sql Glob pattern examples Use globs to scope a rule to specific files or directories. Separate multiple patterns with commas. Pattern Matches * Any single file name segment ** Any number of directories (recursive) *.ts All .ts files in the root **/*.ts All .ts files in any directory src/** All files anywhere under src/ src/**/*.tsx All .tsx files anywhere under src/ docs/**/*.md, docs/**/*.mdx .md and .mdx files under docs/ (comma-separated) tailwind.config.* tailwind.config with any extension Creating a rule There are two ways to create rules: /create-rule in chat : Type /create-rule in Agent and describe what you want. Agent generates the rule file with proper frontmatter and saves it to .cursor/rules . From settings : Open Cursor Settings > Rules, Commands and click + Add Rule . This creates a new rule file in .cursor/rules . From settings you can see all rules and their status. Best practices Good rules are focused, actionable, and scoped. Keep rules under 500 lines Split large rules into multiple, composable rules Provide concrete examples or referenced files Avoid vague guidance. Write rules like clear internal docs Reuse rules when repeating prompts in chat Reference files instead of copying their contents—this keeps rules short and prevents them from becoming stale as code changes What to avoid in rules Copying entire style guides : Use a linter instead. Agent already knows common style conventions. Documenting every possible command : Agent knows common tools like npm, git, and pytest. Adding instructions for edge cases that rarely apply : Keep rules focused on patterns you use frequently. Duplicating what's already in your codebase : Point to canonical examples instead of copying code. Start simple. Add rules only when you notice Agent making the same mistake repeatedly. Don't over-optimize before you understand your patterns. Check your rules into git so your whole team benefits. When you see Agent make a mistake, update the rule. You can even tag @cursor on a GitHub issue or PR to have Agent update the rule for you. Rule file format Each rule is a markdown file with frontmatter metadata and content. The frontmatter metadata is used to control how the rule is applied. The content is the rule itself. --- description: "This rule provides standards for frontend components and API validation" alwaysApply: false --- ...rest of the rule content If alwaysApply is true, the rule will be applied to every chat session. Otherwise, the description of the rule will be presented to the Cursor Agent to decide if it should be applied. Examples Standards for frontend components and API validation This rule provides standards for frontend components: When working in components directory: Always use Tailwind for styling Use Framer Motion for animations Follow component naming conventions This rule enforces validation for API endpoints: In API directory: Use zod for all validation Define return types with zod schemas Export types generated from schemas Templates for Express services and React components This rule provides a template for Express services: Use this template when creating Express service: Follow RESTful principles Include error handling middleware Set up proper logging @express-service-template.ts This rule defines React component structure: React components should follow this layout: Props interface at top Component as named export Styles at bottom @component-template.tsx Automating development workflows and documentation generation This rule automates app analysis: When asked to analyze the app: Run dev server with npm run dev Fetch logs from console Suggest performance improvements This rule helps generate documentation: Help draft documentation by: Extracting code comments Analyzing README.md Generating markdown documentation Adding a new setting in Cursor First create a property to toggle in @reactiveStorageTypes.ts . Add default value in INIT_APPLICATION_USER_PERSISTENT_STORAGE in @reactiveStorageService.tsx . For beta features, add toggle in @settingsBetaTab.tsx , otherwise add in @settingsGeneralTab.tsx . Toggles can be added as for general checkboxes. Look at the rest of the file for examples. < SettingsSubSection label = "Your feature name" description = "Your feature description" value = { vsContext.reactiveStorageService.applicationUserPersistentStorage .myNewProperty ?? false } onChange = {( newVal ) => { vsContext.reactiveStorageService. setApplicationUserPersistentStorage ( "myNewProperty" , newVal, ); }} /> To use in the app, import reactiveStorageService and use the property: const flagIsEnabled = vsContext.reactiveStorageService.applicationUserPersistentStorage .myNewProperty; Examples are available from providers and frameworks. Community-contributed rules are found across crowdsourced collections and repositories online. Team Rules Team and Enterprise plans can create and enforce rules across their entire organization from the Cursor dashboard . Admins can configure whether or not each rule is required for team members. Team Rules work alongside other rule types and take precedence to ensure organizational standards are maintained across all projects. They provide a powerful way to ensure consistent coding standards, practices, and workflows across your entire team without requiring individual setup or configuration. Managing Team Rules Team administrators can create and manage rules directly from the Cursor dashboard: Once team rules are created, they automatically apply to all team members and are visible in the dashboard: Activation and enforcement Enable this rule immediately : When checked, the rule is active as soon as you create it. When unchecked, the rule is saved as a draft and does not apply until you enable it later. Enforce this rule : When enabled, the rule is required for all team members and cannot be disabled in their Cursor settings. When not enforced, team members can toggle the rule off in Cursor Settings → Rules under the Team Rules section. By default, non‑enforced Team Rules can be disabled by users. Use Enforce this rule to prevent that. Format and how Team Rules are applied Content : Team Rules are free‑form text. They do not use the folder structure of Project Rules. Glob patterns : Team Rules support glob patterns for file-scoped application. When a glob pattern is set (e.g., **/*.py ), the rule only applies when matching files are in context. Rules without a glob pattern apply to every conversation. Where they apply : When a Team Rule is enabled (and not disabled by the user, unless enforced), it is included in the model context for Agent (Chat) across all repositories and projects for that team. Precedence : Rules are applied in this order: Team Rules → Project Rules → User Rules . All applicable rules are merged; earlier sources take precedence when guidance conflicts. Some teams use enforced rules as part of internal compliance workflows. While this is supported, AI guidance should not be your only security control. Importing Rules You can import rules from external sources to reuse existing configurations or bring in rules from other tools. Remote rules (via GitHub) Import rules directly from any GitHub repository you have access to—public or private. Open Cursor Settings → Rules, Commands Click + Add Rule next to Project Rules , then select Remote Rule (Github) Paste the GitHub repository URL containing the rules. Cursor will scan for all .mdc files in the repo. Cursor will pull and sync the rule(s) into your project Rules will be placed in .cursor/rules/imported/ . Rules will also keep their relative paths, so dir/rule.mdc will be imported as .cursor/rule/imported//dir/rule.mdc . AGENTS.md AGENTS.md is a simple markdown file for defining agent instructions. Place it in your project root as an alternative to .cursor/rules for straightforward use cases. Unlike Project Rules, AGENTS.md is a plain markdown file without metadata or complex configurations. It's perfect for projects that need simple, readable instructions without the overhead of structured rules. Cursor supports AGENTS.md in the project root and subdirectories. # Project Instructions ## Code Style - Use TypeScript for all new files - Prefer functional components in React - Use snake_case for database columns ## Architecture - Follow the repository pattern - Keep business logic in service layers Improvements Nested AGENTS.md support Nested AGENTS.md support in subdirectories is now available. You can place AGENTS.md files in any subdirectory of your project, and they will be automatically applied when working with files in that directory or its children. This allows for more granular control of agent instructions based on the area of your codebase you're working in: project/ AGENTS.md # Global instructions frontend/ AGENTS.md # Frontend-specific instructions components/ AGENTS.md # Component-specific instructions backend/ AGENTS.md # Backend-specific instructions Instructions from nested AGENTS.md files are combined with parent directories, with more specific instructions taking precedence. User Rules User Rules are global preferences defined in Cursor Settings → Rules that apply across all projects. They are used by Agent (Chat) and are perfect for setting preferred communication style or coding conventions: Please reply in a concise style. Avoid unnecessary repetition or filler language. FAQ Why isn't my rule being applied? Check the rule type. For Apply Intelligently , ensure a description is defined. For Apply to Specific Files , ensure the file pattern matches referenced files. Can rules reference other rules or files? Yes. Use @filename.ts to include files in your rule's context. You can also @mention rules in chat to apply them manually. Can I create a rule from chat? Yes, you can ask the agent to create a new rule for you. Do rules impact Cursor Tab or other AI features? No. Rules do not impact Cursor Tab or other AI features. Do User Rules apply to Inline Edit (Cmd/Ctrl+K)? No. User Rules are not applied to Inline Edit (Cmd/Ctrl+K). They are only used by Agent (Chat). English English 简体中文 日本語 繁體中文 Español Français Português 한국어 Русский Türkçe Bahasa Indonesia Deutsch हिन्दी

Get Started Quickstart This guide gets you from install to your first useful change in Cursor. You'll sign in, ask Cursor to explain your codebase, make a small edit, and review the result. 1 Install Cursor and sign in Download Cursor. Open the app and sign in. Then pick a folder and start with a small task. Download Cursor ⤓ macOS macOS 12 (Monterey) and later Native installer (.dmg) Apple Silicon and Intel support Windows Windows 10 and later Native installer (.exe) Linux Debian/Ubuntu (recommended) # Add Cursor's GPG key curl -fsSL https://downloads.cursor.com/keys/anysphere.asc | gpg --dearmor | sudo tee /etc/apt/keyrings/cursor.gpg > /dev/null # Add the Cursor repository echo "deb [arch=amd64,arm64 signed-by=/etc/apt/keyrings/cursor.gpg] https://downloads.cursor.com/aptrepo stable main" | sudo tee /etc/apt/sources.list.d/cursor.list > /dev/null # Update and install sudo apt update sudo apt install cursor RHEL/Fedora # Add Cursor's repository sudo tee /etc/yum.repos.d/cursor.repo << 'EOF' [cursor] name=Cursor baseurl=https://downloads.cursor.com/yumrepo enabled=1 gpgcheck=1 gpgkey=https://downloads.cursor.com/keys/anysphere.asc EOF # Install Cursor sudo dnf install cursor AppImage (portable) Download the .AppImage file from cursor.com/downloads , then: chmod +x Cursor- * .AppImage ./Cursor-*.AppImage The apt and yum packages are preferred over AppImage. They provide desktop icons, automatic updates, and CLI tools. 2 Ask Cursor to explain your codebase After you pick a folder, open Agent with Cmd I Ctrl I . Ask Cursor to explain the codebase and point out the main areas to read first. Explain this codebase. Point me to the main entry points, key modules, and anything I should read before making changes. Cursor Logo Try in Cursor Cursor will search your repo, read relevant files, and summarize how the project fits together. This is one of the fastest ways to get oriented in an unfamiliar codebase. Want a deeper walkthrough? See Understand your codebase . 3 Make one small change Once you understand the project, ask Cursor to suggest a few safe improvements. Pick one and ask it to make the change. Suggest three small, safe improvements in this codebase. Explain the tradeoffs and wait for me to choose one. Cursor Logo Try in Cursor Good first tasks are low risk, like improving some copywriting or fixing small UI issues. If you already know what you want to change, ask for it directly and describe the result you want. 4 Review the diff and verify the result Now you can watch Cursor work. The diff view shows changes made by the agent. When it finishes, review the diff and ask Cursor to run the checks your project already uses. That can mean tests, the type checker, linting, or a local build. Want a stronger review workflow? See Reviewing and testing code . 5 Use Plan Mode for bigger changes Now that you know the basics, use Plan Mode for bigger changes. It works well when the task spans multiple files, needs research, or needs approval before coding. Press Shift+Tab in the agent input to toggle Plan Mode . Instead of writing code right away, Cursor will: Research your codebase to find relevant files Ask clarifying questions about your requirements Create a detailed implementation plan Wait for your approval before building For a deeper walkthrough, see Build new features . Next steps Agent Overview Learn about Agent's tools and capabilities Rules Create persistent instructions for your project Understand your code Learn how to get oriented in an unfamiliar repo Build new features See a full workflow for shipping larger changes English English 简体中文 日本語 繁體中文 Español Français Português 한국어 Русский Türkçe Bahasa Indonesia Deutsch हिन्दी

Cloud Agents Security & Network Cloud Agents are available in Privacy Mode. We never train on your code and only retain code for running the agent. Learn more about Privacy mode . Secret protection Secrets provided to Cloud Agents are encrypted at rest and in transit. They are not visible to anyone other than the Cloud Agent user. You can classify secrets as "Redacted" for additional protection. Redacted secrets: Are scanned in commit messages and files, which are rejected if they contain the secret Are redacted from model tool calls, so they are not shown to the models or stored in chat transcripts This prevents accidental exposure of credentials in version control and model context. Signed commits Cloud Agents sign every commit with a HSM-backed Ed25519 key. On GitHub and GitLab, these commits display a "Verified" badge so your team can confirm the commit came from Cursor. This works automatically for all Cloud Agents. No setup is required. If your repository enforces branch protection rules that require signed commits, Cloud Agent PRs satisfy those rules without extra configuration. What you should know Grant read-write privileges to our GitHub app for repos you want to edit. We use this to clone the repo and make changes. Your code runs inside our AWS infrastructure in isolated VMs and is stored on VM disks while the agent is accessible. The agent has internet access by default. You can configure network egress controls for users, teams, and saved environments to restrict the domains the agent can access. The agent auto-runs all terminal commands, letting it iterate on tests. This differs from the foreground agent, which requires user approval for every command. Auto-running introduces data exfiltration risk: attackers could execute prompt injection attacks, tricking the agent to upload code to malicious websites. See OpenAI's explanation about risks of prompt injection for cloud agents . If privacy mode is disabled, we collect prompts and dev environments to improve the product. If you disable privacy mode when starting a cloud agent, then enable it during the agent's run, the agent continues with privacy mode disabled until it completes. Network access Control which network resources your Cloud Agents can reach. These settings are available on the Cloud Agents dashboard for individual users, saved environments, and team admins. Access modes Three modes control outbound network access for Cloud Agents: Mode Behavior Allow all network access Cloud Agents can reach any external host. No domain restrictions apply. Default + allowlist Cloud Agents can reach the default domains plus any domains you add to your allowlist. Allowlist only Cloud Agents can only reach the domains you explicitly add to your allowlist. Even in Allowlist only mode, a small set of domains remain accessible so Cloud Agents can function. These include Cursor's own services and source control management (SCM) providers. Artifact uploads Cloud Agents upload artifacts (screenshots, videos, and log references shown on PRs) to cloud-agent-artifacts.s3.us-east-1.amazonaws.com . If you use Default + allowlist or Allowlist only , add the exact host to your allowlist so artifact uploads succeed. Don't broaden the entry to *.s3.us-east-1.amazonaws.com : the wildcard opens egress to every bucket in the region and creates an exfiltration path for a prompt-injected agent. Blocking the host disables uploads; agent sessions and other tool calls keep working. Self-hosted workers upload artifacts over the same host. For self-hosted deployments, allow it through any firewall between the worker and the public internet. See My Machines networking and Self-Hosted Pool networking . User-level settings Individual users can configure their network access mode from the Cloud Agents dashboard under the Security header. Your user-level setting applies to all Cloud Agents you create. When you select a mode that includes an allowlist ( Default + allowlist or Allowlist only ), an allowlist configuration section appears below the setting where you can add your custom domains. Environment-level settings Saved environments can have their own network access mode and allowlist. Use environment-level settings when one repo or repo group needs stricter egress than the rest of your team. For example, you can keep a production-adjacent environment on Allowlist only while leaving a less sensitive environment on Default + allowlist . Agents that use the stricter environment inherit those restrictions. Environment-level settings include two inheritance options: Mode Behavior Inherit settings Uses the applicable user or team network access setting. Inherit settings + environment allowlist Uses the applicable user or team setting and adds domains from the environment allowlist. You can also set an environment directly to Allow all network access , Default + allowlist , or Allowlist only . Team-level settings Team admins can set a default network access mode for the entire team from the same dashboard. The team-level allowlist is the same allowlist that admins configure for the sandbox default network allowlist . There is no separate allowlist to manage; one allowlist controls both Cloud Agent network access and the sandbox defaults. When a team-level setting exists: If an environment defines its own mode, the environment setting applies to agents that use that environment. If an environment inherits settings and a user has configured their own setting, the user setting takes precedence . If neither the environment nor the user has configured a setting, the team default applies . Locking the setting (Enterprise) Locking is available for Enterprise teams only. Enterprise team admins can lock the network access setting using the Lock Network Access Policy option. When locked: The team-level setting applies to every member, regardless of their individual preference. Users cannot override the locked setting from their own dashboard. This gives admins full control over Cloud Agent network access across the organization. Relationship to sandbox network policy The "Default" domains in the Default + allowlist mode are the same default network allowlist used by the desktop Agent's sandbox. The team-level allowlist is also shared: when an admin configures an allowlist on the dashboard, it applies to both Cloud Agent network access and the sandbox network policy . Egress IP ranges Cloud Agents make network connections from specific IP address ranges when accessing external services, APIs, or repositories. API endpoint The IP ranges are available via a JSON API endpoint : curl https://cursor.com/docs/ips.json Response format { "version" : 1 , "modified" : "2025-09-24T16:00:00.000Z" , "cloudAgents" : { "us3p" : [ "100.26.13.169/32" , "34.195.201.10/32" , "..." ], "us4p" : [ "54.184.235.255/32" , "35.167.37.158/32" , "..." ], "us5p" : [ "3.12.82.200/32" , "52.14.104.140/32" , "..." ] }, "gitEgressProxy" : [ "184.73.225.134/32" , "3.209.66.12/32" , "52.44.113.131/32" ] } version : Schema version number for the API response modified : ISO 8601 timestamp of when the IP ranges were last updated cloudAgents : Object containing IP ranges, keyed by cluster gitEgressProxy : IP addresses used by the git egress proxy IP ranges published in CIDR notation . You can use an online conversion tool to convert from CIDR notation to IP address ranges if needed. Using the IP ranges These published IP ranges may be used by Cloud Agents to: Clone and push to remote repositories (unless using the git egress proxy ) Download packages and dependencies Make API calls to external services Access web resources during agent execution If your organization uses firewall rules or IP allowlists to control network access, you may need to allowlist these IP ranges to ensure Cloud Agents can properly access your services. Important considerations: We make changes to our IP addresses from time to time for scaling and operational needs. We do not recommend allowlisting by IP address as your primary security mechanism. If you must use these IP ranges, we strongly encourage regular monitoring of the JSON API endpoint. Git egress proxy and IP allow list Cursor supports a similar but distinct feature to use a git egress proxy for IP allow lists . This proxy routes all git traffic through a narrower set of IPs and works across all git hosts, including GitHub and GitLab. For git hosts specifically, we recommend the IP allow list configuration described in the link above, as it integrates directly with the Cursor GitHub app. If you need to add the proxy IPs directly to an allowlist, use these addresses: 184.73.225.134 3.209.66.12 52.44.113.131 These IP addresses are stable. If the list ever changes, teams using IP allow lists will get advance notice before any address is added or removed. English English 简体中文 日本語 繁體中文 Español Français Português 한국어 Русский Türkçe Bahasa Indonesia Deutsch हिन्दी

Get Started Models & Pricing Cursor supports all frontier coding models from OpenAI, Anthropic, Google, and more. Every individual plan includes two usage pools so you can pick the right balance of intelligence, speed, and cost. Usage pools There are two separate usage pools for individual plans, each resetting with your monthly billing cycle: Auto + Composer : Significantly more included usage when Auto or Composer 2 is selected. Designed for everyday agentic coding at a lower cost. API : Charged at the model's API price. Individual plans include at least $20 of API usage each month (more on higher tiers) with the option to pay for additional usage as needed. Both pools are visible in your editor settings and on your usage dashboard . Auto + Composer pool Auto allows Cursor to select models that balance intelligence, cost efficiency, and reliability. It is useful for everyday tasks. Auto pricing Token type Price per 1M tokens Input + Cache Write $1.25 Output $6.00 Cache Read $0.25 Composer pricing Composer 2 is Cursor's own model, trained to be highly capable for agentic coding. Both Auto and Composer 2 draw from this pool. Name Input Cache Write Cache Read Output Composer 2 $0.5 - $0.2 $2.5 Composer 2 (Fast) $1.5 - $0.35 $7.5 API pool When you select a specific model (or use Premium routing), usage is drawn from the API pool at that model's API rate. Model pricing All prices are per million tokens, sourced from each provider's API pricing: Name Input Cache Write Cache Read Output Claude 4.6 Sonnet $3 $3.75 $0.3 $15 Claude 4.7 Opus $5 $6.25 $0.5 $25 Composer 2 $0.5 - $0.2 $2.5 Gemini 3.1 Pro $2 - $0.2 $12 GPT-5.3 Codex $1.75 - $0.175 $14 GPT-5.5 $5 - $0.5 $30 Grok 4.3 $1.25 - $0.2 $2.5 Show more models Premium routing Premium allows Cursor to select the most capable models for you, recommended for the most complex tasks. The Cursor team selects Premium models based on internal benchmarks, evaluations, and user feedback. Premium pricing is based on the selected model's API rate. Check your usage page to see cost and model selection at the request level. Plans All individual plans include unlimited tab completions, extended agent usage limits on all models, access to Bugbot, and access to Cloud Agents. Plan Price API usage included Auto + Composer Pro $20/mo $20 Generous included usage Pro Plus $60/mo $70 Generous included usage Ultra $200/mo $400 Generous included usage Since different models have different API costs, your model selection affects how quickly your included usage is consumed. How much usage do I need? Daily Tab users : Always stay within $20 Limited Agent users : Often stay within the included $20 Daily Agent users : Typically $60–$100/mo total usage Power users (multiple agents/automation) : Often $200+/mo total usage What happens when I reach my limit? When you exceed your included monthly usage, you can either: Add on-demand usage : Continue at the same API rates with pay-as-you-go billing Upgrade your plan : Move to a higher tier for more included usage On-demand usage is billed monthly at the same rates. Requests are never downgraded in quality or speed. Teams There are two teams plans: Teams ($40/user/mo) and Enterprise (Custom). Team plans provide additional features like privacy mode enforcement, admin dashboard with usage stats, centralized team billing, and SAML/OIDC SSO. We recommend Teams for any customer that is happy self-serving. We recommend Enterprise for customers that need priority support, pooled usage, invoicing, SCIM, or advanced security controls. Learn more about Teams pricing . Cursor Token Rate On Teams plans, non-Auto agent requests include a Cursor Token Rate of $0.25 per million tokens. This rate applies on top of model API pricing for included usage, on-demand usage, and BYOK usage. Auto is exempt from the Cursor Token Rate. Max Mode Max Mode extends the context window to the maximum a model supports. More context gives models deeper understanding of your codebase, leading to better results on complex tasks. The models table above shows each model's maximum context size. Max Mode uses token-based pricing at the model's API rate, so it consumes usage faster than the default context window. On current individual plans, Max Mode is billed at the model's API rate. On Teams plans, non-Auto requests include the Cursor Token Rate. On legacy request-based plans, Max Mode adds a 20% surcharge. FAQ Where are models hosted? Models are hosted on US, Canada, & Iceland based infrastructure by the model's provider, a trusted partner, or Cursor directly. When Privacy Mode is enabled, neither Cursor nor model providers store your data. All data is deleted after each request. For details see our Privacy Policy and Security pages. Where can I find pricing terms? For enterprise pricing details, billing terms, and fee calculations, see the Pricing Policy . English English 简体中文 日本語 繁體中文 Español Français Português 한국어 Русский Türkçe Bahasa Indonesia Deutsch हिन्दी

Customizing Rules Rules provide system-level instructions to Agent. They bundle prompts, scripts, and more together, making it easy to manage and share workflows across your team. Cursor supports four types of rules: Project Rules Stored in .cursor/rules , version-controlled and scoped to your codebase. User Rules Global to your Cursor environment. Used by Agent (Chat). Team Rules Team-wide rules managed from the dashboard. Available on Team and Enterprise plans. AGENTS.md Agent instructions in markdown format. Simple alternative to .cursor/rules . How rules work Large language models don't retain memory between completions. Rules provide persistent, reusable context at the prompt level. When applied, rule contents are included at the start of the model context. This gives the AI consistent guidance for generating code, interpreting edits, or helping with workflows. Project rules Project rules live in .cursor/rules as markdown files and are version-controlled. They are scoped using path patterns, invoked manually, or included based on relevance. Use project rules to: Encode domain-specific knowledge about your codebase Automate project-specific workflows or templates Standardize style or architecture decisions Rule file structure Each rule is a markdown file that you can name anything you want. Cursor supports .md and .mdc extensions. Use .mdc files with frontmatter to specify description and globs for more control over when rules are applied. .cursor/rules/ react-patterns.mdc # Rule with frontmatter (description, globs) api-guidelines.md # Simple markdown rule frontend/ # Organize rules in folders components.md Rule anatomy Each rule is a markdown file with frontmatter metadata and content. Control how rules are applied from the type dropdown which changes properties description , globs , alwaysApply . Rule Type Description Always Apply Apply to every chat session Apply Intelligently When Agent decides it's relevant based on description Apply to Specific Files When file matches a specified pattern Apply Manually When @-mentioned in chat (e.g., @my-rule ) Under the hood, the three frontmatter fields interact to determine when a rule is included: alwaysApply description globs Behavior true — — Always included. Globs and description are ignored. false — provided Auto-attached when a matching file is in context. false provided omitted Agent reads the description and pulls the rule in when relevant. false omitted omitted Included only when you @ -mention the rule in chat. Always applied --- alwaysApply: true --- - All source files must include the company copyright header - When you are unsure about implementation details, read the relevant source files before proposing changes - Never modify generated files in the `dist/` or `build/` directories Auto-attached by file pattern --- globs: src/components/* */* .tsx alwaysApply: false --- - Use named exports, not default exports - Co-locate styles in a module CSS file next to the component - Keep components under 200 lines. Extract subcomponents into the same directory when a file grows beyond that - Prefer composition over prop drilling. Pass children or render props instead of threading data through multiple layers Agent-selected based on description --- description: RPC service conventions and patterns for the backend alwaysApply: false --- - Define each service in its own file under `src/services/` - Always validate inputs at the service boundary before passing data to internal functions - Return structured error objects with a `code` and `message` field, never throw raw strings - Add a `@service-template.ts` reference file when creating a new service for the standard boilerplate Manual — only via @-mention --- alwaysApply: false --- - Every database migration must have both `up` and `down` functions so it can be fully reversed - Never alter a column type in-place. Add a new column, backfill, then drop the old one in a separate migration - Reference the template for the expected file structure @migration-template.sql Glob pattern examples Use globs to scope a rule to specific files or directories. Separate multiple patterns with commas. Pattern Matches * Any single file name segment ** Any number of directories (recursive) *.ts All .ts files in the root **/*.ts All .ts files in any directory src/** All files anywhere under src/ src/**/*.tsx All .tsx files anywhere under src/ docs/**/*.md, docs/**/*.mdx .md and .mdx files under docs/ (comma-separated) tailwind.config.* tailwind.config with any extension Creating a rule There are two ways to create rules: /create-rule in chat : Type /create-rule in Agent and describe what you want. Agent generates the rule file with proper frontmatter and saves it to .cursor/rules . From settings : Open Cursor Settings > Rules, Commands and click + Add Rule . This creates a new rule file in .cursor/rules . From settings you can see all rules and their status. Best practices Good rules are focused, actionable, and scoped. Keep rules under 500 lines Split large rules into multiple, composable rules Provide concrete examples or referenced files Avoid vague guidance. Write rules like clear internal docs Reuse rules when repeating prompts in chat Reference files instead of copying their contents—this keeps rules short and prevents them from becoming stale as code changes What to avoid in rules Copying entire style guides : Use a linter instead. Agent already knows common style conventions. Documenting every possible command : Agent knows common tools like npm, git, and pytest. Adding instructions for edge cases that rarely apply : Keep rules focused on patterns you use frequently. Duplicating what's already in your codebase : Point to canonical examples instead of copying code. Start simple. Add rules only when you notice Agent making the same mistake repeatedly. Don't over-optimize before you understand your patterns. Check your rules into git so your whole team benefits. When you see Agent make a mistake, update the rule. You can even tag @cursor on a GitHub issue or PR to have Agent update the rule for you. Rule file format Each rule is a markdown file with frontmatter metadata and content. The frontmatter metadata is used to control how the rule is applied. The content is the rule itself. --- description: "This rule provides standards for frontend components and API validation" alwaysApply: false --- ...rest of the rule content If alwaysApply is true, the rule will be applied to every chat session. Otherwise, the description of the rule will be presented to the Cursor Agent to decide if it should be applied. Examples Standards for frontend components and API validation This rule provides standards for frontend components: When working in components directory: Always use Tailwind for styling Use Framer Motion for animations Follow component naming conventions This rule enforces validation for API endpoints: In API directory: Use zod for all validation Define return types with zod schemas Export types generated from schemas Templates for Express services and React components This rule provides a template for Express services: Use this template when creating Express service: Follow RESTful principles Include error handling middleware Set up proper logging @express-service-template.ts This rule defines React component structure: React components should follow this layout: Props interface at top Component as named export Styles at bottom @component-template.tsx Automating development workflows and documentation generation This rule automates app analysis: When asked to analyze the app: Run dev server with npm run dev Fetch logs from console Suggest performance improvements This rule helps generate documentation: Help draft documentation by: Extracting code comments Analyzing README.md Generating markdown documentation Adding a new setting in Cursor First create a property to toggle in @reactiveStorageTypes.ts . Add default value in INIT_APPLICATION_USER_PERSISTENT_STORAGE in @reactiveStorageService.tsx . For beta features, add toggle in @settingsBetaTab.tsx , otherwise add in @settingsGeneralTab.tsx . Toggles can be added as for general checkboxes. Look at the rest of the file for examples. < SettingsSubSection label = "Your feature name" description = "Your feature description" value = { vsContext.reactiveStorageService.applicationUserPersistentStorage .myNewProperty ?? false } onChange = {( newVal ) => { vsContext.reactiveStorageService. setApplicationUserPersistentStorage ( "myNewProperty" , newVal, ); }} /> To use in the app, import reactiveStorageService and use the property: const flagIsEnabled = vsContext.reactiveStorageService.applicationUserPersistentStorage .myNewProperty; Examples are available from providers and frameworks. Community-contributed rules are found across crowdsourced collections and repositories online. Team Rules Team and Enterprise plans can create and enforce rules across their entire organization from the Cursor dashboard . Admins can configure whether or not each rule is required for team members. Team Rules work alongside other rule types and take precedence to ensure organizational standards are maintained across all projects. They provide a powerful way to ensure consistent coding standards, practices, and workflows across your entire team without requiring individual setup or configuration. Managing Team Rules Team administrators can create and manage rules directly from the Cursor dashboard: Once team rules are created, they automatically apply to all team members and are visible in the dashboard: Activation and enforcement Enable this rule immediately : When checked, the rule is active as soon as you create it. When unchecked, the rule is saved as a draft and does not apply until you enable it later. Enforce this rule : When enabled, the rule is required for all team members and cannot be disabled in their Cursor settings. When not enforced, team members can toggle the rule off in Cursor Settings → Rules under the Team Rules section. By default, non‑enforced Team Rules can be disabled by users. Use Enforce this rule to prevent that. Format and how Team Rules are applied Content : Team Rules are free‑form text. They do not use the folder structure of Project Rules. Glob patterns : Team Rules support glob patterns for file-scoped application. When a glob pattern is set (e.g., **/*.py ), the rule only applies when matching files are in context. Rules without a glob pattern apply to every conversation. Where they apply : When a Team Rule is enabled (and not disabled by the user, unless enforced), it is included in the model context for Agent (Chat) across all repositories and projects for that team. Precedence : Rules are applied in this order: Team Rules → Project Rules → User Rules . All applicable rules are merged; earlier sources take precedence when guidance conflicts. Some teams use enforced rules as part of internal compliance workflows. While this is supported, AI guidance should not be your only security control. Importing Rules You can import rules from external sources to reuse existing configurations or bring in rules from other tools. Remote rules (via GitHub) Import rules directly from any GitHub repository you have access to—public or private. Open Cursor Settings → Rules, Commands Click + Add Rule next to Project Rules , then select Remote Rule (Github) Paste the GitHub repository URL containing the rules. Cursor will scan for all .mdc files in the repo. Cursor will pull and sync the rule(s) into your project Rules will be placed in .cursor/rules/imported/ . Rules will also keep their relative paths, so dir/rule.mdc will be imported as .cursor/rule/imported//dir/rule.mdc . AGENTS.md AGENTS.md is a simple markdown file for defining agent instructions. Place it in your project root as an alternative to .cursor/rules for straightforward use cases. Unlike Project Rules, AGENTS.md is a plain markdown file without metadata or complex configurations. It's perfect for projects that need simple, readable instructions without the overhead of structured rules. Cursor supports AGENTS.md in the project root and subdirectories. # Project Instructions ## Code Style - Use TypeScript for all new files - Prefer functional components in React - Use snake_case for database columns ## Architecture - Follow the repository pattern - Keep business logic in service layers Improvements Nested AGENTS.md support Nested AGENTS.md support in subdirectories is now available. You can place AGENTS.md files in any subdirectory of your project, and they will be automatically applied when working with files in that directory or its children. This allows for more granular control of agent instructions based on the area of your codebase you're working in: project/ AGENTS.md # Global instructions frontend/ AGENTS.md # Frontend-specific instructions components/ AGENTS.md # Component-specific instructions backend/ AGENTS.md # Backend-specific instructions Instructions from nested AGENTS.md files are combined with parent directories, with more specific instructions taking precedence. User Rules User Rules are global preferences defined in Cursor Settings → Rules that apply across all projects. They are used by Agent (Chat) and are perfect for setting preferred communication style or coding conventions: Please reply in a concise style. Avoid unnecessary repetition or filler language. FAQ Why isn't my rule being applied? Check the rule type. For Apply Intelligently , ensure a description is defined. For Apply to Specific Files , ensure the file pattern matches referenced files. Can rules reference other rules or files? Yes. Use @filename.ts to include files in your rule's context. You can also @mention rules in chat to apply them manually. Can I create a rule from chat? Yes, you can ask the agent to create a new rule for you. Do rules impact Cursor Tab or other AI features? No. Rules do not impact Cursor Tab or other AI features. Do User Rules apply to Inline Edit (Cmd/Ctrl+K)? No. User Rules are not applied to Inline Edit (Cmd/Ctrl+K). They are only used by Agent (Chat). English English 简体中文 日本語 繁體中文 Español Français Português 한국어 Русский Türkçe Bahasa Indonesia Deutsch हिन्दी

Agent Agents Window The Agents Window is Cursor's agent-first interface. It provides a unified workspace to build with agents across repos and environments, including local, cloud, remote SSH, and more. It combines the power of parallel agents with the depth and control of a development environment. You can switch back to the editor anytime, or have both open simultaneously. Open the Agents Window If you're in the editor, type Cmd+Shift+P → Open Agents Window Ctrl+Shift+P Arrow Right Open Agents Window to open the Agents Window. Switch Back to the Editor To return to the classic Cursor editor, type Cmd+Shift+P → Open Editor Window Ctrl+Shift+P Arrow Right Open Editor Window . This opens the current workspace in the editor. If you want to view or edit files without leaving the Agents Window, you can type Cmd+P Ctrl+P to search files, or Cmd+Shift+F Ctrl+Shift+F to search all files. Features Available Only in the Agents Window The following features are available in the Agents Window: Multi-workspace: work with agents across all your projects from one place. New diffs view: review and commit changes, and manage PRs without leaving Cursor. Parallel agents: run many parallel agents in the cloud (and work with them from your phone, web, Slack, GitHub, and Linear). Easier handoff between local and cloud: quickly move an agent from cloud to local to iterate quickly, and move it back to the cloud so it keeps working on its own. Worktrees: run agents in isolated Git checkouts so each task has its own files and changes. Choosing Between Agents Window and Editor The Agents Window works well when you want to run and manage many agents in parallel. If you are using agents to write most of your code, the Agents Window helps pull you up to a higher level of abstraction. The editor works well when you want the classic IDE with VS Code extensions and flexible screen splitting to see many files at once. You can move between the two interfaces, and we will continue to support and improve both experiences. Enterprise access Agents Window is generally available with Cursor 3, released on April 2, 2026. For the two weeks following launch, Enterprise Admins can control rollout within their organizations by giving access to their entire team or to specific users via Team settings. After the rollout period, all users will have access by default. English English 简体中文 日本語 繁體中文 Español Français Português 한국어 Русский Türkçe Bahasa Indonesia Deutsch हिन्दी

Models Gemini 3.1 Pro Model ID gemini-3.1-pro Context window 200k Max context 1M Provider Google Capabilities Agent Thinking Speed Medium Cost Medium Intelligence Frontier Gemini 3.1 Pro is Google's latest model. It processes images alongside code, making it strong for UI/UX work from design mockups. The context window stretches to 1M tokens in Max Mode for whole-codebase analysis. Strengths Processes images alongside code. Strong for UI/UX coding from design mockups, frontend development, and visual code understanding. Up to 1M tokens in Max Mode for whole-codebase analysis. Strong capabilities at $2/1M input tokens. Tools Gemini 3.1 Pro has access to all agent tools when used with Cursor including: Semantic search Search your indexed codebase by meaning, not exact matches. Search files and folders Find files by name, read directory structures, and grep for patterns. Web Generate search queries and fetch results from the web. Read files Read file contents, including images for vision-capable models. Edit files Suggest edits and apply them automatically. Run shell commands Execute terminal commands and monitor output. Browser Control a browser to take screenshots, test applications, and verify visual changes. See the Browser documentation . Image generation Generate images from text descriptions or reference images. Ask questions Ask clarifying questions while continuing to work in the background. Fetch rules Retrieve rules based on type and description. Learn more about how tools work and tool calling fundamentals . Pricing Cursor plans include two usage pools. Gemini 3.1 Pro draws from the API pool, which charges at the rates below. Individual plans include at least $20 of API usage each month (more on higher tiers). All prices are per million tokens. Name Input Cache Write Cache Read Output Gemini 3.1 Pro $2 - $0.2 $12 When input exceeds 200k tokens (long context), input and output pricing increases. See the pricing table above for the long context rates. English English 简体中文 日本語 繁體中文 Español Français Português 한국어 Русский Türkçe Bahasa Indonesia Deutsch हिन्दी

API Copy page Share feedback Explain more Cursor APIs Overview Cursor provides multiple APIs for programmatic access to your team's data, AI-powered coding agents, and analytics. Available APIs API Description Availability Admin API Manage team members, settings, usage data, and spending. Build custom dashboards and monitoring tools. Enterprise teams Analytics API Comprehensive insights into team's Cursor usage, AI metrics, active users, and model usage. Enterprise teams AI Code Tracking API Track AI-generated code contributions at commit and change levels for attribution and analytics. Enterprise teams Cloud Agents API Programmatically create and manage AI-powered coding agents for automated workflows and code generation. Beta (All Plans) TypeScript SDK Run Cursor agents from TypeScript with one interface for local and cloud runtimes. Beta Authentication All Cursor APIs use Basic Authentication. Basic Authentication Use your API key as the username in basic authentication (leave password empty): curl https://api.cursor.com/teams/members \ -u YOUR_API_KEY: Or set the Authorization header directly: Authorization: Basic {base64_encode ( 'YOUR_API_KEY:' ) } Creating API Keys API keys are created from your team settings. Only team administrators can create and manage API keys. Admin API & AI Code Tracking API Navigate to cursor.com/dashboard → Settings tab → Advanced → Admin API Keys Click Create New API Key Give your key a descriptive name (e.g., "Usage Dashboard Integration") Copy the generated key immediately - you won't see it again Key format: crsr_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx Required scope: admin:* Analytics API Generate an API key from your team settings page . Required scope: admin:* (read-only scoped keys will not work) Cloud Agents API Create a user API key from Cursor Dashboard → Integrations , or use a service account API key from team settings. API keys are tied to your organization and viewable by all admins. Keys are unaffected by the original creator's account status. Rate Limits All APIs implement rate limiting to ensure fair usage and system stability. Rate limits are enforced per team and reset every minute. Rate Limits by API API Endpoint Type Rate Limit Admin API Most endpoints 20 requests/minute Admin API /teams/user-spend-limit 250 requests/minute Analytics API Most team-level endpoints 100 requests/minute Analytics API /analytics/team/conversation-insights 20 requests/minute Analytics API By-user endpoints 50 requests/minute AI Code Tracking API All endpoints 20 requests/minute per endpoint Cloud Agents API All endpoints Standard rate limiting Rate Limit Response When you exceed the rate limit, you'll receive a 429 Too Many Requests response: { "error" : "Too Many Requests" , "message" : "Rate limit exceeded. Please try again later." } Caching Several APIs support HTTP caching with ETags to reduce bandwidth usage and improve performance. Supported APIs Analytics API : All endpoints (both team-level and by-user) support HTTP caching AI Code Tracking API : Endpoints support HTTP caching How Caching Works Initial Request : Make a request to any supported endpoint Response Includes ETag : The API returns an ETag header in the response Subsequent Requests : Include the ETag value in an If-None-Match header 304 Not Modified : If data hasn't changed, you'll receive a 304 Not Modified response with no body Example # Initial request curl -X GET "https://api.cursor.com/analytics/team/dau" \ -H "Authorization: Bearer YOUR_API_KEY" \ -D headers.txt # Response includes: ETag: "abc123xyz" # Subsequent request with ETag curl -X GET "https://api.cursor.com/analytics/team/dau" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "If-None-Match: \" abc123xyz \" " # Returns 304 Not Modified if data hasn't changed Cache Duration Cache duration: 15 minutes ( Cache-Control: public, max-age=900 ) Responses include an ETag header Include If-None-Match header in subsequent requests to receive 304 Not Modified when data hasn't changed Benefits Reduces bandwidth usage : 304 responses contain no body Faster responses : Avoids processing unchanged data Rate limit friendly : 304 responses don't count against rate limits Better performance : Especially useful for frequently polled endpoints Best Practices 1. Implement Exponential Backoff When you receive a 429 response, wait before retrying with increasing delays: import time import requests def make_request_with_backoff (url, headers, max_retries = 5 ): for attempt in range (max_retries): response = requests.get(url, headers = headers) if response.status_code == 429 : # Exponential backoff: 1s, 2s, 4s, 8s, 16s wait_time = 2 ** attempt print ( f "Rate limited. Waiting { wait_time } s before retry..." ) time.sleep(wait_time) continue return response raise Exception ( "Max retries exceeded" ) 2. Distribute Requests Over Time Spread your API calls over time rather than making burst requests: Schedule batch jobs to run at different intervals Add delays between requests when processing large datasets Use queuing systems to smooth out traffic spikes 3. Leverage Caching For Analytics API and AI Code Tracking API: These APIs support HTTP caching with ETags. See the Caching section above for details on how to use ETags to reduce bandwidth usage and avoid unnecessary requests. Key benefits: Reduces bandwidth usage Faster responses when data hasn't changed Doesn't count against rate limits (for 304 responses) Use date shortcuts ( 7d , 30d ) instead of timestamps for better caching support in Analytics API. 4. Monitor Your Usage Track your request patterns to stay within limits: Log API call timestamps and response codes Set up alerts for 429 responses Monitor daily/weekly usage trends Adjust polling intervals based on actual needs 5. Batch Wisely For endpoints with pagination: Use appropriate page sizes to get more data per request For Analytics API by-user endpoints: Use users parameter to filter specific users For large data extractions: Use CSV endpoints when available (they stream data efficiently) 6. Poll at Appropriate Intervals Don't over-poll endpoints that update infrequently: Admin API /teams/daily-usage-data : Poll at most once per hour (data aggregated hourly) Admin API /teams/filtered-usage-events : Poll at most once per hour (data aggregated hourly) Analytics API : Use date shortcuts ( 7d , 30d ) for better caching support AI Code Tracking API : Data is ingested in near real-time but polling every few minutes is sufficient 7. Handle Errors Gracefully Implement proper error handling for all API calls: async function fetchAnalytics ( endpoint ) { try { const response = await fetch ( `https://api.cursor.com${ endpoint }` , { headers: { 'Authorization' : `Basic ${ btoa ( API_KEY + ':' ) }` } }); if (response.status === 429 ) { // Rate limited - implement backoff throw new Error ( 'Rate limit exceeded' ); } if (response.status === 401 ) { // Invalid API key throw new Error ( 'Authentication failed' ); } if (response.status === 403 ) { // Insufficient permissions throw new Error ( 'Enterprise access required' ); } if ( ! response.ok) { throw new Error ( `API error: ${ response . status }` ); } return await response. json (); } catch (error) { console. error ( 'API request failed:' , error); throw error; } } Common Error Responses All APIs use standard HTTP status codes: 400 Bad Request Request parameters are invalid or missing required fields. { "error" : "Bad Request" , "message" : "Some users are not in the team" } 401 Unauthorized Invalid or missing API key. { "error" : "Unauthorized" , "message" : "Invalid API key" } 403 Forbidden Valid API key but insufficient permissions (e.g., Enterprise features on non-Enterprise plan). { "error" : "Forbidden" , "message" : "Enterprise access required" } 404 Not Found Requested resource doesn't exist. { "error" : "Not Found" , "message" : "Resource not found" } 429 Too Many Requests Rate limit exceeded. Implement exponential backoff. { "error" : "Too Many Requests" , "message" : "Rate limit exceeded. Please try again later." } 500 Internal Server Error Server-side error. Contact support if persistent. { "error" : "Internal Server Error" , "message" : "An unexpected error occurred" } English English 简体中文 日本語 繁體中文 Español Français Português 한국어 Русский Türkçe Bahasa Indonesia Deutsch हिन्दी

Agent Cursor Agent Agent is Cursor's assistant that can complete complex coding tasks independently, run terminal commands, and edit code. Access in sidepane with Cmd+I Ctrl+I . Learn more about how agents work and help you build faster. How Agent works An agent is built on three components: Instructions : The system prompt and rules that guide agent behavior Tools : File editing, codebase search, terminal execution, and more Model : The agent model you pick for the task Cursor's agent orchestrates these components for each model we support, tuning instructions and tools specifically for every frontier model. As new models are released, you can focus on building software while Cursor handles the model-specific optimizations. Tools Tools are the building blocks of Agent. They are used to search your codebase and the web to find relevant information, make edits to your files, run terminal commands, and more. To understand how tool calling works under the hood, see our tool calling fundamentals . There is no limit on the number of tool calls Agent can make during a task. Semantic search Perform semantic searches within your indexed codebase . Finds code by meaning, not just exact matches. Search files and folders Search for files by name, read directory structures, and find exact keywords or patterns within files. Web Generate search queries and perform web searches. Fetch Rules Retrieve specific rules based on type and description. Read files Intelligently read the content of a file. Also supports image files (.png, .jpg, .gif, .webp, .svg) and includes them in the conversation context for analysis by vision-capable models. Edit files Suggest edits to files and apply them automatically. Run shell commands Execute terminal commands and monitor output. By default, Cursor uses the first terminal profile available. To set your preferred terminal profile: Open Command Palette ( Cmd/Ctrl+Shift+P ) Search for "Terminal: Select Default Profile" Choose your desired profile Browser Control a browser to take screenshots, test applications, and verify visual changes. Agent can navigate pages, interact with elements, and capture the current state for analysis. See the Browser documentation for details. Image generation Generate images from text descriptions or reference images. Useful for creating UI mockups, product assets, and visualizing architecture diagrams. Images are saved to your project's assets/ folder by default and shown inline in chat. message-circle-question Ask questions Ask clarifying questions during a task. While waiting for your response, the agent continues reading files, making edits, or running commands. Your answer is incorporated as soon as it arrives. Checkpoints Checkpoints save snapshots of your codebase during an Agent session. Agent automatically creates them before making significant changes, capturing the state of all modified files. If Agent takes a wrong turn, click any checkpoint in the chat timeline to preview your files at that point, then restore to revert all files to that state. You can also restore from the Restore Checkpoint button on previous requests or the + button when hovering over a message. Checkpoints are useful for exploratory work, complex refactoring, and iterative development where you want safe rollback points. Checkpoints are stored locally and separate from Git. Only use them for undoing Agent changes; use Git for permanent version control. Queued messages Queue follow-up messages while Agent is working on the current task. Your instructions wait in line and execute automatically when ready. Using the queue While Agent is working, type your next instruction Press Enter to add it to the queue Messages appear in order below the active task Drag to reorder queued messages as needed Agent processes them sequentially after finishing Keyboard shortcuts While Agent is working: Press Enter to queue your message (it waits until Agent finishes the current task) Press Cmd+Enter Ctrl+Enter to send immediately, bypassing the queue Immediate messaging When you use Cmd+Enter Ctrl+Enter to send immediately, your message is appended to the most recent user message in the chat and processed right away without waiting in the queue. Your message attaches to tool results and sends immediately This creates a more responsive experience for urgent follow-ups Use this when you need to interrupt or redirect Agent's current work English English 简体中文 日本語 繁體中文 Español Français Português 한국어 Русский Türkçe Bahasa Indonesia Deutsch हिन्दी

Models Composer 2 Model ID composer-2 Context window 200k Max context - Provider Cursor Capabilities Agent Thinking Speed Fast Cost Low Intelligence Frontier Composer 2 is Cursor's own agentic model. It reaches frontier-level coding performance with strong results on CursorBench while using tokens efficiently. Strengths Strong on long-horizon tasks via self-summarization during training. Default fast variant for interactive sessions; standard tier further optimized for cost per token. Tuned for tool use, file edits, and terminal operations inside Cursor. Tools Composer 2 has access to all agent tools when used with Cursor including: Semantic search Search your indexed codebase by meaning, not exact matches. Search files and folders Find files by name, read directory structures, and grep for patterns. Web Generate search queries and fetch results from the web. Read files Read file contents, including images for vision-capable models. Edit files Suggest edits and apply them automatically. Run shell commands Execute terminal commands and monitor output. Browser Control a browser to take screenshots, test applications, and verify visual changes. See the Browser documentation . Image generation Generate images from text descriptions or reference images. Ask questions Ask clarifying questions while continuing to work in the background. Fetch rules Retrieve rules based on type and description. Learn more about how tools work and tool calling fundamentals . Pricing A faster variant with the same intelligence is also available at $1.50/M input and $7.50/M output tokens. Fast is the default in the product and is priced lower than other fast models at similar speeds. On individual plans, Composer draws from a standalone Composer usage pool with generous included usage. On team and enterprise plans, the API price below is charged directly. All prices are per million tokens. Name Input Cache Write Cache Read Output Composer 2 $0.5 - $0.2 $2.5 Composer 2 (Fast) $1.5 - $0.35 $7.5 English English 简体中文 日本語 繁體中文 Español Français Português 한국어 Русский Türkçe Bahasa Indonesia Deutsch हिन्दी

Agent Agent Review Agent Review runs a dedicated code review on your local changes from inside Cursor. Setup To configure Agent Review: Open Cursor Settings Go to Agents Find Agent Review and configure your preferences Agent Review also reads repository rules from BUGBOT.md files. To set up these rule files, see BugBot docs . You can set it to run automatically after every agent task, or leave it manual and trigger it yourself. Running a review There are three ways to start a review: Automatic : When enabled in settings, Agent Review runs after every commit is made. Slash command : Type /agent-review in the agent window input to trigger a review on demand. Source Control tab : Open the Source Control tab and run Agent Review to compare all local changes against your main branch. This catches issues across your full set of changes, not only the latest edit. Review depth Agent Review supports two depth levels. Choose based on the thoroughness of review you need. Depth Speed Cost Best for Quick Fast Low Small diffs, formatting changes, or a fast sanity check Deep Slow High Complex logic, security-sensitive code, or large refactors English English 简体中文 日本語 繁體中文 Español Français Português 한국어 Русский Türkçe Bahasa Indonesia Deutsch हिन्दी

CLI Shell Mode Shell Mode runs shell commands directly from the CLI without leaving your conversation. Use it for quick, non-interactive commands with safety checks and output displayed in the conversation. Command execution Commands run in your login shell ( $SHELL ) with the CLI's working directory and environment. Chain commands to run in other directories: cd subdir && npm test Output Large outputs are truncated automatically and long-running processes timeout to maintain performance. Limitations Commands timeout after 30 seconds Long-running processes, servers, and interactive prompts are not supported Use short, non-interactive commands for best results Permissions Commands are checked against your permissions and team settings before execution. See Permissions for detailed configuration. Admin policies may block certain commands, and commands with redirection cannot be allowlisted inline. Usage guidelines Shell Mode works well for status checks, quick builds, file operations, and environment inspection. Avoid long-running servers, interactive applications, and commands requiring input. Each command runs independently - use cd && ... to run commands in other directories. Troubleshooting If a command hangs, cancel with Ctrl+C and add non-interactive flags When prompted for permissions, approve once or add to allowlist with Tab For truncated output, use Ctrl+O to expand To run in different directories, use cd && ... since changes don't persist Shell Mode supports zsh and bash from your $SHELL variable FAQ Does `cd` persist across runs? No. Each command runs independently. Use cd && ... to run commands in different directories. Can I change the timeout? No. Commands are limited to 30 seconds and this is not configurable. Where are permissions configured? Permissions are managed by CLI and team configuration. Use the decision banner to add commands to allowlists. How do I exit Shell Mode? Press Escape Esc when the input is empty, Backspace / Delete on empty input, or Ctrl+C to clear and exit. English English 简体中文 日本語 繁體中文 Español Français Português 한국어 Русский Türkçe Bahasa Indonesia Deutsch हिन्दी

Agent Debug Mode Debug Mode helps you find root causes and fix tricky bugs that are hard to reproduce or understand. Instead of immediately writing code, the agent generates hypotheses, adds log statements, and uses runtime information to pinpoint the exact issue before making a targeted fix. When to use Debug Mode Debug Mode works best for: Bugs you can reproduce but can't figure out : When you know something is wrong but the cause isn't obvious from reading the code Race conditions and timing issues : Problems that depend on execution order or async behavior Performance problems and memory leaks : Issues that require runtime profiling to understand Regressions where something used to work : When you need to trace what changed When standard Agent interactions struggle with a bug, Debug Mode provides a different approach using runtime evidence rather than guessing at fixes. How it works Explore and hypothesize : The agent explores relevant files, builds context, and generates multiple hypotheses about potential root causes. Add instrumentation : The agent adds log statements that send data to a local debug server running in a Cursor extension. Reproduce the bug : Debug Mode asks you to reproduce the bug and provides specific steps. This keeps you in the loop and ensures the agent captures real runtime behavior. Analyze logs : After reproduction, the agent reviews the collected logs to identify the actual root cause based on runtime evidence. Make targeted fix : The agent makes a focused fix that directly addresses the root cause, often just a few lines of code. Verify and clean up : You can re-run the reproduction steps to verify the fix. Once confirmed, the agent removes all instrumentation. Tips for Debug Mode Provide detailed context : The more you describe the bug and how to reproduce it, the better the agent's instrumentation will be. Include error messages, stack traces, and specific steps. Follow reproduction steps exactly : Execute the steps the agent provides to ensure logs capture the actual issue. Reproduce multiple times if needed : Reproducing the bug multiple times may help the agent identify tricky problems like race conditions. Be specific about expected vs. actual behavior : Help the agent understand what should happen versus what is happening. Switching modes Use the mode picker dropdown in Agent Press Shift+Tab for quick switching English English 简体中文 日本語 繁體中文 Español Français Português 한국어 Русский Türkçe Bahasa Indonesia Deutsch हिन्दी

Cloud Agents Capabilities Computer use Each cloud agent runs in its own isolated VM with a full desktop environment. Agents can use a mouse and keyboard to control the desktop and browser, allowing them to interact with the software they build like a human developer. This means agents can start dev servers, open the app in a browser, click through UI flows, and verify their changes work before pushing a PR. Read more in the announcement blog post . Demos and Artifacts Agents create artifacts such as screenshots, videos, and log references to demonstrate their work. These artifacts are attached to the PR so you can quickly validate changes without checking out the branch locally. Artifacts in GitHub You can opt-in to have Cloud Agents embed artifacts directly into GitHub pull request descriptions by enabling the Allow posting artifacts to GitHub setting in the Cloud Agents dashboard . GitHub's image proxy requires public URLs, so artifacts in PR descriptions use long, unguessable URLs that are viewable without authentication. For context, GitHub used public URLs for all issue and PR attachments until May 2023 . Remote desktop control You can take control of the agent's remote desktop to interact with the software the agent is building. Hand control back to the agent at any time to let it keep working. Cloud agents run in a remote VM that can be fully onboarded with your repo, dependencies, tooling, and setup scripts. This allows you to test changes directly in the agent's VM without checking out the branch on your local machine. MCP tools Cloud agents can use MCP (Model Context Protocol) servers configured for your team. This gives agents access to external tools and data sources like databases, APIs, and third-party services during their runs. Add and enable MCP servers through the MCP dropdown in cursor.com/agents . Cloud agents support OAuth for MCP servers that need it. OAuth is per-user, including for MCP servers shared at the team level. Custom MCP servers You can add custom MCP servers using either HTTP or stdio transport. SSE and mcp-remote are not supported. MCP configurations are encrypted at rest. Sensitive fields are redacted and cannot be read back by any user after saving: env — environment variables for stdio servers headers — request headers for HTTP servers CLIENT_SECRET — OAuth client secret for HTTP servers HTTP vs stdio HTTP (recommended) — server configurations are never present in the cloud agent's VM environment. The agent does not have access to refresh tokens, headers, or other credentials. Tool calls are proxied through the backend. Stdio — servers run inside the cloud agent's VM, so the agent has access to the server's configuration and environment variables. This is similar to how stdio MCPs work in the Cursor IDE. Stdio servers depend on the VM environment to execute. We cannot verify that a stdio server will run successfully until a cloud agent is launched. We recommend using HTTP MCPs when possible, and configuring your environment setup correctly if you use stdio servers. Fixing CI Failures Cloud Agents automatically try to fix CI failures in PRs they create. This currently supports GitHub Actions only. Cloud Agents skip automatic CI follow-ups if: You've pushed a new commit to the branch; cloud agents do not auto-fix CI failures on human commits. You've sent a follow-up message to the agent. The same check is already failing on the base commit of the PR. The PR has already had 10 CI-failure follow-ups. To disable this feature on all your personal Cloud Agents, go to Cursor Dashboard → Cloud Agents → My Settings and disable the "Automatically fix CI Failures" option. To disable this feature on a specific Cloud Agent PR, you can comment @cursor autofix off on the PR. To re-enable it, comment @cursor autofix on . If you want cloud agents to fix CI failures in your own PRs, you can simply ask them by tagging Cursor in a comment as normal. For example, @cursor please fix the CI failures , or @cursor fix the CI lint check failure . Automatically fixing CI failures is currently only available on Teams; support for non-Teams accounts is coming soon. In the meantime, if you want similar behavior, you can ask the cloud agent explicitly to monitor and fix CI failures on the PR. English English 简体中文 日本語 繁體中文 Español Français Português 한국어 Русский Türkçe Bahasa Indonesia Deutsch हिन्दी

Cloud Agents Self-Hosted Pool Self-Hosted Pool is for Enterprise teams that want Cloud Agents to run inside company-managed infrastructure. Instead of each developer starting a worker on a personal machine, admins operate a pool of workers that can be assigned to agents across the organization. Use a pool when you need: Centrally managed workers for a team or organization Service account authentication instead of individual browser logins Kubernetes, autoscaling, or fleet management Labels that route work to the right environment, team, repo, or hardware profile Enterprise controls around network access, secrets, build outputs, and monitoring For a fast personal setup, see My Machines . How it works A worker opens a long-lived outbound HTTPS connection to Cursor's cloud. The agent loop (inference and planning) runs in Cursor's cloud and sends tool calls over this connection. The worker executes those tool calls locally in your infrastructure: terminal commands, file edits, browser actions, and access to internal services. Your repos, build caches, secrets, and tool execution stay in your environment while Cursor handles orchestration, model access, and the Cloud Agent experience. Cloud Agent artifacts , like screenshots and videos, are uploaded to Cursor so you can view them in PRs and the dashboard. Workers only need outbound access. No inbound ports, public IPs, or VPN tunnels are required. See Networking for the full list of required hosts. Self-Hosted Cloud Agents support up to 10 workers per user and 50 per team. For larger company-wide deployments, contact us to discuss scaling. Prerequisites A Cursor Enterprise plan Self-hosted settings configured by a team admin in the Cloud Agents dashboard : Allow Self-Hosted Agents lets users opt in to self-hosted runs. Require Self-Hosted Agents routes every Cloud Agent run to self-hosted workers. A service account API key for pool worker authentication A worker machine or image with: agent CLI installed git installed and available on PATH A cloned repository with a configured remote Access to the build tools, package registries, secrets, and internal services your agents need Install the CLI # macOS, Linux, and WSL curl https://cursor.com/install -fsS | bash # Windows PowerShell irm 'https://cursor.com/install?win32=true' | iex Confirm the CLI is available: agent --version Authenticate workers Pool workers must authenticate with a service account API key . User, personal, team, and organization API keys can't start pool workers. Use personal or user API keys with personal workers on My Machines . export CURSOR_API_KEY = "your-service-account-api-key" You can also pass the key directly: agent worker start --api-key "your-service-account-api-key" Start a pool worker Run the worker from the git repo it should serve: cd /path/to/repo agent worker start --pool --pool registers the worker for pool assignment. Each Cloud Agent session claims one worker at a time. For orchestrated environments, combine it with --idle-release-timeout so the process exits cleanly after work completes: agent worker start --pool --idle-release-timeout 600 --idle-release-timeout keeps the worker alive for a window (in seconds) after a session ends to handle follow-up messages. If a follow-up arrives, the timer resets. Once the timeout fires, the CLI exits with code 0. Pool names Group pool workers under a name when you want sessions to route to a specific subset, like GPU machines, a staging fleet, or a team's dedicated build boxes. The --pool-name flag tags the worker with a pool= label the backend uses for routing: agent worker start --pool --pool-name gpu When --pool-name is omitted, the worker joins the default pool. Workers from CLI versions that predate the flag also match the default pool, so you can roll out pool names gradually without disrupting existing fleets. Set the pool name from the environment when an orchestrator injects config: export CURSOR_WORKER_POOL_NAME = gpu agent worker start --pool --pool-name requires --pool (or the legacy --single-use alias). Multi-use workers don't belong to a pool. From the Cloud Agents dashboard , pick a pool in the worker selector when starting a session or editing an automation. You can also include pool= in a Slack, GitHub, or Linear trigger. Sessions route only to workers registered with that pool name. Triggering pool agents Use pool triggers when you want a Cloud Agent to run on your team's shared worker fleet. Pool workers are the right target for centrally managed capacity, autoscaling, CI-like runners, and repo-scoped infrastructure. Team admins control self-hosted routing from the Self-Hosted section of the Cloud Agents dashboard . Allow Self-Hosted Agents lets users opt in per request. Without opt-in, runs use Cursor's managed infrastructure. Require Self-Hosted Agents routes Cloud Agent runs to self-hosted workers. When Cursor starts a pool agent, it matches workers with labels. Every pool request includes a repo= label. Requests for a named pool also include pool= . Pool workers handle: Runs covered by Require Self-Hosted Agents , unless the request targets a specific My Machines worker with worker= or machine= Requests with self_hosted=true , self_hosted , or selfhosted Requests with pool= , which also selects that named pool Self-hosted requests with repository selection from the trigger surface, such as repo= where supported repo= selects the repository for the run. For self-hosted pool runs, that repository becomes the repo= worker label. It does not target a personal machine. Use these options from integrations to start pool agents: Slack : Mention @Cursor with self_hosted=true , standalone self_hosted , selfhosted , or pool= . Legacy aliases like private_worker=true , useprivateworker , and useprivateworkers=false still work. GitHub : Comment @cursoragent self_hosted=true ... or @cursoragent pool= ... on an issue, pull request, or review comment. The legacy private_worker=true alias still works. Linear : Add pool= or [pool=] to the issue body. You can also use issue or project labels where the parent label is pool and the child label is the value. Linear does not parse standalone self_hosted=true . Policy handling depends on where the request starts: Slack rejects self-hosted opt-in when Allow Self-Hosted Agents is off and replies in Slack. If Require Self-Hosted Agents is on, every Slack mention runs self-hosted. GitHub lets repo OWNER and COLLABORATOR users route runs to self-hosted workers. Other commenters run on managed infrastructure when they opt in, or are skipped if Require Self-Hosted Agents is on. This protects public repos where outside contributors can leave comments. Linear rejects explicit self-hosted requests when Allow Self-Hosted Agents is off. The issue gets an agent activity error that asks an admin to turn on self-hosted workers or remove the hint to run on Cursor's managed infrastructure. To target one of your own machines by name, use My Machines with worker= or machine= . The Cloud Agent API uses the same resolver with usePrivateWorker and labels fields. See the Cloud Agent API docs for endpoint details. Hooks Self-hosted workers run project hooks committed in your repository through .cursor/hooks.json . If you're on Enterprise, self-hosted workers also support team hooks and enterprise-managed hooks. See Hooks for configuration details. Labels Labels are key-value pairs that describe a worker. They control how Cloud Agent sessions route to the right pool. CLI flags JSON file TOML file Environment variable Good for quick testing or small pools: agent worker start --pool \ --label team=backend \ --label env=production The repo and pool labels are reserved. repo comes from the worker directory's git remote. pool is set by --pool-name . Don't set either manually. MCP servers MCP servers on self-hosted workers are routed by transport type: Transport Runs on Use case Command (stdio) Worker The MCP process starts on the worker and can reach private networks, internal APIs, and services behind your firewall. HTTP / SSE (url) Cursor backend Cursor handles OAuth, session caching, and auth for HTTP-based MCP servers. If your MCP server needs to access private-network endpoints, use the command (stdio) transport. The process runs directly on the worker and shares its network. For HTTP-based MCP servers, Cursor manages the connection from its backend, handling OAuth and session caching. Artifacts Artifact behavior is identical on self-hosted workers and Cursor-hosted agents. The agent produces the artifact inside the worker and the worker uploads it to Cursor-managed storage over HTTPS. Everything downstream (PR embeds, dashboard previews, notification attachments) is handled by Cursor's backend and doesn't depend on where the worker runs. Artifacts are on by default. See Capabilities for what they look like in the UI. To disable artifact uploads, block outbound traffic to cloud-agent-artifacts.s3.us-east-1.amazonaws.com . The agent session keeps working; artifacts produced during the session fail to upload. Networking Workers need outbound HTTPS access to: api2.cursor.sh and api2direct.cursor.sh for the agent session cloud-agent-artifacts.s3.us-east-1.amazonaws.com for artifact uploads If your firewall can only match wildcards, *.s3.us-east-1.amazonaws.com covers the artifact host, but also opens every other bucket in the region. Prefer an exact-host rule when the firewall supports it. No inbound ports, public IPs, or VPN tunnels are required. If you use a proxy, set HTTPS_PROXY or https_proxy in the worker environment. Failure modes If you block... Effect api2.cursor.sh or api2direct.cursor.sh The worker can't start or continue an agent session. cloud-agent-artifacts.s3.us-east-1.amazonaws.com Artifact uploads fail. PR embeds, dashboard previews, and notification attachments that depend on artifacts are missing. The agent session and other tool calls keep working. An outbound host a specific tool or integration needs Only that tool or integration fails. The agent continues. The Prerequisites section covers the broader set of hosts a worker needs during agent runs (git hosts, package registries, internal APIs). Kubernetes We provide a Helm chart and Kubernetes operator for managing worker pools at scale. See the Kubernetes deployment guide for setup instructions. Fleet management API For non-Kubernetes environments, use the fleet management API to monitor utilization and build autoscaling. Authenticate with the pool's service account API key via Basic auth or Bearer token. Other API key types can't manage pool worker fleet capacity. List workers curl --request GET \ --url "https://api.cursor.com/v0/private-workers?status=idle&limit=50" \ -u " $CURSOR_API_KEY :" | Parameter | Type | Default | Description | |---|---|---| | status | all | in_use | idle | all | Filter by worker status | | limit | integer (1-100) | 50 | Results per page | | nextPageToken | string | | Pagination cursor | Get summary curl --request GET \ --url "https://api.cursor.com/v0/private-workers/summary" \ -u " $CURSOR_API_KEY :" Returns connected and in-use counts for your user and team. Use this to trigger scaling when utilization is high: const summary = await response. json (); const team = summary.teamSummary; if (team && team.totalConnected > 0 ) { const utilization = team.inUse / team.totalConnected; if (utilization >= 0.9 ) { // Scale up: provision additional workers } } Get worker by ID curl --request GET \ --url "https://api.cursor.com/v0/private-workers/pw_123" \ -u " $CURSOR_API_KEY :" Monitoring The management server exposes GET /metrics , GET /healthz , and GET /readyz when you start a worker with --management-addr : agent worker start --pool --management-addr ":8080" Scrape metrics from your worker: curl http://localhost:8080/metrics Available metrics Gauges Metric Type Description cursor_self_hosted_worker_connected Gauge 1 when the outbound connection to Cursor's cloud is active, 0 otherwise. cursor_self_hosted_worker_session_active Gauge 1 when a cloud agent session is running on this worker, 0 when idle. cursor_self_hosted_worker_last_activity_unix_seconds Gauge Unix timestamp of the last frame or heartbeat from Cursor's cloud. 0 if no activity yet. Counters Metric Type Description cursor_self_hosted_worker_connect_attempts_total Counter Outbound connection attempts to Cursor's cloud. cursor_self_hosted_worker_connect_retry_total Counter Connection retries after a failed attempt. cursor_self_hosted_worker_session_ends_total Counter Agent sessions ended on this worker, labeled by reason . Session end reasons The cursor_self_hosted_worker_session_ends_total counter includes a reason label with one of these values: Reason Description stream_end Connection closed normally. stream_error Connection failed with an error. session_closed HTTP/2 session closed cleanly. session_error HTTP/2 session entered an error state. connection_timeout Initial connection timed out before streaming started. session_aborted Session was aborted, for example because the worker was stopped. Security Forward Return Inference (LLM) loop AGENT LOOP · CURSOR CLOUD TOOL EXECUTION · YOUR NETWORK Outbound-only · no inbound from Cursor Inference (LLM) model inference agent-cli agent worker start Cursor UI web / IDE Agent Loop orchestration state management Bridge frame routing Worker worker runtime Tools Terminal Filesystem Browser start run tool call stream to UI results outbound HTTP/2 prompt tool calls starts worker exec tool calls results Data flow. Two things leave your network: file chunks the model reads during inference, and Cloud Agent artifacts (screenshots, videos, and log references) the worker uploads to Cursor-managed storage so they can appear in PRs and the dashboard. Your repos, build caches, and secrets stay on your machines. Outbound-only. Workers connect outbound over HTTPS. No inbound ports or firewall changes required. Privacy mode. Self-hosted Cloud Agents respect Cursor's privacy mode , which enables zero data retention across all model providers. None of your code is stored or used for training. Isolation. Each agent session gets its own dedicated worker. Sessions are not shared across workers. Authentication. Pool workers authenticate with a service account API key . Other API key types are rejected. Dashboard visibility. Team admins can see all connected workers. Team members see only workers assigned to them. CLI reference agent worker start [options] Flag Env var Description --worker-dir Working directory. Must be a git repo. Default: current directory. --management-addr Address for /healthz , /readyz , and /metrics endpoints, for example :8080 . --label Add a label. Repeatable. Mutually exclusive with --labels-file . --labels-file CURSOR_WORKER_LABELS_FILE Path to JSON or TOML labels file. Mutually exclusive with --label . --idle-release-timeout CURSOR_WORKER_IDLE_RELEASE_TIMEOUT Seconds to stay connected after a session ends. Default: no timeout. --pool Register for pool assignment. Each session claims one worker at a time. --single-use Legacy alias for --pool . --pool-name CURSOR_WORKER_POOL_NAME Pool label for pool-managed workers. Requires --pool . Default: default . --api-key CURSOR_API_KEY Service account API key for pool workers. --auth-token Pre-minted access token. Used by the Kubernetes operator and other automation that exchanges an API key for a short-lived token externally. --auth-token-file File containing an access token. The CLI re-reads this file when reconnecting after an auth failure or disconnect, which lets a controller rotate the mounted token without restarting the pod. -e, --endpoint API endpoint. Default: https://api2.cursor.sh . FAQ How should I size workers? There is no fixed worker spec. Size each worker the same way you size a CI runner or devbox for the repo it serves. Each worker needs enough CPU, memory, disk, and network access to clone the repo and run the builds, tests, and tools your agents need. Can I bake skills into the worker image? Yes. Project-level skills in .cursor/skills/ or .agents/skills/ are automatically available on self-hosted workers. To share skills across a team, check them into the repo or bake them into your custom worker image. Do MCP servers work on self-hosted workers? Yes. Configure MCP servers through the Cloud Agents dashboard. See the MCP servers section for how routing works by transport type. Related My Machines Kubernetes deployment guide Cloud Agent security and network Service accounts English English 简体中文 日本語 繁體中文 Español Français Português 한국어 Русский Türkçe Bahasa Indonesia Deutsch हिन्दी

Customizing Agent Skills Agent Skills is an open standard for extending AI agents with specialized capabilities. Skills package domain-specific knowledge and workflows that agents can use to perform specific tasks. What are skills? A skill is a portable, version-controlled package that teaches agents how to perform domain-specific tasks. Skills can include scripts, templates, and references that agents may act on using their tools. Portable Skills work across any agent that supports the Agent Skills standard. Version-controlled Skills are stored as files and can be tracked in your repository, or installed via GitHub repository links. Actionable Skills can include scripts, templates, and references that agents act on using their tools. Progressive Skills load resources on demand, keeping context usage efficient. How skills work When Cursor starts, it automatically discovers skills from skill directories and makes them available to Agent. The agent is presented with available skills and decides when they are relevant based on context. Skills can also be manually invoked by typing / in Agent chat and searching for the skill name. Skill directories Skills are automatically loaded from these locations: Location Scope .agents/skills/ Project-level .cursor/skills/ Project-level ~/.agents/skills/ User-level (global) ~/.cursor/skills/ User-level (global) For compatibility, Cursor also loads skills from Claude and Codex directories: .claude/skills/ , .codex/skills/ , ~/.claude/skills/ , and ~/.codex/skills/ . Each skill should be a folder containing a SKILL.md file: .agents/ └── skills/ └── my-skill/ └── SKILL.md Skills can also include optional directories for scripts, references, and assets: .agents/ └── skills/ └── deploy-app/ ├── SKILL.md ├── scripts/ │ ├── deploy.sh │ └── validate.py ├── references/ │ └── REFERENCE.md └── assets/ └── config-template.json Nested skill directories Skill directories can be organized into subdirectories. This is useful for grouping related skills by category, team, or domain. Cursor walks the skills root recursively and picks up any SKILL.md it finds: .cursor/ └── skills/ ├── shipping/ │ ├── land-it/ │ │ └── SKILL.md │ └── careful-merge-conflicts/ │ └── SKILL.md ├── debugging/ │ └── using-datadog-mcp/ │ └── SKILL.md └── workflow/ └── tdd/ └── SKILL.md The category folder is purely organizational. The skill's identity comes from the folder containing SKILL.md (here land-it , tdd , etc.), not the parent category. Cursor also discovers skills inside nested project subdirectories. A .cursor/skills/ (or .agents/skills/ ) folder anywhere inside your repository is picked up, so monorepos can colocate skills with the package they apply to: my-monorepo/ ├── .cursor/skills/ # repo-wide skills │ └── land-it/SKILL.md └── apps/ └── web/ └── .cursor/skills/ # app-specific skills └── deploy-web/SKILL.md Skills in nested project directories are automatically scoped to files inside that directory. In the example above, deploy-web is only surfaced when the agent works with files under apps/web/ , while skills in the repo-wide .cursor/skills/ are available everywhere. This is similar to the paths frontmatter field — you don't need to set paths on a nested skill to scope it to its directory. SKILL.md file format Each skill is defined in a SKILL.md file with YAML frontmatter: --- name: my-skill description: Short description of what this skill does and when to use it. --- # My Skill Detailed instructions for the agent. ## When to Use - Use this skill when... - This skill is helpful for... ## Instructions - Step-by-step guidance for the agent - Domain-specific conventions - Best practices and patterns - Use the ask questions tool if you need to clarify requirements with the user Frontmatter fields Field Required Description name Yes Skill identifier. Lowercase letters, numbers, and hyphens only. Must match the parent folder name. description Yes Describes what the skill does and when to use it. Used by the agent to determine relevance. paths No Glob patterns that scope the skill to matching files. Accepts a comma-separated string or a list. When set, the skill is only surfaced when the agent works with files that match. disable-model-invocation No When true , the skill is only included when explicitly invoked via /skill-name . The agent will not automatically apply it based on context. metadata No Arbitrary key-value mapping for additional metadata. Scoping a skill to specific files Use the paths field to limit a skill to files that match one or more glob patterns. The skill is then only surfaced to the agent when it is reading or editing matching files. This keeps file-specific guidance out of context for unrelated work. --- name: react-component-patterns description: Conventions for writing React components in this codebase. paths: - "* */* .tsx" - "packages/ui/* */* .ts" --- # React component patterns ... You can also pass a single comma-separated string: --- name: python-style description: Style rules for Python files. paths: " **/ *.py, scripts/** /*.py" --- Patterns follow standard glob syntax. Leave paths unset for a skill that should be available regardless of which files are open. The legacy globs field is still accepted as a fallback for older skills, but new skills should use paths . Disabling automatic invocation By default, skills are automatically applied when the agent determines they are relevant. Set disable-model-invocation: true to make a skill behave like a traditional slash command, where it is only included in context when you explicitly type /skill-name in chat. Including scripts in skills Skills can include a scripts/ directory containing executable code that agents can run. Reference scripts in your SKILL.md using relative paths from the skill root. --- name: deploy-app description: Deploy the application to staging or production environments. Use when deploying code or when the user mentions deployment, releases, or environments. --- # Deploy App Deploy the application using the provided scripts. ## Usage Run the deployment script: `scripts/deploy.sh ` Where `` is either `staging` or `production` . ## Pre-deployment Validation Before deploying, run the validation script: `python scripts/validate.py` The agent reads these instructions and executes the referenced scripts when the skill is invoked. Scripts can be written in any language—Bash, Python, JavaScript, or any other executable format supported by the agent implementation. Scripts should be self-contained, include helpful error messages, and handle edge cases gracefully. Optional directories Skills support these optional directories: Directory Purpose scripts/ Executable code that agents can run references/ Additional documentation loaded on demand assets/ Static resources like templates, images, or data files Keep your main SKILL.md focused and move detailed reference material to separate files. This keeps context usage efficient since agents load resources progressively—only when needed. Viewing skills To view discovered skills: Open Cursor Settings (Cmd+Shift+J on Mac, Ctrl+Shift+J on Windows/Linux) Navigate to Rules Skills appear in the Agent Decides section Installing skills from GitHub You can import skills from GitHub repositories: Open Cursor Settings → Rules In the Project Rules section, click Add Rule Select Remote Rule (Github) Enter the GitHub repository URL Migrating rules and commands to skills Cursor includes a built-in /migrate-to-skills skill in 2.4 that helps you convert existing dynamic rules and slash commands to skills. The migration skill converts: Dynamic rules : Rules that use the "Apply Intelligently" configuration—rules with alwaysApply: false (or undefined) and no globs patterns defined. These are converted to standard skills. Slash commands : Both user-level and workspace-level commands are converted to skills with disable-model-invocation: true , preserving their explicit invocation behavior. To migrate: Type /migrate-to-skills in Agent chat The agent will identify eligible rules and commands and convert them to skills Review the generated skills in .cursor/skills/ Rules with alwaysApply: true or specific globs patterns are not migrated, as they have explicit triggering conditions that differ from skill behavior. User rules are also not migrated since they are not stored on the file system. Learn more Agent Skills is an open standard. Learn more at agentskills.io . English English 简体中文 日本語 繁體中文 Español Français Português 한국어 Русский Türkçe Bahasa Indonesia Deutsch हिन्दी

Customizing Hooks Hooks let you observe, control, and extend the agent loop using custom scripts. Hooks are spawned processes that communicate over stdio using JSON in both directions. They run before or after defined stages of the agent loop and can observe, block, or modify behavior. With hooks, you can: Run formatters after edits Add analytics for events Scan for PII or secrets Gate risky operations (e.g., SQL writes) Control subagent (Task tool) execution Inject context at session start Looking for ready-to-use integrations? See Partner Integrations for security, governance, and secrets management solutions from our ecosystem partners. Cursor supports loading hooks from third-party tools like Claude Code. See Third Party Hooks for details on compatibility and configuration. Hook categories Hooks fall into three categories based on what triggers them: Agent hooks (Cmd+K/Agent Chat) fire during an agent session: sessionStart / sessionEnd - Session lifecycle management preToolUse / postToolUse / postToolUseFailure - Generic tool use hooks (fires for all tools) subagentStart / subagentStop - Subagent (Task tool) lifecycle beforeShellExecution / afterShellExecution - Control shell commands beforeMCPExecution / afterMCPExecution - Control MCP tool usage beforeReadFile / afterFileEdit - Control file access and edits beforeSubmitPrompt - Validate prompts before submission preCompact - Observe context window compaction stop - Handle agent completion afterAgentResponse / afterAgentThought - Track agent responses Tab hooks (inline completions) fire for autonomous Tab operations: beforeTabFileRead - Control file access for Tab completions afterTabFileEdit - Post-process Tab edits App lifecycle hooks fire outside any agent session: workspaceOpen - Fires when Cursor opens a workspace and on every workspace folder change. Can return additional plugin paths to load for the current workspace. These separate hook surfaces let you apply different policies to autonomous Tab operations, user-directed Agent operations, and workspace startup. Cloud agents also run repo hooks. On Enterprise plans, they also run team hooks and enterprise-managed hooks. Quickstart Create a hooks.json file. You can create it at the project level ( /.cursor/hooks.json ) or in your home directory ( ~/.cursor/hooks.json ). Project-level hooks apply only to that specific project, while home directory hooks apply globally. User hooks (~/.cursor/) Project hooks (.cursor/) For user-level hooks that apply globally, create ~/.cursor/hooks.json : { "version" : 1 , "hooks" : { "afterFileEdit" : [{ "command" : "./hooks/format.sh" }] } } Create your hook script at ~/.cursor/hooks/format.sh : #!/bin/bash # Read input, do something, exit 0 cat > /dev/null exit 0 Make it executable: chmod +x ~/.cursor/hooks/format.sh Cursor watches hooks config files and reloads them automatically. Your hook runs after every file edit. Hook Types Hooks support two execution types: command-based (default) and prompt-based (LLM-evaluated). Command-Based Hooks Command hooks execute shell scripts that receive JSON input via stdin and return JSON output via stdout. { "hooks" : { "beforeShellExecution" : [ { "command" : "./scripts/approve-network.sh" , "timeout" : 30 , "matcher" : "curl|wget|nc" } ] } } Exit code behavior: Exit code 0 - Hook succeeded, use the JSON output Exit code 2 - Block the action (equivalent to returning permission: "deny" ) Other exit codes - Hook failed, action proceeds (fail-open by default) Prompt-Based Hooks Prompt hooks use an LLM to evaluate a natural language condition. They're useful for policy enforcement without writing custom scripts. { "hooks" : { "beforeShellExecution" : [ { "type" : "prompt" , "prompt" : "Does this command look safe to execute? Only allow read-only operations." , "timeout" : 10 } ] } } Features: Returns structured { ok: boolean, reason?: string } response Uses a fast model for quick evaluation $ARGUMENTS placeholder is auto-replaced with hook input JSON If $ARGUMENTS is absent, hook input is auto-appended Optional model field to override the default LLM model Examples The examples below use ./hooks/... paths, which work for user hooks ( ~/.cursor/hooks.json ) where scripts run from ~/.cursor/ . For project hooks ( /.cursor/hooks.json ), use .cursor/hooks/... paths instead since scripts run from the project root. hooks.json audit.sh block-git.sh { "version" : 1 , "hooks" : { "sessionStart" : [ { "command" : "./hooks/session-init.sh" } ], "sessionEnd" : [ { "command" : "./hooks/audit.sh" } ], "beforeShellExecution" : [ { "command" : "./hooks/audit.sh" }, { "command" : "./hooks/block-git.sh" } ], "beforeMCPExecution" : [ { "command" : "./hooks/audit.sh" } ], "afterShellExecution" : [ { "command" : "./hooks/audit.sh" } ], "afterMCPExecution" : [ { "command" : "./hooks/audit.sh" } ], "afterFileEdit" : [ { "command" : "./hooks/audit.sh" } ], "beforeSubmitPrompt" : [ { "command" : "./hooks/audit.sh" } ], "preCompact" : [ { "command" : "./hooks/audit.sh" } ], "stop" : [ { "command" : "./hooks/audit.sh" } ], "beforeTabFileRead" : [ { "command" : "./hooks/redact-secrets-tab.sh" } ], "afterTabFileEdit" : [ { "command" : "./hooks/format-tab.sh" } ] } } TypeScript stop automation hook Choose TypeScript when you need typed JSON, durable file I/O, and HTTP calls in the same hook. This Bun-powered stop hook tracks per-conversation failure counts on disk, forwards structured telemetry to an internal API, and can automatically schedule a retry when the agent fails twice in a row. hooks.json .cursor/hooks/track-stop.ts { "version" : 1 , "hooks" : { "stop" : [ { "command" : "bun run .cursor/hooks/track-stop.ts --stop" } ] } } Set AGENT_TELEMETRY_URL to the internal endpoint that should receive run summaries. Python manifest guard hook Python shines when you need rich parsing libraries. This hook uses pyyaml to inspect Kubernetes manifests before kubectl apply runs; Bash would struggle to parse multi-document YAML safely. hooks.json .cursor/hooks/kube_guard.py { "version" : 1 , "hooks" : { "beforeShellExecution" : [ { "command" : "python3 .cursor/hooks/kube_guard.py" } ] } } Install PyYAML (for example, pip install pyyaml ) wherever your hook scripts run so the parser import succeeds. Partner Integrations We partner with ecosystem vendors who have built hooks support with Cursor. These integrations cover security scanning, governance, secrets management, and more. MCP governance and visibility Partner Description MintMCP Build a complete inventory of MCP servers, monitor tool usage patterns, and scan responses for sensitive data before it reaches the AI model. Oasis Security Enforce least-privilege policies on AI agent actions and maintain full audit trails across enterprise systems. Runlayer Wrap MCP tools and integrate with their MCP broker for centralized control and visibility over agent-to-tool interactions. Code security and best practices Partner Description Corridor Get real-time feedback on code implementation and security design decisions as code is being written. Semgrep Automatically scan AI-generated code for vulnerabilities with real-time feedback to regenerate code until security issues are resolved. Dependency security Partner Description Endor Labs Intercept package installations and scan for malicious dependencies, preventing supply chain attacks before they enter your codebase. Agent security and safety Partner Description Snyk Review agent actions in real-time with Evo Agent Guard, detecting and preventing issues like prompt injection and dangerous tool calls. Secrets management Partner Description 1Password Validate that environment files from 1Password Environments are properly mounted before shell commands execute, enabling just-in-time secrets access without writing credentials to disk. For more details about our hooks partners, see the Hooks for security and platform teams blog post. Configuration Define hooks in a hooks.json file. Configuration can exist at multiple levels. All matching hooks from every source run; when responses conflict, higher-priority sources take precedence during merge: ~ /.cursor/ ├── hooks.json └── hooks/ ├── audit.sh └── block-git.sh Enterprise (MDM-managed, system-wide): macOS: /Library/Application Support/Cursor/hooks.json Linux/WSL: /etc/cursor/hooks.json Windows: C:\\ProgramData\\Cursor\\hooks.json Team (Cloud-distributed, enterprise only): Configured in the web dashboard and synced to all team members automatically Project (Project-specific): /.cursor/hooks.json Project hooks run in any trusted workspace and are checked into version control with your project User (User-specific): ~/.cursor/hooks.json Priority order (highest to lowest): Enterprise → Team → Project → User The hooks object maps hook names to arrays of hook definitions. Each definition currently supports a command property that can be a shell string, an absolute path, or a relative path. The working directory depends on the hook source: Project hooks ( .cursor/hooks.json in a repository): Run from the project root User hooks ( ~/.cursor/hooks.json ): Run from ~/.cursor/ Enterprise hooks (system-wide config): Run from the enterprise config directory Team hooks (cloud-distributed): Run from the managed hooks directory For project hooks, use paths like .cursor/hooks/script.sh (relative to project root), not ./hooks/script.sh (which would look for /hooks/script.sh ). Configuration file This example shows a user-level hooks file ( ~/.cursor/hooks.json ). For project-level hooks, change paths like ./hooks/script.sh to .cursor/hooks/script.sh : { "version" : 1 , "hooks" : { "sessionStart" : [{ "command" : "./session-init.sh" }], "sessionEnd" : [{ "command" : "./audit.sh" }], "preToolUse" : [ { "command" : "./hooks/validate-tool.sh" , "matcher" : "Shell|Read|Write" } ], "postToolUse" : [{ "command" : "./hooks/audit-tool.sh" }], "subagentStart" : [{ "command" : "./hooks/validate-subagent.sh" }], "subagentStop" : [{ "command" : "./hooks/audit-subagent.sh" }], "beforeShellExecution" : [{ "command" : "./script.sh" }], "afterShellExecution" : [{ "command" : "./script.sh" }], "afterMCPExecution" : [{ "command" : "./script.sh" }], "afterFileEdit" : [{ "command" : "./format.sh" }], "preCompact" : [{ "command" : "./audit.sh" }], "stop" : [{ "command" : "./audit.sh" , "loop_limit" : 10 }], "beforeTabFileRead" : [{ "command" : "./redact-secrets-tab.sh" }], "afterTabFileEdit" : [{ "command" : "./format-tab.sh" }], "workspaceOpen" : [{ "command" : "./register-workspace-plugins.sh" }] } } The Agent hooks ( sessionStart , sessionEnd , preToolUse , postToolUse , postToolUseFailure , subagentStart , subagentStop , beforeShellExecution , afterShellExecution , beforeMCPExecution , afterMCPExecution , beforeReadFile , afterFileEdit , beforeSubmitPrompt , preCompact , stop , afterAgentResponse , afterAgentThought ) apply to Cmd+K and Agent Chat operations. The Tab hooks ( beforeTabFileRead , afterTabFileEdit ) apply specifically to inline Tab completions. The app lifecycle hook ( workspaceOpen ) fires when a workspace opens and on workspace folder changes, independent of any agent session. Global Configuration Options Option Type Default Description version number 1 Config schema version Per-Script Configuration Options Option Type Default Description command string required Script path or command type "command" | "prompt" "command" Hook execution type timeout number platform default Execution timeout in seconds loop_limit number | null 5 Per-script loop limit for stop/subagentStop hooks. null means no limit. Default is 5 for Cursor hooks, null for Claude Code hooks. failClosed boolean false When true , hook failures (crash, timeout, invalid JSON) block the action instead of allowing it through. Useful for security-critical hooks. matcher object - Filter criteria for when hook runs Matcher Configuration Matchers let you filter when a hook runs. Which field the matcher applies to depends on the hook: { "hooks" : { "preToolUse" : [ { "command" : "./validate-shell.sh" , "matcher" : "Shell" } ], "subagentStart" : [ { "command" : "./validate-explore.sh" , "matcher" : "explore|shell" } ], "beforeShellExecution" : [ { "command" : "./approve-network.sh" , "matcher" : "curl|wget|nc " } ] } } subagentStart : The matcher runs against the subagent type (e.g. explore , shell , generalPurpose ). Use it to run hooks only when a specific kind of subagent is started. The example above runs validate-explore.sh only for explore or shell subagents. beforeShellExecution : The matcher runs against the shell command string. Use it to run hooks only when the command matches a pattern (e.g. network calls, file deletions). The example above runs approve-network.sh only when the command contains curl , wget , or nc . Available matchers by hook: preToolUse / postToolUse / postToolUseFailure : Filter by tool type. Values include Shell , Read , Write , Grep , Delete , Task , and MCP tools using the MCP: format. subagentStart / subagentStop : Filter by subagent type ( generalPurpose , explore , shell , etc.). beforeShellExecution / afterShellExecution : Filter by the shell command text; the matcher is matched against the full command string. beforeReadFile : Filter by tool type ( TabRead , Read , etc.). afterFileEdit : Filter by tool type ( TabWrite , Write , etc.). beforeSubmitPrompt : Matched against the value UserPromptSubmit . stop : Matched against the value Stop . afterAgentResponse : Matched against the value AgentResponse . afterAgentThought : Matched against the value AgentThought . Team Distribution Hooks can be distributed to team members using project hooks (via version control), MDM tools, or Cursor's cloud distribution system. Project Hooks (Version Control) Project hooks are the simplest way to share hooks with your team. Place a hooks.json file at /.cursor/hooks.json and commit it to your repository. When team members open the project in a trusted workspace, Cursor automatically loads and runs the project hooks. Cloud agents also load these project hooks when they work on your repository in the cloud. Project hooks: Are stored in version control alongside your code Automatically load for all team members in trusted workspaces Can be project-specific (e.g., enforce formatting standards for a particular codebase) Require the workspace to be trusted to run (for security) MDM Distribution Distribute hooks across your organization using Mobile Device Management (MDM) tools. Place the hooks.json file and hook scripts in the target directories on each machine. User home directory (per-user distribution): ~/.cursor/hooks.json ~/.cursor/hooks/ (for hook scripts) Global directories (system-wide distribution): macOS: /Library/Application Support/Cursor/hooks.json Linux/WSL: /etc/cursor/hooks.json Windows: C:\\ProgramData\\Cursor\\hooks.json Note: MDM-based distribution is fully managed by your organization. Cursor does not deploy or manage files through your MDM solution. Ensure your internal IT or security team handles configuration, deployment, and updates in accordance with your organization's policies. Cloud Distribution (Enterprise Only) Enterprise teams can use Cursor's native cloud distribution to automatically sync hooks to all team members. Configure hooks in the web dashboard . Cursor automatically delivers configured hooks to all client machines when team members log in. Cloud distribution provides: Automatic synchronization to all team members (every thirty minutes) Operating system targeting for platform-specific hooks Centralized management through the dashboard Enterprise administrators can create, edit, and manage team hooks from the dashboard without requiring access to individual machines. Contact sales to get Enterprise cloud hook distribution. Reference Common schema Input (all hooks) All hooks receive a base set of fields in addition to their hook-specific fields: { "conversation_id" : "string" , "generation_id" : "string" , "model" : "string" , "hook_event_name" : "string" , "cursor_version" : "string" , "workspace_roots" : [ "" ], "user_email" : "string | null" , "transcript_path" : "string | null" } Field Type Description conversation_id string Stable ID of the conversation across many turns generation_id string The current generation that changes with every user message model string The model configured for the composer that triggered the hook hook_event_name string Which hook is being run cursor_version string Cursor application version (e.g. "1.7.2") workspace_roots string[] The list of root folders in the workspace (normally just one, but multiroot workspaces can have multiple) user_email string | null Email address of the authenticated user, if available transcript_path string | null Path to the main conversation transcript file (null if transcripts disabled) App lifecycle hooks ( workspaceOpen ) fire outside any agent session, so the request omits conversation_id , generation_id , model , session_id , and transcript_path . They still receive hook_event_name , cursor_version , workspace_roots , and user_email . Hook events preToolUse Called before any tool execution. This is a generic hook that fires for all tool types (Shell, Read, Write, MCP, Task, etc.). Use matchers to filter by specific tools. // Input { "tool_name" : "Shell" , "tool_input" : { "command" : "npm install" , "working_directory" : "/project" }, "tool_use_id" : "abc123" , "cwd" : "/project" , "model" : "claude-sonnet-4-20250514" , "agent_message" : "Installing dependencies..." } // Output { "permission" : "allow" | "deny" , "user_message" : "" , "agent_message" : "" , "updated_input" : { "command" : "npm ci" } } Output Field Type Description permission string "allow" to proceed, "deny" to block. "ask" is accepted by the schema but not enforced for preToolUse today. user_message string (optional) Message shown to the user when the action is denied agent_message string (optional) Message fed back to the agent when the action is denied updated_input object (optional) Modified tool input to use instead postToolUse Called after successful tool execution. Useful for auditing, analytics, and injecting context. // Input { "tool_name" : "Shell" , "tool_input" : { "command" : "npm test" }, "tool_output" : "{ \" exitCode \" :0, \" stdout \" : \" All tests passed \" }" , "tool_use_id" : "abc123" , "cwd" : "/project" , "duration" : 5432 , "model" : "claude-sonnet-4-20250514" } // Output { "updated_mcp_tool_output" : { "modified" : "output" }, "additional_context" : "Test coverage report attached." } Input Field Type Description duration number Execution time in milliseconds tool_output string JSON-stringified result payload from the tool (not raw terminal text) Output Field Type Description updated_mcp_tool_output object (optional) For MCP tools only: replaces the tool output seen by the model additional_context string (optional) Extra context injected into the conversation after the tool result postToolUseFailure Called when a tool fails, times out, or is denied. Useful for error tracking and recovery logic. // Input { "tool_name" : "Shell" , "tool_input" : { "command" : "npm test" }, "tool_use_id" : "abc123" , "cwd" : "/project" , "error_message" : "Command timed out after 30s" , "failure_type" : "timeout" | "error" | "permission_denied" , "duration" : 5000 , "is_interrupt" : false } // Output { // No output fields currently supported } Input Field Type Description error_message string Description of the failure failure_type string Type of failure: "error" , "timeout" , or "permission_denied" duration number Time in milliseconds until the failure occurred is_interrupt boolean Whether this failure was caused by a user interrupt/cancellation subagentStart Called before spawning a subagent (Task tool). Can allow or deny subagent creation. // Input { "subagent_id" : "abc-123" , "subagent_type" : "generalPurpose" , "task" : "Explore the authentication flow" , "parent_conversation_id" : "conv-456" , "tool_call_id" : "tc-789" , "subagent_model" : "claude-sonnet-4-20250514" , "is_parallel_worker" : false , "git_branch" : "feature/auth" } // Output { "permission" : "allow" | "deny" , "user_message" : "" } Input Field Type Description subagent_id string Unique identifier for this subagent instance subagent_type string Type of subagent: generalPurpose , explore , shell , etc. task string The task description given to the subagent parent_conversation_id string Conversation ID of the parent agent session tool_call_id string ID of the tool call that triggered the subagent subagent_model string Model the subagent will use is_parallel_worker boolean Whether this subagent is running as a parallel worker git_branch string (optional) Git branch the subagent will operate on, if applicable Output Field Type Description permission string "allow" to proceed, "deny" to block. "ask" is not supported for subagentStart and is treated as "deny" . user_message string (optional) Message shown to the user when the subagent is denied subagentStop Called when a subagent completes, errors, or is aborted. Can trigger follow-up actions. // Input { "subagent_type" : "generalPurpose" , "status" : "completed" | "error" | "aborted" , "task" : "Explore the authentication flow" , "description" : "Exploring auth flow" , "summary" : "" , "duration_ms" : 45000 , "message_count" : 12 , "tool_call_count" : 8 , "loop_count" : 0 , "modified_files" : [ "src/auth.ts" ], "agent_transcript_path" : "/path/to/subagent/transcript.txt" } // Output { "followup_message" : "" } Input Field Type Description subagent_type string Type of subagent: generalPurpose , explore , shell , etc. status string "completed" , "error" , or "aborted" task string The task description given to the subagent description string Short description of the subagent's purpose summary string Output summary from the subagent duration_ms number Execution time in milliseconds message_count number Number of messages exchanged during the subagent session tool_call_count number Number of tool calls the subagent made loop_count number Number of times a subagentStop follow-up has already triggered for this subagent (starts at 0) modified_files string[] Files the subagent modified agent_transcript_path string | null Path to the subagent's own transcript file (separate from the parent conversation) Output Field Type Description followup_message string (optional) Auto-continue with this message. Only consumed when status is "completed" . The followup_message field enables loop-style flows where subagent completion triggers the next iteration. Follow-ups are subject to the same configurable loop limit as the stop hook (default 5, configurable via loop_limit ). beforeShellExecution / beforeMCPExecution Called before any shell command or MCP tool is executed. Return a permission decision. By default, hook failures (crash, timeout, invalid JSON) allow the action through (fail-open). Set failClosed: true on the hook definition to block the action on failure instead. This is recommended for security-critical beforeMCPExecution hooks. // beforeShellExecution input { "command" : "" , "cwd" : "" , "sandbox" : false } // beforeMCPExecution input { "tool_name" : "" , "tool_input" : "" } // Plus either: { "url" : "" } // Or: { "command" : "" } // Output { "permission" : "allow" | "deny" | "ask" , "user_message" : "" , "agent_message" : "" } afterShellExecution Fires after a shell command executes; useful for auditing or collecting metrics from command output. // Input { "command" : "" , "output" : "" , "duration" : 1234 , "sandbox" : false } Field Type Description command string The full terminal command that was executed output string Full output captured from the terminal duration number Duration in milliseconds spent executing the shell command (excludes approval wait time) sandbox boolean Whether the command ran in a sandboxed environment afterMCPExecution Fires after an MCP tool executes; includes the tool's input parameters and full JSON result. // Input { "tool_name" : "" , "tool_input" : "" , "result_json" : "" , "duration" : 1234 } Field Type Description tool_name string Name of the MCP tool that was executed tool_input string JSON params string passed to the tool result_json string JSON string of the tool response duration number Duration in milliseconds spent executing the MCP tool (excludes approval wait time) afterFileEdit Fires after the Agent edits a file; useful for formatters or accounting of agent-written code. // Input { "file_path" : "" , "edits" : [{ "old_string" : "" , "new_string" : "" }] } beforeReadFile Called before Agent reads a file. Use for access control to block sensitive files from being sent to the model. By default, beforeReadFile hook failures (crash, timeout, invalid JSON) are logged and the read is allowed through. Set failClosed: true on the hook definition to block the read on failure instead. // Input { "file_path" : "" , "content" : "" , "attachments" : [ { "type" : "file" | "rule" , "file_path" : "" } ] } // Output { "permission" : "allow" | "deny" , "user_message" : "" } Input Field Type Description file_path string Absolute path to the file being read content string Full contents of the file attachments array Context attachments associated with the prompt. Each entry has a type ( "file" or "rule" ) and a file_path . Output Field Type Description permission string "allow" to proceed, "deny" to block user_message string (optional) Message shown to user when denied beforeTabFileRead Called before Tab (inline completions) reads a file. Enable redaction or access control before Tab accesses file contents. Key differences from beforeReadFile : Only triggered by Tab, not Agent Does not include attachments field (Tab doesn't use prompt attachments) Useful for applying different policies to autonomous Tab operations // Input { "file_path" : "" , "content" : "" } // Output { "permission" : "allow" | "deny" } afterTabFileEdit Called after Tab (inline completions) edits a file. Useful for formatters or auditing of Tab-written code. Key differences from afterFileEdit : Only triggered by Tab, not Agent Includes detailed edit information: range , old_line , and new_line for precise edit tracking Useful for fine-grained formatting or analysis of Tab edits // Input { "file_path" : "" , "edits" : [ { "old_string" : "" , "new_string" : "" , "range" : { "start_line_number" : 10 , "start_column" : 5 , "end_line_number" : 10 , "end_column" : 20 }, "old_line" : "" , "new_line" : "" } ] } // Output { // No output fields currently supported } beforeSubmitPrompt Called right after user hits send but before backend request. Can prevent submission. // Input { "prompt" : "" , "attachments" : [ { "type" : "file" | "rule" , "file_path" : "" } ] } // Output { "continue" : true | false , "user_message" : "" } Output Field Type Description continue boolean Whether to allow the prompt submission to proceed user_message string (optional) Message shown to the user when the prompt is blocked afterAgentResponse Called after the agent has completed an assistant message. // Input { "text" : "" } afterAgentThought Called after the agent completes a thinking block. Useful for observing the agent's reasoning process. // Input { "text" : "" , "duration_ms" : 5000 } // Output { // No output fields currently supported } Field Type Description text string Fully aggregated thinking text for the completed block duration_ms number (optional) Duration in milliseconds for the thinking block stop Called when the agent loop ends. Can optionally auto-submit a follow-up user message to keep iterating. // Input { "status" : "completed" | "aborted" | "error" , "loop_count" : 0 } // Output { "followup_message" : "" } The optional followup_message is a string. When provided and non-empty, Cursor will automatically submit it as the next user message. This enables loop-style flows (e.g., iterate until a goal is met). The loop_count field indicates how many times the stop hook has already triggered an automatic follow-up for this conversation (starts at 0). The default limit is 5 auto follow-ups per script, configurable via the loop_limit option. Set loop_limit to null to remove the cap. The same limit applies to subagentStop follow-ups. sessionStart Called when a new composer conversation is created. This hook runs as fire-and-forget; the agent loop does not wait for or enforce a blocking response. Use it to set up session-specific environment variables or inject additional context. // Input { "session_id" : "" , "is_background_agent" : true | false , "composer_mode" : "agent" | "ask" | "edit" } // Output { "env" : { "" : "" }, "additional_context" : "" } Input Field Type Description session_id string Unique identifier for this session (same as conversation_id ) is_background_agent boolean Whether this is a background agent session vs interactive session composer_mode string (optional) The mode the composer is starting in (e.g., "agent", "ask", "edit") Output Field Type Description env object (optional) Environment variables to set for this session. Available to all subsequent hook executions additional_context string (optional) Additional context to add to the conversation's initial system context The schema also accepts continue and user_message fields, but current callers do not enforce them. Session creation is not blocked even when continue is false . sessionEnd Called when a composer conversation ends. This is a fire-and-forget hook useful for logging, analytics, or cleanup tasks. The response is logged but not used. // Input { "session_id" : "" , "reason" : "completed" | "aborted" | "error" | "window_close" | "user_close" , "duration_ms" : 45000 , "is_background_agent" : true | false , "final_status" : "" , "error_message" : "" } // Output { // No output fields - fire and forget } Input Field Type Description session_id string Unique identifier for the session that is ending reason string How the session ended: "completed", "aborted", "error", "window_close", or "user_close" duration_ms number Total duration of the session in milliseconds is_background_agent boolean Whether this was a background agent session final_status string Final status of the session error_message string (optional) Error message if reason is "error" preCompact Called before context window compaction/summarization occurs. This is an observational hook that cannot block or modify the compaction behavior. Useful for logging when compaction happens or notifying users. // Input { "trigger" : "auto" | "manual" , "context_usage_percent" : 85 , "context_tokens" : 120000 , "context_window_size" : 128000 , "message_count" : 45 , "messages_to_compact" : 30 , "is_first_compaction" : true | false } // Output { "user_message" : "" } Input Field Type Description trigger string What triggered the compaction: "auto" or "manual" context_usage_percent number Current context window usage as a percentage (0-100) context_tokens number Current context window token count context_window_size number Maximum context window size in tokens message_count number Number of messages in the conversation messages_to_compact number Number of messages that will be summarized is_first_compaction boolean Whether this is the first compaction for this conversation Output Field Type Description user_message string (optional) Message to show to the user when compaction occurs workspaceOpen Fires once when Cursor opens a workspace and again on every workspace folder change. Skipped when the window has zero workspace folders. Runs in the Cursor desktop app and CLI. // Input { "hook_event_name" : "workspaceOpen" , "cursor_version" : "string" , "workspace_roots" : [ "" ], "user_email" : "string | null" } // Output { "pluginPaths" : [ "" , "..." ] } Output Field Type Description pluginPaths string[] (optional) Absolute paths to plugin directories to load for the current workspace. Environment Variables Hook scripts receive environment variables when executed: Variable Description Always Present CURSOR_PROJECT_DIR Workspace root directory Yes CURSOR_VERSION Cursor version string Yes CURSOR_USER_EMAIL Authenticated user email If logged in CURSOR_TRANSCRIPT_PATH Path to the conversation transcript file If transcripts enabled CURSOR_CODE_REMOTE Set to the string "true" when running in a remote workspace For remote workspaces CLAUDE_PROJECT_DIR Alias for project dir (Claude compatibility) Yes Session-scoped environment variables from sessionStart hooks are passed to all subsequent hook executions within that session. Troubleshooting How to confirm hooks are active There is a Hooks tab in Cursor Settings to debug configured and executed hooks, as well as a Hooks output channel to see errors. If hooks are not working Cursor watches hooks.json files and reloads them on save. If hooks still do not load, restart Cursor. Check that relative paths are correct for your hook source: For project hooks , paths are relative to the project root (e.g., .cursor/hooks/script.sh ) For user hooks , paths are relative to ~/.cursor/ (e.g., ./hooks/script.sh or hooks/script.sh ) Exit code blocking Exit code 2 from command hooks blocks the action (equivalent to returning permission: "deny" ). This matches Claude Code behavior for compatibility. Enterprise hooks and distribution Cloud distribution and team-wide hook management are available on Enterprise. Contact Sales English English 简体中文 日本語 繁體中文 Español Français Português 한국어 Русский Türkçe Bahasa Indonesia Deutsch हिन्दी

Customizing Hooks Hooks let you observe, control, and extend the agent loop using custom scripts. Hooks are spawned processes that communicate over stdio using JSON in both directions. They run before or after defined stages of the agent loop and can observe, block, or modify behavior. With hooks, you can: Run formatters after edits Add analytics for events Scan for PII or secrets Gate risky operations (e.g., SQL writes) Control subagent (Task tool) execution Inject context at session start Looking for ready-to-use integrations? See Partner Integrations for security, governance, and secrets management solutions from our ecosystem partners. Cursor supports loading hooks from third-party tools like Claude Code. See Third Party Hooks for details on compatibility and configuration. Hook categories Hooks fall into three categories based on what triggers them: Agent hooks (Cmd+K/Agent Chat) fire during an agent session: sessionStart / sessionEnd - Session lifecycle management preToolUse / postToolUse / postToolUseFailure - Generic tool use hooks (fires for all tools) subagentStart / subagentStop - Subagent (Task tool) lifecycle beforeShellExecution / afterShellExecution - Control shell commands beforeMCPExecution / afterMCPExecution - Control MCP tool usage beforeReadFile / afterFileEdit - Control file access and edits beforeSubmitPrompt - Validate prompts before submission preCompact - Observe context window compaction stop - Handle agent completion afterAgentResponse / afterAgentThought - Track agent responses Tab hooks (inline completions) fire for autonomous Tab operations: beforeTabFileRead - Control file access for Tab completions afterTabFileEdit - Post-process Tab edits App lifecycle hooks fire outside any agent session: workspaceOpen - Fires when Cursor opens a workspace and on every workspace folder change. Can return additional plugin paths to load for the current workspace. These separate hook surfaces let you apply different policies to autonomous Tab operations, user-directed Agent operations, and workspace startup. Cloud agents also run repo hooks. On Enterprise plans, they also run team hooks and enterprise-managed hooks. Quickstart Create a hooks.json file. You can create it at the project level ( /.cursor/hooks.json ) or in your home directory ( ~/.cursor/hooks.json ). Project-level hooks apply only to that specific project, while home directory hooks apply globally. User hooks (~/.cursor/) Project hooks (.cursor/) For user-level hooks that apply globally, create ~/.cursor/hooks.json : { "version" : 1 , "hooks" : { "afterFileEdit" : [{ "command" : "./hooks/format.sh" }] } } Create your hook script at ~/.cursor/hooks/format.sh : #!/bin/bash # Read input, do something, exit 0 cat > /dev/null exit 0 Make it executable: chmod +x ~/.cursor/hooks/format.sh Cursor watches hooks config files and reloads them automatically. Your hook runs after every file edit. Hook Types Hooks support two execution types: command-based (default) and prompt-based (LLM-evaluated). Command-Based Hooks Command hooks execute shell scripts that receive JSON input via stdin and return JSON output via stdout. { "hooks" : { "beforeShellExecution" : [ { "command" : "./scripts/approve-network.sh" , "timeout" : 30 , "matcher" : "curl|wget|nc" } ] } } Exit code behavior: Exit code 0 - Hook succeeded, use the JSON output Exit code 2 - Block the action (equivalent to returning permission: "deny" ) Other exit codes - Hook failed, action proceeds (fail-open by default) Prompt-Based Hooks Prompt hooks use an LLM to evaluate a natural language condition. They're useful for policy enforcement without writing custom scripts. { "hooks" : { "beforeShellExecution" : [ { "type" : "prompt" , "prompt" : "Does this command look safe to execute? Only allow read-only operations." , "timeout" : 10 } ] } } Features: Returns structured { ok: boolean, reason?: string } response Uses a fast model for quick evaluation $ARGUMENTS placeholder is auto-replaced with hook input JSON If $ARGUMENTS is absent, hook input is auto-appended Optional model field to override the default LLM model Examples The examples below use ./hooks/... paths, which work for user hooks ( ~/.cursor/hooks.json ) where scripts run from ~/.cursor/ . For project hooks ( /.cursor/hooks.json ), use .cursor/hooks/... paths instead since scripts run from the project root. hooks.json audit.sh block-git.sh { "version" : 1 , "hooks" : { "sessionStart" : [ { "command" : "./hooks/session-init.sh" } ], "sessionEnd" : [ { "command" : "./hooks/audit.sh" } ], "beforeShellExecution" : [ { "command" : "./hooks/audit.sh" }, { "command" : "./hooks/block-git.sh" } ], "beforeMCPExecution" : [ { "command" : "./hooks/audit.sh" } ], "afterShellExecution" : [ { "command" : "./hooks/audit.sh" } ], "afterMCPExecution" : [ { "command" : "./hooks/audit.sh" } ], "afterFileEdit" : [ { "command" : "./hooks/audit.sh" } ], "beforeSubmitPrompt" : [ { "command" : "./hooks/audit.sh" } ], "preCompact" : [ { "command" : "./hooks/audit.sh" } ], "stop" : [ { "command" : "./hooks/audit.sh" } ], "beforeTabFileRead" : [ { "command" : "./hooks/redact-secrets-tab.sh" } ], "afterTabFileEdit" : [ { "command" : "./hooks/format-tab.sh" } ] } } TypeScript stop automation hook Choose TypeScript when you need typed JSON, durable file I/O, and HTTP calls in the same hook. This Bun-powered stop hook tracks per-conversation failure counts on disk, forwards structured telemetry to an internal API, and can automatically schedule a retry when the agent fails twice in a row. hooks.json .cursor/hooks/track-stop.ts { "version" : 1 , "hooks" : { "stop" : [ { "command" : "bun run .cursor/hooks/track-stop.ts --stop" } ] } } Set AGENT_TELEMETRY_URL to the internal endpoint that should receive run summaries. Python manifest guard hook Python shines when you need rich parsing libraries. This hook uses pyyaml to inspect Kubernetes manifests before kubectl apply runs; Bash would struggle to parse multi-document YAML safely. hooks.json .cursor/hooks/kube_guard.py { "version" : 1 , "hooks" : { "beforeShellExecution" : [ { "command" : "python3 .cursor/hooks/kube_guard.py" } ] } } Install PyYAML (for example, pip install pyyaml ) wherever your hook scripts run so the parser import succeeds. Partner Integrations We partner with ecosystem vendors who have built hooks support with Cursor. These integrations cover security scanning, governance, secrets management, and more. MCP governance and visibility Partner Description MintMCP Build a complete inventory of MCP servers, monitor tool usage patterns, and scan responses for sensitive data before it reaches the AI model. Oasis Security Enforce least-privilege policies on AI agent actions and maintain full audit trails across enterprise systems. Runlayer Wrap MCP tools and integrate with their MCP broker for centralized control and visibility over agent-to-tool interactions. Code security and best practices Partner Description Corridor Get real-time feedback on code implementation and security design decisions as code is being written. Semgrep Automatically scan AI-generated code for vulnerabilities with real-time feedback to regenerate code until security issues are resolved. Dependency security Partner Description Endor Labs Intercept package installations and scan for malicious dependencies, preventing supply chain attacks before they enter your codebase. Agent security and safety Partner Description Snyk Review agent actions in real-time with Evo Agent Guard, detecting and preventing issues like prompt injection and dangerous tool calls. Secrets management Partner Description 1Password Validate that environment files from 1Password Environments are properly mounted before shell commands execute, enabling just-in-time secrets access without writing credentials to disk. For more details about our hooks partners, see the Hooks for security and platform teams blog post. Configuration Define hooks in a hooks.json file. Configuration can exist at multiple levels. All matching hooks from every source run; when responses conflict, higher-priority sources take precedence during merge: ~ /.cursor/ ├── hooks.json └── hooks/ ├── audit.sh └── block-git.sh Enterprise (MDM-managed, system-wide): macOS: /Library/Application Support/Cursor/hooks.json Linux/WSL: /etc/cursor/hooks.json Windows: C:\\ProgramData\\Cursor\\hooks.json Team (Cloud-distributed, enterprise only): Configured in the web dashboard and synced to all team members automatically Project (Project-specific): /.cursor/hooks.json Project hooks run in any trusted workspace and are checked into version control with your project User (User-specific): ~/.cursor/hooks.json Priority order (highest to lowest): Enterprise → Team → Project → User The hooks object maps hook names to arrays of hook definitions. Each definition currently supports a command property that can be a shell string, an absolute path, or a relative path. The working directory depends on the hook source: Project hooks ( .cursor/hooks.json in a repository): Run from the project root User hooks ( ~/.cursor/hooks.json ): Run from ~/.cursor/ Enterprise hooks (system-wide config): Run from the enterprise config directory Team hooks (cloud-distributed): Run from the managed hooks directory For project hooks, use paths like .cursor/hooks/script.sh (relative to project root), not ./hooks/script.sh (which would look for /hooks/script.sh ). Configuration file This example shows a user-level hooks file ( ~/.cursor/hooks.json ). For project-level hooks, change paths like ./hooks/script.sh to .cursor/hooks/script.sh : { "version" : 1 , "hooks" : { "sessionStart" : [{ "command" : "./session-init.sh" }], "sessionEnd" : [{ "command" : "./audit.sh" }], "preToolUse" : [ { "command" : "./hooks/validate-tool.sh" , "matcher" : "Shell|Read|Write" } ], "postToolUse" : [{ "command" : "./hooks/audit-tool.sh" }], "subagentStart" : [{ "command" : "./hooks/validate-subagent.sh" }], "subagentStop" : [{ "command" : "./hooks/audit-subagent.sh" }], "beforeShellExecution" : [{ "command" : "./script.sh" }], "afterShellExecution" : [{ "command" : "./script.sh" }], "afterMCPExecution" : [{ "command" : "./script.sh" }], "afterFileEdit" : [{ "command" : "./format.sh" }], "preCompact" : [{ "command" : "./audit.sh" }], "stop" : [{ "command" : "./audit.sh" , "loop_limit" : 10 }], "beforeTabFileRead" : [{ "command" : "./redact-secrets-tab.sh" }], "afterTabFileEdit" : [{ "command" : "./format-tab.sh" }], "workspaceOpen" : [{ "command" : "./register-workspace-plugins.sh" }] } } The Agent hooks ( sessionStart , sessionEnd , preToolUse , postToolUse , postToolUseFailure , subagentStart , subagentStop , beforeShellExecution , afterShellExecution , beforeMCPExecution , afterMCPExecution , beforeReadFile , afterFileEdit , beforeSubmitPrompt , preCompact , stop , afterAgentResponse , afterAgentThought ) apply to Cmd+K and Agent Chat operations. The Tab hooks ( beforeTabFileRead , afterTabFileEdit ) apply specifically to inline Tab completions. The app lifecycle hook ( workspaceOpen ) fires when a workspace opens and on workspace folder changes, independent of any agent session. Global Configuration Options Option Type Default Description version number 1 Config schema version Per-Script Configuration Options Option Type Default Description command string required Script path or command type "command" | "prompt" "command" Hook execution type timeout number platform default Execution timeout in seconds loop_limit number | null 5 Per-script loop limit for stop/subagentStop hooks. null means no limit. Default is 5 for Cursor hooks, null for Claude Code hooks. failClosed boolean false When true , hook failures (crash, timeout, invalid JSON) block the action instead of allowing it through. Useful for security-critical hooks. matcher object - Filter criteria for when hook runs Matcher Configuration Matchers let you filter when a hook runs. Which field the matcher applies to depends on the hook: { "hooks" : { "preToolUse" : [ { "command" : "./validate-shell.sh" , "matcher" : "Shell" } ], "subagentStart" : [ { "command" : "./validate-explore.sh" , "matcher" : "explore|shell" } ], "beforeShellExecution" : [ { "command" : "./approve-network.sh" , "matcher" : "curl|wget|nc " } ] } } subagentStart : The matcher runs against the subagent type (e.g. explore , shell , generalPurpose ). Use it to run hooks only when a specific kind of subagent is started. The example above runs validate-explore.sh only for explore or shell subagents. beforeShellExecution : The matcher runs against the shell command string. Use it to run hooks only when the command matches a pattern (e.g. network calls, file deletions). The example above runs approve-network.sh only when the command contains curl , wget , or nc . Available matchers by hook: preToolUse / postToolUse / postToolUseFailure : Filter by tool type. Values include Shell , Read , Write , Grep , Delete , Task , and MCP tools using the MCP: format. subagentStart / subagentStop : Filter by subagent type ( generalPurpose , explore , shell , etc.). beforeShellExecution / afterShellExecution : Filter by the shell command text; the matcher is matched against the full command string. beforeReadFile : Filter by tool type ( TabRead , Read , etc.). afterFileEdit : Filter by tool type ( TabWrite , Write , etc.). beforeSubmitPrompt : Matched against the value UserPromptSubmit . stop : Matched against the value Stop . afterAgentResponse : Matched against the value AgentResponse . afterAgentThought : Matched against the value AgentThought . Team Distribution Hooks can be distributed to team members using project hooks (via version control), MDM tools, or Cursor's cloud distribution system. Project Hooks (Version Control) Project hooks are the simplest way to share hooks with your team. Place a hooks.json file at /.cursor/hooks.json and commit it to your repository. When team members open the project in a trusted workspace, Cursor automatically loads and runs the project hooks. Cloud agents also load these project hooks when they work on your repository in the cloud. Project hooks: Are stored in version control alongside your code Automatically load for all team members in trusted workspaces Can be project-specific (e.g., enforce formatting standards for a particular codebase) Require the workspace to be trusted to run (for security) MDM Distribution Distribute hooks across your organization using Mobile Device Management (MDM) tools. Place the hooks.json file and hook scripts in the target directories on each machine. User home directory (per-user distribution): ~/.cursor/hooks.json ~/.cursor/hooks/ (for hook scripts) Global directories (system-wide distribution): macOS: /Library/Application Support/Cursor/hooks.json Linux/WSL: /etc/cursor/hooks.json Windows: C:\\ProgramData\\Cursor\\hooks.json Note: MDM-based distribution is fully managed by your organization. Cursor does not deploy or manage files through your MDM solution. Ensure your internal IT or security team handles configuration, deployment, and updates in accordance with your organization's policies. Cloud Distribution (Enterprise Only) Enterprise teams can use Cursor's native cloud distribution to automatically sync hooks to all team members. Configure hooks in the web dashboard . Cursor automatically delivers configured hooks to all client machines when team members log in. Cloud distribution provides: Automatic synchronization to all team members (every thirty minutes) Operating system targeting for platform-specific hooks Centralized management through the dashboard Enterprise administrators can create, edit, and manage team hooks from the dashboard without requiring access to individual machines. Contact sales to get Enterprise cloud hook distribution. Reference Common schema Input (all hooks) All hooks receive a base set of fields in addition to their hook-specific fields: { "conversation_id" : "string" , "generation_id" : "string" , "model" : "string" , "hook_event_name" : "string" , "cursor_version" : "string" , "workspace_roots" : [ "" ], "user_email" : "string | null" , "transcript_path" : "string | null" } Field Type Description conversation_id string Stable ID of the conversation across many turns generation_id string The current generation that changes with every user message model string The model configured for the composer that triggered the hook hook_event_name string Which hook is being run cursor_version string Cursor application version (e.g. "1.7.2") workspace_roots string[] The list of root folders in the workspace (normally just one, but multiroot workspaces can have multiple) user_email string | null Email address of the authenticated user, if available transcript_path string | null Path to the main conversation transcript file (null if transcripts disabled) App lifecycle hooks ( workspaceOpen ) fire outside any agent session, so the request omits conversation_id , generation_id , model , session_id , and transcript_path . They still receive hook_event_name , cursor_version , workspace_roots , and user_email . Hook events preToolUse Called before any tool execution. This is a generic hook that fires for all tool types (Shell, Read, Write, MCP, Task, etc.). Use matchers to filter by specific tools. // Input { "tool_name" : "Shell" , "tool_input" : { "command" : "npm install" , "working_directory" : "/project" }, "tool_use_id" : "abc123" , "cwd" : "/project" , "model" : "claude-sonnet-4-20250514" , "agent_message" : "Installing dependencies..." } // Output { "permission" : "allow" | "deny" , "user_message" : "" , "agent_message" : "" , "updated_input" : { "command" : "npm ci" } } Output Field Type Description permission string "allow" to proceed, "deny" to block. "ask" is accepted by the schema but not enforced for preToolUse today. user_message string (optional) Message shown to the user when the action is denied agent_message string (optional) Message fed back to the agent when the action is denied updated_input object (optional) Modified tool input to use instead postToolUse Called after successful tool execution. Useful for auditing, analytics, and injecting context. // Input { "tool_name" : "Shell" , "tool_input" : { "command" : "npm test" }, "tool_output" : "{ \" exitCode \" :0, \" stdout \" : \" All tests passed \" }" , "tool_use_id" : "abc123" , "cwd" : "/project" , "duration" : 5432 , "model" : "claude-sonnet-4-20250514" } // Output { "updated_mcp_tool_output" : { "modified" : "output" }, "additional_context" : "Test coverage report attached." } Input Field Type Description duration number Execution time in milliseconds tool_output string JSON-stringified result payload from the tool (not raw terminal text) Output Field Type Description updated_mcp_tool_output object (optional) For MCP tools only: replaces the tool output seen by the model additional_context string (optional) Extra context injected into the conversation after the tool result postToolUseFailure Called when a tool fails, times out, or is denied. Useful for error tracking and recovery logic. // Input { "tool_name" : "Shell" , "tool_input" : { "command" : "npm test" }, "tool_use_id" : "abc123" , "cwd" : "/project" , "error_message" : "Command timed out after 30s" , "failure_type" : "timeout" | "error" | "permission_denied" , "duration" : 5000 , "is_interrupt" : false } // Output { // No output fields currently supported } Input Field Type Description error_message string Description of the failure failure_type string Type of failure: "error" , "timeout" , or "permission_denied" duration number Time in milliseconds until the failure occurred is_interrupt boolean Whether this failure was caused by a user interrupt/cancellation subagentStart Called before spawning a subagent (Task tool). Can allow or deny subagent creation. // Input { "subagent_id" : "abc-123" , "subagent_type" : "generalPurpose" , "task" : "Explore the authentication flow" , "parent_conversation_id" : "conv-456" , "tool_call_id" : "tc-789" , "subagent_model" : "claude-sonnet-4-20250514" , "is_parallel_worker" : false , "git_branch" : "feature/auth" } // Output { "permission" : "allow" | "deny" , "user_message" : "" } Input Field Type Description subagent_id string Unique identifier for this subagent instance subagent_type string Type of subagent: generalPurpose , explore , shell , etc. task string The task description given to the subagent parent_conversation_id string Conversation ID of the parent agent session tool_call_id string ID of the tool call that triggered the subagent subagent_model string Model the subagent will use is_parallel_worker boolean Whether this subagent is running as a parallel worker git_branch string (optional) Git branch the subagent will operate on, if applicable Output Field Type Description permission string "allow" to proceed, "deny" to block. "ask" is not supported for subagentStart and is treated as "deny" . user_message string (optional) Message shown to the user when the subagent is denied subagentStop Called when a subagent completes, errors, or is aborted. Can trigger follow-up actions. // Input { "subagent_type" : "generalPurpose" , "status" : "completed" | "error" | "aborted" , "task" : "Explore the authentication flow" , "description" : "Exploring auth flow" , "summary" : "" , "duration_ms" : 45000 , "message_count" : 12 , "tool_call_count" : 8 , "loop_count" : 0 , "modified_files" : [ "src/auth.ts" ], "agent_transcript_path" : "/path/to/subagent/transcript.txt" } // Output { "followup_message" : "" } Input Field Type Description subagent_type string Type of subagent: generalPurpose , explore , shell , etc. status string "completed" , "error" , or "aborted" task string The task description given to the subagent description string Short description of the subagent's purpose summary string Output summary from the subagent duration_ms number Execution time in milliseconds message_count number Number of messages exchanged during the subagent session tool_call_count number Number of tool calls the subagent made loop_count number Number of times a subagentStop follow-up has already triggered for this subagent (starts at 0) modified_files string[] Files the subagent modified agent_transcript_path string | null Path to the subagent's own transcript file (separate from the parent conversation) Output Field Type Description followup_message string (optional) Auto-continue with this message. Only consumed when status is "completed" . The followup_message field enables loop-style flows where subagent completion triggers the next iteration. Follow-ups are subject to the same configurable loop limit as the stop hook (default 5, configurable via loop_limit ). beforeShellExecution / beforeMCPExecution Called before any shell command or MCP tool is executed. Return a permission decision. By default, hook failures (crash, timeout, invalid JSON) allow the action through (fail-open). Set failClosed: true on the hook definition to block the action on failure instead. This is recommended for security-critical beforeMCPExecution hooks. // beforeShellExecution input { "command" : "" , "cwd" : "" , "sandbox" : false } // beforeMCPExecution input { "tool_name" : "" , "tool_input" : "" } // Plus either: { "url" : "" } // Or: { "command" : "" } // Output { "permission" : "allow" | "deny" | "ask" , "user_message" : "" , "agent_message" : "" } afterShellExecution Fires after a shell command executes; useful for auditing or collecting metrics from command output. // Input { "command" : "" , "output" : "" , "duration" : 1234 , "sandbox" : false } Field Type Description command string The full terminal command that was executed output string Full output captured from the terminal duration number Duration in milliseconds spent executing the shell command (excludes approval wait time) sandbox boolean Whether the command ran in a sandboxed environment afterMCPExecution Fires after an MCP tool executes; includes the tool's input parameters and full JSON result. // Input { "tool_name" : "" , "tool_input" : "" , "result_json" : "" , "duration" : 1234 } Field Type Description tool_name string Name of the MCP tool that was executed tool_input string JSON params string passed to the tool result_json string JSON string of the tool response duration number Duration in milliseconds spent executing the MCP tool (excludes approval wait time) afterFileEdit Fires after the Agent edits a file; useful for formatters or accounting of agent-written code. // Input { "file_path" : "" , "edits" : [{ "old_string" : "" , "new_string" : "" }] } beforeReadFile Called before Agent reads a file. Use for access control to block sensitive files from being sent to the model. By default, beforeReadFile hook failures (crash, timeout, invalid JSON) are logged and the read is allowed through. Set failClosed: true on the hook definition to block the read on failure instead. // Input { "file_path" : "" , "content" : "" , "attachments" : [ { "type" : "file" | "rule" , "file_path" : "" } ] } // Output { "permission" : "allow" | "deny" , "user_message" : "" } Input Field Type Description file_path string Absolute path to the file being read content string Full contents of the file attachments array Context attachments associated with the prompt. Each entry has a type ( "file" or "rule" ) and a file_path . Output Field Type Description permission string "allow" to proceed, "deny" to block user_message string (optional) Message shown to user when denied beforeTabFileRead Called before Tab (inline completions) reads a file. Enable redaction or access control before Tab accesses file contents. Key differences from beforeReadFile : Only triggered by Tab, not Agent Does not include attachments field (Tab doesn't use prompt attachments) Useful for applying different policies to autonomous Tab operations // Input { "file_path" : "" , "content" : "" } // Output { "permission" : "allow" | "deny" } afterTabFileEdit Called after Tab (inline completions) edits a file. Useful for formatters or auditing of Tab-written code. Key differences from afterFileEdit : Only triggered by Tab, not Agent Includes detailed edit information: range , old_line , and new_line for precise edit tracking Useful for fine-grained formatting or analysis of Tab edits // Input { "file_path" : "" , "edits" : [ { "old_string" : "" , "new_string" : "" , "range" : { "start_line_number" : 10 , "start_column" : 5 , "end_line_number" : 10 , "end_column" : 20 }, "old_line" : "" , "new_line" : "" } ] } // Output { // No output fields currently supported } beforeSubmitPrompt Called right after user hits send but before backend request. Can prevent submission. // Input { "prompt" : "" , "attachments" : [ { "type" : "file" | "rule" , "file_path" : "" } ] } // Output { "continue" : true | false , "user_message" : "" } Output Field Type Description continue boolean Whether to allow the prompt submission to proceed user_message string (optional) Message shown to the user when the prompt is blocked afterAgentResponse Called after the agent has completed an assistant message. // Input { "text" : "" } afterAgentThought Called after the agent completes a thinking block. Useful for observing the agent's reasoning process. // Input { "text" : "" , "duration_ms" : 5000 } // Output { // No output fields currently supported } Field Type Description text string Fully aggregated thinking text for the completed block duration_ms number (optional) Duration in milliseconds for the thinking block stop Called when the agent loop ends. Can optionally auto-submit a follow-up user message to keep iterating. // Input { "status" : "completed" | "aborted" | "error" , "loop_count" : 0 } // Output { "followup_message" : "" } The optional followup_message is a string. When provided and non-empty, Cursor will automatically submit it as the next user message. This enables loop-style flows (e.g., iterate until a goal is met). The loop_count field indicates how many times the stop hook has already triggered an automatic follow-up for this conversation (starts at 0). The default limit is 5 auto follow-ups per script, configurable via the loop_limit option. Set loop_limit to null to remove the cap. The same limit applies to subagentStop follow-ups. sessionStart Called when a new composer conversation is created. This hook runs as fire-and-forget; the agent loop does not wait for or enforce a blocking response. Use it to set up session-specific environment variables or inject additional context. // Input { "session_id" : "" , "is_background_agent" : true | false , "composer_mode" : "agent" | "ask" | "edit" } // Output { "env" : { "" : "" }, "additional_context" : "" } Input Field Type Description session_id string Unique identifier for this session (same as conversation_id ) is_background_agent boolean Whether this is a background agent session vs interactive session composer_mode string (optional) The mode the composer is starting in (e.g., "agent", "ask", "edit") Output Field Type Description env object (optional) Environment variables to set for this session. Available to all subsequent hook executions additional_context string (optional) Additional context to add to the conversation's initial system context The schema also accepts continue and user_message fields, but current callers do not enforce them. Session creation is not blocked even when continue is false . sessionEnd Called when a composer conversation ends. This is a fire-and-forget hook useful for logging, analytics, or cleanup tasks. The response is logged but not used. // Input { "session_id" : "" , "reason" : "completed" | "aborted" | "error" | "window_close" | "user_close" , "duration_ms" : 45000 , "is_background_agent" : true | false , "final_status" : "" , "error_message" : "" } // Output { // No output fields - fire and forget } Input Field Type Description session_id string Unique identifier for the session that is ending reason string How the session ended: "completed", "aborted", "error", "window_close", or "user_close" duration_ms number Total duration of the session in milliseconds is_background_agent boolean Whether this was a background agent session final_status string Final status of the session error_message string (optional) Error message if reason is "error" preCompact Called before context window compaction/summarization occurs. This is an observational hook that cannot block or modify the compaction behavior. Useful for logging when compaction happens or notifying users. // Input { "trigger" : "auto" | "manual" , "context_usage_percent" : 85 , "context_tokens" : 120000 , "context_window_size" : 128000 , "message_count" : 45 , "messages_to_compact" : 30 , "is_first_compaction" : true | false } // Output { "user_message" : "" } Input Field Type Description trigger string What triggered the compaction: "auto" or "manual" context_usage_percent number Current context window usage as a percentage (0-100) context_tokens number Current context window token count context_window_size number Maximum context window size in tokens message_count number Number of messages in the conversation messages_to_compact number Number of messages that will be summarized is_first_compaction boolean Whether this is the first compaction for this conversation Output Field Type Description user_message string (optional) Message to show to the user when compaction occurs workspaceOpen Fires once when Cursor opens a workspace and again on every workspace folder change. Skipped when the window has zero workspace folders. Runs in the Cursor desktop app and CLI. // Input { "hook_event_name" : "workspaceOpen" , "cursor_version" : "string" , "workspace_roots" : [ "" ], "user_email" : "string | null" } // Output { "pluginPaths" : [ "" , "..." ] } Output Field Type Description pluginPaths string[] (optional) Absolute paths to plugin directories to load for the current workspace. Environment Variables Hook scripts receive environment variables when executed: Variable Description Always Present CURSOR_PROJECT_DIR Workspace root directory Yes CURSOR_VERSION Cursor version string Yes CURSOR_USER_EMAIL Authenticated user email If logged in CURSOR_TRANSCRIPT_PATH Path to the conversation transcript file If transcripts enabled CURSOR_CODE_REMOTE Set to the string "true" when running in a remote workspace For remote workspaces CLAUDE_PROJECT_DIR Alias for project dir (Claude compatibility) Yes Session-scoped environment variables from sessionStart hooks are passed to all subsequent hook executions within that session. Troubleshooting How to confirm hooks are active There is a Hooks tab in Cursor Settings to debug configured and executed hooks, as well as a Hooks output channel to see errors. If hooks are not working Cursor watches hooks.json files and reloads them on save. If hooks still do not load, restart Cursor. Check that relative paths are correct for your hook source: For project hooks , paths are relative to the project root (e.g., .cursor/hooks/script.sh ) For user hooks , paths are relative to ~/.cursor/ (e.g., ./hooks/script.sh or hooks/script.sh ) Exit code blocking Exit code 2 from command hooks blocks the action (equivalent to returning permission: "deny" ). This matches Claude Code behavior for compatibility. Enterprise hooks and distribution Cloud distribution and team-wide hook management are available on Enterprise. Contact Sales English English 简体中文 日本語 繁體中文 Español Français Português 한국어 Русский Türkçe Bahasa Indonesia Deutsch हिन्दी

Customizing Subagents Subagents are specialized AI assistants that Cursor's agent can delegate tasks to. Each subagent operates in its own context window, handles specific types of work, and returns its result to the parent agent. Use subagents to break down complex tasks, do work in parallel, and preserve context in the main conversation. You can use subagents in the editor, CLI, and Cloud Agents . Context isolation Each subagent has its own context window. Long research or exploration tasks don't consume space in your main conversation. Parallel execution Launch multiple subagents simultaneously. Work on different parts of your codebase without waiting for sequential completion. Specialized expertise Configure subagents with custom prompts, tool access, and models for domain-specific tasks. Reusability Define custom subagents and use them across projects. How subagents work When Agent encounters a complex task, it can launch a subagent automatically. The subagent receives a prompt with all necessary context, works autonomously, and returns a final message with its results. Subagents start with a clean context. The parent agent includes relevant information in the prompt since subagents don't have access to prior conversation history. Foreground vs background Subagents run in one of two modes: Mode Behavior Best for Foreground Blocks until the subagent completes. Returns the result immediately. Sequential tasks where you need the output. Background Returns immediately. The subagent works independently. Long-running tasks or parallel workstreams. Built-in subagents Cursor includes three built-in subagents that handle context-heavy operations automatically. These subagents were designed based on analysis of agent conversations where context window limits were hit. Subagent Purpose Why it's a subagent Explore Searches and analyzes codebases Codebase exploration generates large intermediate output that would bloat the main context. Uses a faster model to run many parallel searches. Bash Runs series of shell commands Command output is often verbose. Isolating it keeps the parent focused on decisions, not logs. Browser Controls browser via MCP tools Browser interactions produce noisy DOM snapshots and screenshots. The subagent filters this down to relevant results. Why these subagents exist These three operations share common traits: they generate noisy intermediate output, benefit from specialized prompts and tools, and can consume significant context. Running them as subagents solves several problems: Context isolation — Intermediate output stays in the subagent. The parent only sees the final summary. Model flexibility — The explore subagent uses a faster model by default. This enables running 10 parallel searches in the time a single main-agent search would take. Specialized configuration — Each subagent has prompts and tool access tuned for its specific task. Cost efficiency — Faster models cost less. Isolating token-heavy work in subagents with appropriate model choices reduces overall cost. You don't need to configure these subagents. Agent uses them automatically when appropriate. When to use subagents Use subagents when... Use skills when... You need context isolation for long research tasks The task is single-purpose (generate changelog, format) Running multiple workstreams in parallel You want a quick, repeatable action The task requires specialized expertise across many steps The task completes in one shot You want an independent verification of work You don't need a separate context window If you find yourself creating a subagent for a simple, single-purpose task like "generate a changelog" or "format imports," consider using a skill instead. Quick start Agent automatically uses subagents when appropriate. You can also create a custom subagent by asking Agent: Create a subagent file at .cursor/agents/verifier.md with YAML frontmatter (name, description) followed by the prompt. The verifier subagent should validate completed work, check that implementations are functional, run tests, and report what passed vs what's incomplete. Cursor Logo Try in Cursor For more control, create custom subagents manually in your project or user directory. Custom subagents Define custom subagents to encode specialized knowledge, enforce team standards, or automate repetitive workflows. File locations Type Location Scope Project subagents .cursor/agents/ Current project only .claude/agents/ Current project only (Claude compatibility) .codex/agents/ Current project only (Codex compatibility) User subagents ~/.cursor/agents/ All projects for current user ~/.claude/agents/ All projects for current user (Claude compatibility) ~/.codex/agents/ All projects for current user (Codex compatibility) Project subagents take precedence when names conflict. When multiple locations contain subagents with the same name, .cursor/ takes precedence over .claude/ or .codex/ . File format Each subagent is a markdown file with YAML frontmatter: --- name: security-auditor description: Security specialist. Use when implementing auth, payments, or handling sensitive data. model: inherit readonly: true --- You are a security expert auditing code for vulnerabilities. When invoked: 1. Identify security-sensitive code paths 2. Check for common vulnerabilities (injection, XSS, auth bypass) 3. Verify secrets are not hardcoded 4. Review input validation and sanitization Report findings by severity: - Critical (must fix before deploy) - High (fix soon) - Medium (address when possible) Configuration fields Field Type Required Default Description name string No Derived from filename Display name and identifier. Use lowercase letters and hyphens. description string No — Short description shown in Task tool hints. Agent reads this to decide delegation. model string No inherit Model to use: inherit or a specific model ID. See model configuration . readonly boolean No false If true , the subagent runs with restricted write permissions (no file edits, no state-changing shell commands). is_background boolean No false If true , the subagent runs in the background without blocking the parent. Model configuration The model field controls which model a subagent uses. There are two options: Value Behavior inherit Uses the same model as the parent agent. This is the default. A specific model ID Uses the exact model you specify, such as composer-2 or gpt-5.5 . See the models reference for available IDs. Choose inherit when the subagent needs the same reasoning power as the parent. Use a specific model ID when you need a particular model's capabilities regardless of what the parent uses. When the configured model won't be used Cursor honors the model field in your subagent frontmatter unless one of these conditions applies: Team admin restrictions — Your organization's admin has blocked the specified model. Max Mode required — The model requires Max Mode and you don't have it enabled. Plan limitations — The model isn't available on your current plan. In these cases, Cursor falls back to a compatible model. If you're seeing unexpected model behavior, check your plan settings and Max Mode status. --- name: code-reviewer description: Reviews code for correctness and style. model: inherit --- Review the code changes for bugs, style issues, and edge cases. --- name: search-agent description: Searches the codebase for relevant files and symbols. model: inherit --- Search the codebase and return relevant file paths and code snippets. --- name: reasoning-agent description: Handles complex architectural decisions. model: gpt-5.5 --- Analyze the architecture and recommend changes with detailed reasoning. Using subagents Automatic delegation Agent proactively delegates tasks based on: The task complexity and scope Custom subagent descriptions in your project Current context and available tools Include phrases like "use proactively" or "always use for" in your description field to encourage automatic delegation. Explicit invocation Request a specific subagent by using the /name syntax in your prompt: > /verifier confirm the auth flow is complete > /debugger investigate this error > /security-auditor review the payment module You can also invoke subagents by mentioning them naturally: > Use the verifier subagent to confirm the auth flow is complete > Have the debugger subagent investigate this error > Run the security-auditor subagent on the payment module Parallel execution Launch multiple subagents concurrently for maximum throughput: > Review the API changes and update the documentation in parallel Agent sends multiple Task tool calls in a single message, so subagents run simultaneously. Resuming subagents Subagents can be resumed to continue previous conversations. This is useful for long-running tasks that span multiple invocations. Each subagent execution returns an agent ID. Pass this ID to resume the subagent with full context preserved: > Resume agent abc123 and analyze the remaining test failures Background subagents write their state as they run. You can resume a subagent after it completes to continue the conversation with preserved context. Common patterns Verification agent A verification agent independently validates whether claimed work was actually completed. This addresses a common issue where AI marks tasks as done but implementations are incomplete or broken. --- name: verifier description: Validates completed work. Use after tasks are marked done to confirm implementations are functional. --- You are a skeptical validator. Your job is to verify that work claimed as complete actually works. When invoked: 1. Identify what was claimed to be completed 2. Check that the implementation exists and is functional 3. Run relevant tests or verification steps 4. Look for edge cases that may have been missed Be thorough and skeptical. Report: - What was verified and passed - What was claimed but incomplete or broken - Specific issues that need to be addressed Do not accept claims at face value. Test everything. Create a subagent file at .cursor/agents/verifier.md with YAML frontmatter containing name and description. The description should be 'Validates completed work. Use after tasks are marked done to confirm implementations are functional.' The prompt body should instruct it to be skeptical, verify implementations actually work by running tests, and look for edge cases. Cursor Logo Try in Cursor This pattern is useful for: Validating that features work end-to-end before marking tickets complete Catching partially implemented functionality Ensuring tests actually pass (not just that test files exist) Orchestrator pattern For complex workflows, a parent agent can coordinate multiple specialist subagents in sequence: Planner analyzes requirements and creates a technical plan Implementer builds the feature based on the plan Verifier confirms the implementation matches requirements Each handoff includes structured output so the next agent has clear context. Example subagents Debugger --- name: debugger description: Debugging specialist for errors and test failures. Use when encountering issues. --- You are an expert debugger specializing in root cause analysis. When invoked: 1. Capture error message and stack trace 2. Identify reproduction steps 3. Isolate the failure location 4. Implement minimal fix 5. Verify solution works For each issue, provide: - Root cause explanation - Evidence supporting the diagnosis - Specific code fix - Testing approach Focus on fixing the underlying issue, not symptoms. Create a subagent file at .cursor/agents/debugger.md with YAML frontmatter containing name and description. The debugger subagent should specialize in root cause analysis: capture stack traces, identify reproduction steps, isolate failures, implement minimal fixes, and verify solutions. Cursor Logo Try in Cursor Test runner --- name: test-runner description: Test automation expert. Use proactively to run tests and fix failures. --- You are a test automation expert. When you see code changes, proactively run appropriate tests. If tests fail: 1. Analyze the failure output 2. Identify the root cause 3. Fix the issue while preserving test intent 4. Re-run to verify Report test results with: - Number of tests passed/failed - Summary of any failures - Changes made to fix issues Create a subagent file at .cursor/agents/test-runner.md with YAML frontmatter containing name and description (mentioning 'Use proactively'). The test-runner subagent should proactively run tests when it sees code changes, analyze failures, fix issues while preserving test intent, and report results. Cursor Logo Try in Cursor Best practices Write focused subagents — Each subagent should have a single, clear responsibility. Avoid generic "helper" agents. Invest in descriptions — The description field determines when Agent delegates to your subagent. Spend time refining it. Test by making prompts and checking if the right subagent gets triggered. Keep prompts concise — Long, rambling prompts dilute focus. Be specific and direct. Add subagents to version control — Check .cursor/agents/ into your repository so the team benefits. Start with Agent-generated agents — Let Agent help you draft the initial configuration, then customize. Use hooks for file output — If you need subagents to produce structured output files, consider using hooks to process and save their results consistently. Anti-patterns to avoid Don't create dozens of generic subagents. Having 50+ subagents with vague instructions like "helps with coding" is ineffective. Agent won't know when to use them, and you'll waste time maintaining them. Vague descriptions — "Use for general tasks" gives Agent no signal about when to delegate. Be specific: "Use when implementing authentication flows with OAuth providers." Overly long prompts — A 2,000-word prompt doesn't make a subagent smarter. It makes it slower and harder to maintain. Duplicating slash commands — If a task is single-purpose and doesn't need context isolation, use a slash command instead. Too many subagents — Start with 2-3 focused subagents. Add more only when you have clear, distinct use cases. Managing subagents Creating subagents The easiest way to create a subagent is to ask Agent to create one for you: Create a subagent file at .cursor/agents/security-reviewer.md with YAML frontmatter containing name and description. The security-reviewer subagent should check code for common vulnerabilities like injection, XSS, and hardcoded secrets. Cursor Logo Try in Cursor You can also create subagents manually by adding markdown files to .cursor/agents/ (project) or ~/.cursor/agents/ (user). Viewing subagents Agent includes all custom subagents in its available tools. You can see which subagents are configured by checking the .cursor/agents/ directory in your project. Performance and cost Subagents have trade-offs. Understanding them helps you decide when to use them. Benefit Trade-off Context isolation Startup overhead (each subagent gathers its own context) Parallel execution Higher token usage (multiple contexts running simultaneously) Specialized focus Latency (may be slower than main agent for simple tasks) Token and cost considerations Subagents consume tokens independently — Each subagent has its own context window and token usage. Running five subagents in parallel uses roughly five times the tokens of a single agent. Evaluate the overhead — For quick, simple tasks, the main agent is often faster. Subagents shine for complex, long-running, or parallel work. Subagents can be slower — The benefit is context isolation, not speed. A subagent doing a simple task may be slower than the main agent because it starts fresh. FAQ What are the built-in subagents? Cursor includes three built-in subagents: explore for codebase search, bash for running shell commands, and browser for browser automation via MCP. These handle context-heavy operations automatically. You don't need to configure them. Can subagents launch other subagents? Yes. Since Cursor 2.5, subagents can launch child subagents to create a tree of coordinated work. Nested launches require Task tool access in the current mode, and hooks or tool policies can block spawning. How do I see what a subagent is doing? Background subagents write output to ~/.cursor/subagents/ . The parent agent can read these files to check progress. What happens if a subagent fails? The subagent returns an error status to the parent agent. The parent can retry, resume with additional context, or handle the failure differently. Can I use MCP tools in subagents? Yes. Subagents inherit all tools from the parent, including MCP tools from configured servers. How do I debug a misbehaving subagent? Check the subagent's description and prompt. Ensure the instructions are specific and unambiguous. You can also test the subagent by invoking it explicitly with a simple task. Why is my subagent using a different model? Cursor overrides the configured model in three cases: the model is blocked by your team admin, the model requires Max Mode and you don't have it enabled, or the model isn't available on your plan. On legacy request-based plans without Max Mode, subagents run using Composer regardless of any model configuration. If your team admin has blocked Composer, subagents will only be able to run in Max Mode for request-based plans. Usage-based plans and Max Mode will default to the parent model. See model configuration for details. English English 简体中文 日本語 繁體中文 Español Français Português 한국어 Русский Türkçe Bahasa Indonesia Deutsch हिन्दी

API Copy page Share feedback Explain more Cloud Agents API Public beta The Cloud Agents API v1 is in public beta. APIs may change before general availability. The Cloud Agents API lets you programmatically launch and manage cloud agents that work on your repositories. The Cloud Agents API uses Basic Authentication . Generate a user API key from Cursor Dashboard → Integrations , or use a service account API key . For details on authentication methods, rate limits, and best practices, see the API Overview . View the full OpenAPI specification for detailed schemas and examples. Webhooks are coming soon. The legacy v0 API still supports them — see Webhooks . Migrating from v0? This API splits work into a durable agent plus per-prompt runs, replacing the flatter v0 surface. The legacy v0 reference remains available. Endpoints Create An Agent POST /v1/agents Create a Cloud Agent and immediately enqueue its initial run. The response returns both the durable agent and the initial run . Request Body prompt object (required) The task prompt for the agent, including optional images. prompt.text string (required) The instruction text for the agent. prompt.images array (optional) Array of base64-encoded image inputs. Maximum 5 images, 15 MB each. model object (optional) Model selection. Omit this field to use the configured default. When omitted, Cursor resolves your user default model, then your team default model, then a system default. model.id string (required if model provided) An explicit model ID returned by GET /v1/models (for example, claude-4-sonnet-thinking ). model.params array (optional) Per-model parameters to apply to the run, such as reasoning effort or max mode. Each item has an id and value . Use only parameters supported by the selected model. env object (optional) Execution environment target. Use a named cloud environment, or route to a self-hosted pool or machine . Mutually exclusive with explicit repos when selecting a named Cursor-hosted environment. env.type string (required if env provided) Execution environment type. cloud uses Cursor-hosted VMs; pool and machine route to self-hosted workers. env.name string (optional) Named Cursor-hosted environment, self-hosted pool, or self-hosted machine name. repos array (optional) Repository configuration. Mutually exclusive with a named cloud environment. Omit both repos and env to start a no-repo agent. Maximum 20 repositories. repos[0].url string (required unless prUrl is provided) GitHub repository URL (for example, https://github.com/your-org/your-repo ). repos[0].startingRef string (optional) Branch, tag, or commit hash to use as the starting point. repos[0].prUrl string (optional) GitHub pull request URL. When provided, the agent works on this PR's repository and branches; url and startingRef are ignored. branchName string (optional) Custom branch name for the agent to create. autoGenerateBranch boolean (optional, default: true) Whether to create a new branch ( true ) or push to an existing head branch ( false ). Only applies when repos[0].prUrl is provided. autoCreatePR boolean (optional) Whether Cursor should open a pull request when the run completes. skipReviewerRequest boolean (optional) Whether to skip requesting the user as a reviewer when Cursor opens a PR. Only applies when autoCreatePR is true . envVars object (optional) Session-scoped environment variables for the cloud agent. Values are encrypted at rest, injected into the agent's shell, and deleted with the agent. Names can't start with CURSOR_ . curl --request POST \ --url https://api.cursor.com/v1/agents \ -u YOUR_API_KEY: \ --header 'Content-Type: application/json' \ --data '{ "prompt": { "text": "Add a README with setup instructions" }, "model": { "id": "composer-2", "params": [ { "id": "thinking", "value": "high" } ] }, "repos": [ { "url": "https://github.com/your-org/your-repo", "startingRef": "main" } ], "autoCreatePR": true }' Response: { "agent" : { "id" : "bc-00000000-0000-0000-0000-000000000001" , "name" : "Add README with setup instructions" , "status" : "ACTIVE" , "env" : { "type" : "cloud" }, "repos" : [ { "url" : "https://github.com/your-org/your-repo" , "startingRef" : "main" } ], "branchName" : "cursor/add-readme" , "autoGenerateBranch" : true , "autoCreatePR" : true , "url" : "https://cursor.com/agents?id=bc-00000000-0000-0000-0000-000000000001" , "createdAt" : "2026-04-13T18:30:00.000Z" , "updatedAt" : "2026-04-13T18:30:00.000Z" , "latestRunId" : "run-00000000-0000-0000-0000-000000000001" }, "run" : { "id" : "run-00000000-0000-0000-0000-000000000001" , "agentId" : "bc-00000000-0000-0000-0000-000000000001" , "status" : "CREATING" , "createdAt" : "2026-04-13T18:30:00.000Z" , "updatedAt" : "2026-04-13T18:30:00.000Z" } } List Agents GET /v1/agents List agents for the authenticated user, newest first. Query Parameters limit number (optional) Number of agents to return. Default: 20, Max: 100. cursor string (optional) Pagination cursor from nextCursor on the previous response. prUrl string (optional) Filter agents by GitHub pull request URL. includeArchived boolean (optional, default: true) Whether to include archived agents in the response. List items only include the durable identity fields. Call GET /v1/agents/{id} to load the full record ( repos , branchName , autoCreatePR , etc.). curl --request GET \ --url 'https://api.cursor.com/v1/agents?limit=20' \ -u YOUR_API_KEY: Response: { "items" : [ { "id" : "bc-00000000-0000-0000-0000-000000000001" , "name" : "Add README with setup instructions" , "status" : "ACTIVE" , "env" : { "type" : "cloud" }, "url" : "https://cursor.com/agents?id=bc-00000000-0000-0000-0000-000000000001" , "createdAt" : "2026-04-13T18:30:00.000Z" , "updatedAt" : "2026-04-13T18:45:00.000Z" , "latestRunId" : "run-00000000-0000-0000-0000-000000000001" } ], "nextCursor" : "bc-00000000-0000-0000-0000-000000000002" } Get An Agent GET /v1/agents/{id} Retrieve durable metadata for an agent. Execution status lives on runs — fetch latestRunId and call Get A Run to read run state. Path Parameters id string Unique identifier for the agent (for example, bc-00000000-0000-0000-0000-000000000001 ). curl --request GET \ --url https://api.cursor.com/v1/agents/bc-00000000-0000-0000-0000-000000000001 \ -u YOUR_API_KEY: Response: { "id" : "bc-00000000-0000-0000-0000-000000000001" , "name" : "Add README with setup instructions" , "status" : "ACTIVE" , "env" : { "type" : "cloud" }, "repos" : [ { "url" : "https://github.com/your-org/your-repo" , "startingRef" : "main" } ], "branchName" : "cursor/add-readme" , "autoGenerateBranch" : true , "autoCreatePR" : true , "url" : "https://cursor.com/agents?id=bc-00000000-0000-0000-0000-000000000001" , "createdAt" : "2026-04-13T18:30:00.000Z" , "updatedAt" : "2026-04-13T18:30:00.000Z" , "latestRunId" : "run-00000000-0000-0000-0000-000000000001" } Create A Run POST /v1/agents/{id}/runs Send a follow-up prompt to an existing active agent. The new run uses the agent's current conversation and workspace state. Only one run can be active per agent. Calling this while another run is CREATING or RUNNING returns 409 agent_busy . Wait for the existing run to terminate, or cancel it. Path Parameters id string Unique identifier for the agent (for example, bc-00000000-0000-0000-0000-000000000001 ). Request Body prompt object (required) The follow-up prompt, including optional images. prompt.text string (required) The follow-up instruction text. prompt.images array (optional) Array of base64-encoded image inputs. Maximum 5 images, 15 MB each. curl --request POST \ --url https://api.cursor.com/v1/agents/bc-00000000-0000-0000-0000-000000000001/runs \ -u YOUR_API_KEY: \ --header 'Content-Type: application/json' \ --data '{ "prompt": { "text": "Also add troubleshooting steps" } }' Response: { "run" : { "id" : "run-00000000-0000-0000-0000-000000000002" , "agentId" : "bc-00000000-0000-0000-0000-000000000001" , "status" : "CREATING" , "createdAt" : "2026-04-13T18:50:00.000Z" , "updatedAt" : "2026-04-13T18:50:00.000Z" } } List Runs GET /v1/agents/{id}/runs List runs for an agent, newest first. Path Parameters id string Unique identifier for the agent. Query Parameters limit number (optional) Number of runs to return. Default: 20, Max: 100. cursor string (optional) Pagination cursor from nextCursor on the previous response. curl --request GET \ --url 'https://api.cursor.com/v1/agents/bc-00000000-0000-0000-0000-000000000001/runs?limit=20' \ -u YOUR_API_KEY: Response: { "items" : [ { "id" : "run-00000000-0000-0000-0000-000000000002" , "agentId" : "bc-00000000-0000-0000-0000-000000000001" , "status" : "RUNNING" , "createdAt" : "2026-04-13T18:50:00.000Z" , "updatedAt" : "2026-04-13T18:51:00.000Z" } ], "nextCursor" : null } Get A Run GET /v1/agents/{id}/runs/{runId} Retrieve status and timestamps for a specific run. Path Parameters id string Unique identifier for the agent. runId string Unique identifier for the run (for example, run-00000000-0000-0000-0000-000000000001 ). curl --request GET \ --url https://api.cursor.com/v1/agents/bc-00000000-0000-0000-0000-000000000001/runs/run-00000000-0000-0000-0000-000000000001 \ -u YOUR_API_KEY: Response: { "id" : "run-00000000-0000-0000-0000-000000000001" , "agentId" : "bc-00000000-0000-0000-0000-000000000001" , "status" : "FINISHED" , "createdAt" : "2026-04-13T18:30:00.000Z" , "updatedAt" : "2026-04-13T18:45:00.000Z" } Stream A Run GET /v1/agents/{id}/runs/{runId}/stream Stream Server-Sent Events (SSE) for one run. The stream is scoped to the requested run and does not replay prior runs. Event types status — run status update. Payload: { runId, status } . assistant — assistant text delta. Payload: { text } . thinking — thinking text delta. Payload: { text } . tool_call — tool call status update. heartbeat — keepalive event. result — terminal run status. Payload: { runId, status } . error — stream error. Payload: { code, message } . done — stream complete. Payload: {} . Resuming a stream SSE responses include id values when available. To resume after a disconnect, reconnect with Last-Event-ID set to the most recent received event id. The event id must belong to the requested run; otherwise the request returns 400 invalid_last_event_id . Retention Stream responses include the X-Cursor-Stream-Retention-Seconds header. After the retention window elapses, this endpoint may return 410 stream_expired . Treat that as a signal to read terminal state via Get A Run instead of retrying the stream. curl --request GET \ --url https://api.cursor.com/v1/agents/bc-00000000-0000-0000-0000-000000000001/runs/run-00000000-0000-0000-0000-000000000001/stream \ -u YOUR_API_KEY: \ --header 'Accept: text/event-stream' Example stream: event: status data: {"runId":"run-00000000-0000-0000-0000-000000000001","status":"RUNNING"} id: 1713033000000-0 event: assistant data: {"text":"I'll update the README now."} id: 1713033010000-0 event: result data: {"runId":"run-00000000-0000-0000-0000-000000000001","status":"FINISHED"} id: 1713033010000-0 event: done data: {} Cancel A Run POST /v1/agents/{id}/runs/{runId}/cancel Cancel the active run for an agent. Cancellation is terminal — the run transitions to CANCELLED and cannot be resumed. To continue the conversation, create a new run on the same agent. Cancelling a run that is already in a terminal state, or one that was never active, returns 409 run_not_cancellable . Path Parameters id string Unique identifier for the agent. runId string Unique identifier for the run to cancel. curl --request POST \ --url https://api.cursor.com/v1/agents/bc-00000000-0000-0000-0000-000000000001/runs/run-00000000-0000-0000-0000-000000000001/cancel \ -u YOUR_API_KEY: Response: { "id" : "run-00000000-0000-0000-0000-000000000001" } Artifacts Artifacts are agent-scoped because the workspace persists across runs. List Artifacts GET /v1/agents/{id}/artifacts List artifacts produced by an agent. Each artifact's path is relative to the workspace's artifacts/ directory. Pass the path value returned here directly to Download An Artifact . v1 paths are relative; absolute v0 paths ( /opt/cursor/artifacts/... ) are not accepted. Path Parameters id string Unique identifier for the agent. curl --request GET \ --url https://api.cursor.com/v1/agents/bc-00000000-0000-0000-0000-000000000001/artifacts \ -u YOUR_API_KEY: Response: { "items" : [ { "path" : "artifacts/screenshot.png" , "sizeBytes" : 12345 , "updatedAt" : "2026-04-13T18:45:00.000Z" } ] } Download An Artifact GET /v1/agents/{id}/artifacts/download Retrieve a temporary 15-minute presigned S3 URL for a specific artifact. Path Parameters id string Unique identifier for the agent. Query Parameters path string Relative artifact path returned by List Artifacts (for example, artifacts/screenshot.png ). Must be under artifacts/ . curl --request GET \ --url 'https://api.cursor.com/v1/agents/bc-00000000-0000-0000-0000-000000000001/artifacts/download?path=artifacts/screenshot.png' \ -u YOUR_API_KEY: Response: { "url" : "https://cloud-agent-artifacts.s3.us-east-1.amazonaws.com/..." , "expiresAt" : "2026-04-13T19:00:00.000Z" } Agent Lifecycle Archive An Agent POST /v1/agents/{id}/archive Archive an agent. Archived agents remain readable but cannot accept new runs until unarchived. Use this for reversible "soft delete" flows. Path Parameters id string Unique identifier for the agent. curl --request POST \ --url https://api.cursor.com/v1/agents/bc-00000000-0000-0000-0000-000000000001/archive \ -u YOUR_API_KEY: Unarchive An Agent POST /v1/agents/{id}/unarchive Unarchive an agent so it can accept new runs again. Path Parameters id string Unique identifier for the agent. curl --request POST \ --url https://api.cursor.com/v1/agents/bc-00000000-0000-0000-0000-000000000001/unarchive \ -u YOUR_API_KEY: Delete An Agent Permanently DELETE /v1/agents/{id} Permanently delete an agent. This action is irreversible. Use Archive for reversible removal. Path Parameters id string Unique identifier for the agent. curl --request DELETE \ --url https://api.cursor.com/v1/agents/bc-00000000-0000-0000-0000-000000000001 \ -u YOUR_API_KEY: Worker Tokens Create A User-Scoped Worker Token POST /v1/sub-tokens Create a one-hour user-scoped token for a My Machines worker to run as an active team member. Requires an agent-scoped team service account API key. User-scoped tokens can't mint other user-scoped tokens. The returned token expires after 1 hour and cannot refresh itself. Mint a new token with the service account API key when you need to refresh a running worker. Request Body Specify exactly one of the following to identify the target user: forUserEmail string (optional) Active team member email. Case-insensitive. forUserId integer (optional) Active team member's numeric Cursor user ID. By email: curl --request POST \ --url https://api.cursor.com/v1/sub-tokens \ --header "Authorization: Bearer $CURSOR_SERVICE_ACCOUNT_API_KEY " \ --header "Content-Type: application/json" \ --data '{ "forUserEmail": "alice@company.com" }' By user ID: curl --request POST \ --url https://api.cursor.com/v1/sub-tokens \ --header "Authorization: Bearer $CURSOR_SERVICE_ACCOUNT_API_KEY " \ --header "Content-Type: application/json" \ --data '{ "forUserId": 42 }' Response: { "accessToken" : "eyJ..." , "expiresAt" : "2026-04-24T19:00:00.000Z" , "userId" : 42 , "teamId" : 456 } Metadata Endpoints API Key Info GET /v1/me Retrieve information about the API key being used for authentication. curl --request GET \ --url https://api.cursor.com/v1/me \ -u YOUR_API_KEY: Response: { "apiKeyName" : "Production API Key" , "createdAt" : "2026-04-13T18:30:00.000Z" , "userEmail" : "developer@example.com" } List Models GET /v1/models Returns a recommended set of explicit model IDs you can pass to the model.id field on Create An Agent . Model parameters use the same model.params shape as the TypeScript SDK ModelSelection . To use the configured default model, omit model from the request body. Cursor resolves your user default model, then your team default model, then a system default. curl --request GET \ --url https://api.cursor.com/v1/models \ -u YOUR_API_KEY: Response: { "items" : [ "claude-4-sonnet-thinking" , "gpt-5.2" , "claude-4.5-sonnet-thinking" ] } List GitHub Repositories GET /v1/repositories List GitHub repositories accessible to the authenticated user through Cursor's GitHub App installation. This endpoint has very strict rate limits. Limit requests to 1 / user / minute , and 30 / user / hour. This request can take tens of seconds to respond for users with access to many repositories. Make sure to handle this information not being available gracefully. curl --request GET \ --url https://api.cursor.com/v1/repositories \ -u YOUR_API_KEY: Response: { "items" : [ { "url" : "https://github.com/your-org/your-repo" } ] } English English 简体中文 日本語 繁體中文 Español Français Português 한국어 Русский Türkçe Bahasa Indonesia Deutsch हिन्दी

Integrations GitLab The GitLab integration connects your repositories so you can use features like Cloud Agents and Bugbot . Setup GitLab.com GitLab Self-Hosted Requires Cursor admin access and GitLab maintainer access. GitLab integration requires a paid GitLab plan (Premium or Ultimate). Project access tokens, which are required for this integration, are not available on GitLab Free. Go to Integrations in the dashboard Click Connect next to GitLab (or Manage Connections if already connected) Follow the GitLab installation flow Back on the Integrations tab, click Manage next to your GitLab connection and select Sync Repos Return to the dashboard to configure features on your repositories To disconnect your GitLab account, return to the integrations dashboard and click Disconnect Account . Advanced networking Self-hosted instances support multiple connection methods beyond IP whitelisting. PrivateLink (AWS) or Private Service Connect (GCP) Available for Enterprise customers. Allow Cursor to access your instance over a private network connection. Contact your Cursor representative for setup. Best for: Instances behind a firewall on a private network in AWS, Azure, or GCP Security: HTTPS encryption with optional mTLS, PrivateLink/Service Connect, VPC allowlisting, service account access tokens Drawbacks: Only supports public clouds with private networking connections between VPCs Reverse Proxy Tunnel Available for Enterprise customers. Run a reverse proxy tunnel on-premises that establishes a long-lived websocket connection to Cursor's servers. Network requests are forwarded through to your instance. Requires no inbound network access. Contact your Cursor representative for setup. Best for: Environments without inbound network access Security: HTTPS encryption, service account access tokens Drawbacks: Introduces additional complexity, maintenance requirements, and potential security considerations compared to more direct connection methods Next steps Once your GitLab integration is connected, configure the features that use it: Bugbot — automated PR reviews that catch bugs and security issues Cloud Agents — AI agents that run in the cloud on your repositories English English 简体中文 日本語 繁體中文 Español Français Português 한국어 Русский Türkçe Bahasa Indonesia Deutsch हिन्दी

Integrations Xcode Xcode 26.3+ exposes a built-in MCP server that gives Cursor direct access to your Xcode projects. Cursor's agent can read and edit files, trigger builds, run tests, capture SwiftUI previews, and search Apple's documentation; all without leaving your editor. This works through xcrun mcpbridge , a binary Apple ships with Xcode that translates MCP protocol messages into Xcode's internal XPC layer. You configure it once, and Cursor treats Xcode's 20 built-in tools like any other MCP server. Prerequisites macOS with Xcode 26.3 or later installed A paid Cursor plan An Xcode project open in Xcode (Xcode must be running) Enable MCP in Xcode Before Cursor can connect, turn on Xcode's MCP bridge: 1 Open Xcode settings Go to Xcode > Settings > Intelligence . 2 Enable MCP Under Model Context Protocol , toggle Xcode Tools on. Set up Cursor Pick whichever method suits your workflow. Option 1: MCP settings UI 1 Open MCP settings Go to Cursor Settings > Features > MCP . 2 Add the server Click Add New MCP Server . Set the transport to stdio , name it xcode-tools , and enter xcrun mcpbridge as the command. Option 2: mcp.json Add an entry to your MCP config file : ~/.cursor/mcp.json { "mcpServers" : { "xcode-tools" : { "command" : "xcrun" , "args" : [ "mcpbridge" ] } } } Option 3: Cursor CLI If you use the Cursor CLI , register the server from your terminal: agent mcp add xcode-tools -- xcrun mcpbridge The CLI shares the same MCP config as the editor, so the server appears in both. Available tools Xcode exposes 20 MCP tools across five categories: File operations XcodeRead - Read file contents (up to 600 lines per call, with offset/limit for larger files) XcodeWrite - Create or overwrite files XcodeUpdate - Apply targeted edits to existing files XcodeGrep - Search file contents with regex XcodeGlob - Find files by pattern XcodeLS - List directory contents XcodeMakeDir - Create directories XcodeRM - Remove files or directories XcodeMV - Move or rename files Build and test BuildProject - Build the active scheme GetBuildLog - Retrieve build logs, filterable by severity, regex, or file glob RunAllTests - Run the full test suite RunSomeTests - Run specific test classes or methods GetTestList - List available tests Diagnostics XcodeListNavigatorIssues - Show warnings and errors from the Issue Navigator XcodeRefreshCodeIssuesInFile - Re-check a file for code issues Intelligence RenderPreview - Capture a screenshot of a SwiftUI preview DocumentationSearch - Semantic search across Apple's documentation and WWDC transcripts ExecuteSnippet - Run a Swift code snippet Workspace XcodeListWindows - List open Xcode windows and tabs Example workflow A typical Cursor + Xcode workflow looks like this: Open your project in both Cursor and Xcode Ask Cursor's agent to add a feature or fix a bug The agent uses XcodeRead and XcodeGrep to understand your code It edits files with XcodeWrite or XcodeUpdate It runs BuildProject to check for errors, reads results with GetBuildLog It runs tests with RunSomeTests to verify the change It captures a SwiftUI preview with RenderPreview to confirm the UI You stay in Cursor the whole time. Xcode handles compilation, testing, and previews in the background. Cursor CLI with Xcode The Cursor CLI also works with Xcode's MCP tools. This is useful for headless workflows, CI pipelines, or terminal-first developers. # Run agent with Xcode tools available agent "Add unit tests for the NetworkManager class" The agent picks up the xcode-tools MCP server from your config and uses the same tools available in the editor. Troubleshooting Cursor can't find the xcode-tools server Make sure Xcode is running with a project open. The xcrun mcpbridge process needs an active Xcode session to communicate with. Tools show errors about missing tabIdentifier Some Xcode MCP tools need a workspace context. Confirm you have a project or workspace open in Xcode, not an empty window. Build or test tools time out Large projects take longer to build. Check Xcode's build progress directly. The MCP bridge waits for Xcode's response, so timeouts usually mean the underlying operation is still running. MCP toggle missing in Xcode settings You need Xcode 26.3 or later. Check your version under Xcode > About Xcode and update through the Mac App Store or Apple Developer downloads . xcrun: error: unable to find utility "mcpbridge" Your system is pointed at Command Line Tools instead of the full Xcode installation. Fix this by running: sudo xcode-select -s /Applications/Xcode.app/Contents/Developer sudo xcodebuild -runFirstLaunch Then confirm the bridge is available: xcrun --find mcpbridge This should return a file path, not an error. Once it does, open Xcode with your project, go to Settings > Intelligence > Model Context Protocol , and enable Allow external agents . Then toggle the Xcode MCP server back on in Cursor settings. You should see a permission dialog in Xcode confirming the connection. Related MCP overview Complete MCP guide with setup, configuration, and authentication iOS & macOS (Swift) Swift development workflow with Cursor, Sweetpad, and Xcode Build Server Cursor CLI Use Cursor's agent from the terminal CLI MCP commands Manage MCP servers from the command line English English 简体中文 日本語 繁體中文 Español Français Português 한국어 Русский Türkçe Bahasa Indonesia Deutsch हिन्दी

CLI Cursor CLI Cursor CLI lets you interact with AI agents directly from your terminal to write, review, and modify code. Whether you prefer an interactive terminal interface or print automation for scripts and CI pipelines, the CLI provides powerful coding assistance right where you work. Getting started # Install (macOS, Linux, WSL) curl https://cursor.com/install -fsS | bash # Install (Windows PowerShell) irm 'https://cursor.com/install?win32=true' | iex # Run interactive session agent Interactive mode Start a conversational session with the agent to describe your goals, review proposed changes, and approve commands: # Start interactive session agent # Start with initial prompt agent "refactor the auth module to use JWT tokens" Modes The CLI supports the same modes as the editor. Switch between modes using slash commands, keyboard shortcuts, or the --mode flag. Mode Description Shortcut Agent Full access to all tools for complex coding tasks Default (no --mode value needed) Plan Design your approach before coding with clarifying questions Shift+Tab , /plan , --plan , --mode=plan Ask Read-only exploration without making changes /ask , --mode=ask Non-interactive mode Use print mode for non-interactive scenarios like scripts, CI pipelines, or automation: # Run with specific prompt and model agent -p "find and fix performance issues" --model "gpt-5.2" # Use with git changes included for review agent -p "review these changes for security issues" --output-format text Cloud Agent handoff Push your conversation to a Cloud Agent to continue running while you're away. Prepend & to any message: # Send a task to Cloud Agent mid-conversation & refactor the auth module and add comprehensive tests Pick up your Cloud Agent tasks on web or mobile at cursor.com/agents . Sessions Resume previous conversations to maintain context across multiple interactions: # List all previous chats agent ls # Resume latest conversation agent resume # Continue the previous session agent --continue # Resume specific conversation agent --resume= "chat-id-here" Sandbox controls Configure command execution settings with /sandbox or the --sandbox flag ( enabled or disabled ). Toggle sandbox mode on or off and control network access through an interactive menu. Settings persist across sessions. Max Mode Toggle Max Mode on models that support it using /max-mode [on|off] . Sudo password prompting Run commands requiring elevated privileges without leaving the CLI. When a command needs sudo , Cursor displays a secure, masked password prompt. Your password flows directly to sudo via a secure IPC channel; the AI model never sees it. English English 简体中文 日本語 繁體中文 Español Français Português 한국어 Русский Türkçe Bahasa Indonesia Deutsch हिन्दी

Integrations Slack With Cursor's integration for Slack, you can use Cloud Agents to work on your tasks directly from Slack by mentioning @cursor with a prompt. Get started Installation Go to Cursor integrations Click Connect next to Slack or go to installation page from here You'll be prompted to install the Cursor app for Slack in your workspace. After installing in Slack, you'll be redirected back to Cursor to finalize setup Connect GitHub (if not already connected) and pick a default repository Enable usage-based pricing Confirm privacy settings Start using Cloud Agents in Slack by mentioning @cursor How to use Mention @cursor and give your prompt. Cursor automatically picks the right repository and model based on your message and your recent agent activity. To use a specific repository, include its name in your message: @Cursor in cursor-app, fix the login bug @Cursor fix the auth issue in backend-api To use a specific model, mention it in your message: @Cursor with opus, fix the login bug @Cursor use gpt-5.2 to refactor the auth module Commands Run @Cursor help for an up-to-date command list. Command Description @Cursor [prompt] Start a Cloud Agent. In threads with existing agents, adds followup instructions @Cursor settings Configure defaults and channel's default repository @Cursor [options] [prompt] Use advanced options: branch , autopr @Cursor agent [prompt] Force create a new agent in a thread @Cursor list my agents Show your running agents Options Customize Cloud Agent behavior with these options: Option Description Example branch Specify base branch branch=main autopr Enable/disable automatic PR creation autopr=false Syntax Formats Natural: @Cursor with opus, fix the login bug in backend-api Inline: @Cursor branch=dev autopr= false Fix the login bug in backend-api Option precedence When combining options: Explicit values override defaults Later values override earlier ones if duplicated Inline options take precedence over settings modal defaults The bot parses options from anywhere in the message, allowing natural command writing. Using thread context Cloud Agents understand and use context from existing thread discussions. Useful when your team discusses an issue and you want the agent to implement the solution based on that conversation. Cloud Agents read the entire thread for context when invoked, understanding and implementing solutions based on the team's discussion. When to use force commands When do I need @Cursor agent ? In threads with existing agents, @Cursor [prompt] adds followup instructions (only works if you own the agent). Use @Cursor agent [prompt] to launch a separate agent. When do I need Add follow-up (from context menu)? Use the context menu (⋯) on an agent's response for followup instructions. Useful when multiple agents exist in a thread and you need to specify which one to follow up on. Status updates & handoff When Cloud Agent runs, you first get an option to Open in Cursor . When Cloud Agent completes, you get a notification in Slack and an option to view the created PR in GitHub. Managing agents To see all running agents, run @Cursor list my agents . Manage Cloud Agents using the context menu by clicking the three dots (⋯) on any agent message. Available options: Add follow-up : Add instructions to an existing agent Delete : Stop and archive the Cloud Agent View request ID : View unique request ID for troubleshooting (include when contacting support) Give feedback : Provide feedback about agent performance Configuration Manage default settings and privacy options from Dashboard → Cloud Agents . Settings Default Model Used when no model is specified in your message. See settings for available options. Repository Selection Cursor automatically selects the right repository based on: Your message content — Repository names or keywords in your prompt Recent agent activity — Repositories you've used recently Routing rules — Custom keyword-to-repo mappings (see below) Default repository — Fallback when no match is found To use a specific repository, include its name in your message. For example: @Cursor in mobile-app, fix the login bug . Base Branch Starting branch for Cloud Agent. Leave blank to use the repository's default branch (often main ) Channel Settings Configure default settings at the channel level using @Cursor settings . These settings are per team and override your personal defaults for that channel. Channel settings only apply to public channels. Particularly useful when: Different channels work on different repositories Teams want consistent settings across all members To configure channel settings: Run @Cursor settings in the desired channel Set the default repository for that channel All team members using Cloud Agents in that channel use these defaults Channel settings take precedence over personal defaults but can be overridden by mentioning a specific repo in your message. Routing Rules Routing rules let you define keywords that automatically map to specific repositories. When your message contains specific keywords, Cursor routes the agent to the associated repo. Setting up routing rules Go to Dashboard → Cloud Agents Find the Routing Rules section Add keyword-to-repository mappings Example rules Keyword Repository frontend acme/web-app mobile acme/mobile-app api acme/backend-services docs acme/documentation With these rules configured: @Cursor fix the frontend nav bug → routes to acme/web-app @Cursor update the mobile onboarding flow → routes to acme/mobile-app @Cursor add rate limiting to the api → routes to acme/backend-services How routing works Cursor evaluates your message in this order: Your message content — Repository names or keywords in your prompt Recent agent activity — Repositories you've used recently Routing rules — Custom keyword-to-repo mappings Channel default — The repository set for this channel Default repository — Fallback when no match is found Privacy Cloud Agents support Privacy Mode. Read more about Privacy Mode or manage your privacy settings . Privacy Mode (Legacy) is not supported. Cloud Agents require temporary code storage while running. Display Agent Summary Display agent summaries and diff images. May contain file paths or code snippets. Can be turned On/Off. Display Agent Summary in External Channels For Slack Connect with other workspaces or channels with external members like Guests, choose to display agent summaries in external channels. Permissions Cursor requests these Slack permissions for Cloud Agents to work within your workspace: Permission Description app_mentions:read Detects @mentions to start Cloud Agents and respond to requests channels:history Reads previous messages in threads for context when adding follow-up instructions channels:join Automatically joins public channels when invited or requested channels:read Accesses channel metadata (IDs and names) to post replies and updates chat:write Sends status updates, completion notifications, and PR links when agents finish files:read Downloads shared files (logs, screenshots, code samples) for additional context files:write Uploads visual summaries of agent changes for quick review groups:history Reads previous messages in private channels for context in multi-turn conversations groups:read Accesses private channel metadata to post responses and maintain conversation flow im:history Accesses direct message history for context in continued conversations im:read Reads DM metadata to identify participants and maintain proper threading im:write Initiates direct messages for private notifications or individual communication mpim:history Accesses group DM history for multi-participant conversations mpim:read Reads group DM metadata to address participants and ensure proper delivery reactions:read Observes emoji reactions for user feedback and status signals reactions:write Adds emoji reactions to mark status - ⏳ for running, ✅ for completed, ❌ for failed team:read Identifies workspace details to separate installations and apply settings users:read Matches Slack users with Cursor accounts for permissions and secure access Disclaimer Cursor can make mistakes. Please double-check code and responses. Privacy Policy For information about how Cursor collects, uses, and protects your data, see our Privacy Policy . English English 简体中文 日本語 繁體中文 Español Français Português 한국어 Русский Türkçe Bahasa Indonesia Deutsch हिन्दी

Models GPT-5.5 Model ID gpt-5.5 Context window 272k Max context 1M Provider OpenAI Capabilities Agent Thinking Speed Medium Cost Medium Intelligence Frontier GPT-5.5 is OpenAI's most intelligent model in Cursor. It keeps momentum on long-running work and stays on task for significantly longer before stopping early, which matters most in complex, multi-step coding sessions. Strengths Highest overall intelligence in the GPT-5 family for challenging coding and reasoning tasks. More persistent on long-running work; it keeps digging instead of ending early when tasks are still incomplete. Strong at maintaining context and execution quality across larger, multi-step workflows. More token-efficient than GPT-5.4 on complex, long-running tasks, which helps reduce total token usage for the same outcomes. Limitations Higher per-token pricing than GPT-5.3 Codex. Throughput can be lower on straightforward tasks where smaller models are already enough. Tools GPT-5.5 has access to all agent tools when used with Cursor including: Semantic search Search your indexed codebase by meaning, not exact matches. Search files and folders Find files by name, read directory structures, and grep for patterns. Web Generate search queries and fetch results from the web. Read files Read file contents, including images for vision-capable models. Edit files Suggest edits and apply them automatically. Run shell commands Execute terminal commands and monitor output. Browser Control a browser to take screenshots, test applications, and verify visual changes. See the Browser documentation . Image generation Generate images from text descriptions or reference images. Ask questions Ask clarifying questions while continuing to work in the background. Fetch rules Retrieve rules based on type and description. Learn more about how tools work and tool calling fundamentals . Pricing Cursor plans include two usage pools. GPT-5.5 draws from the API pool, which charges at the rates below. Individual plans include at least $20 of API usage each month (more on higher tiers). All prices are per million tokens. Name Input Cache Write Cache Read Output GPT-5.5 $5 - $0.5 $30 GPT-5.5 (Fast Mode) $12.5 - $1.25 $75 GPT-5.5 (Long Context (>272k)) $10 - $1 $45 A Fast mode tier ( gpt-5.5-fast ) is available for priority processing. It has higher per-token pricing than standard mode. GPT-5.5 uses the same cache discount, regional endpoint pricing, and long-context pricing behavior as GPT-5.4. When input exceeds 272k tokens (long context / Max Mode), input pricing doubles and output pricing is 1.5x the standard rate. English English 简体中文 日本語 繁體中文 Español Français Português 한국어 Русский Türkçe Bahasa Indonesia Deutsch हिन्दी

Cloud Agents Security Agents Security Agents scan your code for security bugs, risky patterns, and vulnerabilities. This feature is available only for Teams and Enterprise plans. How it works Security Agents include two Cursor-managed agent types: Security Reviewer checks pull requests before they merge. Use it to catch vulnerabilities during code review. Vulnerability Scanner scans your codebase at rest. Use it to find pre-existing vulnerabilities, long-standing issues, and problems missed during PR review. Both agent types run on the Automations platform and require Cloud Agents. Setup To configure Security Agents, open the Security Agents Dashboard and create your first agent. Triggers Security Reviewer agents support Git-based Automations triggers, including pull request and merge request events. Use these triggers to run security checks when code changes. Vulnerability Scanner agents support cron-based triggers. Use these triggers to scan your codebase on a recurring schedule, independent of pull request activity. Security Checks Both agent types include built-in security checks. Enable or disable individual checks based on what you want each agent to review. Custom instructions Use custom instructions to give each agent more context. You can describe the types of issues to prioritize, explain project-specific security expectations, or define how the agent should behave. Tools and MCPs Both agent types support tools and MCPs. Each agent needs at least one tool or MCP to run. Use tools and MCPs to connect Security Agents to the systems where your team tracks security work. Send vulnerabilities to a Slack channel, issue tracker, or another connected system. Add custom instructions that explain when and how the agent should use each MCP. Give the agent extra context from tools or MCPs before it reports a finding. Environment Setup Security Agents run on Cloud Agents. You can use Cursor's cloud with no additional setup, or configure self-hosted Cloud Agents to run reviews in your own environment. Billing Security Agents are billed at the team usage level: Usage is charged to the team's usage pool. Agents run under a shared team service account, so they don't affect any individual user's usage. Analytics Security Agents track three key metrics across agent runs: Vulnerabilities found : the number of security findings reported by agents. Issues fixed : the number of findings that were resolved after they were reported. Resolution rate : the percentage of reported findings that were fixed. To determine whether an issue was fixed, Cursor uses LLMs to review incremental diffs and assess whether the flagged issue was resolved. Viewing Runs Every agent run is tracked in the dashboard. Use the run history to see when an agent ran, which tools it used, its final status, and how long it took. Open a run to inspect the underlying Cloud Agent for more detail about what the agent did. English English 简体中文 日本語 繁體中文 Español Français Português 한국어 Русский Türkçe Bahasa Indonesia Deutsch हिन्दी