Cover illustration for “Cursor Agent Mode on Large Monorepos”

Essay Agentic IDE Reviews

Cursor Agent Mode on Large Monorepos

Scoped rules, tight ignores, and isolation keep agents useful.

Cursor Agent Mode can work effectively on large monorepos, but its usefulness depends on how developers bound its work. Indexing makes a large repository searchable. Scoped rules, focused workspaces, and isolated execution make that search useful. Production safety then depends on a separate discipline, namely keeping autonomous edits behind branches, review, and CI gates.

What Cursor Agent Mode actually does when it runs inside a monorepo

Agent Mode is an autonomous loop. It searches code semantically, creates and modifies files, runs terminal commands, reads errors, and attempts corrections without requesting confirmation at every step. Instead of a developer copying a fix into related files and running tests manually, the agent can chain those operations together. The distinction is operational rather than cosmetic. It can act on the repository.

Search must tell dozens of packages apart, and edits can cross the boundaries between applications or areas of responsibility. Terminal commands may need scripts for the workspace. Error output can also point to types or modules in sibling packages that the agent has not explicitly opened. As a result, successful execution depends on retrieving the right surrounding code without treating every available package as equally relevant.

How Cursor indexes a large codebase and why the architecture matters for agent performance

Cursor builds a persistent semantic index rather than searching the repository from scratch for each request. Its embedding-based index is stored in Turbopuffer, and a trigram-style pattern-match index offers another way to find the right text. AST chunking adds structure-aware retrieval. These mechanisms underpin sub-second file retrieval across a large codebase. They also explain why repository search is more than a file scanner with a model attached.

Keeping that index current is a separate problem. Cursor uses Merkle-tree diffing to identify changed files and re-embeds only those. This keeps an edit from triggering a full indexing pass that blocks the editor. In a monorepo, that distinction becomes especially important because a local edit should not require work proportional to the whole repository. The architecture makes large-scale retrieval tractable, but the contents of the index still determine what the agent can retrieve.

What context the agent actually loads, and what that costs at monorepo scale

A searchable repository is not the same as a loaded context window. The code chunks it finds share that window with rules files, and instructions can fill the space before the code needed for the task arrives. Cursor treats AGENTS.md files as “Always” rules, loading their full contents on agent requests. In a monorepo with rules distributed throughout the directory tree, that behavior can defeat an otherwise narrow task. A prompt naming one file does not necessarily constrain the instructions loaded around it.

The Cursor Community Forum documents this failure directly. One report describes several hundred AGENTS.md files and says the agent will “often load all rules files across the entire repo.” Another forum account places the discovery change “Since 3.6,” although the official changelog does not document that change. The supplied record shows the regression across Cursor 3.6–3.10, but does not show which version reliably fixes it or which older version to pin.

This is a documented, reproducible failure mode. Loading hundreds of thousands of tokens of rules also increases session cost, potentially making root-level operation economically unviable. A separate report on symlinked-skills said the same AGENTS.md was injected nine times, with context reaching 181% on the first turn. Rules must therefore be configured before further agent work. Which rules belong everywhere, and which should load only for a particular package?

The three rules formats in use in 2026 and how to choose between them in a monorepo

The practical recommendation is to separate repository-wide conventions from package-specific instructions. Three rules families coexist in 2026, namely AGENTS.md,.cursorrules and its successor.cursor/rules/*.mdc, and Claude Code Skills. They are not interchangeable in their loading behavior. A small root AGENTS.md works for conventions that apply everywhere, but putting full instructions in hundreds of subdirectories risks context explosion. The presence of a rules file is not evidence that its contents will load at the right scope.

For Cursor-specific package rules,.mdc provides the necessary attachment mechanism. Its globs field scopes a rule to matching file paths, making it “Auto Attached” when the agent touches those files. Strong content then specifies the framework and version, permitted import relationships, forbidden patterns, and directory conventions. “Use best practices” provides no comparable constraint.

Teams using multiple AI harnesses may not be able to migrate completely to.mdc. For them, opening a subfolder instead of the repository root offers a mitigation without migration cost. Where migration is possible, the safest posture is one authoritative rules format, with alternatives empty or deleted. Otherwise, duplicated conventions can drift apart within weeks.

The.cursorignore configuration that keeps the index clean and the agent focused

Scoped rules control instructions, while.cursorignore controls the indexed working surface. On a large monorepo, this second control is essential because irrelevant files dilute retrieval and add re-embedding work. The recommended exclusions include node_modules, build outputs such as dist/, out/, and.next/, generated files, coverage directories,.env files, lock files, and unrelated packages. Cursor already respects.gitignore. The additional file keeps material out of agent search even when it belongs in version control, including generated TypeScript declarations, large vendored assets, and documentation builds.

Domain boundaries provide a useful further cut. When a session targets frontend work, excluding unrelated backend and data-pipeline domains sharpens retrieval and reduces cross-domain suggestions. After adding packages or reorganizing directories, the recommended refresh is “Cursor: Rebuild Index” from the command palette.

Teams running long monorepo sessions have reported that they use extreme amounts of RAM and need frequent editor restarts. Aggressive exclusions reduce the index footprint and memory pressure, but do not eliminate them.

Search must tell dozens of packages apart, and edits can cross the boundaries between applications or areas of responsibility.

How parallel agents and git worktrees distribute work across a large monorepo

Subagents, introduced in v2.4 in January 2026, allow a parent agent to delegate discrete subtasks to independent children with separate context windows. Rather than asking one agent to reason continuously across the root, the workflow can assign a package to each subagent.

The 14-package TypeScript migration case illustrates this pattern. Each agent received a scoped task with a verifiable success criterion, namely resolving all strict null check errors in its package. The unit of assessment becomes a bounded package diff.

Git worktrees formalize isolation at the agent level, while separate Cursor windows give packages independent, scoped indexes. Cursor’s April 24, 2026 changelog also introduced the /multitask workflow and multi-root workspaces in the Agents Window. Those workspaces allow a session to target reusable groups of folders spanning frontend, backend, and shared libraries. The resulting choice is not simply root access or total separation, but deliberate orchestration of the surfaces each task needs.

Cloud environments and the Environments API as the path around local RAM limits

Cursor shipped multi-repo cloud environments on May 13, 2026, with Dockerfile configuration improvements, faster layer caching, environment version history and rollback, and scoped secrets management. Agents can therefore run off the developer’s machine. That removes local RAM as a constraint on the cloud session.

Cursor’s October 16, 2026 changelog announced the Environments API in public beta. It lets teams create and manage cloud environments programmatically, including the operating-system dependencies, secrets scope, and repository list needed to reproduce an execution environment. This is useful for CI-adjacent work because configuration can be versioned.

Repository capacity remains a documentation gap. The changelog and API-reference pages give different limits, and the supplied versions of the reference also disagree. Consequently, the published figures do not establish a single dependable capacity contract for an integration. Cloud infrastructure makes larger autonomous sessions practical, but it does not settle their authority. If an agent can execute commands remotely, what prevents those commands from shipping unreviewed changes to main?

Cross-package boundary violations and the governance gap agent mode opens

The strongest objection is that plausible, executable code can violate architecture and reach production without review. An agent may suggest importing backend code into a frontend package when both are indexed and the import resolves. Unless package boundaries are explicitly codified in a scoped rule, successful resolution can substitute for architectural legitimacy. Even an explicit rule is not an enforcement boundary.

Cursor is a predictive engine. It can ignore instructions in favor of plausible output, while compromised or overly broad rules can introduce unintended instructions. Automatic context selection also means developers may not know which source files, configuration files, or environment variables reached the model. Those uncertainties complicate governance beyond the correctness of the final diff.

The command-execution path makes the risk immediate. Agent Mode can run commands that commit changes, and a repository permitting pushes to main or deployment on push can turn an unchecked session into a production change. Extended sessions add another weakness because reasoning quality can degrade as context is repeatedly compressed. Larger workspaces and cloud resources do not resolve either problem.

Structural containment: the workflow discipline that makes agent mode safe enough to use

Constrain what an agent session can accomplish without passing an external gate. Agents should work only on feature branches, with CI security scans required before merge and no automatic deployment from the branch they write to. This breaks the direct path to production. It also places the decisive control outside the model’s willingness to follow a prompt. Rules guide the work, while the workflow controls its release.

Within that boundary, package-specific.mdc rules should spell out which imports are restricted, which paths are security-sensitive, and which patterns are forbidden. Each session should receive one concrete task in the smallest effective workspace, using subagents when parallel subtasks are needed. These constraints make output easier to inspect. They also reduce the amount of unrelated code and instruction text competing for context.

Agent output should be treated as a draft PR. Bugbot adds a PR-time review layer, but remains a supplementary catch mechanism rather than a replacement for branch isolation and CI. The TypeScript migration’s package-level success criterion illustrates why bounded tasks help here, since reviewers can assess a specific result against a limited diff. The required discipline is familiar to established engineering teams, consisting of feature branches, CI gates, and scoped pull requests.

What the late-2026 infrastructure changes mean for teams deciding how to adopt agent mode on monorepos now

Late-2026 infrastructure changes shift the adoption decision from basic feasibility to controlled operation. Selective re-embedding supports a changing codebase, parallel agents divide the reasoning load, and cloud environments remove dependence on a developer’s available RAM. Those capabilities still leave a default root-level session as a poor way to run agent mode.

The unsettled parts remain relevant to planning. The Environments API is in public beta, repository-capacity documentation conflicts, and the AGENTS.md regression has no fully clean fix for teams that must load the repository root. Long-session context degradation also remains unresolved. These are reasons to limit the initial working surface.

A team starting now should begin with scoped.mdc rules, aggressive.cursorignore exclusions, and package-level windows. Feature branches and CI gates should be non-negotiable, while evaluation of the cloud API for the largest packages should follow its exit from public beta and stabilization of capacity documentation. The adoption unit should be a bounded, reviewable task.

Notes

  1. Cursor loads all rules from all folders in monorepo and blows past context limits $$ - Bug Reports - Cursor - Community Forum

    Documented the AGENTS.md rules-loading regression in monorepos, including loading all rule files and context overflow.

Tomás Červenka

← Back to Agent Bake-off