Skip to main content

03 - Agent Mode: Modify Your Entire Codebase with One Command

How to hand a task to Cursor's Agent without losing control: a verifiable prompt, Run Modes and permissions, and a perimeter check on the changes.

What do you think about this article?

03 - Agent Mode: Modify Your Entire Codebase with One Command
Cursor IDEPhoto:Nimit KansagraPexels

At a Glance

How to hand a task to Cursor's Agent without losing control: a verifiable prompt, Run Modes and permissions, and a perimeter check on the changes.

The problem: handing over a whole task without losing control of it

Imagine writing to Cursor's Agent "add pagination to the orders list" and finding, a few minutes later, many files changed, a new dependency in package.json and a test that used to pass and has now been rewritten. The work may even be good, but you cannot tell, because you had not said what it was supposed to touch or how you would verify that it was finished. The Agent is the tool that makes the editor work "with one command": the difference between a useful result and an afternoon of review lies almost entirely in three decisions you make before, during and after its work. Before, how you describe the task. During, which actions it can take without asking your permission. After, how you check that it did only what you had asked.

Here I explain all three on the official documentation read on 2026-11-13, with two tools that I wrote and ran: a perimeter check on the changes and a permissions file. Cursor was not installed on the machine I am writing on: what happens inside the editor is described by the documentation and I did not try it. If you do not know tools and modes yet, first read the opening guide and the one on project rules, which I take as known here.

What the Agent is, according to the documentation

According to the documentation, an agent is made of three components: the instructions, that is the system prompt plus your rules, the tools to search and edit code and run commands, and the model you choose for the task. Cursor optimises instructions and tools for every supported model. The point that matters to anyone working is that the agent does not guess the content of files: it searches for them and reads them, applies the changes, runs the commands in the terminal and reads the result, can ask you questions while it keeps working and, in the cases that call for it, uses a browser to try out an application. The same page states that there is no limit on the number of tool calls in a task: a vague task can therefore run for a long time, which is one more reason to define it well.

For tasks that require a lot of searching, the Agent can start subagents, each with its own context window. The exploration one searches the code with a faster model and runs many searches in parallel, returning only the conclusions to the main agent; the browser one filters out the noise of screenshots. The stated advantage is context: voluminous searches do not fill the main conversation. You can explicitly ask it to use them, for example "use a subagent to find all the places where we validate input". Background agents and long plans are the subject of the fourth article.

Before starting: a clean tree and a verifiable task

An Agent change lands on disk immediately, except for configuration files, which ask for consent. If before starting you have uncommitted changes of your own, in the diff you can no longer tell your work from the agent's. The first move is therefore a clean working tree, and the second is knowing what you expect to find afterwards. The tool that follows automates both: with the before command it refuses to continue if there are modified files, with the after command it lists the changed files and flags those outside a perimeter that you declare with patterns. It uses git status --porcelain, the format that Git defines as stable across versions and suited to scripts, and glob.translate for the patterns.

perimeter.py
"""Perimeter check before and after a task handed to an agent.

before: exits with 1 if the working tree is not clean.
after:  lists the changed files and flags those outside the allowed paths.
"""
import glob
import re
import subprocess
import sys


def git(*args):
    return subprocess.run(["git", *args], capture_output=True, text=True, check=True).stdout


def changed():
    lines = git("status", "--porcelain", "--untracked-files=all").splitlines()
    return [(r[:2].strip() or "?", r[3:]) for r in lines]


def allowed(path, patterns):
    return any(re.fullmatch(glob.translate(m, recursive=True), path) for m in patterns)


def main(argv):
    command, patterns = argv[0], argv[1:]
    entries = changed()
    if command == "before":
        if entries:
            print(f"tree NOT clean: {len(entries)} modified files, commit or put them aside before starting")
            return 1
        print("tree clean: every difference you will see afterwards will be the agent's")
        return 0
    outside = [(s, p) for s, p in entries if not allowed(p, patterns)]
    for status, path in entries:
        tag = "OUTSIDE" if (status, path) in outside else "ok     "
        print(f"{tag} {status:2} {path}")
    print(f"{len(entries)} files changed, {len(outside)} outside the perimeter")
    return 2 if outside else 0


if __name__ == "__main__":
    sys.exit(main(sys.argv[1:]))

In the changed() function the --untracked-files=all option is there to see new files one by one too: without it, Git would show a new folder as a single entry and a file created by the agent in an unexpected folder would go unnoticed. The allowed() function compares the path with the patterns; exit code 2 of after is meant to distinguish "there are files outside the perimeter" from a program error.

To try it without involving an agent I simulated the changes myself: a temporary repository with a service, a component and a package.json, then three changes by hand, two inside the orders folder and one that touches package.json, exactly the kind of overstepping described at the beginning. The scenario.sh script builds the repository, runs the checks and deletes it.

scenario.sh
#!/bin/bash
set -u
D=$(mktemp -d)
cd "$D" || exit 1
git init -q .
git config user.email test@example.invalid; git config user.name test
mkdir -p src/app/orders
echo "export class OrdersService {}" > src/app/orders/orders.service.ts
echo "export class OrdersComponent {}" > src/app/orders/orders.component.ts
echo '{"name":"shop"}' > package.json
git add . && git commit -q -m base
P=$HOME/demo/perimeter.py
echo "--- before, clean tree"; python3 -I $P before; echo "exit $?"
echo "// page" >> src/app/orders/orders.service.ts
echo "export const PAGE = 20;" > src/app/orders/orders.pagination.ts
echo '{"name":"shop","dependencies":{"x":"1"}}' > package.json
echo "--- after, perimeter src/app/orders/**"; python3 -I $P after 'src/app/orders/**'; echo "exit $?"
echo "--- before, dirty tree"; python3 -I $P before; echo "exit $?"
rm -rf "$D"

The output shows the three situations: a clean tree, changes inside the perimeter with one file outside, and the refusal to start again with a dirty tree. The two lines that matter are the one for package.json marked OUTSIDE and the exit 2: in a real task that line tells you the agent changed the dependencies, and at that point it is you who decides whether to keep them. The codes are the program's, not Cursor's.

Output of scenario.sh
# Output of scenario.sh (Python 3.14.4, git 2.53.0, two identical runs)
# --- before, clean tree
# tree clean: every difference you will see afterwards will be the agent's
# exit 0
# --- after, perimeter src/app/orders/**
# OUTSIDE M  package.json
# ok      M  src/app/orders/orders.service.ts
# ok      ?? src/app/orders/orders.pagination.ts
# 3 files changed, 1 outside the perimeter
# exit 2
# --- before, dirty tree
# tree NOT clean: 3 modified files, commit or put them aside before starting
# exit 1

The perimeter, on the other hand, holds only if you have communicated it to the agent. The prompt that follows is an example for an Angular project: it states the expected result, the constraints (where it may write, what it must not touch) and how to verify. It is a template to adapt and was not run, because it requires Cursor and a project.

Prompt for the Agent (template to adapt, not run)
In the src/app/orders folder add pagination to the orders list.

Expected result:
- the OrdersService service accepts a page and a page size and passes them
  as query parameters to the GET /api/orders endpoint;
- the component shows twenty orders at a time and two buttons, Next and Back;
- Back is disabled on the first page.

Constraints:
- change only the files inside src/app/orders;
- do not add dependencies to package.json;
- follow the project rules.

Verification: write or update the tests for the service and the component, then run
"npm test" and report the result to me. If a test fails do not change it to make it
pass: tell me why it fails.

Three choices make the prompt verifiable. The result is expressed with behaviours you can observe (twenty orders at a time, a disabled button), not with adjectives. The constraints match the perimeter you check afterwards with the script: src/app/orders/** and no dependencies. The last sentence blocks the most common shortcut, changing a test to make it pass. There is no need to attach every file with the at sign: the documentation suggests @ mentions when you already know which files matter, and letting the Agent search in the other cases. If the task changes subject, open a new chat: the context ring next to the text field shows how much of the window is already taken, and a long conversation gets summarised.

During: what it can run on its own

Run Modes decide when the agent must stop and ask you for confirmation for shell commands, MCP tools and network requests. In the desktop application you choose them from Settings, Agents, Approvals & Execution. There are three, and the difference between one and another is how much trust you give in advance.

  • Auto-review: actions on the allowed list start immediately; other shell commands run in the sandbox when possible; whatever cannot use it is examined by a classifier.
  • Allowlist: only the listed actions start without asking, deterministic behaviour, no classifier.
  • Run Everything: every call starts on its own, with no checks and no sandbox.

The documentation names Auto-review as the safest setting for most people, and right afterwards warns that it is not a security boundary: the classifier can be wrong in both directions. The Run Everything mode corresponds to what many older guides call YOLO; the equivalence is mine, the documentation does not use that name. If the project contains secrets or you work on a machine with access to real systems, the reasonable choice is Allowlist with a few trusted commands, such as tests and the build, or Auto-review with rules of your own. The security page also says that, by default, terminal commands require approval: check in Settings which mode is active on your installation, because the Run Modes page does not say which one is the starting one.

With Auto-review you can add instructions in plain language in a permissions.json file, in ~/.cursor/ for all your projects or in .cursor/ for the current one; if both exist, Cursor merges them, and a team configuration in the dashboard, if present, takes precedence over both. The file that follows asks that commands that rewrite Git history and those that delete outside dist/ always go through approval.

.cursor/permissions.json (template to adapt)
{
  "autoRun": {
    "allow_instructions": [],
    "block_instructions": [
      "Every command that changes git history (rebase, reset, push) must go through approval.",
      "Every command that deletes files outside the dist/ folder must go through approval."
    ]
  }
}

The keys are those of the documentation: allow_instructions describes what Auto-review should tend to let through, block_instructions what it should tend to block, so that the agent picks another route or asks you. They are sentences, not formal rules: "tend" is the documentation's verb, so they do not replace a backup nor an account without write permissions on the production server. I validated the file as JSON and checked the two keys; the behaviour inside Cursor was not tried.

Underneath there is the sandbox, one more layer for shell commands: in the default mode it works with read and write access in the project, blocks the network until you open it with sandbox.json and protects paths such as .git/config and .git/hooks. A command that needs more access leaves the sandbox and Cursor flags it to you by asking for approval. A warning from the ignore file page: the .cursorignore file hides files from the agent, but does not govern terminal tools or MCP servers.

After: checking what changed

Changes appear in the diff view while the agent works, and you do not have to wait for the end: the Stop button, or Cmd/Ctrl+Shift+Backspace according to the "Reviewing and testing code" guide, stops it midway. If the route is wrong, the guide advises undoing the changes and refining the plan before rerunning it, instead of correcting it with follow-up messages. To go back there are checkpoints: with "Restore Checkpoint" you bring the files back to the state of that point, but they are local, separate from Git, they do not remove the messages from the conversation, and they serve to undo the agent's changes, while the permanent history is kept by Git.

For the actual review Cursor offers two routes: after a task the Review button, then "Find Issues", starts a dedicated line-by-line review; for all local changes, the Agent Review command in the Source Control tab compares them with the main branch. You can also attach @Branch to a message in Ask mode and ask "review the changes in this branch". The guide recalls that generated code can look correct, compile and pass the tests you wrote, and still be wrong on edge cases or duplicate logic that already exists: the criterion for deciding what to merge remains the one you would apply to hand-written code.

One last precaution concerns commits. An agent produces many changes together, and a single commit of hundreds of lines is hard for a colleague to review. Cursor's guide suggests working freely and then asking the agent to rewrite the history into small, descriptive commits, with a final check that the overall diff is identical to the original; it also reports a skill (rework-commits) that you can adapt. Before using it look at the commands it runs: it contains a git reset, and it is one of those that is worth sending through approval.

When it is not worth handing it the task

It is not the right tool when you cannot describe the result (use Ask or Plan first to understand the problem), when the outcome can only be judged by eye across many files, and when the code touches secrets or production systems that you do not even want to expose to the context. For one-line changes, Tab completion is faster and leaves less to review. A general criterion stands: the more verifiable the result is with a command, the more delegable the task is.

Frequently asked questions

How do I stop the Agent from running dangerous commands?

Choose the right mode in Settings, Agents, Approvals & Execution, preferring Allowlist or Auto-review to Run Everything, and add blocking instructions in permissions.json. The documentation admits that none of these is an absolute security boundary.

How do I undo what the Agent changed?

With "Restore Checkpoint" on an earlier message you bring the files back to that state, but checkpoints are local and separate from Git. If you work on a clean tree, git restore or a previous commit remain the permanent safety net.

Can I write another message while the Agent is working?

Yes. Pressing Enter puts the message in a queue and it starts at the end of the task; with Cmd/Ctrl+Enter it is sent immediately, without going through the queue. For a side question, side chats avoid interrupting the main conversation.

What you can do now

You can describe a task with a result, constraints and verification, you can decide which commands the Agent may run on its own and which not, and you can check afterwards that the changes stayed within the perimeter you had indicated, with a clean tree as the starting point. The next step is to let the Agent stop and plan before writing, in Plan Mode, and, to automate what happens around the agent, in hooks. If the Agent has to talk to a database or an API, there is MCP; if the task is a bug, there is debugging. For a whole project, from configuration to checks, there is the workflow on an Angular application.

Sources

The perimeter tool was run with Python 3.14.4 and Git 2.53.0 in a temporary repository outside the project, twice with identical output; I simulated the scenario's changes by hand, without any agent. The permissions file was validated as JSON. The prompt and the behaviour of Cursor, of Run Modes and of checkpoints were not tried: Cursor was not installed.

Try These Tools

Free developer tools related to this topic.

Commenti

Caricamento commenti...

Sign in to comment

New articles and tools on Telegram too

The Telegram channel flags the site's new articles and tools.

Did you like this article?

Explore other content on the blog or discover my projects