Essential Cursor configuration for agent work

Essential Cursor configuration is the set of repository and account settings that let Cursor’s agent run a project’s checks without asking each time, while keeping destructive commands and secrets behind approval. It has five parts: one verify command, a run mode, project rules, a stop hook that re-runs the gate, and .cursorignore plus Privacy Mode.

You open a real repository in Cursor, ask the agent to fix a failing test, and it stops to ask before npm test, then again before tsc, then again before eslint. After the tenth approval you either give up or tell it to run everything, which is how an agent ends up running git push or reading .env. Neither is a configuration. Both leave you reading every line of the diff to find out whether the change works.

This page is for the developer setting up Cursor on a working repository in the first hour, and the tech lead who commits the result so the whole team gets the same setup. It assumes Cursor is installed (installation and platform setup).

What this page checked

On 2026-10-12 Cursor’s docs and help confirm the run modes, the Auto-review classifier, the .mdc rule format and frontmatter keys, and Cursor’s support for AGENTS.md and CLAUDE.md. On 2026-09-26 cursor.com could not be fetched, so the rest of the settings behaviour (hooks, .cursorignore, protected config files) was checked against the agent runtime shipped in Cursor’s own @cursor/sdk 1.0.32 package on npm (the current release on 2026-09-26; @cursor/sdk on npm and cursor-sdk on PyPI are both at 1.0.37 as of 2026-10-07), and the feature names against Cursor’s docs as fetched on 2026-08-28. That other behaviour was not re-checked on 2026-10-12. Menu labels change between releases, so this page names settings by what they do, not by their exact position in the UI.

What a working Cursor configuration gives you

• A single npm run verify command that proves a change, which the agent, your stop hook and CI all run.
• A run mode that lets the agent run that command unattended while git push, rm -rf and anything with sudo still stop for you.
• A committed project rule that tells the agent your stack, commands and boundaries.
• A stop hook that re-runs the gate when the agent says it is finished and sends it back to work if the gate fails.
• A five-minute smoke test that proves the configuration works before you trust it with a real task.

What order should you configure Cursor in?

Configure from the inside out. The verify command comes first, because every later layer points at it. Account-level privacy comes before you open proprietary code, because data that already left cannot be recalled.

Layer	Lives in	Committed to git?	Owner
Verify command	package.json (or Makefile, pyproject.toml)	Yes	Developer
Run mode and allowlist	Cursor Settings > Agents > Approvals & Execution	No: per user; a team admin can add a team-wide terminal allowlist	Developer, then tech lead
Project rules	.cursor/rules/*.mdc	Yes	Tech lead
Stop hook	.cursor/hooks.json and .cursor/hooks/	Yes	Tech lead
Secret exclusions	.cursorignore	Yes	Tech lead with security
Privacy Mode	Your Cursor account or team admin dashboard	No	Account owner or admin
Editor settings	.vscode/settings.json	Yes	Tech lead

Give the agent one command that proves the work

An agent that has to guess how to test your project guesses differently every session: npx jest today, npm test -- --watch tomorrow, which hangs. A single script removes the guess and gives the allowlist, the hook and CI the same thing to call.

{
  "scripts": {
    "typecheck": "tsc --noEmit",
    "lint": "eslint .",
    "test": "vitest run",
    "verify": "npm run typecheck && npm run lint && npm run test"
  }
}

The script has to exit non-zero on any failure and must never start a watcher. If your project already has a CI workflow, verify runs the same steps CI runs, so a green local gate predicts a green pipeline.

Copy-paste prompt: build the verify command

Read package.json, any Makefile, and every workflow under .github/workflows/.
List each check that CI runs (type check, lint, unit tests, format check) and
the exact command it uses.

Then add a single "verify" script to package.json that runs those same checks
in order, fails on the first error, and never starts a watch mode. Do not
change any existing script. Run `npm run verify` once and report: the exit code,
how long it took, and every check that failed with its first error line.
Do not fix failures yet.

A red verify on an untouched checkout is useful information: it is the baseline. Fix it, or record it in the project rule, before you ask the agent for anything else. Otherwise the agent inherits failures it did not cause and “fixes” them in ways you did not ask for.

Choose a run mode that lets the agent run the gate

Cursor groups terminal control under run modes (Cursor’s run modes page). The runtime supports three mechanisms that combine:

• An allowlist: commands that always run without asking.
• A sandbox for shell commands, which limits what a command can write and reach on the network.
• Auto-review, which sends tool calls that are neither allowlisted nor sandboxable to a classifier that decides whether they run or come to you.

Cursor’s docs name three run modes (checked 2026-10-12), set under Settings > Agents > Approvals & Execution:

• Auto-review is the recommended default since Cursor 3.6 and, in Cursor’s words, “the safest useful setup for most people”. Allowlisted calls run immediately, other shell commands run in the sandbox when possible, and calls that do not use the sandbox go to the Auto-review classifier.
• Allowlist: “Actions in your allowlist run without approval.”
• Run Everything: “Every tool call runs automatically.” In the CLI, /run-everything [on|off|status] switches it, and /auto-run is an alias.

The classifier is itself a model. Cursor’s docs say “Today it uses Gemini 3.5 Flash Lite, with Claude 4.5 Haiku as the fallback”, and that blocking Claude 4.5 Haiku “can disable Auto-review”. They also say “Auto-review is not a security boundary” and “The classifier can make mistakes”, so keep irreversible commands off the allowlist whichever mode you use. Cursor 3.24 added “Auto-review stops risky deletes for your approval”, and CLI v2026.10.08 made Auto-review stricter on risky deletes.

Tutorials still use older names. YOLO mode and Auto-Run are old names, and “run modes” is the current term. Cursor 3.5 deprecated Ask Every Time (use Allowlist with an empty allowlist for the same behaviour) and folded Run in Sandbox into Allowlist with sandboxing enabled.

Run modes apply to local agents only: Cursor’s docs say “Cloud Agents run inside their own dedicated machine, so the agent never asks you to approve an action”. The same docs page lists ~/.cursor/permissions.json and <project>/.cursor/permissions.json (merged) as config files, and sandbox.json for the sandbox; the steps below use the Settings screen.

On a team plan, an admin can set a team-wide terminal allowlist that overrides yours, so check what your admin already set before you change anything.

1. Open Cursor Settings and go to Agents > Approvals & Execution, where the run modes live.

2. Keep a mode that sends anything not allowlisted to review (Auto-review) or to the sandbox (Allowlist with sandboxing enabled), not Run Everything.

3. Add the commands the agent needs to verify its own work to the allowlist. A starter set for a TypeScript project:

   npm run verify, npm test, npm run lint, npm run typecheck, npx vitest run,
   tsc, eslint, prettier --check, git status, git diff, git log

   For Python, add pytest, ruff check, mypy. For Rust, cargo test, cargo clippy.

4. Leave everything irreversible off the list: git push, git commit, git reset --hard, rm -rf, sudo, npm publish, docker rm, curl, ssh, and any deploy or database migration script.

Do not run every command without review on your laptop

Cursor also offers a mode, Run Everything, that runs every command without asking. Use it only inside a disposable, network-restricted environment, never on a machine that holds credentials, SSH keys or a production kubeconfig. An allowlist plus review for everything else gets the same speed for the commands that matter. The trade-offs across all three agents are in permissions and sandboxing.

Copy-paste prompt: propose an allowlist from the repository

List every command an agent would need to verify a change in this repository:
the scripts in package.json, the tools CI calls, and the git read commands.

Sort them into two tables:
1. Safe to run unattended: read-only, or writes only inside the working tree
   and is undone by `git restore .`.
2. Must ask first: pushes, publishes, deletes outside the working tree,
   touches the network, a database or a cloud account, or needs sudo.

For every row say why. Do not run any command in table 2. Print table 1 as a
single comma-separated line I can paste into Cursor's allowlist.

Tell the agent your conventions with a project rule

Project rules are the instructions the agent loads with every request. The runtime reads rules from .cursor/rules/**/*.mdc, and a rule whose frontmatter sets alwaysApply: true loads in every session. One always-apply rule is enough to start; scoped rules by file pattern, and the full format, are in project rules in Cursor. Cursor’s docs also say it supports AGENTS.md in the project root and in subdirectories, and that it reads CLAUDE.md files the same way (checked 2026-10-12).

Copy-paste starter rule: .cursor/rules/project.mdc

---
description: Stack, commands and boundaries for this repository
alwaysApply: true
---

Stack: Next.js App Router, TypeScript strict, Tailwind CSS, Drizzle ORM on
PostgreSQL, Vitest. Package manager: npm (never pnpm or yarn).

Before you say a task is done, run `npm run verify` and paste the last lines
of its output. A task is not done while verify fails.

Never edit or delete an existing test to make it pass. If a test looks wrong,
stop and explain why instead.

Use named exports. Validate all external input with zod. Handle errors from
every async call; never swallow them.

Ask before adding a dependency, changing a migration, or touching anything
under .github/ or .cursor/.

A rule shapes what the agent writes. It does not stop a command, so never rely on a rule where the run mode, a hook or .cursorignore should hold the line. Cursor’s help calls a root .cursorrules file “legacy and will be deprecated” (checked 2026-10-12), and the SDK 1.0.32 runtime still loads it as an always-apply rule next to your new ones. Move its content into .cursor/rules/ and delete it, or the agent reads two sets of instructions that drift apart.

Make Cursor re-run the gate before it says “done”

The rule asks the agent to run verify. A hook makes it happen. Cursor’s hooks are processes that “communicate over stdio using JSON” and “can observe, block, or modify behavior” (Cursor hooks docs, checked 2026-08-28). The stop hook runs when the agent finishes a turn. In the SDK 1.0.32 runtime it receives the turn’s status and a loop_count, and if it prints a followup_message, the agent receives that message and keeps working.

{
  "version": 1,
  "hooks": {
    "stop": [{ "command": "node .cursor/hooks/verify-on-stop.mjs", "loop_limit": 3, "timeout": 900 }]
  }
}

// .cursor/hooks/verify-on-stop.mjs: send the agent back if the gate fails
import { readFileSync } from 'node:fs';
import { spawnSync } from 'node:child_process';

const input = JSON.parse(readFileSync(0, 'utf8'));
const done = () => { process.stdout.write('{}'); process.exit(0); };

// Only check turns the agent finished on its own, not ones you stopped.
if (input.status !== 'completed') done();

const run = spawnSync('npm run verify', { shell: true, encoding: 'utf8' });
if (run.status === 0) done();

const tail = `${run.stdout}\n${run.stderr}`.trim().split('\n').slice(-40).join('\n');
process.stdout.write(JSON.stringify({
  followup_message:
    'npm run verify failed after your last change. Fix the cause. Do not edit, ' +
    'skip or delete tests to make it pass. Output:\n' + tail,
}));

loop_limit caps how many times the hook can send the agent back in one task. Three is enough to fix a missed import; a fourth failure usually means the approach is wrong, and you want to see it. Without loop_limit the runtime stops after 5 loops (SDK 1.0.32). Hooks time out after 60 seconds unless you set timeout (seconds; SDK 1.0.32), and a timed-out hook lets the agent stop, so set it above your slowest verify run.

Commit both files. The runtime treats JSON files under .cursor/ as protected configuration, so an agent edit to hooks.json or mcp.json asks for your approval instead of happening silently. That protection covers JSON only: the hook script verify-on-stop.mjs and the verify script in package.json are not protected files, and the agent can edit them without a prompt. An agent that shortens verify or neuters the hook turns the gate green without the work being right, so the diff check under when Cursor configuration breaks covers them too. The companion guard that blocks secret reads and network commands with beforeShellExecution and beforeReadFile hooks is in privacy and security in Cursor.

Keep secrets and private code out of the agent’s reach

Two settings decide what leaves your machine, and they live in different places.

• .cursorignore, committed at the repository root in .gitignore syntax. The agent’s file tools refuse to read matching paths. Start with .env, .env.*, *.pem, *.key, secrets/ and any database dump.
• Privacy Mode, an account-level setting on Cursor’s side. A repository cannot set it. On a team plan, confirm the tier in the admin dashboard; on a personal account, check it in your own settings before you open proprietary code.

What each tier guarantees depends on your plan and contract, so confirm it on Cursor’s current privacy pages rather than from a blog post. The full setup, including a CI test that proves the guard still blocks, is in privacy and security in Cursor.

Editor settings that keep agent changes reviewable

Cursor is built on VS Code, so workspace settings in .vscode/settings.json apply and can be committed for the team.

{
  "files.autoSave": "afterDelay",
  "editor.formatOnSave": true,
  "search.exclude": {
    "**/node_modules": true,
    "**/dist": true,
    "**/.next": true,
    "**/coverage": true
  }
}

Auto-save keeps the files on disk in step with what you see, so the agent’s commands never run against a stale buffer. Format on save covers the files you edit. It does not guarantee that files the agent writes are formatted, so keep prettier --check (or your formatter’s check mode) inside verify and let the gate catch it.

For a monorepo, open the packages you work on rather than the root, or group them in a multi-root workspace file:

{
  "folders": [
    { "path": "apps/web", "name": "Web (Next.js)" },
    { "path": "services/api", "name": "API (Express)" },
    { "path": "packages/shared", "name": "Shared types" }
  ]
}

Save it as myproject.code-workspace and open it with File > Open Workspace from File. The agent can then edit across all three folders in one conversation. Strategies for larger trees are in large codebase strategies and multi-repository workflows.

How do you prove the configuration works?

Do not trust a configuration you have not seen hold. Commit a clean baseline first (git status shows nothing), then give the agent a small task that exercises every layer.

Copy-paste prompt: smoke-test the Cursor configuration

This is a configuration test. Do the following in order and report each result.

1. Add a function `slugify(title: string): string` to src/lib/slugify.ts that
   lowercases, trims, replaces runs of non-alphanumerics with "-", and strips
   leading and trailing "-". Add three Vitest cases in src/lib/slugify.test.ts,
   including an empty string.
2. Run `npm run verify` and paste the last 10 lines of output.
3. Try to run `git push --dry-run`. Report whether you were asked for approval.
4. Try to read .env with your file tool and then with the terminal. Report
   exactly what happened each time.
5. List every command you ran and whether it needed my approval.

The configuration passes when all of these are true, and none of them requires reading the new code:

Check	Where you see it	Pass
verify ran without an approval prompt	The agent’s command list	Yes, no prompt
The gate result is real	Run npm run verify yourself	Exit code 0
git push stopped	The approval prompt (or the guard hook’s deny message, if you added the guard from privacy and security in Cursor)	Asked or blocked
.env was not read	The agent’s report	Refused by .cursorignore (file tool) or stopped for approval (shell); a shell read that ran without a prompt is a fail
Only the expected files changed	git diff --stat	Two files
Gate files unchanged	git diff --stat -- package.json .cursor/	No lines
The stop hook works	Break a test by hand, ask the agent to “finish up”	It is sent back with the failure

Then open a pull request with .cursor/, .cursorignore, .vscode/settings.json and the verify script. The tech lead reviews that configuration PR once, and CI runs the same npm run verify on every later PR. From then on, a change is judged by its gate result and a short diff summary, not by reading every line; the method behind that is in reading evidence instead of code.

When Cursor configuration breaks

The agent still asks before every test run. The command it runs does not match the allowlist entry: npx vitest is not npm test. Add a line to the project rule (“run tests only with npm run verify”) and allowlist that exact string.

The agent ran something destructive. Stop the agent. Run git status and git diff --stat to see the damage, then git restore . (tracked files) and git clean -n followed by git clean -f (untracked files, after you check the list). Remove the command from the allowlist, or block it in the beforeShellExecution guard from privacy and security in Cursor. This is why the clean baseline comes before the first task. For in-editor rollback, see checkpoints and branching.

The stop hook never fires, or loops. Check that .cursor/hooks.json is valid JSON and that the command path works from the project root. If the agent keeps coming back with the same failure, the loop_limit is doing its job: read the failure yourself, because the plan is wrong, not the code.

The stop hook passes but verify is red. The hook timed out, and a timed-out hook lets the agent stop. Raise timeout in .cursor/hooks.json above the time your slowest npm run verify takes.

The agent weakens a test or the gate to get green. Run git diff --stat -- '*.test.*' '*.spec.*' package.json .cursor/ .cursorignore after every task. Any change to an existing test that you did not ask for is a rejection, whatever the gate says. The same goes for the hook script (.mjs) and package.json: they are not protected files, so any change to them that you did not request is a rejection. The rule line “Never edit or delete an existing test” reduces this; the diff check catches the rest.

The agent ignores the project rule. Confirm the file is under .cursor/rules/, ends in .mdc, and has alwaysApply: true in valid frontmatter. Delete any leftover root .cursorrules that contradicts it, and check that no AGENTS.md or CLAUDE.md does either, because Cursor reads both. More diagnosis is in project rules in Cursor.

Teammates get different behaviour. Everything in git is shared; the run mode and Privacy Mode are not. Ask your admin to set a team-wide terminal allowlist, and add .cursor/ and .cursorignore to CODEOWNERS so a change to the configuration gets a reviewer.

Where to go next after configuring Cursor

Model selection Which model to run in Cursor, and when to switch.

Project rules in Cursor Scoped rules, rule types and how to check they load.

MCP setup Connect the agent to your issue tracker, database and browser.

Your first feature Put the configuration to work on a real change.

Using more than one agent? The same layers for the other tools are in Claude Code configuration and Codex configuration. Model prices and defaults live on the models hub.