How the Cursor agent works and when it is better to run an agent in the terminal

The Cursor agent is the part of the product that does work on its own: it reads the codebase, edits files, runs shell commands, and keeps going until the task is finished or it needs an answer. Understanding it well enough to trust it comes down to three questions. What can it reach, when does it stop to ask, and where should it be running. The third question is the one most people skip, and it is the one that decides whether a twenty minute task blocks the window that was going to be used for something else.

Three components, and why only one of them is the model

The documentation describes the agent as built on three parts: instructions, which are the system prompt and the rules that guide behavior, tools, which are file editing, codebase search, terminal execution and more, and the model chosen for the task. Cursor tunes the instructions and tools for each supported model, which is why the same prompt behaves differently across editors even when the underlying model is identical.

Most complaints about agent quality are instruction problems wearing a model costume. A repository with no rules file gives the agent nothing about how the project is laid out, which commands are safe, or what the house style is. Adding a project rule in .cursor/rules, or a plain AGENTS.md at the root, changes more about day to day behavior than switching between frontier models does.

The tool list is worth reading once in full, because it sets the boundary of what the agent can do without a person. It searches files and folders, reads directory structures, reads files including images, edits files and applies the edits, runs shell commands, controls a browser to take screenshots and verify visual changes, fetches pages from the web, and can generate images. One line in the documentation sets expectations for how long a single task can run.

There is no limit on the number of tool calls Agent can make during a task. Source: cursor.com

That is a feature for a long refactor and a hazard for a vague prompt, which is why the approval settings below exist.

Talking to an agent while it works

An agent that cannot be corrected mid-task wastes whole runs. Cursor gives three ways to intervene, and they behave differently.

Queuing is the default. Typing an instruction while the agent works and pressing Enter adds it below the active task, queued messages can be reordered by dragging, and the agent processes them in order once the current work is done. Sending immediately with Cmd+Enter attaches the message to the most recent user message and processes it right away, which is the option for urgent redirection. Steering sits between the two: a follow-up sent with Send now, or by pressing Enter twice, is delivered at the agent's next tool call rather than cutting off an action in progress, so in-flight work is preserved.

Two more controls change the shape of a session. A side chat, started by typing /side or /btw, opens a separate durable conversation that uses the main thread as hidden context, which keeps a tangent from polluting the main transcript. The /goal command gives the agent a long-lived objective to work toward across messages instead of treating each message as a new job, which suits tasks like making a flaky test suite pass.

Plan mode, for work that is worth designing first

Plan Mode is reached with Shift+Tab from the chat input, and it inverts the order of operations: the agent asks clarifying questions, researches the codebase, and produces a reviewable plan that can be edited before any code is written. Plans are saved in the home directory by default, and a Save to workspace option moves one into the repository for sharing.

The documentation is direct about when this pays off: complex features with multiple valid approaches, tasks touching many files, unclear requirements, and architectural decisions. For quick changes or repeated tasks, going straight to Agent mode is fine.

There is one habit in that page worth adopting. When an agent builds something that does not match the intent, the recommended move is not to fix it with follow-up prompts. It is to revert, sharpen the plan, and run it again, which tends to be faster and produces cleaner results than steering a run that started from the wrong idea.

Approvals, sandboxing, and undo

The agent's autonomy is set by Run Modes, in Settings under Agents. Auto-review runs allowlisted calls immediately, runs other shell commands in a sandbox where possible, and sends anything that cannot be sandboxed to a classifier that can allow it, ask the agent for another approach, or ask for human approval. Allowlist mode runs only explicitly approved actions without asking. Run Everything runs every tool call automatically.

The sandbox blocks unauthorized file access and network activity for shell commands. Commands needing writes outside the workspace or privileged operations cannot run in it, so they go to review rather than running quietly.

Undo is handled by checkpoints, which snapshot modified files before significant changes and appear in the chat timeline. Checkpoints are stored locally, are separate from Git, and are for undoing agent changes only, not for version control. Restoring one reverts files without removing messages from the conversation. Alongside that, Agent Review runs a dedicated review of local changes, either automatically after commits or on demand with /agent-review, and from the Source Control tab it compares all local changes against the main branch rather than only the last edit.

What the agent is allowed to see

Autonomy settings decide what the agent may do. A second pair of controls decides what it may look at, and they are easy to leave at the defaults for months.

Rules supply persistent instructions. Project rules sit in .cursor/rules as .mdc files and are version-controlled with the code, so a rule about how migrations are written travels with the repository to everyone who clones it. Each rule can apply always, apply when the agent judges it relevant from its description, apply to files matching a path pattern, or apply only when mentioned by name. User rules are global to one person's setup, and team rules are managed centrally on Team and Enterprise plans. A plain AGENTS.md at the root works when that much control is not needed.

Ignore files work in the other direction. A .cursorignore in the project root excludes paths from AI context, .gitignore is respected automatically, and environment files, .git/, and lock files are excluded by default. The limit is stated plainly in the documentation: ignored files are blocked from the agent, but terminal commands and MCP tools run outside those file access controls and may still read them. For an agent that is allowed to run shell commands, that distinction is the whole point. The ignore file shapes context, and the Run Mode is what actually constrains reach.

The same agent, outside the editor

Cursor ships the agent in three places, and the choice between them is about where the work lives rather than which is more capable.

The CLI installs with a single shell command and starts with agent, optionally with an initial prompt. It supports the same modes as the editor, switched with slash commands or the --mode flag, and a print mode for scripts and CI pipelines. Sessions can be listed and resumed, sandbox behavior is set with /sandbox or --sandbox, and pressing Enter while the agent works steers the active run at a safe boundary, with a second Enter interrupting it.

Cloud agents run somewhere else entirely.

Cloud agents use the same agent fundamentals but run in isolated VMs in the cloud with full development environments instead of on your local machine. Source: cursor.com

They can be run in parallel without limit, they do not need the local machine to stay connected, and they can be started from the desktop app, the web interface, Slack, a comment on a pull request, Linear, an API, or the iOS app. Getting there requires an account admin to connect source control first, and the quality of the run depends almost entirely on the environment configured for it, since an agent that cannot run the tests cannot verify its own work. A conversation in the CLI can be handed to a cloud agent mid-flight by prefixing a message with &.

Where it runs	Best for	What it costs
Editor	Focused work in one project, reading diffs as they land	The window stays busy
CLI	Terminal-centered work, scripts, CI, several repos in tabs	No editor context or inline diffs
Cloud	Long or parallel tasks, work continued from a phone	Setup of source control and environment

When the terminal is the better place

The case for running the agent in the terminal is not ideological. It is about what the surrounding work looks like.

Terminal runs fit when the task is already shell shaped: a migration script, a batch of file operations, a build that needs watching, a repository that is not the one open in the editor. They fit when several tasks run at once, since separate terminal tabs are cheaper than separate editor windows. They fit when the machine is being reached over SSH, where an editor window is not available at all. And they fit when the work is not code, which is the case more often than editor-centric writing admits: renaming a directory of exports, converting assets, sorting downloads into project folders.

What the terminal gives up is the diff view. An agent editing five files in the editor shows each change in place, and that is the fastest way to catch an edit that was not asked for. Running in the terminal means leaning on git diff and on Agent Review afterwards. For work with real consequences, that trade is worth making deliberately rather than by accident.

The practical setup that results is a split: the editor for code that needs reading as it changes, the terminal for everything that is shell shaped, and the cloud for anything long enough that waiting would waste the afternoon. The friction in that setup is not the agent. It is the number of windows needed to see the files, run the commands, and watch the output at the same time. A file manager with a built-in terminal collapses two of those into one, which is the part described on Features, and the question of whether a running agent can be answered from a phone while away from the desk is covered on From iPhone and iPad.

What to change first

Set the Run Mode before the next agent task, then run one real task from the CLI instead of the editor and notice which one matched the work. If most tasks turn out to be shell shaped, the window to rethink is the one holding files and the terminal, which is what Atriens is for.