Cursor Projects: Coordinate Long-Running Agent Work Safely
Cursor Projects is built for software work that will not fit into one chat: a feature spread across repositories, a migration that needs dozens of pull requests, or maintenance that keeps coming back. You give one persistent coordinator a goal. It plans the work, delegates implementation to other agents, and returns the results for review. The important shift is not simply “more agents.” It is managing shared context, parallel execution, recurring triggers, and human review as one long-running unit.
Cursor announced Projects in beta on September 10, 2026 and said it was rolling out to all users. Whether the menu is visible, how much agent usage is available, and what it costs can still depend on your account, plan, and organization policies. This guide explains the public feature and a cautious setup path; it does not claim firsthand results from running it on a production repository.
How Projects differs from an ordinary agent chat
A normal agent conversation is a good fit for a bounded request such as fixing one reproducible bug. In Projects, the coordinator is not the coder. Its job is to break down the objective, launch implementation agents, track dependencies, and bring the work back for inspection. A Project runs on its own cloud computer, so closing your laptop does not stop it. When a task must be tested on your machine, the coordinator can start a local agent for that part of the work.
| Option | Best fit | Main limitation |
|---|---|---|
| Regular chat or local agent | One-file edits, short research, and bugs you can verify immediately | You must preserve decisions and context as the conversation grows. |
| One Cloud Agent | A single independent job that can finish in the background | You still coordinate dependencies and the longer plan. |
| Cursor Projects | Multi-PR, multi-repository, or recurring work with a durable objective | Broad permissions and unclear review rules can expand the blast radius. |
Six things to prepare before the first run
- A clean remote baseline. Decide which GitHub, GitLab, Azure DevOps Services, or Bitbucket Cloud repositories the Project needs, and confirm the default branch builds. Cloud Agents clone remote repositories and work on separate branches. Uncommitted local edits do not automatically follow them.
- An acceptance contract. Replace “build the feature” with the allowed scope, test commands, pass criteria, excluded files, required documentation, and rollback expectation.
- A review owner. Name the person who will inspect and merge pull requests. Payments, identity and access, personal data, and deployment configuration should not be auto-merge candidates.
- A reproducible environment. Put setup and test instructions in the repository instead of making every agent guess.
- Minimal secrets and network access. Inject only the secrets the environment needs. Prefer an outbound allowlist when practical, and never commit credentials to the repository.
- A spending boundary. Cloud Agents are billed at API pricing for the selected model, and larger context windows can increase usage. Set a spend limit and a review interval before scaling parallel work.
From the left navigation to a reviewable pull request
1. Open Projects and pin the objective
Open Projects from Cursor’s left navigation and start a new Project. If the beta has not reached your account, the item may not be present yet. Write a bounded result: “Add an administrator CSV export while preserving the existing authorization rules and API response contract” is more useful than “improve the app.”
2. Connect only the repositories it needs
A Cloud Agent needs read-write access to the target repository and any dependent repositories or submodules. Team membership alone does not grant visibility into a teammate’s agent. Each viewer must connect their own source-control account and have access to the repository involved.
3. Put a work contract in the first message
Include the goal, editable areas, forbidden areas, test commands, pull-request boundaries, and conditions that require a human decision. For example: “Research and propose a plan first; wait for approval; do not change database schema, authentication, or deployment files; keep every pull request independently reversible.” A prompt is an instruction, not an enforcement boundary, so repository permissions and network controls must still be configured separately.
4. Review the plan, then authorize one small pilot
Do not begin with a fleet producing dozens of pull requests. Inspect the coordinator’s dependency order and approve one low-impact slice with an objective test. Ask each pull request to state the changed files, checks run, remaining risks, and rollback method. That evidence makes the next review faster.
5. Review an evidence bundle, not a completion claim
“The agent says it is done” is not verification. Check the diff, test output, CI state, documentation, affected repositories, and the rollback path. A local agent can handle browser or machine-specific checks, but its actual output should remain distinguishable from an expected result written in the plan.
6. Add recurring triggers only after the pilot passes
Projects can subscribe to a Slack channel, a schedule, or pull-request events. Start with one channel, one repository, and one event type. It can open a proposed fix, while merge and deployment remain human-controlled. Expand only after you have measured false positives and review load.
Three practical Project designs
Example 1: A cross-stack export feature
Goal: let an administrator export filtered records as CSV. Provide the frontend and API repositories, authorization rules, API contract, sample data, and test commands. The coordinator can first map the data flow, then separate API, interface, and documentation work. Even if agents create independent pull requests, the plan should show that the API contract must land before the UI depends on it. Review for authorization bypass, memory use on large exports, and spreadsheet formula injection. The deliverable is a set of independently reviewable pull requests, tests, and docs, not a sentence saying the feature works.
Example 2: A runtime upgrade across repositories
Goal: move services from an old runtime to a supported version. Choose one representative repository as the pilot and require build, test, and pre-deployment checks. Record what worked in shared context, group the remaining repositories by risk, and create pull requests in batches. This is easier to diagnose and roll back than one bulk change. Lockfiles, native modules, and CI images that resist mechanical replacement should remain on a separate review list.
Example 3: Continuous pull-request gardening
Goal: catch recurring design-system violations or a specific regression pattern. Begin by giving the Project a small set of historical pull requests and defining exactly when it should comment. Watch new pull requests, but initially allow only comments and suggested patches. Track false positives and the suggestions reviewers actually accept. Once the rule is stable, permit small fix pull requests. Security configuration, billing logic, and customer-data paths should always require human review.
Cost, security, and beta constraints
| Question | What the official material says | Practical response |
|---|---|---|
| Plans | The current pricing page lists limited Agent requests on Hobby, Cloud Agents on the $20/month Individual plan, and shared-context automations on Teams at $40 per user/month. | Even if Projects appears, confirm your actual limits and organization policy in the dashboard and checkout surface. |
| Usage cost | Cloud Agents are charged at API pricing for the selected model. Context-window size can affect usage. | Begin with a pilot repository and a spend limit, then compare usage by task type. |
| Code storage | Cloud Agents must store code in the cloud while they run. They support Privacy Mode and isolated VMs, but the risk model differs from local-only work. | Exclude sensitive repositories when policy does not allow this storage. |
| Network | You can allow all outbound access or restrict agents to an allowlist. | Permit only required package and source-control domains, and account for prompt injection from internet content. |
| Beta status | The feature is rolling out and may change. | Use small, reversible scopes and avoid automatic merging for important systems. |
Cursor published internal examples and productivity figures, but those are self-reported by the supplier. Evaluate Projects with measurements you control: pull-request rework, failed CI, review time, incident rate, and actual spend.
Common failure modes and the order to troubleshoot them
- Projects is missing: confirm the app is current and reload the account. If the item is still absent, the staged beta may not have reached you. Do not rely on an undocumented hidden route.
- Your local changes are missing: a Cloud Agent starts from clean remote state. Commit and push the needed work to a safe branch, or finish sensitive local changes before handing off.
- A repository or submodule is unavailable: check read-write access for the connected account and every dependent repository.
- A secret is unavailable: secrets are injected when an agent starts. Confirm the correct team and environment, then validate with a new run. Never print the value to logs or a pull request.
- The work drifts from the objective: add a short decision log, forbidden areas, and test procedure to shared context, then reduce the next batch.
- Spend grows faster than expected: inspect context size, parallel-agent count, selected models, and repeated failures in that order. Lower the cap and reduce independent work streams.
Who should try it first
Projects is a strong candidate for teams whose work naturally splits into several pull requests but still has clear acceptance criteria, reliable CI, and active code review. If requirements change daily, tests are missing, and one person merges everything immediately, parallelism can multiply confusion instead of progress. A better first Project is a documentation check, a non-critical migration, or a narrow regression monitor, not your core billing system.
If your real goal is packaging reusable team instructions and commands rather than coordinating a long-running body of work, the Claude Code plugins guide provides a more direct comparison point.
Launch checklist
- Is the objective, excluded scope, and definition of done written on one page?
- Does the remote baseline build, with test commands documented?
- Are repository, secret, and network permissions minimized?
- Is the first pull request small and reversible?
- Is a person assigned to inspect diffs and CI evidence?
- Is there a spend limit and a stop condition?
- Will subscriptions remain off until the pilot passes?
Korean version: 한국어로 읽기
Official sources
Sources checked September 17, 2026.
Comments
Post a Comment