Cursor Agent: The Terminal Tool

The terminal tool is how the agent runs shell commands. Cursor runs them directly in your terminal rather than a hidden process, so the output lands where you can read it. What decides whether a command runs on its own, pauses for your approval, or drops into the sandbox is your Run Mode setting, not the terminal tool itself.

Cursor's one-line summary of the terminal page names three things: sandboxing, preserved history and native terminal integration. Running in your own terminal is what makes the middle one ordinary rather than a feature. When an agent has been going for twenty minutes and the working tree looks wrong, the commands that got it there are already where you would look for anything else you ran today.

Of the tools the agent has, the terminal is the one I would configure before any of the others. A Cursor agent runs on your machine as you, so a shell command it issues has the same reach over files, processes and the network that your own login has. Run Mode, hooks and the sandbox are what bound that reach, and all three are things you set.

Most of this page is therefore about the settings around the terminal rather than the terminal itself.

That decision lives in Run Mode. Run Mode controls three things for terminal commands: when they run automatically, when Cursor stops and asks you, and when a command enters the sandbox. Set the behavior you want there before you let an agent loose on a repo.

The word doing the work in that last sentence is "before". Run Mode is easy enough to find once you know it exists and close to invisible if you do not, so the usual introduction to it is watching a command you would have declined scroll by. Nothing is usually broken at that point. It is still a worse first hour with the agent than changing one setting would have been. On a new machine, change it before you send the first prompt.

The three modes are Auto-review, which is the default in Cursor 3Cursor's agent-forward interface (also called the agent window or Glass), built to run and supervise many agents at once rather than edit one file. Press Enter for the full definition..6 and later, plus Allowlist and Run Everything. Which one to pick, and why the classifier inside Auto-review is not a security boundary, is worked through on the Auto-review Run Mode guide.

What the mode names do not show is who the trade lands on. Solo, a strict mode costs clicks, and clicks are cheap. On a team I used to frame that the same way, one person's clicks multiplied by headcount, which misses the part that actually bites: a mode that interrupts constantly gets turned off, and then you are running looser than the default you started from while believing you have a control. So set it centrally rather than per person. On Enterprise the mode is set as an org policy from the team dashboard; without that policy, it is each developer's own setting.

Write a hook. beforeShellExecution fires before any shell command executes and returns allow, deny or ask, and since the script is yours and sits in the repo with the rest of your config, the same command gets the same answer every run.

The matcher on that hook runs against the full command string, which is more useful than it first looks. A hook that fires on every command turns into noise inside a week. Cursor's own example fires an approval script only when the command contains curl, wget or nc, and stays out of the way for everything else.

The input that hook receives carries the command, the working directory, and a sandbox boolean saying whether this command is about to run inside the sandbox. Easy field to skip past. It is also the point where Run Mode and your own policy meet, since your script can allow a sandboxed command that it would deny against the real filesystem.

afterShellExecution is the counterpart, and it audits rather than blocks. It hands you the command, the full terminal output, the same sandbox flag, and a duration in milliseconds. Read that duration field carefully, because it excludes the time the command spent waiting for approval. It measures execution only, so it will tell you nothing about how long anyone sat looking at a prompt. If interruption cost is what you are trying to size, and I suspect it is the number most teams should want first, count approvals rather than timing them.

Hooks fail open unless you set failClosed, which changes what you can honestly call a control. Where to set it, and where leaving it off is the better call, is covered on security hardening.

The sandbox runs terminal commands in a restricted environment that blocks unauthorized file access and network activity. It is the containment layer for commands the agent runs, so a command that tries to reach files or the network it should not touch is stopped.

.cursorignore excludes matching files from indexing, from what the agent reads directly and from context selection. Terminal output, as it happens, sits outside what it filters. A command the agent runs can print the contents of a file those rules were written to keep away from the model, and the model then reads that output like any other. Cursor's advice is to back the ignore rules with approvals and with file permissions at the OS level.

The deeper sandbox details (platform requirements, network modes, environment variables and the sandbox.json configuration) live in the Run Modes sandboxing section, not on the terminal page. Read that section when you need to tune what the sandbox permits.

The network side has one detail that saves a duplicated effort. The default network allowlist the sandbox uses is the same set of domains Cloud AgentsAgents that run in a Cursor-managed virtual machine, check out the repo, do the work and open a pull request, then shut down, with no load on your laptop. Press Enter for the full definition. get in Default + allowlist mode, and the team-level allowlist an admin configures applies to both, so there is one list to maintain. The Cloud Agent network access page describes what tends to fail when that list is tightened faster than the host names are known.

Whether the sandbox is a control or a habit depends on the plan you are on. Sandbox ModeAn isolated agent execution mode that contains the blast radius: file access scoped to the workspace, network off by default and git restricted to read-only, enforceable org-wide. Press Enter for the full definition. set as an organization policy holds no matter who is at the keyboard, and on a managed fleet that is the only version I would count on. Without it the sandbox is a per-user default, which works at five people who all know what the setting is and stops working somewhere well short of fifty.

Some shell themes interfere with the inline terminal output. Cursor names Powerlevel9k and Powerlevel10k as examples. If a command's output looks truncated or misformatted, disable the theme or switch to a simpler prompt while Cursor runs.

Check the command before you check the theme. What the docs describe is inline output that looks truncated or misformatted, with the theme interfering in how the output is shown. Re-run the command in a plain shell and compare. My rule is to clear the command first and touch shell config only after that.

You do not have to give up your prompt everywhere. Cursor sets the CURSOR_AGENT environment variable when it is running, so you can detect it in your shell config and skip the heavy theme only for Cursor sessions. The zsh snippet below does that for Powerlevel10k.

if [[ -n "$CURSOR_AGENT" ]]; then
  # Skip theme initialization for better compatibility
else
  [[ -r ~/.p10k.zsh ]] && source ~/.p10k.zsh
fi

The empty branch in that snippet is deliberate. The if body is a comment and nothing else, and the theme load happens in the else, so Cursor sessions skip Powerlevel10k while every other shell you open still gets it. Switching the theme off globally would probably make the symptom go away too, and it is a heavier fix than the problem needs, since the only session misbehaving is the one Cursor is driving.

The same check works in bash if you would rather fall back to a plain prompt for Cursor sessions instead of skipping a theme.

if [[ -n "$CURSOR_AGENT" ]]; then
  PS1='\u@\h \W \$ '
fi

Neither snippet changes what the agent is allowed to run. They change what the prompt prints.